Repository navigation
BirdBox 2.1 replaces PCEN with log-floor spectrograms and takes each window's noise floor from the 60 s before its end, so boxes are final as soon as the audio reaches them. Both models are retrained: a new Just-Bird with tighter call boxes, and Birds-With-Labels with 351 more species from Bird-Sounds-Global (633 classes).
The models of 2.0 were trained on PCEN spectrograms and do not run correctly with 2.1. Use the weights of this release. See Upgrading from 2.0 below.
Just-Bird performance
As for 2.0, the recipe was trained without the Southern Sierra Nevada dataset and run on its full recordings, a site it has never seen. The recipes of the two previous models were retrained and tested the same way.
| Event F1 on the unseen site | IoU 0.25 | IoU 0.5 | IoU 0.75 | IoU 0.5 at the threshold chosen on Hawai'i val |
|---|---|---|---|---|
| 2.1 (November 2026) | 0.568 | 0.387 | 0.127 | 0.385 |
| 2.0 (October 2026) | 0.541 | 0.384 | 0.116 | 0.383 |
| 1.0 (March 2026) | 0.465 | 0.281 | 0.059 | 0.250 |
The gain is where the fit of a box counts: +0.009 at IoU 0.75 at the threshold chosen on Hawai'i val (95% interval +0.000 to +0.016; +0.011 between the best values in the table) and +0.027 at IoU 0.25, while IoU 0.5 ties. It comes from new training labels: a call-sized human box is kept when a teacher box covers at least half of it, and of two nested label boxes only the larger one is kept. On song-labelled Western-US validation minutes, which no model trained on, F1 at IoU 0.5 rises from 0.171 to 0.230 (each model at its best threshold, phrase gap off).
On the Hawai'i validation recordings the new model scores lower at IoU 0.5 (0.570 against 0.593) and ties at IoU 0.75. That is the price of a spectrogram that no longer changes with the recording level: the 2.0 model used the level to tell faint, mostly unlabelled background calls from the labelled ones. Details: Just-Bird.
The default confidence stays 0.15 and the phrase gap 0.05 s.
Highlights
- Log-floor spectrograms. Each mel band's level in dB above its noise floor, the 20th percentile of the band, mapped from −3 to 45 dB. The picture no longer depends on how loud a recording is. Python inference, the ONNX graph and the demo compute it the same way. Spectrogram Generation
- Rolling noise floor. Each window's floor is taken over the 60 s up to its end, on one frame grid for the whole file. No audio after a window changes its boxes, so a recording can be analysed while it runs. The JSON output states the floor (
model_config.floor_window_seconds). - Birds-With-Labels with 633 classes. The 281 regional species, 351 species from Bird-Sounds-Global (annotated xeno-canto soundscapes) and the unknown class
????, trained on log-floor spectrograms with the rolling floor. Macro F1 at IoU 0.25 on the test splits of both, 516 species: 0.407, against 0.170 for the 282-class model retrained on log-floor spectrograms. On the five regional datasets alone it is 0.018 lower (0.523 against 0.540). Birds-With-Labels - Steadier window fusion. A larger phrase gap no longer splits a box in two or joins boxes in neighbouring bands, and boxes in one band no longer overlap: the phrase join uses the same frequency rule as the call join (IoU 0.8), boxes are linked pairwise, and nested boxes are dropped before the join. Scores stay within 0.002.
- Demo. Boxes appear while a file runs and while you record, and boxes that the next windows can still change are drawn dashed. A stopped detection can be continued. The progress line shows the speed in real time, and the noise floor is computed in the page, which makes detection up to 17% faster.
- Documentation. How It Works is split into Overview, Inference and Demo. New pages explain the demo's two spectrograms (STFT and log-floor) and how to add a model to the demo, and Species from BirdNET shows how to name the species of Just-Bird's boxes with BirdNET V3.0.
Upgrading from 2.0
- Model files: download the weights of this release (below or from the TUC-Cloud). The 2.0 weights expect PCEN spectrograms, which 2.1 no longer computes. The file names and
--species-mappingvalues stay the same. - Birds-With-Labels mapping: ids 0–281 keep their species, ids 282–632 are the new Bird-Sounds-Global species.
--species-mapping Birds-With-Labelsserves the new model. - Demo graphs: an ONNX graph exported with 2.0 has no rolling floor, and the demo refuses it. Export it again with
src/inference/onnx_export.py. - Results change with the new spectrogram, the new models and the rolling floor.
BIRDBOX_FLOOR_WINDOW=segmentstill takes the floor over each 60 s segment, for comparisons with log-floor results made that way. It is deprecated and will be removed in a later release.
Model files
The weights for this release are attached below as assets, so v2.1.0 stays tied to exactly these files. They are the same files as on the TUC-Cloud at the time of release, which may be updated later. The format parity results in the docs were measured on these files.
| Model | .pt |
.onnx |
.tflite |
|---|---|---|---|
| Just-Bird (recommended) | Just-Bird_fp32.pt |
Just-Bird_fp16.onnx, Just-Bird_int8.onnx |
Just-Bird_fp16.tflite, Just-Bird_int8.tflite |
| Birds-With-Labels | Birds-With-Labels_fp32.pt |
Birds-With-Labels_fp16.onnx, Birds-With-Labels_int8.onnx |
Birds-With-Labels_fp16.tflite, Birds-With-Labels_int8.tflite |
Save the files in models/. SHA256SUMS.txt lists the checksum of every model file; check a download with sha256sum -c SHA256SUMS.txt --ignore-missing. TensorRT .engine files are not included, because they only run on the GPU and TensorRT version they were built for.
The weights are licensed under the AGPL-3.0 (LICENSE-AGPL-3.0, NOTICE.txt).
Training pipeline and recipe for these weights: BirdBox-Train v2.1.0.
Full changelog: v2.0.0...v2.1.0