The most basic configuration of BioacousticAnnotator is a simple Player / Visualizer.
BioacousticAnnotator(data='detections.csv', audio='recording.flac').open()Here we have used a CSV for the source data. We could similarly have provided a Parquet, or JSONL file path, an API-endpoit, a Database Query (using DuckDB), or have passed a dataframe directly. For audio we have passed a path to an audio file. For this example all the clips will come from the same file. You can also pass an audio_column so that each clip can be read from different audio file. The audio files can be local paths or be read over https://, s3://, and gs://.
For more advanced configurations it is suggested that to use a configurtion file.
Here’s a basic example:
description:
title: Annotation Instructions
text: "There are 4 types of annotations available:\n\n---\n\n- `time_select`: Single\
\ draggable vertical line\n- `start\\_end\\_time_select`: Two draggable vertical\
\ lines (constrained \u2014 can't cross)\n- `bounding\\_box`: Click+drag rectangle\
\ with individually draggable edges\n- `multibox`: Draw multiple bounding boxes,\
\ each with optional per-box form. Submits one row per box.\n- `fixed_duration`:\
\ Click to place a fixed-length time region. Duration is set in config."
open: false
display_columns:
- common_name
- scientific_name
- confidence
- rank
output:
index_column: detection_id
uri: s3://dse-soundhub/dev/annotations/simple-example-3.sync.csv
sync_button: Sync To S3
info_card_title: '[[common_name]]'
info_card_text: 'scientific_name: [[scientific_name]]'
capture: true
capture_dir: spectrograms
audio:
column: audio_url
data:
index_column: id
default_buffer: 0.5
form_config: annotator_config/forms/simple-examples-3.yaml
The data file itself is not in the config: it is set in the project file (annotator_config/projects/simple-examples-3.yaml) or passed in the notebook, so the same config can be reused across datasets and users. Because this config has a form, it sets the input’s index column (data: {index_column: id}).
FORM CONFIG
We could have included the form config directly, however seperating the form config allows different projects to use the same forms. Forms themeselves can range to a simple select-dropdown to multipart dynamic forms. Even the most complex forms however are easy to configure.
Here we create a “species” select list populated with values from a csv:

form:
- select:
label: species
column: common_name
required: true
items:
path: data/species_counts.N-dse.csv
value: common_nameAdditional functionality is easily added. The config below, again creates a “species” select list but now adds a filter box, an Unknown-option and the ability to add custom-values:
form:
- select:
label: species
column: common_name
required: true
items:
path: data/species_counts.N-dse.csv
value: common_name
filter_box: true
custom_value: true
not_available:
label: Unknown Species
value: unknownThe following configuration below adds a custom title and a progress-tracker, passes the source id to the output dataset with name detection_id, and asks the user if the model has correctly identified the species.
title:
value: REVIEW DETECTION
progress_tracker: true
pass_value:
source_column: id
column: detection_id
form:
- select:
label: Is [[common_name]] Valid?
column: is_valid
required: true
items:
- label: 'yes'
value: 'yes'
form: confirmed_form
- label: 'no'
value: 'no'
form: rejected_form
dynamic_forms:
confirmed_form:
- select:
label: confidence
column: reviewer_confidence
items:
- low
- medium
- high
- textbox:
label: notes
column: notes
rejected_form:
- select:
label: corrected species
column: corrected_common_name
required: true
items:
path: data/species_counts.N-dse.csv
value: common_name
filter_box: true
custom_value: true
not_available:
label: Unknown Species
value: unknown
- select:
label: rejection reason
column: rejection_reason
required: true
items:
- noise
- wrong species
- overlapping signals
- too faint
- other
- number:
label: signal quality (1-5)
column: signal_quality
min: 1
max: 5
step: 1
- checkbox:
label: flag for expert review
column: flagged
- textbox:
label: notes
column: notes
multiline: true
submission_buttons:
line: true
next:
label: Skip
submit:
label: Verify
If the response is yes the confirmed_form allows for the user to add additional detials.

If the response is no the rejected_form allows the user to select the correct species, ask for a review, etc.

Additional examples are given in the Customizable Forms section.