birdnet analyzer

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_analyzer]"

audioclass.models.birdnet_analyzer

Audio Classification Module for Bird Sound Detection.

This module provides tools for loading and using the BirdNET sound event detection model. BirdNET is a deep learning model designed to classify bird species from audio recordings.

Classes:

Name	Description
BirdNETAnalyzer	BirdNET sound event detection model.

Functions:

Name	Description
load_tags	Load BirdNET labels from a file.

Attributes:

Name	Type	Description
INPUT_SAMPLES		Default number of samples expected in the input tensor.
LABELS_PATH		Default path to the BirdNET labels file.
SAMPLERATE		Default sample rate of the audio data expected by the model (in Hz).
SAVED_MODEL_PATH

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.

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.

SAVED_MODEL_PATH = DATA_DIR / 'BirdNET_GLOBAL_6K_V2.4' module-attribute

Classes

BirdNETAnalyzer(callable, signature, tags, confidence_threshold, samplerate, name, logits=True, batch_size=8)

Bases: TensorflowModel

BirdNET sound event detection model.

This class loads and wraps the BirdNET TensorFlow SavedModel for bird sound classification and embedding extraction.

Parameters:

Name	Type	Description	Default
callable	Callable	The TensorFlow callable representing the model.	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 saved model directory.

Functions

load(model_url=SAVED_MODEL_PATH, tags_url=LABELS_PATH, confidence_threshold=DEFAULT_THRESHOLD, samplerate=SAMPLERATE, name='BirdNET', common_name=False, batch_size=8) classmethod

Load a BirdNET model from a saved model directory.

Parameters:

Name	Type	Description	Default
model_url	Union[Path, str]	The path to the saved model directory. Defaults to a local copy of the BirdNET model.	SAVED_MODEL_PATH
tags_url	Union[Path, str]	The URL or path to the file containing the labels. Defaults to the labels file in the BirdNET repository.	LABELS_PATH
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 SAMPLERATE.	SAMPLERATE
name	str	The name of the model. Defaults to "BirdNET".	'BirdNET'

Returns:

Type	Description
BirdNETAnalyzer	An instance of the BirdNET model.

Functions

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.