Quick start¶
This guide will help you get started with BirdNET quickly. It covers installation, basic usage, and running benchmarks to evaluate performance.
Installation¶
To install BirdNET, you can use pip. Open your terminal and run the following command:
pip install birdnet[tf] --user
This command installs the BirdNET package with TensorFlow, which the tf backend
used in the examples below relies on. Plain pip install birdnet installs a
TensorFlow-free package that runs the V3.0 models via onnx and the 2.4 models via
birdnet.load(.., "tf", library="litert"); see Setup for the extras.
Predict species from audio file¶
import birdnet
if __name__ == "__main__":
model = birdnet.load("acoustic", "2.4", "tf")
predictions = model.predict("example/soundscape.wav")
predictions.to_csv("example/predictions.csv")
predict runs in worker processes, and each of them imports the script again.
In a script, the code that calls birdnet therefore has to be under
if __name__ == "__main__":, as in the examples here; code typed into an
interactive interpreter needs no guard. See General functionalities for the details.
Predict species from multiple audio files in a directory¶
import birdnet
if __name__ == "__main__":
model = birdnet.load("acoustic", "2.4", "tf")
predictions = model.predict("example/soundscapes/")
predictions.to_csv("example/predictions.csv")
Limit prediction worker processes¶
predict starts one worker process per physical CPU core when n_workers is
omitted, or fewer when the memory available to the process (a container’s cgroup
limit included) would not hold that many; the choice is logged at INFO. Pass a
fixed value when a scheduler or container limits the number of processes
available to the job, or to override the estimate:
import birdnet
if __name__ == "__main__":
model = birdnet.load("acoustic", "2.4", "tf")
predictions = model.predict("example/soundscapes/", n_workers=2)
predictions.to_csv("example/predictions.csv")
Each call to predict shuts down its producer and worker processes before it
returns, including when inference raises an exception. To process several batches
without restarting two workers for every batch, reuse a prediction session:
import birdnet
if __name__ == "__main__":
model = birdnet.load("acoustic", "2.4", "tf")
with model.predict_session(n_workers=2) as session:
first = session.run("example/soundscapes/day-1/")
second = session.run("example/soundscapes/day-2/")
first.to_csv("example/day-1.csv")
second.to_csv("example/day-2.csv")
Predict species for a given location and time¶
import birdnet
model = birdnet.load("geo", "2.4", "tf")
predictions = model.predict(42.5, -76.45, week=4)
predictions.to_csv("example/location.csv")
predict loads the model’s backend for every call, runs the query and
unloads it again; that load dominates the call. To query several locations or
weeks, open one session and reuse it:
with model.predict_session() as session:
spring = session.run(42.5, -76.45, week=16)
autumn = session.run(42.5, -76.45, week=40)
Predict species with a custom species list¶
import birdnet
if __name__ == "__main__":
model = birdnet.load("acoustic", "2.4", "tf")
predictions = model.predict(
"example/soundscape.wav",
custom_species_list="example/species_list.txt",
)
predictions.to_csv("example/predictions.csv")
Show model download progress¶
Official models (plus their labels and, for the V3.0 geo model, a taxonomy) are downloaded on first use inside birdnet.load(..). By default progress is only shown as a tqdm bar on stderr, which is invisible to a GUI application that redirects stderr to a log file. Register a process-wide callback to drive your own progress UI instead; while a callback is registered the tqdm bar is silenced. The callback receives a DownloadProgress snapshot:
"started"once per attempt (a second"started"with a higherattemptis a retry – reset your bar),"progress"while bytes arrive (throttled to ~10 per second),"retrying"before each back-off, witherrorandretry_in_s,exactly one of
"finished"/"failed"(witherror) at the end –failedmeans the download gave up andload(..)raises right after.
import birdnet
from birdnet import DownloadProgress
def on_download_progress(p: DownloadProgress) -> None:
# Runs on the thread that called birdnet.load(); hand off to your UI thread if needed.
# A single load() may run several downloads (labels, taxonomy, model): key on p.description.
if p.status == "started":
ui.show_progress(p.description, attempt=p.attempt, of=p.max_attempts)
elif p.status == "progress":
ui.set_progress(p.fraction) # None while the total size is unknown
elif p.status == "retrying":
ui.set_message(f"{p.error} - retrying in {p.retry_in_s:.0f} s")
elif p.status == "finished":
ui.hide_progress()
elif p.status == "failed":
ui.show_error(f"Could not download {p.description}: {p.error}")
birdnet.set_download_progress_callback(on_download_progress) # once, at application start
model = birdnet.load("acoustic", "3.0", "onnx") # downloads on first use
To cancel a running download from the UI, raise an exception inside the callback: the partial file is discarded, no retry is attempted, and your exception propagates out of load(..). set_download_progress_callback returns the previously registered callback; get_download_progress_callback reads it. Use birdnet.download_progress_callback(cb) as a with block instead if the callback should only apply to a specific piece of code:
import birdnet
with birdnet.download_progress_callback(on_download_progress):
model = birdnet.load("acoustic", "3.0", "onnx")
Use a different model version or backend¶
The version and backend arguments of birdnet.load select the model. Besides V2.4, the V3.0 acoustic model is available in the tf, pb, pt and onnx backends, and the V3.0 geo model in the tf, pb, pt and onnx backends. See Models for the full support matrix.
import birdnet
if __name__ == "__main__":
# V3.0 acoustic model via the ONNX backend (part of the base install)
model = birdnet.load("acoustic", "3.0", "onnx")
predictions = model.predict("example/soundscape.wav")
predictions.to_csv("example/predictions.csv")