birdnet.acoustic.models.perch_v2 package

Submodules

birdnet.acoustic.models.perch_v2.model module

class birdnet.acoustic.models.perch_v2.model.AcousticModelPerchV2(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 Perch V2 model on files or paths to obtain embeddings.

Return type:

AcousticEncodingResultBase

Parameters:

  • inp – Path(s) or string(s) pointing to audio files to encode.

  • n_producers – Threads tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • on_file_complete – Optional callback fired once per input file as soon as that file is fully processed, receiving a single-file AcousticFileEncodingResult (invalid files are reported with their input marked unprocessable). Enables streaming per-file persistence. Invoked from a background thread with a copy of the caller’s context; file inputs only (not encode_arrays). A callback that raises cancels the run.

Returns:

Object containing embeddings for each file.

Return type:

AcousticEncodingResultBase

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

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

Return type:

AcousticEncodingResultBase

Parameters:

  • inp – Tuple(s) of (audio ndarray, sampling rate).

  • n_producers – Threads generating batches from the arrays.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

Returns:

Object containing embeddings for each input array.

Return type:

AcousticEncodingResultBase

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

Create an encoding session with explicit resource configuration.

Return type:

AcousticEncodingSession

Parameters:

  • species_list – Ordered species collection used during the session.

  • model_path – Path to the acoustic model binary.

  • n_producers – Threads tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • half_precision – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • max_n_files – Upper bound on files to limit resource consumption.

Returns:

Session capable of running encodings.

Return type:

AcousticEncodingSession

final classmethod get_embeddings_dim()
Return type:

int

final classmethod get_sample_rate()
Return type:

int

final classmethod get_segment_size_s()
Return type:

float

final classmethod get_segment_size_samples()
Return type:

int

final classmethod get_sig_fmax()
Return type:

int

final classmethod get_sig_fmin()
Return type:

int

final classmethod get_version()

Return the string label that identifies the acoustic model version.

Return type:

Literal['2.4', '3.0']

Returns:

Registered enum constant for the supported version.

Return type:

ACOUSTIC_MODEL_VERSIONS

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

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:

AcousticPredictionResultBase

Parameters:

  • inp – Path(s) or string(s) pointing to audio files to analyze.

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

  • n_producers – Threads tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as probabilities.

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

  • sigmoid_sensitivity – Optional scale for the sigmoid function.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a probability (typical range 0 to 1); when apply_sigmoid=False it is a logit value.

  • custom_confidence_thresholds – Species-specific override thresholds.

  • custom_species_list – Path or iterable defining a subset of species.

  • half_precision – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • device – Target device(s) for running the backend.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

Returns:

Object containing detected species and confidence

scores.

Return type:

AcousticPredictionResultBase

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

AcousticPredictionResultBase

Parameters:

  • inp – Tuple(s) of (audio ndarray, sampling rate).

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

  • n_producers – Threads generating batches from the arrays.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as probabilities.

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

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

AcousticPredictionSession

Parameters:

  • species_list – Ordered species collection used during the session.

  • model_path – Path to the acoustic model binary.

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

  • n_producers – Threads tasked with producing audio batches.

  • n_workers – Optional worker count for backend processing.

  • batch_size – Number of records evaluated per inference call.

  • prefetch_ratio – How many batches to decode ahead of processing.

  • overlap_duration_s – Seconds of overlap between sliding windows.

  • bandpass_fmin – Lower bound for the bandpass filter in Hz.

  • bandpass_fmax – Upper bound for the bandpass filter in Hz.

  • speed – Resampling multiplier to accommodate different recording speeds.

  • apply_sigmoid – Whether to transform logits with a sigmoid. When False, output scores are raw logits and thresholds are interpreted in logit space rather than as probabilities.

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

  • sigmoid_sensitivity – Optional scale for the sigmoid function.

  • default_confidence_threshold – Base threshold to emit a detection. When apply_sigmoid=True this is a probability (typical range 0 to 1); when apply_sigmoid=False it is a logit value.

  • custom_confidence_thresholds – Species-specific override thresholds.

  • custom_species_list – Path or iterable defining a subset of species.

  • half_precision – Use float16 where supported for inference.

  • max_audio_duration_min – Maximum total duration per call.

  • show_stats – Level of statistics logging to emit.

  • progress_callback – Optional callback to report progress. Invoked from a background worker thread, inheriting a copy of the caller’s context (contextvars) as captured when the call starts.

  • device – Target device(s) for running the backend.

  • max_n_files – Upper bound on files to limit resource consumption.

Returns:

Session capable of running predictions.

Return type:

AcousticPredictionSession

birdnet.acoustic.models.perch_v2.pb module

class birdnet.acoustic.models.perch_v2.pb.AcousticPBBackendFP32PerchV2(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.perch_v2.pb.AcousticPBDownloaderPerchV2

Bases: object

LABELS_HEADER = 'inat2024_fsd50k'
MODEL_DOWNLOAD_SIZE_CPU = 379116813
MODEL_DOWNLOAD_SIZE_GPU = 379119624
MODEL_DOWNLOAD_URL_CPU = 'https://tuc.cloud/index.php/s/z3eo89G9MmHexG6/download'
MODEL_DOWNLOAD_URL_GPU = 'https://tuc.cloud/index.php/s/HddMnr9Lf4wdAYJ/download'
classmethod get_model_path_and_labels(device)
Return type:

tuple[Path, OrderedSet[str]]

birdnet.acoustic.models.perch_v2.pb.check_tf_version_for_perch_v2()
Return type:

None

Module contents