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

Methods

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

Bases: object

Methods

validate_input_audio

validate_input_data

validate_input_files
filtering_conf: FilteringConfig
model_conf: ModelConfig
output_conf: OutputConfig
processing_conf: ProcessingConfig
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

Attributes:
n_species
segment_size_samples

Methods

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

Bases: object

Methods

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

Bases: SpecificConfigBase

Methods

validate_custom_confidence_thresholds

validate_custom_species_list

validate_default_confidence_threshold

validate_sigmoid_sensitivity

validate_top_k
apply_sigmoid: 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

Attributes:
n_slots

Methods

validate_batch_size

validate_device

validate_half_precision

validate_max_audio_duration_min

validate_max_n_files

validate_n_producers

validate_n_workers

validate_overlap_duration

validate_prefetch_ratio

validate_speed
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]

Methods

create_array_result

create_files_result

create_full_benchmark_meta

create_minimal_benchmark_meta

create_tensor

create_workers

get_benchmark_dir_name

save_results_extra

validate_config
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

Methods

__call__()

Call self as a function.

birdnet.acoustic.inference.prediction_strategy module

class birdnet.acoustic.inference.prediction_strategy.PredictionStrategy

Bases: InferenceStrategyBase[AcousticPredictionResultBase, PredictionConfig, AcousticPredictionTensor]

Methods

create_array_result

create_files_result

create_full_benchmark_meta

create_minimal_benchmark_meta

create_tensor

create_workers

get_benchmark_dir_name

get_top_k

save_results_extra

validate_config
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

Methods

join

join_logging

run_consumer

start

start_file_analyzer_thread

start_file_logging_thread

start_performance_tracker_process

start_processing

start_producer_processes

start_progress_dispatcher_thread

start_worker_processes

wait_until_all_finished
join()
Return type:

None

join_logging()
Return type:

None

run_consumer(result_tensor)
Return type:

None

start()
Return type:

None

start_file_analyzer_thread()
Return type:

Thread

start_file_logging_thread()
Return type:

Thread

start_performance_tracker_process()
Return type:

Process

start_processing(input_data)
Return type:

None

start_producer_processes()
Return type:

list[Process]

start_progress_dispatcher_thread()
Return type:

Thread

start_worker_processes()
Return type:

list[Process]

wait_until_all_finished()
Return type:

None

birdnet.acoustic.inference.resources module

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

Attributes:
input_durations
unprocessed_inputs

Methods

collect_input_durations

create

reset
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

Methods

create

reset
classmethod create(session_id, 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)

Bases: object

Methods

reset
analyzer_resources: InputAnalyzerResources
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

Attributes:
is_first_run
update_interval

Methods

create

increment_run_nr

reset
cancel_event: Event
classmethod create()
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

Attributes:
unprocessed_inputs

Methods

collect_unprocessed_inputs

create

reset
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

Attributes:
resources

Methods

create_resources
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

Methods

create

delete_ring_variables

reset

set_all_flags_writeable

shared_memory_context
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

Attributes:
end_timepoint
start_iso_time
stop
tracking_result

Methods

collect_performance_results

create

reset

save_end_time
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

Methods

create

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

Bases: AcousticSessionBase

Methods

cancel

end

run

run_arrays
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, 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.acoustic.inference.session.AcousticSessionBase(conf, strategy, specific_config)

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

Methods

cancel

end

run
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

Methods

create_array_result

create_files_result

create_full_benchmark_meta

create_minimal_benchmark_meta

create_tensor

create_workers

get_benchmark_dir_name

save_results_extra

validate_config
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