Anotación de espectrogramas: rectángulos de tiempo-frecuencia sobre audio

Dibuja rectángulos de tiempo-frecuencia etiquetados sobre un espectrograma en Potato para llamadas de aves, murciélagos, ranas y mamíferos marinos, con exportación a Raven y Audacity.

Nuevo en v2.12.0

Un esquema spectrogram_annotation muestra un espectrograma del audio del ítem. Los anotadores dibujan sobre él rectángulos de tiempo-frecuencia y dan a cada rectángulo una etiqueta de la lista del esquema, como especies o tipos de llamada. Está pensado para la bioacústica: llamadas de aves, murciélagos, ranas y mamíferos marinos, donde una llamada se describe por cuándo empieza y termina y por su rango de frecuencias.

La anotación de audio marca segmentos solo en el tiempo. Usa spectrogram_annotation cuando importa el rango de frecuencias de cada evento, o cuando importas rectángulos de Raven, Audacity o BirdNET-Analyzer (Bioacústica).

El espectrograma se calcula en el navegador: la página decodifica el audio con Web Audio y ejecuta una transformada de Fourier de tiempo corto con una columna por píxel del dibujo. No se carga ninguna biblioteca de terceros, y el servidor no necesita herramientas de audio.

Configuración

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 nombra el campo del ítem que contiene la URL del audio, y los archivos de la carpeta media/ del proyecto se sirven en /media/<name>. Funciona cualquier formato que el navegador pueda decodificar (WAV, FLAC, MP3, Ogg, M4A). Para un archivo WAV, la página lee la frecuencia de muestreo de la cabecera del archivo, así que el eje de frecuencias termina en la frecuencia de Nyquist de la propia grabación. Para otros formatos, indica la frecuencia en un campo del ítem llamado sample_rate; si no, se usa la del propio navegador.

Clave	Valor por defecto	Significado
`labels`	obligatorio	Nombres de etiqueta, u objetos `{name, color, key_value}`. Las etiquetas 1 a 9 reciben las teclas `1` a `9` salvo que `key_value` fije otra tecla
`source_field`	`audio_url`	Campo del ítem que contiene la URL del audio
`min_freq`	`0`	Frecuencia más baja que se muestra, en Hz
`max_freq`	Frecuencia de Nyquist	Frecuencia más alta que se muestra, en Hz
`fft_size`	`1024`	Longitud de la ventana de la FFT en muestras: 256, 512, 1024, 2048 o 4096. Las ventanas más grandes resuelven la frecuencia con más detalle y el tiempo con menos
`colormap`	`viridis`	`viridis`, `magma` o `grayscale`
`height`	`280`	Altura del espectrograma en píxeles
`min_boxes`	`0`	Rectángulos necesarios para que el ítem cuente como terminado
`max_boxes`	ninguno	Máximo de rectángulos permitidos en un ítem
`label_requirement`	ninguno	`required: true` hace que el esquema cuente como sin responder hasta que el anotador lo haya guardado una vez. Guardar sin rectángulos cuenta como respuesta, así que usa `min_boxes` para exigir rectángulos

Controles

Acción	Ratón o pantalla táctil	Teclado (con el foco en el widget)
Dibujar un rectángulo	Arrastrar sobre una zona vacía del espectrograma	`N` añade un rectángulo en la posición de reproducción
Elegir la etiqueta de los rectángulos nuevos	Hacer clic en un botón de etiqueta	`1` a `9`
Reetiquetar un rectángulo	Seleccionarlo y hacer clic en un botón de etiqueta, o usar su menú en la lista	Seleccionarlo y pulsar `1` a `9`
Mover un rectángulo	Arrastrarlo	Flechas
Redimensionar un rectángulo	Arrastrar su esquina superior izquierda o inferior derecha	`Shift` y las flechas
Eliminar un rectángulo	Delete en la lista	`Delete` o `Backspace`
Reproducir o pausar	Botón de reproducción	`Space`
Reproducir un rectángulo	Play en la lista	`P`
Zoom en el tiempo	Botones `+` y `-`, hasta 16×

La lista bajo el espectrograma muestra cada rectángulo con sus tiempos y frecuencias, un menú de etiquetas y los botones Play y Delete. Un rectángulo importado de un detector se dibuja con un borde discontinuo y su confianza junto a la etiqueta hasta que alguien lo modifica.

Respuesta guardada

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}]

Los tiempos son segundos desde el inicio del archivo, y las frecuencias están en Hz. low_hz y high_hz son null en un rectángulo que abarca todas las frecuencias, que es como se importan una etiqueta de Audacity sin selección espectral o una fila de un CSV de BirdNET. Los rectángulos que dibuja el anotador reciben "source": "human". Los rectángulos importados conservan source, ai_model, confidence e import_format, y reciben "edited": true en cuanto se mueven, se redimensionan o se reetiquetan.

Las preanotaciones usan la misma lista, bajo el nombre del esquema en el campo pre_annotation. Un rectángulo rellenado previamente cuenta como respuesta del anotador: si hace clic en Next sin tocar un clip, los rectángulos se guardan como su respuesta revisada sin la marca edited, así que un estudio de revisión puede contarlos como aceptados sin cambios.

Exportación

Formato	Salida
`raven`	Una tabla de selección de Raven por grabación, con la etiqueta en una columna `Annotation` (`--option label_column=Species` le cambia el nombre) y `Confidence` cuando un rectángulo la tiene
`audacity_labels`	Un archivo de etiquetas de Audacity por grabación, con una línea espectral bajo cada rectángulo que tiene rango de frecuencias
`jsonl`, `csv` y los demás formatos generales	La lista JSON como valor del esquema

bash

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

Un rectángulo sin rango de frecuencias se escribe en Raven desde 0 Hz hasta la frecuencia de Nyquist, tomada del sample_rate del ítem, de la cabecera de un archivo WAV o de max_freq. Sin ninguno de ellos, High Freq (Hz) se deja vacío y la exportación muestra una advertencia.

El archivo entero se decodifica en el navegador, y el espectrograma tiene como mucho 4096 columnas, así que una grabación larga se dibuja con poca resolución temporal. Corta las grabaciones en clips de unos pocos minutos o menos.

Ejemplo

bash

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

Lecturas adicionales

Bioacústica - Importar la salida de Raven, Audacity y BirdNET y exportar los rectángulos corregidos
Anotación de audio - Segmentos temporales sobre una forma de onda
Cámaras trampa - La parte de imagen del seguimiento de fauna

Para detalles de implementación, consulta la documentación fuente.