# `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 esay way to draw contours on vocalisations from audio recordings. It uses [Tkinter](https://docs.python.org/3/library/tkinter.html) for its graphical interface and can be run on any OS. It does not require images (aka spectrogram) to function, only waveforms, which is its main advantage to be an easy and efficient annotation tool.

![Show PyAVA](./images/PyAVA_show.gif?raw=true)


## Features

- [x] Spectrogram contour annotations. 
- [x] Spectrogram automatically computed from waveform.
- [x] Choose custom spectrogram resolutions (fft, hop length, clipping dB value and PCEN).
- [x] Select a new file directly from the interface.
- [x] Exportation of contours to local `.json`.
- [x] Move points once they are placed (with mouse wheel).
- [x] 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 run `$python PyAVA.py -dir myWavefileFolder -out myOutputFolder` in terminal.  
Run `$python PyAVA.py --help` for details.  

The annotations are saved in [JSON](http://www.json.org/) files. Each file contains a dict of contours. For each contour there is a list of points, each point is defined by a list of two elements : [time (in sec), frequency (in kHz)].

### User interaction
- Use the toolbar to interact with the plot. 
- User must not have any toolbar item selected in order to annotate the image.
- 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.
- Click on `Open file explorer` Button to change Wavefile (will end 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.

### 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:  
```python
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](mailto:loic.lehnhoff@gmail.com) for any question and/or idea.