Spektrogrammannotation: Zeit-Frequenz-Boxen auf Audio

In Potato beschriftete Zeit-Frequenz-Boxen auf ein Spektrogramm zeichnen, für Rufe von Vögeln, Fledermäusen, Fröschen und Meeressäugern, mit Export nach Raven und Audacity.

Neu in v2.12.0

Ein Schema vom Typ spectrogram_annotation zeigt ein Spektrogramm des Audios eines Items. Annotatoren zeichnen Zeit-Frequenz-Boxen darauf und geben jeder Box ein Label aus der Liste des Schemas, etwa Arten oder Ruftypen. Es ist für die Bioakustik gedacht: Rufe von Vögeln, Fledermäusen, Fröschen und Meeressäugern, bei denen ein Ruf dadurch beschrieben wird, wann er beginnt und endet und welchen Frequenzbereich er hat.

Die Audio-Annotation markiert Segmente nur in der Zeit. Verwenden Sie spectrogram_annotation, wenn der Frequenzbereich jedes Ereignisses wichtig ist oder wenn Sie Boxen aus Raven, Audacity oder BirdNET-Analyzer importieren (Bioakustik).

Das Spektrogramm wird im Browser berechnet: Die Seite dekodiert das Audio mit Web Audio und führt eine Kurzzeit-Fourier-Transformation mit einer Spalte pro Pixel der Zeichnung aus. Es wird keine Bibliothek von Drittanbietern geladen, und der Server braucht keine Audiowerkzeuge.

Konfiguration

yaml

item_properties:
  id_key: id
  text_key: recording
 
annotation_schemes:
  - annotation_type: spectrogram_annotation
    name: calls
    description: Draw a box around every call and label it
    source_field: audio_url
    labels:
      - name: Turdus migratorius
        color: "#2563eb"
      - name: Cardinalis cardinalis
        color: "#dc2626"
      - unknown
    max_freq: 12000

json

{"id": "site3_0612", "recording": "site3_0612.wav", "audio_url": "/media/site3_0612.wav"}

source_field nennt das Item-Feld, das die Audio-URL enthält, und Dateien im Ordner media/ des Projekts werden unter /media/<name> ausgeliefert. Jedes Format, das der Browser dekodieren kann, funktioniert (WAV, FLAC, MP3, Ogg, M4A). Bei einer WAV-Datei liest die Seite die Abtastrate aus dem Dateiheader, sodass die Frequenzachse bei der Nyquist-Frequenz der Aufnahme selbst endet. Bei anderen Formaten geben Sie die Rate in einem Item-Feld namens sample_rate an, sonst wird die eigene Rate des Browsers verwendet.

Schlüssel	Standard	Bedeutung
`labels`	erforderlich	Labelnamen oder Objekte `{name, color, key_value}`. Die Labels 1 bis 9 erhalten die Tasten `1` bis `9`, sofern `key_value` keine andere Taste festlegt
`source_field`	`audio_url`	Item-Feld mit der Audio-URL
`min_freq`	`0`	Niedrigste angezeigte Frequenz in Hz
`max_freq`	Nyquist-Frequenz	Höchste angezeigte Frequenz in Hz
`fft_size`	`1024`	Länge des FFT-Fensters in Samples: 256, 512, 1024, 2048 oder 4096. Größere Fenster lösen die Frequenz feiner und die Zeit gröber auf
`colormap`	`viridis`	`viridis`, `magma` oder `grayscale`
`height`	`280`	Höhe des Spektrogramms in Pixeln
`min_boxes`	`0`	Boxen, die nötig sind, bevor das Item als erledigt gilt
`max_boxes`	keiner	Höchstzahl der Boxen auf einem Item
`label_requirement`	keiner	`required: true` lässt das Schema als unbeantwortet gelten, bis der Annotator es einmal gespeichert hat. Speichern ohne Boxen zählt als Antwort; verlangen Sie Boxen daher mit `min_boxes`

Bedienung

Aktion	Maus oder Touch	Tastatur (Fokus im Widget)
Eine Box zeichnen	Auf leerem Spektrogramm ziehen	`N` fügt an der Wiedergabeposition eine Box hinzu
Das Label für neue Boxen wählen	Auf eine Label-Schaltfläche klicken	`1` bis `9`
Eine Box umbenennen	Auswählen, dann auf eine Label-Schaltfläche klicken oder ihr Menü in der Liste verwenden	Auswählen, dann `1` bis `9`
Eine Box verschieben	Ziehen	Pfeiltasten
Die Größe einer Box ändern	An ihrer oberen linken oder unteren rechten Ecke ziehen	`Shift` und die Pfeiltasten
Eine Box löschen	Delete in der Liste	`Delete` oder `Backspace`
Abspielen oder pausieren	Wiedergabeschaltfläche	`Space`
Eine einzelne Box abspielen	Play in der Liste	`P`
In der Zeit zoomen	Schaltflächen `+` und `-`, bis 16×

Die Liste unter dem Spektrogramm zeigt jede Box mit ihren Zeiten und Frequenzen, einem Label-Menü und den Schaltflächen Play und Delete. Eine aus einem Detektor importierte Box wird mit gestricheltem Rand und ihrer Konfidenz neben dem Label gezeichnet, bis jemand sie ändert.

Gespeicherte Antwort

json

[{"start_s": 0.5, "end_s": 1.1, "low_hz": 2900.0, "high_hz": 3100.0, "label": "whistle"},
 {"start_s": 3.0, "end_s": 3.8, "low_hz": 5900.0, "high_hz": 6600.0, "label": "trill",
  "source": "import", "import_format": "raven", "edited": true}]

Zeiten sind Sekunden ab Dateianfang, und Frequenzen sind Hz. low_hz und high_hz sind null für eine Box, die alle Frequenzen abdeckt, und so werden ein Audacity-Label ohne spektrale Auswahl oder eine Zeile einer BirdNET-CSV importiert. Boxen, die der Annotator zeichnet, erhalten "source": "human". Importierte Boxen behalten source, ai_model, confidence und import_format und erhalten "edited": true, sobald sie verschoben, in der Größe geändert oder umbenannt werden.

Vorannotationen verwenden dieselbe Liste, unter dem Schemanamen im Feld pre_annotation. Eine vorbelegte Box zählt als Antwort des Annotators: Klickt er auf Next, ohne einen Clip anzurühren, werden die Boxen als seine geprüfte Antwort ohne edited-Flag gespeichert, sodass eine Prüfstudie sie als unverändert akzeptiert zählen kann.

Export

Format	Ausgabe
`raven`	Eine Raven-Selection-Table pro Aufnahme, mit dem Label in einer Spalte `Annotation` (`--option label_column=Species` benennt sie um) und `Confidence`, wenn eine Box eine hat
`audacity_labels`	Eine Audacity-Labeldatei pro Aufnahme, mit einer spektralen Zeile unter jeder Box, die einen Frequenzbereich hat
`jsonl`, `csv` und die anderen allgemeinen Formate	Die JSON-Liste als Wert des Schemas

bash

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

Eine Box ohne Frequenzbereich wird nach Raven von 0 Hz bis zur Nyquist-Frequenz geschrieben, die aus sample_rate des Items, aus dem Header einer WAV-Datei oder aus max_freq stammt. Fehlt all das, bleibt High Freq (Hz) leer, und der Export gibt eine Warnung aus.

Die gesamte Datei wird im Browser dekodiert, und das Spektrogramm hat höchstens 4096 Spalten, sodass eine lange Aufnahme zeitlich grob gezeichnet wird. Schneiden Sie Aufnahmen in Clips von höchstens einigen Minuten.

Beispiel

bash

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

Weiterführende Informationen

Bioakustik - Raven-, Audacity- und BirdNET-Ausgaben importieren und korrigierte Boxen exportieren
Audio-Annotation - Zeitsegmente auf einer Wellenform
Kamerafallen - Die Bildseite des Wildtiermonitorings

Implementierungsdetails finden Sie in der Quelldokumentation.