birdnet.acoustic.inference package

Submodules

birdnet.acoustic.inference.benchmarking module

birdnet.acoustic.inference.benchmarking.handle_statistics(session_id, config, strategy, specific_config, result, resources)
Return type:

None

birdnet.acoustic.inference.configs module

class birdnet.acoustic.inference.configs.EncodingConfig(emb_dim)

Bases: SpecificConfigBase

emb_dim: int
class birdnet.acoustic.inference.configs.FilteringConfig(bandpass_fmin, bandpass_fmax)

Bases: object

bandpass_fmax: int
bandpass_fmin: int
classmethod validate_bandpass_frequencies(bandpass_fmin, bandpass_fmax, supported_fmin, supported_fmax)
Return type:

tuple[int, int]

class birdnet.acoustic.inference.configs.InferenceConfig(model_conf, processing_conf, filtering_conf, output_conf, start_method=<factory>)

Bases: object

filtering_conf: FilteringConfig
model_conf: ModelConfig
output_conf: OutputConfig
processing_conf: ProcessingConfig
start_method: str
classmethod validate_input_audio(input_audios)
Return type:

list[tuple[TypeAliasType, int]]

classmethod validate_input_data(input_data)
Return type:

list[Path | tuple[TypeAliasType, int]]

classmethod validate_input_files(input_files)
Return type:

list[Path]

class birdnet.acoustic.inference.configs.ModelConfig(species_list, path, version, segment_size_s, sample_rate, sig_fmin, sig_fmax, is_custom, backend_type, backend_kwargs)

Bases: object

backend_kwargs: dict[str, Any]
backend_type: type[VersionedBackendProtocol]
is_custom: bool
property n_species: int
path: Path
sample_rate: int
segment_size_s: float
property segment_size_samples: int
sig_fmax: int
sig_fmin: int
species_list: OrderedSet[str]
classmethod validate_backend_supports_embeddings(backend)
Return type:

None

version: Literal['2.4', '3.0']
class birdnet.acoustic.inference.configs.OutputConfig(show_stats, progress_callback, file_completion_callback=None)

Bases: object

file_completion_callback: Callable[[Any], None] | None = None
progress_callback: Callable[[AcousticProgressStats], None] | None
show_stats: Optional[Literal['minimal', 'progress', 'benchmark']]
classmethod validate_show_stats(show_stats)
Return type:

Literal['minimal', 'progress', 'benchmark']

class birdnet.acoustic.inference.configs.PredictionConfig(top_k, default_confidence_threshold, custom_confidence_thresholds, custom_species_list, apply_sigmoid, apply_softmax, sigmoid_sensitivity)

Bases: SpecificConfigBase

apply_sigmoid: bool
apply_softmax: bool
custom_confidence_thresholds: dict[str, float] | None
custom_species_list: set[str] | None
default_confidence_threshold: float | None
sigmoid_sensitivity: float | None
top_k: int | None
classmethod validate_custom_confidence_thresholds(custom_confidence_thresholds, model_species)
Return type:

dict[str, float]

classmethod validate_custom_species_list(custom_species_list, model_species)
Return type:

set[str]

classmethod validate_default_confidence_threshold(default_confidence_threshold)
Return type:

float

classmethod validate_sigmoid_sensitivity(sigmoid_sensitivity)
Return type:

float

classmethod validate_top_k(top_k, max_value)
Return type:

int

class birdnet.acoustic.inference.configs.ProcessingConfig(producers, workers, batch_size, prefetch_ratio, overlap_duration_s, speed, half_precision, max_audio_duration_min, device, max_n_files)

Bases: object

batch_size: int
device: str | list[str]
half_precision: bool
max_audio_duration_min: float | None
max_n_files: int
property n_slots: int
overlap_duration_s: float
prefetch_ratio: int
producers: int
speed: float
classmethod validate_batch_size(batch_size)
Return type:

int

classmethod validate_device(device, workers)
Return type:

str | list[str]

classmethod validate_half_precision(half_precision)
Return type:

bool

classmethod validate_max_audio_duration_min(max_audio_duration_min)
Return type:

float

classmethod validate_max_n_files(max_n_files)
Return type:

int

classmethod validate_n_producers(n_producers)
Return type:

int

classmethod validate_n_workers(n_workers)
Return type:

int

classmethod validate_overlap_duration(overlap_duration_s, segment_size_s)
Return type:

float

classmethod validate_prefetch_ratio(prefetch_ratio)
Return type:

int

classmethod validate_speed(speed)
Return type:

float

workers: int
class birdnet.acoustic.inference.configs.SpecificConfigBase

Bases: object

birdnet.acoustic.inference.encoding_strategy module

class birdnet.acoustic.inference.encoding_strategy.EncodingStrategy

Bases: InferenceStrategyBase[AcousticEncodingResultBase, EncodingConfig, AcousticEncodingTensor]

build_single_file_result(config, file_path, arrays, is_invalid, duration_s)

Build a single-file result from already-materialised per-file arrays.

arrays is the strategy-specific tuple produced by the tensor’s copy_file_slice (predictions: species ids/probs/masked; encodings: embeddings/mask). Used by the per-file completion dispatcher (on_file_complete).

Return type:

AcousticFileEncodingResult

create_array_result(tensor, config, resources)
Return type:

AcousticEncodingResultBase

create_files_result(tensor, config, resources, files)
Return type:

AcousticEncodingResultBase

create_full_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

FullBenchmarkEmbMeta

create_minimal_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

MinimalBenchmarkEmbMeta

create_tensor(session_id, config, specific_config, resources, n_inputs)
Return type:

AcousticEncodingTensor

create_workers(session_id, config, specific_config, resources)
Return type:

list[WorkerBase]

get_benchmark_dir_name()
Return type:

str

save_results_extra(result, benchmark_run_out_dir, prepend)
Return type:

list[Path]

validate_config(config, specific_config)
Return type:

None

birdnet.acoustic.inference.file_writer module

class birdnet.acoustic.inference.file_writer.QueueFileWriter(session_id, log_queue, logging_level, log_file, cancel_event, stop_event, processing_finished_event)

Bases: object

birdnet.acoustic.inference.prediction_strategy module

class birdnet.acoustic.inference.prediction_strategy.PredictionStrategy

Bases: InferenceStrategyBase[AcousticPredictionResultBase, PredictionConfig, AcousticPredictionTensor]

build_single_file_result(config, file_path, arrays, is_invalid, duration_s)

Build a single-file result from already-materialised per-file arrays.

arrays is the strategy-specific tuple produced by the tensor’s copy_file_slice (predictions: species ids/probs/masked; encodings: embeddings/mask). Used by the per-file completion dispatcher (on_file_complete).

Return type:

AcousticFilePredictionResult

create_array_result(tensor, config, resources)
Return type:

AcousticPredictionResultBase

create_files_result(tensor, config, resources, files)
Return type:

AcousticPredictionResultBase

create_full_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

FullBenchmarkMeta

create_minimal_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

MinimalBenchmarkMeta

create_tensor(session_id, config, specific_config, resources, n_inputs)
Return type:

AcousticPredictionTensor

create_workers(session_id, config, specific_config, resources)
Return type:

list[WorkerBase]

get_benchmark_dir_name()
Return type:

str

get_top_k(config, specific_config)
Return type:

int

save_results_extra(result, benchmark_run_out_dir, prepend)
Return type:

list[Path]

validate_config(config, specific_config)
Return type:

None

birdnet.acoustic.inference.prediction_strategy.create_species_blacklist(config, pred_config)

Setup species filtering logic

Return type:

TypeAliasType

birdnet.acoustic.inference.prediction_strategy.create_thresholds(config, pred_conf)
Return type:

TypeAliasType

birdnet.acoustic.inference.process_manager module

class birdnet.acoustic.inference.process_manager.ProcessManager(session_id, config, strategy, specific_config, resources)

Bases: object

property child_death_error: ChildProcessError | None

Set when a child was found dead; the session surfaces it to the caller.

close_queues()

Release the parent’s handles on the multiprocessing queues.

Call once during teardown, after all child processes and the logging thread have been joined. Closing is non-blocking (cancel_join_thread first, so close never waits on a feeder) and lets the OS reclaim the pipes and semaphores promptly instead of leaving it to garbage collection – which the caller may skip entirely (e.g. os._exit).

A queue whose drainer is still wedged is skipped; see _collect_wedged_drainers for why closing it would be worse than leaking it.

Return type:

None

join()
Return type:

None

join_logging()

Wait for the log writer, but never on something that cannot finish.

The writer reads the shared logging queue with a blocking get, and a child killed mid-put leaves a message whose remainder never arrives: the read then blocks for good, with no exception to catch, exactly as on the cancel-path drain (issue #77). It is a daemon thread, so leaving it parked costs the tail of the session log and nothing else – whereas waiting on it costs the whole teardown.

Return type:

None

raise_if_child_died()

Fail fast when a child process is gone without having signalled.

Every parent-side wait in a healthy run is unbounded on purpose: the run takes as long as the audio requires. That only holds while the children are actually working. A child killed by the OOM killer, or dying in a native crash during its TensorFlow import, never sets its finish signal and never puts its sentinel on the results queue, so an unbounded wait would block forever with no output at all. Checking liveness turns that silent hang into an error naming the process.

A process that exited after setting its finish signal is not an error: that is the normal end-of-session shutdown path.

Marks the run cancelled before raising. The cancel event is what routes teardown through _join_processes_after_cancel, which drains the child-to-parent queues while joining; the plain path assumes every child still delivers its buffered data, which a dead one never will. Setting it here keeps both callers consistent – the consumer would set it via its own exception handler, wait_until_all_finished has no such handler.

The error is also stored so the session can surface it to the caller: the consumer’s broad except Exception swallows it into a generic “cancelled”, and the process name and exit code are the only actionable part.

Return type:

None

run_consumer(result_tensor, inputs=None, *, completion_active=False)
Return type:

None

start()
Return type:

None

start_file_analyzer_thread()
Return type:

Thread

start_file_completion_dispatcher_thread()
Return type:

Thread

start_file_logging_thread()
Return type:

Thread

start_performance_tracker_process()
Return type:

BaseProcess

start_processing(input_data)
Return type:

None

start_producer_processes()
Return type:

list[BaseProcess]

start_progress_dispatcher_thread()
Return type:

Thread

start_worker_processes()
Return type:

list[BaseProcess]

wait_for_completion_dispatcher(finish_signal)

Wait for the per-file completion dispatcher, cancel- and liveness-aware.

Same guard as the finish-signal waits: this dispatcher is a thread, so a callback that raises sets the cancel event and returns without signalling.

Return type:

None

wait_until_all_finished()
Return type:

None

birdnet.acoustic.inference.resources module

class birdnet.acoustic.inference.resources.FileCompletionResources(enabled, callback_fn, marker_queue, dispatch_queue, start_signal, finish_signal)

Bases: object

Resources backing the per-file completion callback (on_file_complete).

When enabled, producers push a completion marker per file onto marker_queue (cross-process); the consumer turns those into per-file results and hands them to the dispatcher thread via the in-process dispatch_queue. All fields are None when the feature is disabled, so the pipeline pays no cost.

callback_fn: Callable[[object], None] | None
classmethod create(conf)
Return type:

FileCompletionResources

dispatch_queue: queue.Queue | None
enabled: bool
finish_signal: threading.Event | None
marker_queue: Queue | None
reset()
Return type:

None

start_signal: threading.Event | None
class birdnet.acoustic.inference.resources.InputAnalyzerResources(input_queue, analyzer_queue, tot_n_segments_ptr, max_segment_idx_ptr, max_segment_idx_init_value, finished, start_signal, finish_signal, segments_dtype, _unprocessed_inputs=None, _input_durations=None)

Bases: object

analyzer_queue: Queue
collect_input_durations()
Return type:

None

classmethod create(conf)
Return type:

InputAnalyzerResources

finish_signal: Event
finished: Event
property input_durations: ndarray
input_queue: Queue
max_segment_idx_init_value: int
max_segment_idx_ptr: RawValue
reset()
Return type:

None

segments_dtype: dtype
start_signal: Event
tot_n_segments_ptr: RawValue
property unprocessed_inputs: set[int]
class birdnet.acoustic.inference.resources.LoggingResources(session_log_file, global_log_file, logging_level, logging_queue, queue_handler, stop_logging_event)

Bases: object

classmethod create(session_id, conf, stats_resources)
Return type:

LoggingResources

global_log_file: Path
logging_level: int
logging_queue: Queue
queue_handler: QueueHandler
reset()
Return type:

None

session_log_file: Path
stop_logging_event: Event
class birdnet.acoustic.inference.resources.PipelineResources(stats_resources, logging_resources, processing_resources, analyzer_resources, producer_resources, worker_resources, ring_buffer_resources, file_completion_resources)

Bases: object

analyzer_resources: InputAnalyzerResources
file_completion_resources: FileCompletionResources
logging_resources: LoggingResources
processing_resources: ProcessingResources
producer_resources: ProducerResources
reset()
Return type:

None

ring_buffer_resources: RingBufferResources
stats_resources: StatisticsResources
worker_resources: WorkerResources
class birdnet.acoustic.inference.resources.ProcessingResources(processing_finished_event, cancel_event, end_event, current_run_nr)

Bases: object

cancel_event: Event
classmethod create(conf)
Return type:

ProcessingResources

current_run_nr: int
end_event: Event
increment_run_nr()
Return type:

None

property is_first_run: bool
processing_finished_event: Event
reset()
Return type:

None

property update_interval: float
class birdnet.acoustic.inference.resources.ProducerResources(n_producers, n_finished_pointer, all_finished, ring_access_lock, input_queue, unprocessed_inputs_queue, start_signals, finish_signals, _unprocessed_inputs=None)

Bases: object

all_finished: multiprocessing.synchronize.Event
collect_unprocessed_inputs()
Return type:

None

classmethod create(conf)
Return type:

ProducerResources

finish_signals: list[multiprocessing.synchronize.Event]
input_queue: Queue
n_finished_pointer: Synchronized[ctypes.c_uint8] | Synchronized[ctypes.c_uint16] | Synchronized[ctypes.c_uint32] | Synchronized[ctypes.c_uint64]
n_producers: int
reset()
Return type:

None

ring_access_lock: multiprocessing.synchronize.Lock
start_signals: list[multiprocessing.synchronize.Event]
property unprocessed_inputs: set[int]
unprocessed_inputs_queue: Queue
class birdnet.acoustic.inference.resources.ResourceManager(conf)

Bases: object

create_resources(session_id, benchmark_dir_name)
Return type:

PipelineResources

property resources: PipelineResources
class birdnet.acoustic.inference.resources.RingBufferResources(rf_file_indices, rf_segment_indices, rf_audio_samples, rf_batch_sizes, rf_flags, sem_free_slots, sem_filled_slots, _rf_flags_memory=None)

Bases: object

classmethod create(session_id, conf, analyzer_resources)
Return type:

RingBufferResources

delete_ring_variables()
Return type:

None

reset()
Return type:

None

rf_audio_samples: RingField
rf_batch_sizes: RingField
rf_file_indices: RingField
rf_flags: RingField
rf_segment_indices: RingField
sem_filled_slots: CountedSemaphore
sem_free_slots: Semaphore
set_all_flags_writeable()
Return type:

None

shared_memory_context(session_id)
Return type:

Iterator[None]

class birdnet.acoustic.inference.resources.StatisticsResources(start, start_time, start_timepoint, track_performance, wkr_stats_queue, prd_stats_queue, sem_active_workers, perf_res_queue, perf_res_start_signal, perf_res_finish_signal, use_callback, callback_fn, callback_queue, callback_start_signal, callback_finish_signal, benchmarking, benchmark_dir, benchmark_session_dir, benchmark_dir_name, _stop=None, _end_timepoint=None, _tracking_result=None)

Bases: object

benchmark_dir: Path | None
benchmark_dir_name: str
benchmark_session_dir: Path | None
benchmarking: bool
callback_finish_signal: threading.Event | None
callback_fn: Callable[[AcousticProgressStats], None] | None
callback_queue: Queue | None
callback_start_signal: threading.Event | None
collect_performance_results()
Return type:

None

classmethod create(session_id, conf, benchmark_dir_name)
Return type:

StatisticsResources

property end_timepoint: datetime | None
perf_res_finish_signal: multiprocessing.synchronize.Event | None
perf_res_queue: Queue | None
perf_res_start_signal: multiprocessing.synchronize.Event | None
prd_stats_queue: Queue | None
reset()
Return type:

None

save_end_time()
Return type:

None

sem_active_workers: CountedSemaphore | None
start: float
property start_iso_time: str
start_time: float
start_timepoint: datetime
property stop: float | None
track_performance: bool
property tracking_result: PerformanceTrackingResult | None
use_callback: bool
wkr_stats_queue: Queue | None
class birdnet.acoustic.inference.resources.WorkerResources(results_queue, ring_access_lock, devices, backend_loader, start_signals, finish_signals)

Bases: object

backend_loader: BackendLoader
classmethod create(config)
Return type:

WorkerResources

devices: list[str]
finish_signals: list[Event]
reset()
Return type:

None

results_queue: Queue
ring_access_lock: Lock
start_signals: list[Event]
birdnet.acoustic.inference.resources.get_iso_time(timepoint)
Return type:

str

birdnet.acoustic.inference.session module

class birdnet.acoustic.inference.session.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, on_file_complete=None)

Bases: AcousticSessionBase

run(inputs)
Return type:

AcousticFileEncodingResult

run_arrays(inputs)
Return type:

AcousticDataEncodingResult

class birdnet.acoustic.inference.session.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, apply_softmax, 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, on_file_complete=None)

Bases: AcousticSessionBase

run(inputs)
Return type:

AcousticFilePredictionResult

run_arrays(inputs)
Return type:

AcousticDataPredictionResult

class birdnet.acoustic.inference.session.AcousticSessionBase(conf, strategy, specific_config)

Bases: Generic[ResultType, ConfigType, TensorType], SessionBase, ABC

cancel()
Return type:

None

end()
Return type:

None

birdnet.acoustic.inference.strategy module

class birdnet.acoustic.inference.strategy.InferenceStrategyBase

Bases: Generic[ResultType, ConfigType, TensorType], ABC

build_single_file_result(config, file_path, arrays, is_invalid, duration_s)

Build a single-file result from already-materialised per-file arrays.

arrays is the strategy-specific tuple produced by the tensor’s copy_file_slice (predictions: species ids/probs/masked; encodings: embeddings/mask). Used by the per-file completion dispatcher (on_file_complete).

Return type:

TypeVar(ResultType, bound= ResultBase)

abstractmethod create_array_result(tensor, config, resources)
Return type:

TypeVar(ResultType, bound= ResultBase)

abstractmethod create_files_result(tensor, config, resources, files)
Return type:

TypeVar(ResultType, bound= ResultBase)

abstractmethod create_full_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

FullBenchmarkMetaBase

abstractmethod create_minimal_benchmark_meta(config, specific_config, resources, pred_result)
Return type:

MinimalBenchmarkMetaBase

abstractmethod create_tensor(session_id, config, specific_config, resources, n_inputs)
Return type:

TypeVar(TensorType, bound= AcousticTensorBase)

abstractmethod create_workers(session_id, config, specific_config, resources)
Return type:

list[WorkerBase]

abstractmethod get_benchmark_dir_name()
Return type:

str

abstractmethod save_results_extra(result, benchmark_run_out_dir, prepend)
Return type:

list[Path]

abstractmethod validate_config(config, specific_config)
Return type:

None

Module contents