birdnet package ¶

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; 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 – 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:

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:

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.

Returns:

Session capable of running encodings.

Return type:

AcousticEncodingSession

classmethod get_embeddings_dim()¶

Return type:: int

classmethod get_sample_rate()¶

Return type:: int

classmethod get_segment_size_s()¶

Return type:: float

classmethod get_segment_size_samples()¶

Return type:: int

classmethod get_sig_fmax()¶

Return type:: int

classmethod get_sig_fmin()¶

Return type:: int

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

classmethod load_custom(model_path, species_list, backend_type, backend_kwargs, check_validity)¶

Return type:: AcousticModelPerchV2

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

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 – 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.
sigmoid_sensitivity – Optional scale for the sigmoid function.
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 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:

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:

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.

Returns:

Session capable of running predictions.

Return type:

AcousticPredictionSession

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

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:

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

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:

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

classmethod get_embeddings_dim()¶

Return type:: int

classmethod get_sample_rate()¶

Return type:: int

classmethod get_segment_size_s()¶

Return type:: float

classmethod get_segment_size_samples()¶

Return type:: int

classmethod get_sig_fmax()¶

Return type:: int

classmethod get_sig_fmin()¶

Return type:: int

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:

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:

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