Audio and Model Inputs¶
BirdBox reads field recordings and a trained YOLO weights file, then maps neural-network class IDs to species using a named mapping in src/config.py. This page documents the accepted formats for the --audio, --model, and --species-mapping inputs. For CLI flags, defaults, and invocation examples see the detect-birds reference.
Audio inputs¶
--audio may be a single file or a directory. Directories are searched recursively for supported files.
Supported extensions¶
| Extension | Recommended? | Notes |
|---|---|---|
.wav |
Yes | Lossless. Matches training data best. |
.flac |
Yes | Lossless. Fully supported. |
.ogg |
Use with care | Lossy. May reduce recall on faint or high-frequency calls. |
.mp3 |
Use with care | Lossy. Same caveat as OGG. |
Case is ignored (.WAV and .wav are both found).
Processing behavior¶
- Mono conversion: Stereo recordings are collapsed to mono before spectrogram generation.
- Arbitrary length: Clips are processed in overlapping windows.
- Batch mode: Point
--audioat a folder to process every supported file under it in one run.
Lossy audio formats
MP3 and OGG are supported via soundfile, but the models were trained on lossless WAV. In a study of avian recordings, MP3 compression reduced the detections of human listeners and automated recognisers [19]. If detections look weak on a compressed file, re-run the same recording as WAV or FLAC before tuning thresholds.
Model files¶
--model must point to a YOLO-compatible weights file loaded by Ultralytics. BirdBox supports four formats:
| Format | Typical use | Runtime |
|---|---|---|
.pt |
PyTorch checkpoint. Default for BirdBox releases. | PyTorch (CUDA or CPU) |
.onnx |
Cross-platform deployment. Quantized variants available. | ONNX Runtime (GPU or CPU) |
.tflite |
Edge devices and mobile targets. | LiteRT / ai-edge-litert (CPU) |
.engine |
Maximum throughput on NVIDIA GPUs. | TensorRT (NVIDIA GPU required) |
Pretrained releases on TUC-Cloud ship as .pt. Custom models can be trained with BirdBox-Train.
Each format requires its own Python environment. Install the correct runtime before switching formats.
Environment must match the model format
Loading a .tflite, .onnx, or .engine model from a .pt environment will fail with an import error or silently produce incorrect results. Run python install.py --model-format <FORMAT> to set up the right environment. See Install Parameters for the full format-to-runtime table.
Format parity
Detection quality of the .onnx and .tflite formats is validated by running inference on the same audio and comparing results against the .pt baseline. See Just-Bird format parity and Birds-With-Labels format parity for the current scores.
Platform restrictions
.engine files are compiled for a specific GPU architecture and TensorRT version. A model built on one card may not run on a different GPU generation, and it only loads in the TensorRT version that built it. Pass --model-format engine during installation to set up the pinned TensorRT runtime.
Species Mapping¶
The --species-mapping name must match the label space the model was trained on. It is not inferred from the weights filename. You pass it explicitly.
For specific mappings see SPECIES_MAPPING in src/config.py.
Allowed values for the species-mapping parameter:
| Value | Region / role |
|---|---|
Just-Bird |
Binary bird vs. background |
Birds-With-Labels |
Species-level model for all five regions |
Each key resolves to id_to_ebird, ebird_to_name, and display colors in src/config.py. The mapping name is stored in detection JSON as model_config.species_mapping.
Mapping must match the model
If --species-mapping does not match the model's training conf.yaml / class list, outputs will carry wrong eBird codes with no error. Always pair model file and mapping from the same release (e.g. Birds-With-Labels_fp32.pt with Birds-With-Labels).
References¶
[19] MacPhail, A. G., Yip, D. A., Knight, E. C., Hedley, R., Knaggs, M., Shonfield, J., Upham-Mills, E., & Bayne, E. M. (2024). "Audio data compression affects acoustic indices and reduces detections of birds by human listening and automated recognisers." Bioacoustics, 33(1):74–90.