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 and clipping 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.py --modify SCW6070_20220717_174215-contours.json SCW6070_20220717_174215.wav

Support

Please contact me for any question and/or idea.