Skip to content

Troubleshooting

This section provides information for typical mistakes one can make when interacting with BirdBox.

No Detections

If BirdBox returns an empty results file, the most common cause is a model/mapping mismatch or a threshold that is set too high for exploratory work.

  • Verify that --model and --species-mapping belong together: Just-Bird for Just-Bird.pt, Birds-With-Labels for Birds-With-Labels.pt (files from before 28 October 2026 may still be called All-In-One.pt).
  • Lower the confidence threshold for exploratory runs. The defaults are 0.15 for Just-Bird and 0.2 for Birds-With-Labels. Try --conf 0.1, or --conf 0.001 to capture every raw hit.
  • Check audio format and quality. WAV and FLAC outperform lossy formats such as MP3 and OGG for faint or distant calls. In a study of avian recordings, MP3 compression reduced the detections of human listeners and automated recognisers [19].
  • Confirm that the audio file actually covers the time ranges recorded in your labels when running an evaluation.

Quick sanity check

Run BirdBox on a short clip you know contains a loud, clear call. If that also returns nothing, the issue is almost certainly the model/mapping pair, not the audio.

Too Many False Positives

False positives usually indicate that the confidence threshold is too permissive or that overlapping detections are being merged incorrectly.

  • Increase --conf to raise the detection bar. Even a small step (e.g., 0.3 to 0.5) can cut noise significantly.
  • Tune --nms-iou to control how aggressively duplicate bounding boxes within a window are suppressed.
  • Run confusion_matrix_analysis.py and inspect the background row and column to distinguish species confusion from generic noise hits.

Boxes Too Long or Too Short

Box length depends on the merge (see Merging the Windows) and should match how your labels are drawn.

  • Just-Bird boxes single syllables, but your labels box phrases or songs: raise --phrase-gap (default 0.05 s, try 0.1 to 0.5) so nearby syllables in the same band are joined.
  • Just-Bird joins calls that your labels keep apart: pass --phrase-gap 0 for one box per call.
  • Birds-With-Labels joins unrelated calls into one long song box: reduce --song-gap (default 0.1 s). Raise it to join songs across longer pauses.

Recording in the Demo Is Silent

The Demo warns while recording when no sound arrives from the microphone for 1.5 s, and shows the input level under the timer. If the warning appears, check that the microphone is not muted, turned all the way down, or blocked for the browser in the system settings.

Memory or Runtime Issues

Large audio collections can put pressure on RAM or stretch runtimes. Process smarter before scaling up hardware.

  • Reduce parallelism by lowering --num-workers for inference and F-beta analysis.
  • Process subsets of files and merge the resulting reports afterwards rather than running everything in one pass.
  • Prefer GPU-backed runs for large jobs when a compatible device is available.

Avoid redundant inference

Generate the raw detections JSON once using --no-merge. Re-running full inference just to experiment with confidence thresholds wastes significant time on large datasets.

Filename Mismatch in Evaluation

Evaluation tools match audio files against labels using the normalized stem, which is the base filename with the extension stripped. If stems do not match, the file is silently skipped.

Audio file Label file Result
recording_01.wav recording_01.flac Match
siteA_recording_01.wav recording_01.flac No match

How to fix a mismatch

Inspect both the filename fields in your detection CSV or JSON and the filenames in your labels CSV. Unify the base names in one of the two sources, then re-run metrics.

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.