Bioacoustics in Potato: Reviewing Raven, Audacity and BirdNET Detections

Potato 2.12.0 checks and corrects time-frequency boxes on wildlife recordings when the boxes come from Raven, Audacity or BirdNET-Analyzer. You import the tables with their recordings, annotators correct the boxes on a spectrogram in a spectrogram_annotation scheme, and the corrected boxes export back to Raven or Audacity.

Potato reads BirdNET's output and does not run BirdNET. The BirdNET models are licensed CC BY-NC-SA and are not distributed with Potato. Run BirdNET-Analyzer yourself and import what it writes.

Import the tables

# A folder of Raven selection tables with the recordings beside them
potato import -i recordings/ -o review-project/
 
# BirdNET-Analyzer output, keeping detections with confidence 0.5 or more
potato import -i birdnet-output/ -f birdnet --min-confidence 0.5 -o review-project/
 
# One Audacity label file (site3_0612.txt next to site3_0612.wav)
potato import -i site3_0612.txt -f audacity_labels -o review-project/

-i is one table or a folder of them. The format is detected from the content, and -f raven, -f audacity_labels or -f birdnet chooses explicitly.

Each recording becomes one item, copied into the project's media/ folder, and every row of its table becomes a box pre-annotation, so annotators open the clip with the boxes drawn. A table is matched to its recording by name: site3_0612.Table.1.selections.txt, site3_0612.BirdNET.selection.table.txt, site3_0612.BirdNET.results.csv and site3_0612.txt all belong to site3_0612.wav (or .flac, .mp3, .ogg, .m4a, .aac, .opus, .webm). A table that covers several recordings names them in a Begin File, Begin Path or File column, and its rows are split by that column.

The generated scheme's labels are the labels found in the tables. Add the rest of your species or call-type list to labels in config.yaml, so annotators can label calls the source missed.

Raven selection tables

The label comes from --label-column NAME when given. Otherwise it comes from the first of Annotation, Species, Label, Class, Scientific Name, Common Name, Species Code, Call Type, Type and Sound Type that the table has. A row with an empty label is labelled call.

Audacity label tracks

Each line is start<TAB>end<TAB>label. A label with a spectral selection is followed by a line that starts with a backslash, \<TAB>low<TAB>high. Labels without that line, point labels included, become boxes over all frequencies.

BirdNET-Analyzer output

Both of BirdNET-Analyzer's table formats are read. The Raven selection table (*.BirdNET.selection.table.txt) is labelled with its Scientific Name column when it has one, otherwise Common Name. The CSV (*.BirdNET.results.csv) is labelled with the scientific name, and its rows have no frequency range, so they import as boxes over all frequencies. --label-column "Common name" (CSV) or --label-column "Common Name" (Raven table) uses common names instead.

Rows below --min-confidence (default 0.1) are left out, and the import summary says how many. BirdNET boxes are stored with "source": "ai", "ai_model": "BirdNET" and their confidence, and the page draws them with a dashed border until an annotator changes them.

A row whose time is not a number, such as 3,5 written with a decimal comma, is left out with a warning that names the file, the line and the value. A row whose end time comes before its start is kept with the two times swapped, and a negative frequency is dropped from the box.

Review the boxes

python potato/flask_server.py start review-project/config.yaml -p 8000

Annotators move, resize, relabel and delete boxes, and draw the calls that were missed. Spectrogram Annotation lists the controls. An imported box gets "edited": true once it is changed, so the export can tell boxes a reviewer accepted from boxes they corrected. Clicking Next on a clip without changing anything saves its imported boxes as the reviewer's answer, accepted unchanged.

Export back to Raven or Audacity

python -m potato.export -c review-project/config.yaml -f raven -o export/
python -m potato.export -c review-project/config.yaml -f audacity_labels -o export/

raven writes one selection table per recording, with Selection, View, Channel, Begin Time (s), End Time (s), Low Freq (Hz), High Freq (Hz), the label column (Annotation, or --option label_column=Species) and Confidence when any box has one. audacity_labels writes one label file per recording, with a spectral line for every box that has a frequency range. Both name the file after the recording, so with the audio beside them they open in Raven or Audacity and can be imported into Potato again. With several annotators the annotator's name is added to the file name, and --option annotator=anna exports one person.

Example

examples/audio/bioacoustics-boxes/ has two synthetic 6-second recordings with tones and frequency sweeps at known times and frequencies, imported from the Raven tables in its source/ folder. The tables have two mistakes to fix: one recording is missing a downsweep, and in the other a trill is labelled a whistle.

python potato/flask_server.py start examples/audio/bioacoustics-boxes/config.yaml -p 8000

Further Reading

• Spectrogram Annotation - Scheme options, controls and the stored answer
• Camera Traps - Reviewing MegaDetector output
• Audio Annotation Tools Compared - Audio tools beside each other
• Importing Projects - Every format potato import reads

For implementation details, see the source documentation.