birdnet.acoustic.models.v2_4 package

Submodules

birdnet.acoustic.models.v2_4.model module

class birdnet.acoustic.models.v2_4.model.AcousticDownloaderBaseV2_4

Bases: object

AVAILABLE_LANGUAGES: OrderedSet[str] = OrderedSet(['af', 'ar', 'cs', 'da', 'de', 'en_uk', 'en_us', 'es', 'fi', 'fr', 'hu', 'it', 'ja', 'ko', 'nl', 'no', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'th', 'tr', 'uk', 'zh'])
class birdnet.acoustic.models.v2_4.model.AcousticModelV2_4(model_path, species_list, is_custom_model, backend_type, backend_kwargs)

Bases: AcousticModelBase

property backend_kwargs: dict[str, Any]
property backend_type: type[VersionedAcousticBackendProtocol]
encode(inp, /, *, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, speed=1.0, bandpass_fmin=0, bandpass_fmax=15000, half_precision=False, max_audio_duration_min=None, show_stats=None, progress_callback=None, device='CPU', on_file_complete=None)

Run encoding with the BirdNET 2.4 model on files or paths to obtain embeddings.

Return type:

AcousticEncodingResultBase

Parameters:

  • inp – Path(s) or string(s) pointing to audio files to encode.

  • n_producers – Processes tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • on_file_complete – Optional callback fired once per input file as soon as that file is fully processed, receiving a single-file AcousticFileEncodingResult (invalid files are reported with their input marked unprocessable). Enables streaming per-file persistence. Invoked from a background thread with a copy of the caller’s context; file inputs only (not encode_arrays). A callback that raises cancels the run.

Returns:

Object containing embeddings for each file.

Return type:

AcousticEncodingResultBase

encode_arrays(inp, /, *, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, speed=1.0, bandpass_fmin=0, bandpass_fmax=15000, half_precision=False, max_audio_duration_min=None, show_stats=None, progress_callback=None, device='CPU')

Run encoding with the BirdNET 2.4 model directly on in-memory audio arrays.

Return type:

AcousticEncodingResultBase

Parameters:

  • inp – Tuple(s) of (audio ndarray, sampling rate).

  • n_producers – Processes generating batches from the arrays.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

Returns:

Object containing embeddings for each input array.

Return type:

AcousticEncodingResultBase

encode_session(*, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, speed=1.0, bandpass_fmin=0, bandpass_fmax=15000, half_precision=False, max_audio_duration_min=None, show_stats=None, progress_callback=None, device='CPU', max_n_files=65536, on_file_complete=None)

Create an encoding session with explicit resource configuration.

Return type:

AcousticEncodingSession

Parameters:

  • n_producers – Processes tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • max_n_files – Upper bound on files to limit resource consumption.

  • on_file_complete – Optional callback fired once per input file as soon as that file is fully processed, receiving a single-file AcousticFileEncodingResult (invalid files are reported with their input marked unprocessable). Enables streaming per-file persistence. Invoked from a background thread with a copy of the caller’s context; file inputs only (not run_arrays). A callback that raises cancels the run.

Returns:

Session capable of running encodings.

Return type:

AcousticEncodingSession

final classmethod get_embeddings_dim()
Return type:

int

final classmethod get_sample_rate()
Return type:

int

final classmethod get_segment_size_s()
Return type:

float

final classmethod get_segment_size_samples()
Return type:

int

final classmethod get_sig_fmax()
Return type:

int

final classmethod get_sig_fmin()
Return type:

int

final classmethod get_version()

Return the string label that identifies the acoustic model version.

Return type:

Literal['2.4', '3.0']

Returns:

Registered enum constant for the supported version.

Return type:

ACOUSTIC_MODEL_VERSIONS

property is_custom_model: bool
classmethod load(model_path, species_list, backend_type, backend_kwargs)
Return type:

Self

classmethod load_custom(model_path, species_list, backend_type, backend_kwargs, check_validity)
Return type:

Self

property model_path: Path
property n_species: int
predict(inp, /, *, top_k=5, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, bandpass_fmin=0, bandpass_fmax=15000, speed=1.0, apply_sigmoid=True, sigmoid_sensitivity=1.0, default_confidence_threshold=0.1, custom_confidence_thresholds=None, custom_species_list=None, half_precision=False, max_audio_duration_min=None, device='CPU', show_stats=None, progress_callback=None, on_file_complete=None, apply_softmax=False)

Run prediction with the BirdNET 2.4 model on files or paths with configurable inference options.

This method creates one prediction session for the call. The session shuts down its producer and worker processes before this method returns, including when inference raises an exception.

Return type:

AcousticPredictionResultBase

Parameters:

  • inp – Path(s) or string(s) pointing to audio files to analyze.

  • top_k – Number of highest-confidence results to return per segment.

  • n_producers – Processes tasked with producing audio batches.

  • n_workers – Number of inference worker processes. None uses the number of physical CPU cores. Pass a fixed integer to meet a scheduler or container process limit. Each worker holds its own copy of the model, so a high count raises peak memory use. In the cases the pipeline guards against, a worker killed by the operating system to reclaim memory, including while it is processing a batch, is reported as an error naming the dead worker rather than hanging the call (see issue #73). Lowering n_workers or batch_size reduces peak memory and with it how likely such a kill is, but cannot rule it out.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as sigmoid scores.

  • apply_softmax – Whether to transform logits with a softmax. When False, output scores are raw logits unless apply_sigmoid=True.

  • sigmoid_sensitivity – Shifts the logits by 10 * (sigmoid_sensitivity - 1) before the sigmoid, so values above 1.0 raise the scores and values below lower them; between 0.5 and 1.5, None means 1.0. Ignored with apply_sigmoid=False.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a sigmoid score (range 0 to 1); when apply_sigmoid=False it is a logit value.

  • custom_confidence_thresholds – Species-specific override thresholds.

  • custom_species_list – Path or iterable defining a subset of species.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • device – Target device(s) for running the backend.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • on_file_complete – Optional callback fired once per input file as soon as that file is fully processed, receiving a single-file AcousticFilePredictionResult (invalid files are reported with their input marked unprocessable). Enables streaming per-file persistence (e.g. resumable analysis). Invoked from a background thread with a copy of the caller’s context; file inputs only (not predict_arrays). A callback that raises cancels the run.

A Raven export (load_custom(.., "pb", .., is_raven=True)) applies the sigmoid inside its graph, so apply_sigmoid=True returns its scores as they are. A sigmoid_sensitivity other than 1.0 is applied on logits recovered from those scores; apply_sigmoid=False returns the raw scores and ignores the sensitivity, as for a TFLite export. apply_softmax=True raises a ValueError, as for the V3.0 models.

Returns:

Object containing detected species and confidence

scores.

Return type:

AcousticPredictionResultBase

predict_arrays(inp, /, *, top_k=5, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, bandpass_fmin=0, bandpass_fmax=15000, speed=1.0, apply_sigmoid=True, sigmoid_sensitivity=1.0, default_confidence_threshold=0.1, custom_confidence_thresholds=None, custom_species_list=None, half_precision=False, max_audio_duration_min=None, device='CPU', show_stats=None, progress_callback=None, apply_softmax=False)

Run prediction with the BirdNET 2.4 model directly on in-memory audio arrays.

Return type:

AcousticPredictionResultBase

Parameters:

  • inp – Tuple(s) of (audio ndarray, sampling rate).

  • top_k – Number of highest-confidence results to return per segment.

  • n_producers – Processes generating batches from the arrays.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as sigmoid scores.

  • apply_softmax – Whether to transform logits with a softmax. When False, output scores are raw logits unless apply_sigmoid=True.

  • sigmoid_sensitivity – Shifts the logits by 10 * (sigmoid_sensitivity - 1) before the sigmoid, so values above 1.0 raise the scores and values below lower them; between 0.5 and 1.5, None means 1.0. Ignored with apply_sigmoid=False.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a sigmoid score (range 0 to 1); when apply_sigmoid=False it is a logit value.

  • custom_confidence_thresholds – Species-specific override thresholds.

  • custom_species_list – Path or iterable defining a subset of species.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • device – Target device(s) for running the backend.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

A Raven export (load_custom(.., "pb", .., is_raven=True)) applies the sigmoid inside its graph, so apply_sigmoid=True returns its scores as they are. A sigmoid_sensitivity other than 1.0 is applied on logits recovered from those scores; apply_sigmoid=False returns the raw scores and ignores the sensitivity, as for a TFLite export. apply_softmax=True raises a ValueError, as for the V3.0 models.

Returns:

Object containing detected species and confidence

scores.

Return type:

AcousticPredictionResultBase

predict_session(*, top_k=5, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, speed=1.0, bandpass_fmin=0, bandpass_fmax=15000, apply_sigmoid=True, sigmoid_sensitivity=1.0, default_confidence_threshold=0.1, custom_confidence_thresholds=None, custom_species_list=None, half_precision=False, max_audio_duration_min=None, show_stats=None, progress_callback=None, device='CPU', max_n_files=65536, on_file_complete=None, apply_softmax=False)

Create a prediction session allowing manual control over the inference lifecycle.

Return type:

AcousticPredictionSession

Parameters:

  • top_k – Number of highest-confidence results to return per segment.

  • n_producers – Processes tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as sigmoid scores.

  • apply_softmax – Whether to transform logits with a softmax. When False, output scores are raw logits unless apply_sigmoid=True.

  • sigmoid_sensitivity – Shifts the logits by 10 * (sigmoid_sensitivity - 1) before the sigmoid, so values above 1.0 raise the scores and values below lower them; between 0.5 and 1.5, None means 1.0. Ignored with apply_sigmoid=False.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a sigmoid score (range 0 to 1); when apply_sigmoid=False it is a logit value.

  • custom_confidence_thresholds – Species-specific override thresholds.

  • custom_species_list – Path or iterable defining a subset of species.

  • half_precision – Cast the model’s outputs to float16 after inference; inference itself runs at the model’s precision.

  • max_audio_duration_min – Longest single input, in minutes, the segment indices are sized for; None sizes them for any length. An input with more segments than they can hold raises an error.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • max_n_files – Upper bound on files to limit resource consumption.

  • on_file_complete – Optional callback fired once per input file as soon as that file is fully processed, receiving a single-file AcousticFilePredictionResult (invalid files are reported with their input marked unprocessable). Enables streaming per-file persistence (e.g. resumable analysis). Invoked from a background thread with a copy of the caller’s context; file inputs only (not run_arrays). A callback that raises cancels the run.

A Raven export (load_custom(.., "pb", .., is_raven=True)) applies the sigmoid inside its graph, so apply_sigmoid=True returns its scores as they are. A sigmoid_sensitivity other than 1.0 is applied on logits recovered from those scores; apply_sigmoid=False returns the raw scores and ignores the sensitivity, as for a TFLite export. apply_softmax=True raises a ValueError, as for the V3.0 models.

Returns:

Session capable of running predictions.

Return type:

AcousticPredictionSession

property species_list: OrderedSet[str]

birdnet.acoustic.models.v2_4.pb module

class birdnet.acoustic.models.v2_4.pb.AcousticPBBackendFP32V2_4(model_path, device_name, half_precision, **kwargs)

Bases: PBBackend, VersionedAcousticBackendProtocol

classmethod encoding_key()
Return type:

str | None

classmethod encoding_signature_name()
Return type:

str | None

classmethod input_key()
Return type:

str

classmethod precision()
Return type:

Literal['int8', 'fp16', 'fp32']

classmethod prediction_key()
Return type:

str

classmethod prediction_signature_name()
Return type:

str

classmethod supports_encoding()
Return type:

bool

class birdnet.acoustic.models.v2_4.pb.AcousticPBDownloaderV2_4

Bases: AcousticDownloaderBaseV2_4

classmethod get_model_path_and_labels(lang)
Return type:

tuple[Path, OrderedSet[str]]

class birdnet.acoustic.models.v2_4.pb.AcousticRavenBackendFP32V2_4(model_path, device_name, half_precision, **kwargs)

Bases: PBBackend, VersionedAcousticBackendProtocol

classmethod applies_sigmoid()

Whether the sigmoid is applied inside the model graph.

A model that applies the sigmoid inside its graph must not get the pipeline’s sigmoid on top: that squashes every score into [0.5, 0.73]. The prediction worker recovers the logits from such a model’s scores when a non-default sigmoid sensitivity asks for the pipeline sigmoid after all.

Return type:

bool

classmethod encoding_key()
Return type:

str | None

classmethod encoding_signature_name()
Return type:

str | None

classmethod input_key()
Return type:

str

classmethod name()
Return type:

str

classmethod precision()
Return type:

Literal['int8', 'fp16', 'fp32']

classmethod prediction_key()
Return type:

str

classmethod prediction_signature_name()
Return type:

str

classmethod supports_encoding()
Return type:

bool

birdnet.acoustic.models.v2_4.tf module

class birdnet.acoustic.models.v2_4.tf.AcousticTFBackendCustomNoEmbeddingsV2_4(model_path, device_name, half_precision, **kwargs)

Bases: AcousticTFBackendCustomV2_4

A custom 2.4 classifier whose file exposes no embeddings tensor.

classmethod supports_encoding()
Return type:

bool

class birdnet.acoustic.models.v2_4.tf.AcousticTFBackendCustomV2_4(model_path, device_name, half_precision, **kwargs)

Bases: CustomTFLiteBackend, VersionedAcousticBackendProtocol

A custom 2.4 classifier, whichever head and export version produced it.

classmethod legacy_prediction_indices()
Return type:

Collection[int]

classmethod model_version()
Return type:

Literal['2.4', '3.0']

class birdnet.acoustic.models.v2_4.tf.AcousticTFBackendFP16V2_4(model_path, device_name, half_precision, **kwargs)

Bases: TFBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()
Return type:

int | None

classmethod in_idx()
Return type:

int

classmethod precision()
Return type:

Literal['int8', 'fp16', 'fp32']

classmethod prediction_out_idx()
Return type:

int

classmethod supports_encoding()
Return type:

bool

class birdnet.acoustic.models.v2_4.tf.AcousticTFBackendFP32V2_4(model_path, device_name, half_precision, **kwargs)

Bases: TFBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()
Return type:

int | None

classmethod in_idx()
Return type:

int

classmethod precision()
Return type:

Literal['int8', 'fp16', 'fp32']

classmethod prediction_out_idx()
Return type:

int

classmethod supports_encoding()
Return type:

bool

class birdnet.acoustic.models.v2_4.tf.AcousticTFBackendInt8V2_4(model_path, device_name, half_precision, **kwargs)

Bases: TFBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()
Return type:

int | None

classmethod in_idx()
Return type:

int

classmethod precision()
Return type:

Literal['int8', 'fp16', 'fp32']

classmethod prediction_out_idx()
Return type:

int

classmethod supports_encoding()
Return type:

bool

class birdnet.acoustic.models.v2_4.tf.AcousticTFDownloaderV2_4

Bases: AcousticDownloaderBaseV2_4

classmethod get_model_path_and_labels(lang, precision)
Return type:

tuple[Path, OrderedSet[str]]

Module contents