BirdBox is a comprehensive system for detecting and evaluating bird calls in audio recordings using deep learning. It leverages YOLO (You Only Look Once) object detection on spectrogram images to identify and localize bird vocalizations in time and frequency.
⚠️ Note: This project is still under active development. Performance may vary.
Scope¶
This code repository focuses on model inference and post-processing for bioacoustic event detection. Additionally, one can evaluate the performance of the model inference with ground truth annotations. Metrics like precision, recall, F\(\beta\) and confusion matrices are already implemented and ready to go.
What's not covered here is the model training. For this see BirdBox-Train (currently only available from within the BirdNET-Team).
Example Detection¶
The image shows 15 seconds of a soundscape from Hawai'i (tests/test.wav, 195 to 210 s) as the model sees it: the log-floor mel spectrogram from 50 Hz to 15 kHz.
The boxes are the detections of Just-Bird with the default settings, each with its confidence. Each box localizes a call or a phrase in time and frequency.

Spectrogram Not Stored
The inference software takes in audio files and outputs detections in various formats. The spectrogram is computed internally but never written to disk unless explicitly visualized.
Key Features¶
- Browser Demo - Runs Just-Bird or Birds-With-Labels in the browser, with no installation
- Multiple Audio Formats - Supports WAV, FLAC, OGG, MP3 (WAV/FLAC recommended for best results)
- Arbitrary-Length Audio Processing - Handle audio from seconds to hours
- Window Fusion and Song Reconstruction - Merge the boxes of overlapping windows into calls or phrases (Just-Bird) and adjacent detections into continuous songs (Birds-With-Labels)
- Batch Processing - Process entire directories of audio files
- Log-Floor Spectrograms - Log power above each band's noise floor, independent of the recording level
- Comprehensive Evaluation - F-beta analysis, confusion matrices, optimal threshold finding
- Multiple Output Formats - JSON with algorithm metadata, simplified CSV, xeno-canto Annota-JSON and Raven Selection Table
- Multiple Model Formats - Works with
.pt,.onnx,.tfliteand.enginemodel formats
Quick Links¶
- Installation - set up the environment
- Demo - BirdBox in your browser
- How it works - pipeline and demo description
- Data In/Out - datasets and output-format descriptions
- Models and Metrics - list of models with corresponding metrics
- CLI Reference - command line interface
- API Reference - application programming interface
- GitHub Repository
License¶
BirdBox's own source code is licensed under the MIT License.
BirdBox is built on Ultralytics YOLO11, which is licensed under the AGPL-3.0. Ultralytics also treats models trained or fine-tuned with it as AGPL-3.0, so the BirdBox model weights (.pt and every exported format) are AGPL-3.0 as well. As a result, the project as a whole is subject to the AGPL-3.0:
- Using BirdBox with Ultralytics or the BirdBox models (running, redistributing, or offering it over a network) has to comply with the AGPL-3.0. If you modify it and let users interact with it over a network, you must offer them its source code.
- Reusing BirdBox's own code on its own, in a project that uses neither Ultralytics nor the BirdBox models, is possible under the MIT terms.
A few files are under other licenses (a function adapted from librosa, xeno-canto audio samples, AviList-derived taxonomy data). See NOTICE.md for the full breakdown.