Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Parameters & Configuration

Authors
Affiliations
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley

All parameters can be passed directly to BioacousticAnnotator() or set in a YAML/JSON config file. The config file and constructor signature are the same — a config file is equivalent to BioacousticAnnotator(**yaml.safe_load(open('config.yaml'))).

Data

The data parameter specifies where input rows come from. The source type is auto-detected from the string:

PatternSource
Contains SELECTSQL query (DuckDB)
Starts with api::API endpoint
Starts with http://, s3://, etc.URL / URI
Everything elseLocal file path (.csv, .parquet, .json, .jsonl)
BioacousticAnnotator(data='data/detections.csv', audio='audio_path')  # CSV, Parquet, JSON

DataFrame

df = pd.read_csv('data/detections.csv')
BioacousticAnnotator(data=df[df.confidence > 0.8], audio='audio_path')

SQL

BioacousticAnnotator(
    data="SELECT * FROM 'data/detections.parquet' WHERE common_name = 'Tree Swallow'",
    audio='audio_path',
)  # needs duckdb

Dict form

For explicit control over the source type, secrets, and columns:

BioacousticAnnotator(
    data={'path': 'data/detections.csv', 'index_column': 'id',
          'columns': ['id', 'common_name', 'start_time', 'end_time', 'audio_path']},
    audio='audio_path',
)

In YAML:

data:
  path: data/annotate-data.csv
  index_column: id
  columns: [common_name, confidence, start_time, end_time]
  secrets:
    - key: Authorization
      value: env:API_TOKEN

Top-level overrides

data_path, data_url, data_sql, data_api override the source while keeping other settings in a dict or config file. data_value + data_source_type does the same with the type given explicitly.

Index column

data_index_column (or data: {index_column: ...}) names the column that uniquely identifies each input row. It is required whenever a form is configured, because each output row is linked back to its input row through it. output_index_column (or output: {index_column: ...}) renames that column in the output; it defaults to data_index_column.

Time columns

By default, the widget expects start_time and end_time columns. Use data_start_time, data_end_time to rename them, or data_duration (column name or fixed number) to compute end times:

# 3-second clips starting at `offset`
BioacousticAnnotator(data=df, audio='audio_path', data_start_time='offset', data_duration=3)

Secrets

data_secrets provides authentication. Values can be env:VAR_NAME, dialog (interactive prompt), or literal strings. A global secrets parameter serves as fallback for both data_secrets and audio_secrets.

Audio

The audio parameter specifies where audio files come from. Auto-detected from the string:

PatternSource
Starts with http://, s3://, gs://URL / URI
No / and no .Column name (per-row audio)
Everything elseLocal file path

audio_prefix and audio_suffix are joined with /. audio_fallback provides a default when using column mode with empty values.

Dict form

audio:
  column: audio_path
  prefix: audio
  fallback: audio/default.flac

Audio from SQL/API

Use audio_sql or audio_api with audio_property to resolve the audio path dynamically at init time.

Partial byte-range downloads

Remote FLAC and WAV audio (S3, HTTPS, GCS) is read by byte range by default: only the header and the bytes of the clip being played are fetched, so multi-hour recordings load in seconds. Other formats, or a range read that fails, fall back to downloading and caching the full file. Disable partial downloads with partial_download=False. No ffmpeg is needed.

Forms

The form_config parameter drives the entire form layout. It can be a Python dict, a YAML file path, or embedded in the main config file. Input elements are placed inside a form: list, while structural elements remain at the top level.

Elements

Top-level elements

ElementDescriptionKey fields
titleSection header. String or {value, progress_tracker}; supports [[column]] templatesvalue, progress_tracker
pass_valueCopies a column from input to outputsource_column, column
fixed_valueConstant value in every output rowcolumn, value
annotationSpectrogram interaction toolsstart_time, end_time, min_frequency, max_frequency, tools, form
submission_buttonsSubmit, Skip, Prev buttons; false for none (submit with a button)submit, next, previous
dynamic_formsList of conditional form sections- name: [elements]
side_formtrue: the form beside the spectrogram (draggable divider)side_form_split (spectrogram’s share, default 2/3)

Input elements (inside form: list)

ElementDescriptionKey fields
selectDropdown. Items from inline list, file, or range. Supports form: for conditional sections, filter_box, custom_value, not_availablelabel, column, required, items, width
textboxText input. multiline: true for textarealabel, column, default, multiline
checkboxBoolean. checked_value/unchecked_value for custom values. checked_form/unchecked_form for conditional sectionslabel, column, checked_value, unchecked_value, checked_form, unchecked_form
numberNumeric inputlabel, column, min, max, step
multiselectSeveral labels (tags) per clip; same items as selectlabel, column, items, min, max, output
buttonButton: writes a value, cycles toggle states, and/or submits. jba: built-in iconsicon / image, column, value, submit, toggle, initial_value, pressed_*, hot_key, size
row / column / gridLayout containers (nestable); column / unique / delimiter group the buttons insideitems, columns (grid), gap, align
breakVisual break(no fields)
lineHorizontal line(no fields)
textStatic textvalue

Conditional sections (dynamic_forms)

Select items and checkboxes can trigger conditional form sections. dynamic_forms is a list of named form sections:

form:
    - select:
          label: Is Valid
          column: is_valid
          items:
              - label: 'yes'
                value: 'yes'
              - label: 'no'
                value: 'no'
                form: correction
    - checkbox:
          label: needs review
          column: needs_review
          checked_form: review_form
dynamic_forms:
    - correction:
          - select:
                label: corrected species
                column: corrected_name
                items:
                    path: categories.csv
                    value: common_name
    - review_form:
          - textbox:
                label: reason
                column: review_reason

Annotation tools

ToolInteractionFields
time_selectSingle draggable linestart_time
start_end_time_selectTwo constrained linesstart_time, end_time
bounding_boxDraggable rectanglestart_time, end_time, min_frequency, max_frequency
multiboxMultiple labeled boxesSame + per-box form via annotation.form
fixed_durationClick to place a fixed-length regionstart_time, end_time; length: a number, {window}, or user-editable {initial_window, min, max, step}

Select item features

FeatureDescription
filter_box: trueAdds a text filter input next to the dropdown
custom_value: trueShows “+ Add” button when no exact match
not_available: truePrepends a fallback option (string or {label, value} dict)
selected::valuePrefix to mark the default selection
hot_keys: {1: owl}On the select (not items): keys that pick an item while the select has keyboard focus
pin_hot_keys: trueOn the select: list the hot-keyed items first, in a “hot keys” group

Other Parameters

ParameterDefaultDescription
projectNoneProject file path or dict. No other config params allowed when set.
info_card_title''Info card title — supports [[column_name]] and [[kwarg_name]] templates. Used for capture filenames
project_nameNoneWidget header title. Auto-derived from project filename if not set.
info_card_text''Info card text — supports [[column_name]] and [[kwarg_name]] templates
display_columns[]Columns for the clip table
sortNoneColumn to sort the clip table by (None = input/file order)
sort_order'asc'Sort direction when sort is set ('asc' or 'desc')
duplicate_entriesFalseAllow multiple submissions per row. When False, re-submitting a clip replaces its earlier entry
default_buffer3Buffer time in seconds
captureTrueCapture button (False to hide, string for label)
capture_dir''Directory for captures
capture_heightNoneCapture image height in pixels. Defaults to player_height if not set
spectrogram_resolution[1000, 2000, 4000]Image width(s) in px. selected:: prefix for default
visualizations['linear', 'mel']Built-in strings or callables
partial_downloadTrueByte-range reads for remote FLAC/WAV audio (False = always download the full file)
width'100%'Inline widget width
clip_table_height175Clip table height (px)
player_height260Player/spectrogram height (px). Sets spectrogram resolution height.
info_card_height34Info card height (px)
hide_info_cardFalseHide the info card
playlist_title, spectrogram_titleFalseText after the section’s collapse chevron (True = standard name, or a string)
playlist_open, spectrogram_open, form_openTrueWhether each section starts expanded
freq_min, freq_maxNoneFrequency window (kHz) the spectrogram opens with and Reset returns to
form_panel_height175Form panel height (px)
output''Output file path, or {path, uri, sync_button, recursive, secrets, index_column}. Auto-generated (outputs/annotation_output-<timestamp>.csv) if a form is configured
descriptionNoneCollapsible description panel: markdown text, a .md path, or {title, text, path, open, height}
session_argsNoneWhich extra **kwargs are allowed: a list of names, one name as a string, True (all) or False (none)
configNonePath to YAML/JSON config file