birdnet package

Subpackages

Submodules

birdnet_benchmark.argparse_helper module

class birdnet_benchmark.argparse_helper.ConvertToOrderedSetAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: _StoreAction

Docstring für ConvertToOrderedSetAction.

Methods

__call__(parser, namespace, values[, ...])

Call self as a function.

format_usage
class birdnet_benchmark.argparse_helper.ConvertToSetAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: _StoreAction

Methods

__call__(parser, namespace, values[, ...])

Call self as a function.

format_usage
birdnet_benchmark.argparse_helper.get_optional(method)
Return type:

Callable[[str], Optional[TypeVar(T)]]

birdnet_benchmark.argparse_helper.parse_codec(value)
Return type:

str

birdnet_benchmark.argparse_helper.parse_datetime(value)
Return type:

datetime

birdnet_benchmark.argparse_helper.parse_existing_directory(value)
Return type:

Path

birdnet_benchmark.argparse_helper.parse_existing_file(value)
Return type:

Path

birdnet_benchmark.argparse_helper.parse_float(value)
Return type:

float

birdnet_benchmark.argparse_helper.parse_float_greater_one(value)
Return type:

int

birdnet_benchmark.argparse_helper.parse_integer(value)
Return type:

int

birdnet_benchmark.argparse_helper.parse_integer_greater_one(value)
Return type:

int

birdnet_benchmark.argparse_helper.parse_json(value)
Return type:

dict

birdnet_benchmark.argparse_helper.parse_non_empty(value)
Return type:

str

birdnet_benchmark.argparse_helper.parse_non_empty_or_whitespace(value)
Return type:

str

birdnet_benchmark.argparse_helper.parse_non_negative_float(value)
Return type:

float

birdnet_benchmark.argparse_helper.parse_non_negative_integer(value)
Return type:

int

birdnet_benchmark.argparse_helper.parse_optional_value(value, method)
Return type:

Optional[TypeVar(T)]

birdnet_benchmark.argparse_helper.parse_path(value)
Return type:

Path

birdnet_benchmark.argparse_helper.parse_percent(value)
Return type:

float

birdnet_benchmark.argparse_helper.parse_positive_float(value)
Return type:

float

birdnet_benchmark.argparse_helper.parse_positive_integer(value)
Return type:

int

birdnet_benchmark.argparse_helper.parse_required(value)
Return type:

str

birdnet.core.backends module

class birdnet.core.backends.Backend(model_path, device_name, half_precision)

Bases: Generic[BatchT], ABC

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

half_precision

load

name

precision

predict

supports_cow

supports_encoding

unload
abstractmethod copy_from_device(inference_result)
Return type:

ndarray

abstractmethod copy_to_device(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

abstractmethod encode(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

abstractmethod half_precision(inference_result)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

abstractmethod load()
Return type:

None

abstract property n_species: int
abstractmethod classmethod name()
Return type:

str

abstractmethod classmethod precision()
Return type:

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

abstractmethod predict(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

abstractmethod classmethod supports_cow()
Return type:

bool

abstractmethod classmethod supports_encoding()
Return type:

bool

abstractmethod unload()
Return type:

None

class birdnet.core.backends.BackendLoader(model_path, backend_type, backend_kwargs)

Bases: object

Attributes:
backend

Methods

check_custom_tflite_model(model_path, ...)

Detect the custom TFLite classifier type and number of output species in a subprocess to avoid loading TensorFlow in the main process.

check_model_can_be_loaded(model_path, ...)

Check if the model can be loaded in a subprocess to avoid loading tensorflow in the main process.

load_backend

load_backend_in_main_process_if_possible

unload_backend
property backend: VersionedBackendProtocol
classmethod check_custom_tflite_model(model_path, library, prediction_to_type)

Detect the custom TFLite classifier type and number of output species in a subprocess to avoid loading TensorFlow in the main process.

Returns (n_species, classifier_type) if successful.

Return type:

tuple[int, str]

classmethod check_model_can_be_loaded(model_path, backend_type, kwargs)

Check if the model can be loaded in a subprocess to avoid loading tensorflow in the main process.

Returns the number of species in the model if successful.

Return type:

int

load_backend(device_name, half_precision)
Return type:

VersionedBackendProtocol

load_backend_in_main_process_if_possible(devices, half_precision)
Return type:

None

unload_backend()
Return type:

None

class birdnet.core.backends.OnnxBackend(model_path, device_name, half_precision, **kwargs)

Bases: Backend, ABC

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

encoding_out_idx

half_precision

load

name

precision

predict

prediction_out_idx

probe_input_size_samples

supports_cow

supports_encoding

unload
copy_from_device(inference_result)
Return type:

ndarray

copy_to_device(batch)
Return type:

ndarray

final encode(batch)
Return type:

ndarray

abstractmethod classmethod encoding_out_idx()
Return type:

int | None

half_precision(inference_result)
Return type:

ndarray

load()
Return type:

None

property n_species: int
classmethod name()
Return type:

str

final predict(batch)
Return type:

ndarray

abstractmethod classmethod prediction_out_idx()
Return type:

int

abstractmethod classmethod probe_input_size_samples()
Return type:

int

final classmethod supports_cow()
Return type:

bool

unload()
Return type:

None

class birdnet.core.backends.PBBackend(model_path, device_name, half_precision, **kwargs)

Bases: Backend, ABC

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

encoding_key

encoding_signature_name

half_precision

input_key

load

name

precision

predict

prediction_key

prediction_signature_name

supports_cow

supports_encoding

unload
copy_from_device(inference_result)
Return type:

np.ndarray

copy_to_device(batch)
Return type:

Tensor

final encode(batch)
Return type:

Tensor

abstractmethod classmethod encoding_key()
Return type:

str | None

abstractmethod classmethod encoding_signature_name()
Return type:

str | None

half_precision(inference_result)
Return type:

Tensor

abstractmethod classmethod input_key()
Return type:

str

final load()
Return type:

None

property n_species: int
classmethod name()
Return type:

str

final predict(batch)
Return type:

Tensor

abstractmethod classmethod prediction_key()
Return type:

str

abstractmethod classmethod prediction_signature_name()
Return type:

str

final classmethod supports_cow()
Return type:

bool

unload()
Return type:

None

class birdnet.core.backends.TFBackend(model_path, device_name, half_precision, **kwargs)

Bases: Backend, ABC

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

encoding_out_idx

half_precision

in_idx

load

name

precision

predict

prediction_out_idx

supports_cow

supports_encoding

unload
copy_from_device(inference_result)
Return type:

ndarray

copy_to_device(batch)
Return type:

ndarray

final encode(batch)
Return type:

ndarray

abstractmethod classmethod encoding_out_idx()
Return type:

int | None

half_precision(inference_result)
Return type:

ndarray

abstractmethod classmethod in_idx()
Return type:

int

load()
Return type:

None

property n_species: int
classmethod name()
Return type:

str

final predict(batch)
Return type:

ndarray

abstractmethod classmethod prediction_out_idx()
Return type:

int

final classmethod supports_cow()
Return type:

bool

unload()
Return type:

None

class birdnet.core.backends.TorchBackend(model_path, device_name, half_precision, **kwargs)

Bases: Backend, ABC

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

encoding_out_idx

half_precision

load

name

precision

predict

prediction_out_idx

probe_input_size_samples

supports_cow

supports_encoding

unload
copy_from_device(inference_result)
Return type:

np.ndarray

copy_to_device(batch)
Return type:

TorchTensor

final encode(batch)
Return type:

TorchTensor

abstractmethod classmethod encoding_out_idx()
Return type:

int | None

half_precision(inference_result)
Return type:

TorchTensor

load()
Return type:

None

property n_species: int
classmethod name()
Return type:

str

final predict(batch)
Return type:

TorchTensor

abstractmethod classmethod prediction_out_idx()
Return type:

int

abstractmethod classmethod probe_input_size_samples()
Return type:

int

final classmethod supports_cow()
Return type:

bool

unload()
Return type:

None

class birdnet.core.backends.VersionedAcousticBackendProtocol(model_path, device_name, **kwargs)

Bases: VersionedBackendProtocol, Protocol

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

half_precision

load

name

precision

predict

supports_cow

supports_encoding

unload
class birdnet.core.backends.VersionedBackendProtocol(model_path, device_name, **kwargs)

Bases: Generic[BatchT], Protocol

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

half_precision

load

name

precision

predict

supports_cow

supports_encoding

unload
copy_from_device(inference_result)
Return type:

ndarray

copy_to_device(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

encode(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

half_precision(inference_result)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

load()
Return type:

None

property n_species: int
classmethod name()
Return type:

str

classmethod precision()
Return type:

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

predict(batch)
Return type:

TypeVar(BatchT, ndarray, Tensor, TorchTensor)

classmethod supports_cow()
Return type:

bool

classmethod supports_encoding()
Return type:

bool

unload()
Return type:

None

class birdnet.core.backends.VersionedGeoBackendProtocol(model_path, device_name, **kwargs)

Bases: VersionedBackendProtocol, Protocol

Attributes:
n_species

Methods

copy_from_device

copy_to_device

encode

half_precision

load

name

precision

predict

supports_cow

supports_encoding

unload

year_round_week_inputs
classmethod year_round_week_inputs()
Return type:

tuple[float, ...]

birdnet.core.backends.disable_tf_logging()
Return type:

None

birdnet.core.backends.import_tf()
Return type:

None

birdnet.core.backends.litert_installed()
Return type:

bool

birdnet.core.backends.load_lib_litert_model(model_path, allocate_tensors=False)
Return type:

LiteRTInterpreter

birdnet.core.backends.load_lib_tf_model(model_path, allocate_tensors=False)
Return type:

TFInterpreter

birdnet.core.backends.load_onnx_model(model_path, device)
Return type:

ort.InferenceSession

birdnet.core.backends.load_pb_model(model_path, logical_device_name)
Return type:

Any

birdnet.core.backends.load_pb_model_legacy(model_path, device)
Return type:

Any

birdnet.core.backends.load_tf_model(model_path, library, allocate_tensors=False)
birdnet.core.backends.load_torch_model(model_path, device)
Return type:

RecursiveScriptModule

birdnet.core.backends.onnxruntime_installed()
Return type:

bool

birdnet.core.backends.set_cpu_device_tf()
Return type:

str

birdnet.core.backends.set_gpu_device_tf(device, memory_growth)
Return type:

str

birdnet.core.backends.set_torch_device(device)
Return type:

TorchDevice

birdnet.core.backends.tf_installed()
Return type:

bool

birdnet.core.backends.torch_installed()
Return type:

bool

birdnet.core.base module

class birdnet.core.base.ModelBase(model_path, species_list, is_custom_model)

Bases: ABC

Attributes:
is_custom_model
model_path
n_species
species_list

Methods

load

load_custom

predict

predict_session
property is_custom_model: bool
abstractmethod classmethod load(*args, **kwargs)
Return type:

Self

abstractmethod classmethod load_custom(*args, **kwargs)
Return type:

Self

property model_path: Path
property n_species: int
abstractmethod predict(*args, **kwargs)
Return type:

ResultBase

abstractmethod predict_session(*args, **kwargs)
Return type:

SessionBase

property species_list: OrderedSet[str]
class birdnet.core.base.ResultBase(model_path, model_version, model_precision)

Bases: ABC

Attributes:
memory_size_MiB
model_path
model_precision
model_version

Methods

load

save
classmethod load(path)
Return type:

Self

property memory_size_MiB: float
property model_path: Path
property model_precision: str
property model_version: str
save(npz_out_path, /, *, compress=True)
Return type:

None

class birdnet.core.base.SessionBase

Bases: ABC

Methods

run
abstractmethod run(*args, **kwargs)
Return type:

ResultBase

birdnet.core.base.get_session_id()

Get a unique session ID based on the current process and thread.

Return type:

str

Example for two processes (fork):

Process 1: 53554_127397175535424_1762165676846175803 Process 2: 53555_127397175535424_1762165676846559511

Example for two processes (spawn):

Process 1: 54155_126834937165632_1762165717644505438 Process 2: 54154_132842492557120_1762165717644777865

Example for two threads in the same process:

Thread 1: 53142_138235445503680_1762165643891762916 Thread 2: 53142_138235453896384_1762165653498085145

Example for same thread and process but different calls:

Call 1: 50179_128078941120320_1762165462208616340 Call 2: 50179_128078941120320_1762165485281125126

birdnet.core.base.get_session_id_hash(session_id)
Return type:

str

birdnet_benchmark.cli module

class birdnet_benchmark.cli.BenchmarkResultContainer(ns, model, output=None, stats=None)

Bases: object

Attributes:
output
stats
model: AcousticModelBase
ns: Namespace
output: AcousticPredictionResultBase | None = None
stats: AcousticProgressStats | None = None
birdnet_benchmark.cli.run_benchmark()
Return type:

None

birdnet_benchmark.cli.run_benchmark_from_args(args)
Return type:

None

birdnet_benchmark.cli.run_benchmark_from_ns(ns)
Return type:

None

birdnet_benchmark.cli.save_statistics(result_container)
Return type:

None

birdnet_benchmark.cli.show_progress_stats(info, result_container)
Return type:

None

birdnet.globals module

birdnet.utils.helper module

class birdnet.utils.helper.ModelInfo(dl_url, dl_size, file_size, dl_file_name)

Bases: object

dl_file_name: str
dl_size: int
dl_url: str
file_size: int
birdnet.utils.helper.apply_speed_to_duration(duration_s, speed)
Return type:

float

birdnet.utils.helper.apply_speed_to_samples(samples, speed)
Return type:

int

birdnet.utils.helper.assert_queue_is_empty(queue)
Return type:

None

birdnet.utils.helper.bandpass_signal(audio_signal, rate, fmin, fmax, new_fmin, new_fmax)
Return type:

GenericAlias[float32]

birdnet.utils.helper.check_is_intel_macos()
Return type:

bool

birdnet.utils.helper.check_is_python_312()
Return type:

bool

birdnet.utils.helper.check_protobuf_model_files_exist(folder)
Return type:

bool

birdnet.utils.helper.download_file_tqdm(url, file_path, *, download_size=None, description=None)
Return type:

int

birdnet.utils.helper.duration_as_samples(duration_s, sample_rate)
Return type:

int

birdnet.utils.helper.fillup_with_silence(audio_segment, target_length)
Return type:

GenericAlias[float32]

birdnet.utils.helper.flat_sigmoid_logaddexp_fast(x, sensitivity, clip_val=15.0, bias=1.0)
Return type:

TypeAliasType

birdnet.utils.helper.format_input_for_csv(input_value)
Return type:

str

birdnet.utils.helper.get_file_formats(file_paths)
Return type:

str

birdnet.utils.helper.get_float_dtype(max_value)

Magnitude-based: returns the smallest float dtype whose range covers max_value. Use for bulk arrays where memory matters and per-element rounding is acceptable (e.g. lists of file durations).

Return type:

TypeAliasType

birdnet.utils.helper.get_hash(session_id)
Return type:

str

birdnet.utils.helper.get_hop_duration_s(segment_size_s, overlap_duration_s, speed)
Return type:

float

birdnet.utils.helper.get_lossless_float_dtype(value)
Return type:

dtype

birdnet.utils.helper.get_n_segments_speed(duration_s, segment_size_s, overlap_duration_s, speed)
Return type:

int

birdnet.utils.helper.get_species_from_file(species_file, /, *, encoding='utf8')
Return type:

OrderedSet[str]

birdnet.utils.helper.get_supported_audio_files_recursive(folder)
Return type:

Generator[Path, None, None]

birdnet.utils.helper.get_uint_dtype(max_value)

Return the narrowest unsigned-integer NumPy dtype that can represent max_value (inclusive).

Return type:

dtype

Notes

2**8 = 256 2**16 = 65,536 2**32 = 4,294,967,296 2**64 = 18,446,744,073,709,551,616

Examples

>>> get_uint_dtype(100)
dtype('uint8')
>>> get_uint_dtype(42_000)
dtype('uint16')
>>> get_uint_dtype(3_000_000_000)
dtype('uint64')
birdnet.utils.helper.hms_centis_fast(v)
Return type:

str

birdnet.utils.helper.is_supported_audio_file(file_path)
Return type:

bool

birdnet.utils.helper.itertools_batched(iterable, n)
Return type:

Generator[Any, None, None]

birdnet.utils.helper.max_value_for_uint_dtype(dtype)

Returns the maximum value that can be represented by the given NumPy dtype.

Return type:

int

birdnet.utils.helper.uint_ctype_from_dtype(dtype)
Return type:

c_ubyte | c_ushort | c_uint | c_ulong

birdnet.utils.helper.uint_dtype_for_files(n_files)
Return type:

dtype

birdnet.utils.helper.upgrade_float_dtype_for_value(dtype, value)
Return type:

dtype

birdnet.utils.helper.validate_species_list(species_list)
Return type:

OrderedSet[str]

birdnet.utils.helper.xget_max_n_segments(max_duration_s, segment_size_s, overlap_duration_s)
Return type:

int

birdnet.utils.local_data module

birdnet.utils.local_data.get_app_data_path()
Return type:

Path

birdnet.utils.local_data.get_benchmark_dir(model, dir_name)
Return type:

Path

birdnet.utils.local_data.get_birdnet_app_data_folder()
Return type:

Path

birdnet.utils.local_data.get_lang_dir(model, version, backend)
Return type:

Path

birdnet.utils.local_data.get_model_path(model, version, backend, precision)
Return type:

Path

birdnet.utils.local_data.get_model_root_dir(model, version, backend)
Return type:

Path

birdnet.utils.local_data.get_package_version()
Return type:

str

birdnet.utils.logging_utils module

birdnet.utils.logging_utils.get_logger_for_package(name)
Return type:

Logger

birdnet.utils.logging_utils.get_package_logger()
Return type:

Logger

birdnet.utils.logging_utils.get_package_logging_level()
Return type:

int

birdnet.utils.logging_utils.init_package_logger(logging_level)
Return type:

None

birdnet.model_loader module

Module for loading models. Provides functions to load official and custom models.

birdnet.model_loader.load(model_type, version, backend, /, *, precision='fp32', lang='en_us', **model_kwargs)
Return type:

ModelBase

birdnet.model_loader.load_custom(model_type, version, backend, model, species_list, /, *, precision='fp32', check_validity=True, **model_kwargs)
Return type:

ModelBase

birdnet.model_loader.load_perch_v2(device)
Return type:

AcousticModelPerchV2

birdnet.acoustic.inference.core.shm module

class birdnet.acoustic.inference.core.shm.RingField(name, dtype, shape)

Bases: object

Attributes:
dtype
name
nbytes
shape

Methods

attach_shared_memory()

Attaches to an existing shared memory segment with the specified name.

attach_and_get_array

cleanup

get_array
attach_and_get_array()
Return type:

tuple[SharedMemory, ndarray]

attach_shared_memory()

Attaches to an existing shared memory segment with the specified name.

Return type:

SharedMemory

cleanup(session_id)
Return type:

None

dtype: dtype
get_array(shm)
Return type:

ndarray

name: str
property nbytes: int
shape: tuple[int, ...]
birdnet.acoustic.inference.core.shm.create_shm_ring(session_id, ring)
Return type:

SharedMemory

birdnet.utils module

Module contents

class birdnet.AcousticDataEncodingResult(tensor, input_durations, segment_duration_s, overlap_duration_s, speed, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version)

Bases: AcousticEncodingResultBase

Attributes:
emb_dim

Return the embedding dimensionality.

embeddings

Return the raw embedding tensor produced by the encoder.

embeddings_masked

Return the mask that marks relevant segments across files.

hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments

Return the maximum segment count reserved per input.

memory_size_MiB

Return the total result memory usage including embeddings buffers.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

speed

Speed multiplier that was applied to the inputs.

Methods

to_arrow_table()

Produce a PyArrow table that serializes each embedding with timing metadata.

to_csv(path, *[, encoding, buffer_size_kb, ...])

Dump the structured embeddings to a CSV file for downstream analysis.

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

to_structured_array()

Convert the embeddings and timing metadata into a structured array.

unprocessable_inputs()

Return the indices of inputs that could not be processed.

load

save
class birdnet.AcousticDataPredictionResult(tensor, species_list, input_durations, segment_duration_s, overlap_duration_s, speed, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version)

Bases: AcousticPredictionResultBase

Attributes:
hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments
memory_size_MiB

Memory usage for the base result metadata.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

n_species
overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

species_ids
species_list
species_masked
species_probs
speed

Speed multiplier that was applied to the inputs.

top_k
unprocessable_inputs

Methods

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

load

save

to_arrow_table

to_csv

to_structured_array
class birdnet.AcousticEncodingResultBase(inputs, input_durations, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version, segment_duration_s, overlap_duration_s, speed, tensor)

Bases: AcousticResultBase

Attributes:
emb_dim

Return the embedding dimensionality.

embeddings

Return the raw embedding tensor produced by the encoder.

embeddings_masked

Return the mask that marks relevant segments across files.

hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments

Return the maximum segment count reserved per input.

memory_size_MiB

Return the total result memory usage including embeddings buffers.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

speed

Speed multiplier that was applied to the inputs.

Methods

to_arrow_table()

Produce a PyArrow table that serializes each embedding with timing metadata.

to_csv(path, *[, encoding, buffer_size_kb, ...])

Dump the structured embeddings to a CSV file for downstream analysis.

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

to_structured_array()

Convert the embeddings and timing metadata into a structured array.

unprocessable_inputs()

Return the indices of inputs that could not be processed.

load

save
property emb_dim: int

Return the embedding dimensionality.

Returns:

int: Number of coefficients per embedding vector.

property embeddings: ndarray

Return the raw embedding tensor produced by the encoder.

Returns:

np.ndarray: Embeddings with shape (n_inputs, n_segments, emb_dim).

property embeddings_masked: ndarray

Return the mask that marks relevant segments across files.

Returns:

np.ndarray: Boolean mask of the same shape as embeddings.

property max_n_segments: int

Return the maximum segment count reserved per input.

Returns:

int: Number of overlapping windows available per file.

property memory_size_MiB: float

Return the total result memory usage including embeddings buffers.

Returns:

float: Memory size in mebibytes.

to_arrow_table()

Produce a PyArrow table that serializes each embedding with timing metadata.

Return type:

Table

Returns:

pa.Table: Table containing dictionary-encoded inputs and embeddings lists.

to_csv(path, *, encoding='utf-8', buffer_size_kb=1024, silent=False)

Dump the structured embeddings to a CSV file for downstream analysis.

Return type:

None

Args:

path: File path where the CSV will be written (must end with .csv). encoding: Text encoding for the output file. buffer_size_kb: Buffer size used when writing the file. silent: Suppress progress messages when True.

to_structured_array()

Convert the embeddings and timing metadata into a structured array.

Return type:

ndarray

Returns:

np.ndarray: Array with fields for input path, start/end times, and embedding.

unprocessable_inputs()

Return the indices of inputs that could not be processed.

Return type:

ndarray

Returns:

np.ndarray: Boolean mask or indices for skipped inputs.

class birdnet.AcousticEncodingSession(species_list, model_path, model_segment_size_s, model_sample_rate, model_is_custom, model_sig_fmin, model_sig_fmax, model_version, model_backend_type, model_backend_custom_kwargs, model_emb_dim, *, n_producers, n_workers, batch_size, prefetch_ratio, overlap_duration_s, speed, bandpass_fmin, bandpass_fmax, half_precision, max_audio_duration_min, show_stats, progress_callback, device, max_n_files)

Bases: AcousticSessionBase

Methods

cancel

end

run

run_arrays
run(inputs)
Return type:

AcousticFileEncodingResult

run_arrays(inputs)
Return type:

AcousticDataEncodingResult

class birdnet.AcousticFileEncodingResult(tensor, files, file_durations, segment_duration_s, overlap_duration_s, speed, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version)

Bases: AcousticEncodingResultBase

Attributes:
emb_dim

Return the embedding dimensionality.

embeddings

Return the raw embedding tensor produced by the encoder.

embeddings_masked

Return the mask that marks relevant segments across files.

hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments

Return the maximum segment count reserved per input.

memory_size_MiB

Return the total result memory usage including embeddings buffers.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

speed

Speed multiplier that was applied to the inputs.

Methods

to_arrow_table()

Produce a PyArrow table that serializes each embedding with timing metadata.

to_csv(path, *[, encoding, buffer_size_kb, ...])

Dump the structured embeddings to a CSV file for downstream analysis.

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

to_structured_array()

Convert the embeddings and timing metadata into a structured array.

unprocessable_inputs()

Return the indices of inputs that could not be processed.

load

save
class birdnet.AcousticFilePredictionResult(tensor, files, species_list, file_durations, segment_duration_s, overlap_duration_s, speed, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version)

Bases: AcousticPredictionResultBase

Attributes:
hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments
memory_size_MiB

Memory usage for the base result metadata.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

n_species
overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

species_ids
species_list
species_masked
species_probs
speed

Speed multiplier that was applied to the inputs.

top_k
unprocessable_inputs

Methods

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

get_unprocessed_files

load

save

to_arrow_table

to_csv

to_structured_array
get_unprocessed_files()
Return type:

set[Path]

class birdnet.AcousticModelPerchV2(model_path, species_list, is_custom_model, backend_type, backend_kwargs)

Bases: AcousticModelBase

Attributes:
backend_kwargs
backend_type
is_custom_model
model_path
n_species
species_list

Methods

encode(inp, /, *[, n_producers, n_workers, ...])

Run encoding with the Perch V2 model on files or paths to obtain embeddings.

encode_arrays(inp, /, *[, n_producers, ...])

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

encode_session(*[, n_producers, n_workers, ...])

Create an encoding session with explicit resource configuration.

get_version()

Return the string label that identifies the acoustic model version.

predict(inp, /, *[, top_k, n_producers, ...])

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

predict_arrays(inp, /, *[, top_k, ...])

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

predict_session(*[, top_k, n_producers, ...])

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

get_embeddings_dim

get_sample_rate

get_segment_size_s

get_segment_size_samples

get_sig_fmax

get_sig_fmin

load

load_custom
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')

Run encoding with the Perch V2 model on files or paths to obtain embeddings.

Return type:

AcousticEncodingResultBase

Args:

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.

Returns:

AcousticEncodingResultBase: Object containing embeddings for each file.

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:

AcousticEncodingResultBase

Args:

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:

AcousticEncodingResultBase: Object containing embeddings for each input array.

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)

Create an encoding session with explicit resource configuration.

Return type:

AcousticEncodingSession

Args:

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:

AcousticEncodingSession: Session capable of running encodings.

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:

ACOUSTIC_MODEL_VERSIONS: Registered enum constant for the supported version.

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, 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 on files or paths with configurable inference options.

Return type:

AcousticPredictionResultBase

Args:

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.

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:
AcousticPredictionResultBase: Object containing detected species and confidence

scores.

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

AcousticPredictionResultBase

Args:

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. 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:
AcousticPredictionResultBase: Object containing detected species and confidence

scores.

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, 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)

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

Return type:

AcousticPredictionSession

Args:

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.

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:

AcousticPredictionSession: Session capable of running predictions.

class birdnet.AcousticModelV2_4(model_path, species_list, is_custom_model, backend_type, backend_kwargs)

Bases: AcousticModelBase

Attributes:
backend_kwargs
backend_type
is_custom_model
model_path
n_species
species_list

Methods

encode(inp, /, *[, n_producers, n_workers, ...])

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

encode_arrays(inp, /, *[, n_producers, ...])

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

encode_session(*[, n_producers, n_workers, ...])

Create an encoding session with explicit resource configuration.

get_version()

Return the string label that identifies the acoustic model version.

predict(inp, /, *[, top_k, n_producers, ...])

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

predict_arrays(inp, /, *[, top_k, ...])

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

predict_session(*[, top_k, n_producers, ...])

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

get_embeddings_dim

get_sample_rate

get_segment_size_s

get_segment_size_samples

get_sig_fmax

get_sig_fmin

load

load_custom
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')

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

Return type:

AcousticEncodingResultBase

Args:

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.

Returns:

AcousticEncodingResultBase: Object containing embeddings for each file.

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

Args:

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:

AcousticEncodingResultBase: Object containing embeddings for each input array.

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)

Create an encoding session with explicit resource configuration.

Return type:

AcousticEncodingSession

Args:

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:

AcousticEncodingSession: Session capable of running encodings.

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:

ACOUSTIC_MODEL_VERSIONS: Registered enum constant for the supported version.

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)

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

Return type:

AcousticPredictionResultBase

Args:

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.

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:
AcousticPredictionResultBase: Object containing detected species and confidence

scores.

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)

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

Return type:

AcousticPredictionResultBase

Args:

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. 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:
AcousticPredictionResultBase: Object containing detected species and confidence

scores.

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)

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

Return type:

AcousticPredictionSession

Args:

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.

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:

AcousticPredictionSession: Session capable of running predictions.

class birdnet.AcousticPredictionResultBase(inputs, input_durations, model_path, model_fmin, model_fmax, model_sr, model_precision, model_version, species_list, segment_duration_s, overlap_duration_s, speed, tensor)

Bases: AcousticResultBase

Attributes:
hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

max_n_segments
memory_size_MiB

Memory usage for the base result metadata.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

n_species
overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

species_ids
species_list
species_masked
species_probs
speed

Speed multiplier that was applied to the inputs.

top_k
unprocessable_inputs

Methods

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

load

save

to_arrow_table

to_csv

to_structured_array
property max_n_segments: int
property memory_size_MiB: float

Memory usage for the base result metadata.

Returns:

float: Memory used by metadata buffers in mebibytes.

property n_species: int
property species_ids: ndarray
property species_list: ndarray
property species_masked: ndarray
property species_probs: ndarray
to_arrow_table()
Return type:

Table

to_csv(path, *, encoding='utf-8', buffer_size_kb=1024, silent=False)
Return type:

None

to_structured_array()
Return type:

ndarray

property top_k: int
property unprocessable_inputs: ndarray
class birdnet.AcousticPredictionSession(species_list, model_path, model_segment_size_s, model_sample_rate, model_is_custom, model_sig_fmin, model_sig_fmax, model_version, model_backend_type, model_backend_custom_kwargs, *, top_k, n_producers, n_workers, batch_size=1, prefetch_ratio=1, overlap_duration_s, speed, bandpass_fmin, bandpass_fmax, apply_sigmoid, sigmoid_sensitivity, default_confidence_threshold, custom_confidence_thresholds, custom_species_list, half_precision=True, max_audio_duration_min, show_stats, progress_callback, device, max_n_files)

Bases: AcousticSessionBase

Methods

cancel

end

run

run_arrays
run(inputs)
Return type:

AcousticFilePredictionResult

run_arrays(inputs)
Return type:

AcousticDataPredictionResult

class birdnet.AcousticProgressStats(finished, buffer_stats, producer_stats, worker_stats, wall_time_s, memory_usage_MiB, memory_usage_max_MiB, cpu_usage_pct, cpu_usage_max_pct, progress_pct, est_remaining_time_s, processed_segments, processed_batches, total_segments, speed_xrt, speed_seg_per_s)

Bases: object

Attributes:
est_remaining_time_hhmmss
buffer_stats: BufferStats
cpu_usage_max_pct: float
cpu_usage_pct: float
property est_remaining_time_hhmmss: str | None
est_remaining_time_s: float | None
finished: bool
memory_usage_MiB: float
memory_usage_max_MiB: float
processed_batches: int
processed_segments: int
producer_stats: ProducerStats
progress_pct: float
speed_seg_per_s: float | None
speed_xrt: float | None
total_segments: int | None
wall_time_s: float
worker_stats: WorkerStats | None
class birdnet.GeoModelV2_4(model_path, species_list, is_custom_model, backend_type, backend_kwargs)

Bases: GeoModelBase

Attributes:
backend_kwargs
backend_type
is_custom_model
model_path
n_species
species_list

Methods

get_model_type

get_version

load

load_custom

predict

predict_session
classmethod get_model_type()
Return type:

Literal['acoustic', 'geo']

classmethod get_version()
Return type:

Literal['2.4', '3.0']

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

GeoModelV2_4

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

GeoModelV2_4

predict(latitude, longitude, /, *, week=None, year_round_aggregation='max', min_confidence=0.03, half_precision=False, device='CPU')
Return type:

GeoPredictionResult

predict_session(*, min_confidence=0.03, half_precision=False, device='CPU')
Return type:

GeoPredictionSession

class birdnet.GeoPredictionResult(model_path, model_version, model_precision, latitude, longitude, week, species_masked, species_ids, species_probs, species_list)

Bases: ResultBase

Attributes:
latitude
longitude
memory_size_MiB
model_path
model_precision
model_version
n_species
species_ids
species_list
species_masked
species_probs
week

Methods

load

save

to_arrow_table

to_csv

to_dataframe

to_set

to_structured_array

to_txt
property latitude: int
property longitude: int
property memory_size_MiB: float
property n_species: int
property species_ids: ndarray
property species_list: ndarray
property species_masked: ndarray
property species_probs: ndarray
to_arrow_table(sort_by='species')
Return type:

Table

to_csv(csv_out_path, sort_by='species', encoding='utf8')
Return type:

None

to_dataframe(sort_by='species')
Return type:

DataFrame

to_set()
Return type:

set[str]

to_structured_array(sort_by='species')
Return type:

ndarray

to_txt(txt_out_path, sort_by='species', encoding='utf8')
Return type:

None

property week: int
class birdnet.GeoPredictionSession(species_list, model_path, model_is_custom, model_version, model_backend_type, model_backend_custom_kwargs, *, min_confidence, half_precision, device)

Bases: GeoSessionBase

Methods

run
run(latitude, longitude, /, *, week=None, year_round_aggregation='max')
Return type:

GeoPredictionResult

birdnet.get_package_logger()
Return type:

Logger

birdnet.load(model_type, version, backend, /, *, precision='fp32', lang='en_us', **model_kwargs)
Return type:

ModelBase

birdnet.load_custom(model_type, version, backend, model, species_list, /, *, precision='fp32', check_validity=True, **model_kwargs)
Return type:

ModelBase

birdnet.load_perch_v2(device)
Return type:

AcousticModelPerchV2