birdnet

Warning

Additional Dependencies: To use the BirdNET model, you will need to install additional dependencies. These dependencies are optional, as they can be heavy and may not be needed in all use cases. To install them, run:

pip install "audioclass[birdnet]"

audioclass.models.birdnet

Module for loading and using the BirdNET audio classification model.

This module provides a convenient interface for working with the BirdNET model, which is a TensorFlow Lite-based model designed for bird sound classification. It includes the BirdNET class, which is a subclass of TFLiteModel, and functions for loading the model and its associated labels.

Notes

The BirdNET model was developed by the K. Lisa Yang Center for Conservation Bioacoustics at the Cornell Lab of Ornithology, in collaboration with Chemnitz University of Technology. This package is not affiliated with the BirdNET project.

BirdNET is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

If you use the BirdNET model, please cite:

Kahl, S., Wood, C. M., Eibl, M., & Klinck, H. (2021). BirdNET: A deep
learning solution for avian diversity monitoring. Ecological Informatics,
61, 101236.

For further details, please visit the official BirdNET repository

Classes:

Name	Description
BirdNET	BirdNET audio classification model.

Attributes

INPUT_SAMPLES = 144000 module-attribute

Default number of samples expected in the input tensor.

This value corresponds to 3 seconds of audio data at a sample rate of 48,000 Hz.

LABELS_PATH = 'https://raw.githubusercontent.com/kahst/BirdNET-Analyzer/refs/heads/main/birdnet_analyzer/checkpoints/V2.4/BirdNET_GLOBAL_6K_V2.4_Labels.txt' module-attribute

Default path to the BirdNET labels file.

MODEL_PATH: str = 'https://github.com/kahst/BirdNET-Analyzer/raw/refs/heads/main/birdnet_analyzer/checkpoints/V2.4/BirdNET_GLOBAL_6K_V2.4_Model_FP32.tflite' module-attribute

Default path to the BirdNET TensorFlow Lite model file.

SAMPLERATE = 48000 module-attribute

Default sample rate of the audio data expected by the model (in Hz).

This value corresponds to the sample rate used by the BirdNET model.

Classes

BirdNET(interpreter, signature, tags, confidence_threshold, samplerate, name, logits=True, batch_size=8)

Bases: TFLiteModel

BirdNET audio classification model.

This class is a wrapper around a TensorFlow Lite model for bird sound classification. It provides methods for loading the model, processing audio data, and returning predictions.

Parameters:

Name	Type	Description	Default
interpreter	Interpreter	The TensorFlow Lite interpreter object.	required
signature	Signature	The input and output signature of the model.	required
tags	List[Tag]	The list of tags that the model can predict.	required
confidence_threshold	float	The minimum confidence threshold for assigning a tag to a clip.	required
samplerate	int	The sample rate of the audio data expected by the model (in Hz).	required
name	str	The name of the model.	required
logits	bool	Whether the model outputs logits (True) or probabilities (False). Defaults to True.	True
batch_size	int	The maximum number of frames to process in each batch. Defaults to 8.	8

Methods:

Name	Description
load	Load a BirdNET model from a file or URL.

Functions

load(model_path=MODEL_PATH, labels_path=LABELS_PATH, num_threads=None, confidence_threshold=DEFAULT_THRESHOLD, samplerate=SAMPLERATE, name='BirdNET', common_name=False, batch_size=8) classmethod

Load a BirdNET model from a file or URL.

Parameters:

Name	Type	Description	Default
model_path	Union[Path, str]	The path or URL to the TensorFlow Lite model file. Defaults to the latest version of the BirdNET model.	MODEL_PATH
labels_path	Union[Path, str]	The path or URL to the labels file. Defaults to the latest version of the BirdNET labels.	LABELS_PATH
num_threads	Optional[int]	The number of threads to use for inference. If None, the default number of threads will be used.	None
confidence_threshold	float	The minimum confidence threshold for making predictions. Defaults to DEFAULT_THRESHOLD.	DEFAULT_THRESHOLD
samplerate	int	The sample rate of the audio data expected by the model (in Hz). Defaults to 48,000 Hz.	SAMPLERATE
name	str	The name of the model. Defaults to "BirdNET".	'BirdNET'
common_name	bool	Whether to use common names for bird species instead of scientific names. Defaults to False.	False
batch_size	int	The number of samples to process in each batch. Defaults to 8.	8

Returns:

Type	Description
BirdNET	An instance of the BirdNET class.

Functions

get_signature(interpreter)

Get the signature of a BirdNET model.

Parameters:

Name	Type	Description	Default
interpreter	Interpreter	The TensorFlow Lite interpreter object.	required

Returns:

Type	Description
Signature	The signature of the BirdNET model.

Raises:

Type	Description
ValueError	If the model signature does not match the expected format.

load_tags(path=LABELS_PATH, common_name=False)

Load BirdNET labels from a file.

Parameters:

Name	Type	Description	Default
path	Union[Path, str]	Path or URL to the file containing the labels. Defaults to the latest version of the BirdNET labels.	LABELS_PATH
common_name	bool	Whether to return the common name instead of the scientific name. Defaults to False.	False

Returns:

Type	Description
List[Tag]	List of soundevent Tag objects.