v1.0.0

The first stable release of birdnet. The API is now considered production-ready (Development Status :: 5), and this release brings the V3.0 model generation, four inference backends, per-file streaming results, and a long list of reliability fixes to the multiprocessing pipeline.

Features

• BirdNET V3.0 (preview) acoustic model in four backends — tf, pb, pt and onnx — all supporting predict(..) and encode(..). Load with birdnet.load("acoustic", "3.0", <backend>); pt/onnx need the new birdnet[pt]/birdnet[onnx] extras. by @Josef-Haupt in #41
• BirdNET-Geomodel V3.0 (v3.0.4 — 14,082 classes covering birds, insects, amphibians and mammals) in tf, pb, pt and onnx. The pt backend applies the sigmoid the TorchScript export omits, so all four backends return identical probabilities. by @Josef-Haupt in #41, #60 and #81
• on_file_complete callback for acoustic predict(..)/encode(..) and their session variants, fired the moment each file is done with a single-file result — enabling streaming per-file persistence and live output. Runs off the inference hot path, so throughput is unaffected. by @Josef-Haupt in #57
• apply_softmax option for acoustic predict(..), mirroring apply_sigmoid: scores become a softmax over the model logits, useful for confidence scores (e.g. Perch V2). by @max-mauermann in #54
• Partial Python 3.14 support. TensorFlow has no 3.14 wheels yet, so birdnet installs without it there and runs the TF-free backends — acoustic 3.0 and geo 3.0 via onnx/pt. TensorFlow-only paths raise a clear error instead of an ImportError. by @Josef-Haupt in #59

Changed

• The pipeline now uses the spawn start method by default on all platforms, instead of inheriting Linux's fork, which could deadlock workers after TensorFlow started its multi-threaded runtime. A globally fixed start method is honored, and BIRDNET_START_METHOD overrides both, so fork/forkserver stay available by explicit opt-in. by @Josef-Haupt in #63
• The V3.0 models share the geomodel's versioned taxonomy, which resolves every geo label and matches the acoustic label file more closely than the previous pin. ⚠️ Estonian (et) was dropped from the V3.0 language list, as the new taxonomy has no Estonian column. by @Josef-Haupt in #41 and #81
• The progress callback runs on a background thread with a copy of the caller's context (contextvars), matching on_file_complete. by @Josef-Haupt in #53

Bugfixes

Most of these remove ways the inference pipeline could hang or return quietly wrong data.

• Corrupt rows in prediction/encoding output caused by growing the internal result buffer with numpy.ndarray.resize, plus an off-by-one in the initial segment count. by @Josef-Haupt in #50
• A ~1 s barrier on every run_arrays(..) call — on a warm session a 3 s clip went from 1069 ms to 39 ms. Also fixed an assertion that aborted a run when the ring-buffer scan found no readable slot. by @winedarksea in #66
• Producers and the performance tracker no longer attach the ring buffers inside a fork child, where SharedMemory(create=False) could block forever on a lock CPython does not reinitialize after fork. by @winedarksea in #67
• A pipeline process that dies mid-run — typically an OOM kill — is now reported with its name and exit code instead of leaving the call hanging forever. by @Josef-Haupt in #72
• The progress callback's closing update, which reported zero processed segments for runs that had processed everything, and published nothing at all for a run without predictions — leaving the call waiting indefinitely. by @Josef-Haupt in #78
• Sessions now tear down cleanly when cancelled, instead of blocking while draining worker queues. by @Josef-Haupt in #62
• Model, label and taxonomy downloads retry transient network faults with a growing back-off instead of failing the first load(); permanent client errors still fail immediately. by @Josef-Haupt in #71
• Geo V3.0 caches self-heal across releases. A cached SavedModel or label file from an older release was not detected as stale, so a version bump could keep serving outdated labels; label files now record the taxonomy they came from and regenerate when it changes. by @Josef-Haupt in #41 and #81

Known limitation

A worker killed by the OS while processing a batch still deadlocks the surviving workers on Linux and macOS — the killed process never releases the ring-buffer lock. Lowering n_workers or batch_size reduces the risk. Tracked in #73.

Under the hood

• Documented the prediction worker limits and cleanup behaviour. by @Stava-Java in #65
• Additional test coverage, model caching between test runs, and CI stabilisation across macOS Intel, Windows and the fork lanes. by @Josef-Haupt in #58, #61, #63, #70, #79 and #80
• Docs updates for BirdNET 3.0 and the n_workers memory limitation. by @Josef-Haupt in #52 and #76

New Contributors

• @max-mauermann made their first contribution in #54
• @Stava-Java made their first contribution in #65
• @winedarksea made their first contribution in #66

Full Changelog: v0.2.16...v1.0.0