# Bioacoustics in Potato: Reviewing Raven, Audacity and BirdNET Detections Source: https://www.potatoannotator.com/docs/guides/bioacoustics **Potato 2.12.0 checks and corrects time-frequency boxes on wildlife recordings when the boxes come from [Raven](https://www.ravensoundsoftware.com/), [Audacity](https://www.audacityteam.org/) or [BirdNET-Analyzer](https://github.com/birdnet-team/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 ```bash # 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 | Raven column | Potato | |---|---| | `Begin Time (s)`, `End Time (s)` | `start_s`, `end_s` | | `Low Freq (Hz)`, `High Freq (Hz)` | `low_hz`, `high_hz` | | `Selection`, `View` | Rows with the same selection number become one box, using the `Spectrogram` row | | `Channel` | Kept on the box when it is not 1 | | `Begin File` or `Begin Path`, `File Offset (s)` | The recording, and the start time within it, in a multi-file table | | `Confidence` | Kept on the box, and `--min-confidence` filters on it | | An annotation column | The label | 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 `startendlabel`. A label with a spectral selection is followed by a line that starts with a backslash, `\lowhigh`. 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 ```bash 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](/docs/annotation-types/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 ```bash 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. ```bash python potato/flask_server.py start examples/audio/bioacoustics-boxes/config.yaml -p 8000 ``` ## Further Reading - [Spectrogram Annotation](/docs/annotation-types/spectrogram-annotation) - Scheme options, controls and the stored answer - [Camera Traps](/docs/guides/camera-traps) - Reviewing MegaDetector output - [Audio Annotation Tools Compared](/docs/guides/audio-annotation-tools-compared) - Audio tools beside each other - [Importing Projects](/docs/tools/importing-projects) - Every format `potato import` reads For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/master/docs/guides/bioacoustics.md).