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

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 – Threads 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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. 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 – Threads 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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:

  • species_list – Ordered species collection used during the session.

  • model_path – Path to the acoustic model binary.

  • n_producers – Threads 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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

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

AcousticModelV2_4

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

AcousticModelV2_4

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 – Threads 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 process limit. Each worker holds its own copy of the model, so a high count raises peak memory use. On Linux and macOS, a worker killed by the operating system to reclaim memory while processing a batch deadlocks the run: the killed process never releases the lock it was holding, so the remaining workers wait on it forever and the call never returns (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 probabilities.

  • sigmoid_sensitivity – Optional scale for the sigmoid function.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a probability (typical 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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. A callback that raises cancels the run.

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 – Threads 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 probabilities.

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

  • sigmoid_sensitivity – Optional scale for the sigmoid function.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a probability (typical 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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.

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:

  • species_list – Ordered species collection used during the session.

  • model_path – Path to the acoustic model binary.

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

  • n_producers – Threads 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 probabilities.

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

  • sigmoid_sensitivity – Optional scale for the sigmoid function.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a probability (typical 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 – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • 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.

Returns:

Session capable of running predictions.

Return type:

AcousticPredictionSession

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 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.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.AcousticTFBackendFP32CustomAppendHiddenV2_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.AcousticTFBackendFP32CustomAppendV2_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.AcousticTFBackendFP32CustomReplaceHiddenV2_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