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- 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.
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:
- 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:
- 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:
- 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.
- 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:
ACOUSTIC_MODEL_VERSIONS: Registered enum constant for the supported version.
- classmethod load(model_path, species_list, backend_type, backend_kwargs)¶
- Return type:
- classmethod load_custom(model_path, species_list, backend_type, backend_kwargs, check_validity)¶
- Return type:
- 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:
- 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:
- 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:
- 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.
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- 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
- 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:
objectMethods
get_model_path_and_labels
- 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