birdnet.acoustic.inference.core package

Subpackages

Submodules

birdnet.acoustic.inference.core.benchmarking module

class birdnet.acoustic.inference.core.benchmarking.FullBenchmarkMetaBase(_start_timepoint, _end_timepoint, _time_wall_time_s, _file_durations, file_formats, mem_result_total_memory_usage_MiB, mem_shm_size_file_indices_MiB, mem_shm_size_segment_indices_MiB, mem_shm_size_audio_samples_MiB, mem_shm_size_batch_sizes_MiB, mem_shm_size_flags_MiB, file_segments_total, model_segment_duration_seconds, _time_rampup_first_line_s, model_type, model_backend, model_version, model_is_custom, model_path, model_species, model_sig_fmin, model_sig_fmax, model_sample_rate, model_precision, file_segments_maximum, file_batches_processed, param_producers, param_workers, param_overlap_seconds, param_batch_size, param_prefetch_ratio, param_bandpass_fmin, param_bandpass_fmax, param_half_precision, param_devices, param_inference_library, worker_busy_average, worker_wait_time_average_milliseconds, speed_worker_xrt, speed_worker_xrt_max, _worker_avg_wall_time_s, mem_shm_ringsize, mem_memory_usage_maximum_MiB, mem_memory_usage_average_MiB, cpu_usage_maximum_pct, cpu_usage_average_pct, mem_shm_slots_average_free, mem_shm_slots_average_busy, mem_shm_slots_average_buffered)

Bases: MinimalBenchmarkMetaBase

Attributes:
file_count
file_duration_average
file_duration_maximum
file_duration_minimum
file_duration_sum
hw_cpu
hw_cpu_logical_cores
hw_cpu_physical_cores
hw_host
hw_ram_GiB
mem_shm_size_total_MiB
mem_shm_slots_average_filled
speed_total_audio_per_second
speed_total_rtf
speed_total_seg_per_second
speed_total_xrt
speed_worker_rtf
speed_worker_total_audio_per_second
speed_worker_total_seg_per_second
sw_litert_available
sw_os
sw_package_version
sw_python_implementation
sw_python_version
sw_start_method
sw_tf_available
time_begin
time_end
time_iso
time_rampup_first_line
time_wall_time

Methods

to_dict
cpu_usage_average_pct: float
cpu_usage_maximum_pct: float
file_batches_processed: int
file_segments_maximum: int
property hw_cpu: str
property hw_cpu_logical_cores: int
property hw_cpu_physical_cores: int
property hw_host: str
property hw_ram_GiB: float
mem_memory_usage_average_MiB: float
mem_memory_usage_maximum_MiB: float
mem_shm_ringsize: int
mem_shm_slots_average_buffered: float
mem_shm_slots_average_busy: float
property mem_shm_slots_average_filled: float
mem_shm_slots_average_free: float
model_backend: str
model_is_custom: bool
model_path: str
model_precision: Literal['int8', 'fp16', 'fp32']
model_sample_rate: int
model_sig_fmax: int
model_sig_fmin: int
model_species: int
model_type: Literal['acoustic', 'geo']
model_version: Literal['2.4', '3.0']
param_bandpass_fmax: int
param_bandpass_fmin: int
param_batch_size: int
param_devices: str
param_half_precision: bool
param_inference_library: str | None
param_overlap_seconds: float
param_prefetch_ratio: int
param_producers: int
param_workers: int
property speed_worker_rtf: float
property speed_worker_total_audio_per_second: str
property speed_worker_total_seg_per_second: float
speed_worker_xrt: float
speed_worker_xrt_max: float
property sw_litert_available: bool
property sw_os: str
property sw_package_version: str
property sw_python_implementation: str
property sw_python_version: str
property sw_start_method: str
property sw_tf_available: bool
property time_iso: str
property time_rampup_first_line: str
to_dict()
Return type:

dict[str, Any]

worker_busy_average: float
worker_wait_time_average_milliseconds: float
class birdnet.acoustic.inference.core.benchmarking.MinimalBenchmarkMetaBase(_start_timepoint, _end_timepoint, _time_wall_time_s, _file_durations, file_formats, mem_result_total_memory_usage_MiB, mem_shm_size_file_indices_MiB, mem_shm_size_segment_indices_MiB, mem_shm_size_audio_samples_MiB, mem_shm_size_batch_sizes_MiB, mem_shm_size_flags_MiB, file_segments_total, model_segment_duration_seconds)

Bases: object

Attributes:
file_count
file_duration_average
file_duration_maximum
file_duration_minimum
file_duration_sum
mem_shm_size_total_MiB
speed_total_audio_per_second
speed_total_rtf
speed_total_seg_per_second
speed_total_xrt
time_begin
time_end
time_wall_time
property file_count: int
property file_duration_average: str
property file_duration_maximum: str
property file_duration_minimum: str
property file_duration_sum: str
file_formats: str
file_segments_total: int
mem_result_total_memory_usage_MiB: float
mem_shm_size_audio_samples_MiB: float
mem_shm_size_batch_sizes_MiB: float
mem_shm_size_file_indices_MiB: float
mem_shm_size_flags_MiB: float
mem_shm_size_segment_indices_MiB: float
property mem_shm_size_total_MiB: float
model_segment_duration_seconds: float
property speed_total_audio_per_second: str
property speed_total_rtf: float
property speed_total_seg_per_second: float
property speed_total_xrt: float
property time_begin: str
property time_end: str
property time_wall_time: str

birdnet.acoustic.inference.core.consumer module

class birdnet.acoustic.inference.core.consumer.Consumer(session_id, n_workers, worker_queue, tensor, cancel_event)

Bases: object

Methods

__call__()

Call self as a function.

birdnet.acoustic.inference.core.input_analyzer module

class birdnet.acoustic.inference.core.input_analyzer.InputAnalyzer(session_id, segment_duration_s, overlap_duration_s, speed, rf_segment_indices, max_segment_idx_ptr, input_queue, analyzing_result, tot_n_segments, cancel_event, end_event, finished, start_signal, finish_signal)

Bases: object

Methods

__call__()

Call self as a function.

run_main

run_main_loop
run_main()
Return type:

None

run_main_loop()
Return type:

None

birdnet.acoustic.inference.core.perf_tracker module

class birdnet.acoustic.inference.core.perf_tracker.AcousticProgressStats(finished, buffer_stats, producer_stats, worker_stats, wall_time_s, memory_usage_MiB, memory_usage_max_MiB, cpu_usage_pct, cpu_usage_max_pct, progress_pct, est_remaining_time_s, processed_segments, processed_batches, total_segments, speed_xrt, speed_seg_per_s)

Bases: object

Attributes:
est_remaining_time_hhmmss
buffer_stats: BufferStats
cpu_usage_max_pct: float
cpu_usage_pct: float
property est_remaining_time_hhmmss: str | None
est_remaining_time_s: float | None
finished: bool
memory_usage_MiB: float
memory_usage_max_MiB: float
processed_batches: int
processed_segments: int
producer_stats: ProducerStats
progress_pct: float
speed_seg_per_s: float | None
speed_xrt: float | None
total_segments: int | None
wall_time_s: float
worker_stats: WorkerStats | None
class birdnet.acoustic.inference.core.perf_tracker.BufferStats(slots, free_slots, busy_slots, preloaded_slots)

Bases: object

Attributes:
filled_slots
busy_slots: float
property filled_slots: float
free_slots: float
preloaded_slots: float
slots: int
class birdnet.acoustic.inference.core.perf_tracker.PerformanceTracker(session_id, pred_dur_queue, prod_stats_queue, callback_queue, processing_finished_event, update_interval, n_workers, logging_queue, logging_level, perf_res, sem_active_workers, sem_filled_slots, segment_size_s, parent_process_id, rf_flags, tot_n_segments_ptr, cancel_event, end_event, start_signal, finish_signal, start)

Bases: LogableProcessBase

Attributes:
wall_time

Methods

__call__()

Call self as a function.

reset

run_main

run_main_loop
reset()
Return type:

None

run_main()
Return type:

None

run_main_loop()
Return type:

None

property wall_time: float
class birdnet.acoustic.inference.core.perf_tracker.PerformanceTrackingResult(worker_speed_xrt, worker_speed_xrt_max, worker_avg_wall_time_s, total_segments_processed, total_batches_processed, n_usage_recordings, max_memory_usages_MiB, avg_memory_usages_MiB, max_cpu_usages_pct, avg_cpu_usages_pct, avg_free_slots, avg_busy_slots, avg_preloaded_slots, avg_busy_workers, avg_wait_time_ms)

Bases: object

avg_busy_slots: float
avg_busy_workers: float
avg_cpu_usages_pct: float
avg_free_slots: float
avg_memory_usages_MiB: float
avg_preloaded_slots: float
avg_wait_time_ms: float
max_cpu_usages_pct: float
max_memory_usages_MiB: float
n_usage_recordings: int
total_batches_processed: int
total_segments_processed: int
worker_avg_wall_time_s: float
worker_speed_xrt: float
worker_speed_xrt_max: float
class birdnet.acoustic.inference.core.perf_tracker.ProducerStats(speed_xrt, speed_seg_per_s, wait_ms, batch_ms, search_ms, flush_ms)

Bases: object

batch_ms: float
flush_ms: float
search_ms: float
speed_seg_per_s: float
speed_xrt: float
wait_ms: float
class birdnet.acoustic.inference.core.perf_tracker.ProgressDispatcher(session_id, callback_queue, callback_fn, cancel_event, end_event, start_signal, finish_signal, processing_finished_event, check_interval)

Bases: object

Methods

__call__()

Call self as a function.

get_last_stats

run_main

run_main_loop
get_last_stats()
Return type:

AcousticProgressStats | None

run_main()
Return type:

None

run_main_loop()
Return type:

None

class birdnet.acoustic.inference.core.perf_tracker.ValueTracker(n_last)

Bases: object

Attributes:
avg_val
last_val
max_val
median_val
min_val
n_vals
summed_val
vals

Methods

add_value

reset
add_value(val)
Return type:

None

property avg_val: float
property last_val: float
property max_val: float
property median_val: float
property min_val: float
property n_vals: int
reset()
Return type:

None

property summed_val: float
property vals: deque[float]
class birdnet.acoustic.inference.core.perf_tracker.WorkerStats(speed_xrt, speed_seg_per_s, wait_ms, search_ms, job_ms, copy_ms, inference_ms, add_ms, workers, busy)

Bases: object

add_ms: float
busy: float
copy_ms: float
inference_ms: float
job_ms: float
search_ms: float
speed_seg_per_s: float
speed_xrt: float
wait_ms: float
workers: int

birdnet.acoustic.inference.core.producer module

class birdnet.acoustic.inference.core.producer.Producer(session_id, input_queue, batch_size, n_slots, rf_file_indices, rf_segment_indices, rf_audio_samples, rf_batch_sizes, rf_flags, sem_free_slots, sem_filled_slots, max_segment_idx_ptr, prod_done_ptr, end_event, start_signal, finish_signal, n_producers, prd_ring_access_lock, logging_queue, logging_level, prod_stats_queue, segment_duration_s, overlap_duration_s, speed, target_sample_rate, cancel_event, all_finished, use_bandpass, bandpass_fmin, bandpass_fmax, fmin, fmax, unprocessed_inputs_queue)

Bases: LogableProcessBase

Methods

__call__()

Call self as a function.

get_segments_from_files

get_segments_from_input
get_segments_from_files()
Return type:

Generator[tuple[int, int, GenericAlias[float32]], None, None]

get_segments_from_input(input_idx, inp_data)
Return type:

Generator[tuple[int, GenericAlias[float32]], None, None]

birdnet.acoustic.inference.core.producer.calculate_target_sample_count(n_samples, sample_rate, target_sample_rate)
Return type:

int

birdnet.acoustic.inference.core.producer.convert_to_mono(audio_data)
Return type:

GenericAlias[float32]

birdnet.acoustic.inference.core.producer.get_audio_duration_from_sf(sf_info)
Return type:

float

birdnet.acoustic.inference.core.producer.get_audio_duration_s(audio_path)

Returns the duration of the audio file in seconds.

Return type:

float

birdnet.acoustic.inference.core.producer.get_audio_n_samples(audio_path)

Returns the number of samples in the audio file.

Return type:

int

birdnet.acoustic.inference.core.producer.get_audio_n_samples_from_sf(sf_info)
Return type:

int

birdnet.acoustic.inference.core.producer.get_data_segments_with_overlap(audio_array, sample_rate, segment_duration_s, overlap_duration_s, speed, target_sample_rate)
Return type:

Generator[GenericAlias[float32], None, None]

birdnet.acoustic.inference.core.producer.get_file_segments_with_overlap(audio_path, audio_n_samples, sample_rate, segment_duration_s, overlap_duration_s, speed, target_sample_rate)

Load audio in overlapping segments with optional speed change.

Return type:

Generator[GenericAlias[float32], None, None]

speed:

Speed factor for audio playback. Values < 1.0 slow down the audio, values > 1.0 speed it up.

segment_duration_s, overlap_duration_s:

Refer to the speed-adjusted playback domain. For example, with segment_duration_s=3 and target_sample_rate=48000, each yielded segment will have 3 * 48000 samples, independent of the speed setting. Changing speed only changes how many segments are produced.

birdnet.acoustic.inference.core.producer.get_sample_rate_from_sf(sf_info)
Return type:

int

birdnet.acoustic.inference.core.producer.get_segments_with_overlap(audio_n_samples, audio_sr, audio_read_fn, segment_duration_s, overlap_duration_s, speed, target_sample_rate)
Return type:

Generator[GenericAlias[float32], None, None]

birdnet.acoustic.inference.core.producer.get_segments_with_overlap_all_int(total_duration, segment_duration, overlap_duration)
Return type:

Generator[tuple[int, int], None, None]

birdnet.acoustic.inference.core.producer.get_segments_with_overlap_samples(n_samples, segment_samples, overlap_samples, speed=1.0)

returns tuples of (start_samples_scaled, end_samples_scaled, target_n_samples) samples lie in range [0, n_samples] target_n_samples is the number of samples after speed adjustment

Return type:

Generator[tuple[int, int, int], None, None]

birdnet.acoustic.inference.core.producer.get_sf_info(audio_path)

Returns the soundfile info of the audio file.

Return type:

_SoundFileInfo

birdnet.acoustic.inference.core.producer.read_data_in_mono(start_samples, end_samples, audio_data)
Return type:

GenericAlias[float32]

birdnet.acoustic.inference.core.producer.read_file_in_mono(start_samples, end_samples, audio_path)
Return type:

GenericAlias[float32]

birdnet.acoustic.inference.core.producer.resample_array_by_sr(array, sample_rate, target_sample_rate)
Return type:

TypeAliasType

birdnet.acoustic.inference.core.producer.resample_array_by_stretching(array, target_n_samples)
Return type:

TypeAliasType

birdnet.acoustic.inference.core.producer.to_float32(audio)

Convert integer or floating audio arrays to float32.

Return type:

GenericAlias[float32]

birdnet.acoustic.inference.core.result_base module

class birdnet.acoustic.inference.core.result_base.AcousticResultBase(model_path, model_version, model_precision, inputs, input_durations, segment_duration_s, overlap_duration_s, speed, model_fmin, model_fmax, model_sr)

Bases: ResultBase

Base container for shared acoustic model result metadata and helpers.

Attributes:
hop_duration_s
input_durations

Durations of each input in seconds.

inputs

Identifiers for each input processed by the result.

memory_size_MiB

Memory usage for the base result metadata.

model_fmax

Upper bound of the model’s bandpass filter.

model_fmin

Lower bound of the model’s bandpass filter.

model_path
model_precision
model_sr

Sampling rate expected by the model.

model_version
n_inputs

Number of inputs in the result payload.

overlap_duration_s

Overlap duration between sliding windows in seconds.

segment_duration_s

Segment duration as configured on the inference pipeline.

speed

Speed multiplier that was applied to the inputs.

Methods

to_dataframe()

Convert the structured array into a pandas DataFrame.

to_parquet(path, *[, compression, ...])

Write the contents to disk as an Arrow Parquet file.

load

save

to_arrow_table

to_csv

to_structured_array
property hop_duration_s: float
property input_durations: ndarray

Durations of each input in seconds.

property inputs: ndarray

Identifiers for each input processed by the result.

property memory_size_MiB: float

Memory usage for the base result metadata.

Returns:

float: Memory used by metadata buffers in mebibytes.

property model_fmax: int

Upper bound of the model’s bandpass filter.

property model_fmin: int

Lower bound of the model’s bandpass filter.

property model_sr: int

Sampling rate expected by the model.

property n_inputs: int

Number of inputs in the result payload.

property overlap_duration_s: float

Overlap duration between sliding windows in seconds.

property segment_duration_s: float

Segment duration as configured on the inference pipeline.

property speed: float

Speed multiplier that was applied to the inputs.

abstractmethod to_arrow_table()
Return type:

Table

abstractmethod to_csv(path, *, encoding='utf-8', buffer_size_kb=1024, silent=False)
Return type:

None

to_dataframe()

Convert the structured array into a pandas DataFrame.

Return type:

DataFrame

to_parquet(path, *, compression='snappy', compression_level=None, silent=False)

Write the contents to disk as an Arrow Parquet file.

Return type:

None

abstractmethod to_structured_array()
Return type:

ndarray

class birdnet.acoustic.inference.core.result_base.ModelBase(model_path, species_list, is_custom_model)

Bases: ABC

Attributes:
is_custom_model
model_path
n_species
species_list

Methods

load

load_custom

predict

predict_session
property is_custom_model: bool
abstractmethod classmethod load(*args, **kwargs)
Return type:

Self

abstractmethod classmethod load_custom(*args, **kwargs)
Return type:

Self

property model_path: Path
property n_species: int
abstractmethod classmethod predict(*args, **kwargs)
Return type:

ResultBase

abstractmethod classmethod predict_session(*args, **kwargs)
Return type:

SessionBase

property species_list: OrderedSet[str]
class birdnet.acoustic.inference.core.result_base.SessionBase

Bases: ABC

Methods

run
abstractmethod run(*args, **kwargs)
Return type:

ResultBase

birdnet.acoustic.inference.core.result_base.get_session_id()

Get a unique session ID based on the current process and thread.

Return type:

str

Example for two processes (fork):

Process 1: 53554_127397175535424_1762165676846175803 Process 2: 53555_127397175535424_1762165676846559511

Example for two processes (spawn):

Process 1: 54155_126834937165632_1762165717644505438 Process 2: 54154_132842492557120_1762165717644777865

Example for two threads in the same process:

Thread 1: 53142_138235445503680_1762165643891762916 Thread 2: 53142_138235453896384_1762165653498085145

Example for same thread and process but different calls:

Call 1: 50179_128078941120320_1762165462208616340 Call 2: 50179_128078941120320_1762165485281125126

birdnet.acoustic.inference.core.result_base.get_session_id_hash(session_id)
Return type:

str

birdnet.acoustic.inference.core.tensor module

class birdnet.acoustic.inference.core.tensor.AcousticTensorBase

Bases: object

Attributes:
memory_usage_mb
unprocessable_inputs

Methods

set_unprocessable_inputs

write_block
abstract property memory_usage_mb: float
set_unprocessable_inputs(unprocessable_inputs)
Return type:

None

property unprocessable_inputs: ndarray
abstractmethod write_block(*args, **kwargs)
Return type:

None

birdnet.acoustic.inference.core.worker module

class birdnet.acoustic.inference.core.worker.WorkerBase(session_id, name, backend_loader, batch_size, n_slots, rf_file_indices, rf_segment_indices, rf_audio_samples, rf_batch_sizes, rf_flags, segment_duration_samples, out_q, wkr_ring_access_lock, sem_free, sem_fill, sem_active_workers, half_precision, wkr_stats_queue, logging_queue, logging_level, device, cancel_event, all_producers_finished, start_signal, finish_signal, end_event)

Bases: LogableProcessBase

Methods

__call__()

Call self as a function.

run_main

run_main_loop
run_main()
Return type:

None

run_main_loop()
Return type:

None

Module contents