birdnet.acoustic.models.v3_0 package

Submodules

birdnet.acoustic.models.v3_0.model module

class birdnet.acoustic.models.v3_0.model.AcousticDownloaderBaseV3_0

Bases: object

AVAILABLE_LANGUAGES: OrderedSet[str] = OrderedSet(['bg', 'ca', 'cs', 'cy', 'da', 'de', 'en_us', 'es', 'es_ec', 'es_es', 'es_mx', 'fa', 'fi', 'fr', 'hr', 'ja', 'lt', 'nl', 'no', 'pl', 'pt', 'pt_pt', 'ru', 'sk', 'sr', 'sv', 'tr', 'uk', 'zh'])

classmethod ensure_labels_available()

Return type:

None

classmethod get_lang_file(lang)

Return type:

Path

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

Return type:

AcousticEncodingResultBase

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

Return type:

AcousticEncodingResultBase

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

Return type:

AcousticEncodingSession

final classmethod get_embeddings_dim()

Return type:

int

final classmethod get_sample_rate()

Return type:

int

final classmethod get_segment_size_s()

Return type:

float

final classmethod get_segment_size_samples()

Return type:

int

final classmethod get_sig_fmax()

Return type:

int

final classmethod get_sig_fmin()

Return type:

int

final classmethod get_version()

Return the string label that identifies the acoustic model version.

Return type:

Literal['2.4', '3.0']

Returns:

Registered enum constant for the supported version.

Return type:

ACOUSTIC_MODEL_VERSIONS

classmethod load(model_path, species_list, backend_type, backend_kwargs)

Return type:

AcousticModelV3_0

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

Return type:

AcousticModelV3_0

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 probabilities 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 probabilities either way. sigmoid_sensitivity values other than 1.0 and apply_softmax=True raise a ValueError, because both need the logits the exports do not expose. Custom V3.0 models are expected to output probabilities as well.

n_workers sets the number of inference worker processes. Its default value, 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. 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.

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:

AcousticPredictionResultBase

predict_arrays(inp, /, *, top_k=5, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, bandpass_fmin=0, bandpass_fmax=15000, speed=1.0, apply_sigmoid=True, 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)

Return type:

AcousticPredictionResultBase

predict_session(*, top_k=5, n_producers=1, n_workers=None, batch_size=1, prefetch_ratio=1, overlap_duration_s=0, speed=1.0, bandpass_fmin=0, bandpass_fmax=15000, apply_sigmoid=True, 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, show_stats=None, progress_callback=None, device='CPU', max_n_files=65536, segment_size_s=3.0, on_file_complete=None)

Create a prediction session for the BirdNET 3.0 model.

Scores: every V3.0 export (tf, pb, pt, onnx — official and custom alike) applies the sigmoid inside the model graph, so scores leave the model as probabilities. apply_sigmoid=True (the default) returns them unchanged — no second sigmoid is applied — and apply_sigmoid=False returns the identical raw model output. Because the model does not expose logits, sigmoid_sensitivity values other than 1.0 and apply_softmax=True raise a ValueError.

Return type:

AcousticPredictionSession

birdnet.acoustic.models.v3_0.pb module

class birdnet.acoustic.models.v3_0.pb.AcousticPBBackendFP32V3_0(model_path, device_name, half_precision, **kwargs)

Bases: PBBackend, VersionedAcousticBackendProtocol

classmethod encoding_key()

Return type:

str | None

classmethod encoding_signature_name()

Return type:

str | None

classmethod input_key()

Return type:

str

classmethod precision()

Return type:

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

classmethod prediction_key()

Return type:

str

classmethod prediction_signature_name()

Return type:

str

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.pb.AcousticPBDownloaderV3_0

Bases: AcousticDownloaderBaseV3_0

classmethod get_model_path_and_labels(lang)

Return type:

tuple[Path, OrderedSet[str]]

birdnet.acoustic.models.v3_0.tf module

class birdnet.acoustic.models.v3_0.tf.AcousticTFBackendFP16V3_0(model_path, device_name, half_precision, **kwargs)

Bases: TFBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()

Return type:

int | None

classmethod in_idx()

Return type:

int

classmethod precision()

Return type:

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

classmethod prediction_out_idx()

Return type:

int

classmethod probe_input_size_samples()

Return type:

int

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.tf.AcousticTFBackendFP32V3_0(model_path, device_name, half_precision, **kwargs)

Bases: TFBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()

Return type:

int | None

classmethod in_idx()

Return type:

int

classmethod precision()

Return type:

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

classmethod prediction_out_idx()

Return type:

int

classmethod probe_input_size_samples()

Return type:

int

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.tf.AcousticTFDownloaderV3_0

Bases: AcousticDownloaderBaseV3_0

classmethod get_model_path_and_labels(lang, precision)

Return type:

tuple[Path, OrderedSet[str]]

birdnet.acoustic.models.v3_0.pt module

class birdnet.acoustic.models.v3_0.pt.AcousticPTBackendFP32V3_0(model_path, device_name, half_precision, **kwargs)

Bases: TorchBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()

Return type:

int | None

classmethod precision()

Return type:

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

classmethod prediction_out_idx()

Return type:

int

classmethod probe_input_size_samples()

Return type:

int

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.pt.AcousticPTDownloaderV3_0

Bases: AcousticDownloaderBaseV3_0

classmethod get_model_path_and_labels(lang, precision)

Return type:

tuple[Path, OrderedSet[str]]

birdnet.acoustic.models.v3_0.onnx module

class birdnet.acoustic.models.v3_0.onnx.AcousticOnnxBackendFP16V3_0(model_path, device_name, half_precision, **kwargs)

Bases: OnnxBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()

Return type:

int | None

classmethod precision()

Return type:

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

classmethod prediction_out_idx()

Return type:

int

classmethod probe_input_size_samples()

Return type:

int

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.onnx.AcousticOnnxBackendFP32V3_0(model_path, device_name, half_precision, **kwargs)

Bases: OnnxBackend, VersionedAcousticBackendProtocol

classmethod encoding_out_idx()

Return type:

int | None

classmethod precision()

Return type:

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

classmethod prediction_out_idx()

Return type:

int

classmethod probe_input_size_samples()

Return type:

int

classmethod supports_encoding()

Return type:

bool

class birdnet.acoustic.models.v3_0.onnx.AcousticOnnxDownloaderV3_0

Bases: AcousticDownloaderBaseV3_0

classmethod get_model_path_and_labels(lang, precision)

Return type:

tuple[Path, OrderedSet[str]]

Module contents