birdnet package ¶

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:

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 Perch V2 model directly on in-memory audio arrays.

Return type:

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:

AcousticEncodingSession

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:

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=False, apply_softmax=False, sigmoid_sensitivity=None, 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)¶

Run prediction with the Perch V2 model on files or paths with configurable inference options.

Return type:

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

Returns:

Object containing detected species and confidence: scores.

Return type:

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=False, apply_softmax=False, sigmoid_sensitivity=None, 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)¶

Run prediction with the Perch V2 model directly on in-memory audio arrays.

Return type:

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.
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.
apply_softmax – Whether to transform logits with a softmax. When False, output scores are raw logits unless apply_sigmoid=True.
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.

Returns:

Object containing detected species and confidence: scores.

Return type:

AcousticPredictionSession

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=False, apply_softmax=False, sigmoid_sensitivity=None, 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)¶

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

Return type:

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.

Returns:

Session capable of running predictions.

Return type:

AcousticPredictionSession

property species_list: OrderedSet[str]¶

class birdnet.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:

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:

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:

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:

AcousticEncodingSession

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:

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:

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:

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:

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:

AcousticPredictionSession

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:

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]¶

class birdnet.AcousticModelV3_0(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', segment_size_s=3.0, on_file_complete=None)¶

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

Return type:

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.
segment_size_s – Length in seconds of the audio segments passed to the model. The official tf, onnx and pt exports accept lengths other than the default 3.0 s. pb and the custom classifier exports take only 3.0 s and raise a ValueError for any other length; a custom TFLite export loaded with check_validity=False and an explicit version fails during the run instead. overlap_duration_s must be smaller than this value.
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:

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', segment_size_s=3.0)¶

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

Return type:

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.
segment_size_s – Length in seconds of the audio segments passed to the model. The official tf, onnx and pt exports accept lengths other than the default 3.0 s. pb and the custom classifier exports take only 3.0 s and raise a ValueError for any other length; a custom TFLite export loaded with check_validity=False and an explicit version fails during the run instead. overlap_duration_s must be smaller than this value.

Returns:

Object containing embeddings for each input array.

Return type:

AcousticEncodingSession

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, segment_size_s=3.0, on_file_complete=None)¶

Create an encoding session with explicit resource configuration.

Return type:

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.
segment_size_s – Length in seconds of the audio segments passed to the model. The official tf, onnx and pt exports accept lengths other than the default 3.0 s. pb and the custom classifier exports take only 3.0 s and raise a ValueError for any other length; a custom TFLite export loaded with check_validity=False and an explicit version fails during the run instead. overlap_duration_s must be smaller than this value.
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, apply_softmax=False, 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, segment_size_s=3.0, on_file_complete=None)¶

Run prediction with the BirdNET 3.0 model on files or paths.

Scores are returned as the model emits them: the V3.0 exports apply the sigmoid inside the model graph. apply_sigmoid=True (the default) returns them unchanged and apply_sigmoid=False returns the identical raw model output, so confidence thresholds are sigmoid scores either way. A sigmoid_sensitivity other than 1.0 is applied as it is to the 2.4 models, on logits recovered from the scores, and is ignored with apply_sigmoid=False as there. apply_softmax=True raises a ValueError. Custom V3.0 models are expected to apply the sigmoid as well.

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

Return type:

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 – The 3.0 exports apply the sigmoid inside the model graph, so False returns the model’s scores unchanged, as does True (the default) at the default sigmoid_sensitivity of 1.0. False ignores sigmoid_sensitivity.
apply_softmax – Must stay False; True raises a ValueError for the 3.0 models.
sigmoid_sensitivity – Shifts the logits, recovered from the model’s scores, 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, as a sigmoid score (range 0 to 1).
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.
segment_size_s – Length in seconds of the audio segments passed to the model. The official tf, onnx and pt exports accept lengths other than the default 3.0 s. pb and the custom classifier exports take only 3.0 s and raise a ValueError for any other length; a custom TFLite export loaded with check_validity=False and an explicit version fails during the run instead. overlap_duration_s must be smaller than this value.
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.

Returns:

Object containing detected species and confidence: scores.

Return type:

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, apply_softmax=False, 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, segment_size_s=3.0)¶

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

Return type:

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 – The 3.0 exports apply the sigmoid inside the model graph, so False returns the model’s scores unchanged, as does True (the default) at the default sigmoid_sensitivity of 1.0. False ignores sigmoid_sensitivity.
apply_softmax – Must stay False; True raises a ValueError for the 3.0 models.
sigmoid_sensitivity – Shifts the logits, recovered from the model’s scores, 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, as a sigmoid score (range 0 to 1).
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.
segment_size_s – Length in seconds of the audio segments passed to the model. The official tf, onnx and pt exports accept lengths other than the default 3.0 s. pb and the custom classifier exports take only 3.0 s and raise a ValueError for any other length; a custom TFLite export loaded with check_validity=False and an explicit version fails during the run instead. overlap_duration_s must be smaller than this value.

Returns:

Object containing detected species and confidence: scores.

Return type: