PyAVA
: Python interface for the Annotation of Vocalisations in Audio recordings.
Description
PyAVA
is a graphical annotation tool written in Python whose purpose is to provide an easy way to draw contours on vocalisations from audio recordings. It uses Tkinter for its graphical interface and can be run on any OS. It does not require images (spectrogram) to function, only waveforms, which is its main advantage.
Features
- Spectrogram contour annotations.
- Spectrogram automatically computed from waveform.
- Choose custom spectrogram resolutions (fft, hop length, clipping dB value and PCEN).
- Select a new file directly from the interface.
-
Exportation of contours to local
.json
. - Move points once they are placed (with mouse wheel).
- Modification of previous annotation. Save & return later!
Requirements
- Ubuntu / Windows / macOS (tested only on Ubuntu but it should work on any OS).
- Python 3.9.7
- Packages in
requirements.txt
Install packages in your python environment with $ pip install -r requirements.txt
.
Usage
Execution
For classic use, download PyAVA folder, then open a terminal in the folder and run $ python PyAVA.py -dir myWavefileFolder -out myOutputFolder
in terminal.
Run $python PyAVA.py --help
for details.
The annotations are saved in JSON files. Each file contains a dictionnary with the categories annotated. For each category there is a list of points, each point is defined by a list of two elements : [time (in sec), frequency (in Hz)].
User actions
- Use the toolbar to interact with the plot (same as with matplotlib.pyplot).
- Draw lines :
- User must not have any toolbar item selected in order to annotate the spectrogram.
- Left-click on a name in the listbox to activate annotation with it.
- Left-click to place a point from the selected category.
- Right-click to remove the nearest point from the selected category.
- Mouse wheel click on a point to move it around.
- Click on
Open file explorer
Button to change Wavefile used as base (will end the annotation of the current file). - Change resolution of the spectrogram with
FFT
,Hop length
andclipping fields
. - Click on
Update display
button to validate inputs. - Click on
Switch to PCEN
to switch between PCEN and spectrogram image.
Re-use data
To load and display the saved annotations, use the "Results" object. It contains several infos: coordinates of the annotations, spectrogram, waveform and more.
Open a terminal window in PyAVA folder and run the following lines with Python to see an exemple of use:
import os
import json
from post_annotation import Results # load functions
# load object with annotation data
annot_data = Results(os.path.join(
".",
"audio_examples",
"SCW1807_20200713_064554.wav"),
os.path.join(
".",
"outputs",
"SCW1807_20200713_064554-contours.json"))
print(json.dumps(annot_data.coords, indent=4)) # show file content
# display annotations
annot_data.display_contours() # or annot_data.display_contours(img="pcen")
To modify previous annotations, run the following line (using annotations on file SCW6070_20220717_174215.wav as an example):
$python PyAVA_V2.py --modify SCW6070_20220717_174215-contours.json SCW6070_20220717_174215.wav
Support
Please contact me for any question and/or idea.