API Reference

All core functionality can be imported directly from the phonometry package.

Name	Type	Description (Inputs)	Usage Snippet (Outputs)
octavefilter	function	High-level analysis. • x: Signal array • fs: Sample rate [Hz] • fraction: 1, 3, etc. (Default: 1) • order: Filter order (Default: 6) • limits: [f_min, f_max] (Default: [12, 20000]) • filter_type: ‘butter’, ‘cheby1’, ‘cheby2’, ‘ellip’, ‘bessel’ (Default: ‘butter’) • sigbands: Return time signals (Default: False) • detrend: Remove DC offset (Default: True) • calibration_factor: Sensitivity multiplier (Default: 1.0) • dbfs: Output in dBFS instead of dB SPL (Default: False) • mode: ‘rms’ or ‘peak’ (Default: ‘rms’) • nominal: IEC 61260-1 nominal labels (Default: False) • show: Plot response (Default: False) • plot_file: Path to save plot (Default: None) • ripple: Passband ripple [dB] (for cheby1/ellip) • attenuation: Stopband atten. [dB] (for cheby2/ellip)	spl, freq = octavefilter(x, fs, ...) • spl: levels [dB] • freq: frequencies [Hz] With sigbands=True: spl, freq, xb = octavefilter(x, fs, sigbands=True) • xb: List of filtered signals (one per band) Calibrated usage: spl, f = octavefilter(x, fs, calibration_factor=0.05)
OctaveFilterBank	class	Efficient bank implementation. • fs: Sample rate [Hz] • fraction: 1, 3, etc. • order: Filter order • limits: [f_min, f_max] (Default: [12, 20000]) • filter_type: Architecture name • show: Plot response (Default: False) • plot_file: Path to save the plot (Default: None) • calibration_factor: Sensitivity multiplier • dbfs: Use dBFS (Default: False) • stateful: Carry filter state between calls (Default: False) • steady_ic: Steady-state initial conditions (Default: False) • resample: Multirate decimation (Default: True) • ripple: Passband ripple [dB] • attenuation: Stopband attenuation [dB]	bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter') spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True, zero_phase=False) • bank: Instance of the filter bank • bank.freq / bank.freq_d / bank.freq_u / bank.sos: computed properties
OctaveFilterBank.spectrogram	method	Band levels over time. • x: Signal array (1D or 2D) • window_time: Window length [s] (Default: 0.125) • overlap: Fraction in [0, 1) (Default: 0.5) • mode: ‘rms’ or ‘peak’ • zero_phase: Group-delay-free frames (Default: False)	levels, freq, times = bank.spectrogram(x) • levels: (bands, frames) or (channels, bands, frames) • times: window centers [s]
weighting_filter	function	Acoustic weighting. • x: Signal array • fs: Sample rate [Hz] • curve: ‘A’, ‘C’, ‘G’ (ISO 7196 infrasound) or ‘Z’ (Default: ‘A’) • high_accuracy: IEC class 1 HF accuracy via internal oversampling (Default: True)	y = weighting_filter(x, fs, curve='A') • y: weighted signal
WeightingFilter	class	Reusable weighting filter. • fs: Sample rate [Hz] • curve: ‘A’, ‘C’, ‘G’ or ‘Z’ • stateful: Block processing (Default: False) • steady_ic: Steady-state initial conditions (Default: False) • high_accuracy: Defaults to True except stateful	wf = WeightingFilter(fs, 'A') y = wf.filter(x)
time_weighting	function	Energy capture. • x: Raw signal array (squared internally; time is the last axis) • fs: Sample rate [Hz] • mode: ‘fast’, ‘slow’, or ‘impulse’ • initial_state: None, ‘zero’, ‘first’, scalar, or array (Default: None)	env = time_weighting(x, fs, mode='fast') • env: energy envelope (Mean Square), same shape as x
TimeWeighting	class	Stateful time weighting. • fs: Sample rate [Hz] • mode: ‘fast’, ‘slow’, ‘impulse’ (Default: ‘fast’)	tw = TimeWeighting(fs, mode='fast') env = tw.process(block) per block tw.reset() to start over
leq	function	Equivalent level (Leq). • x: Signal array (1D or 2D) • calibration_factor: Sensitivity multiplier (Default: 1.0) • dbfs: Output in dBFS (Default: False)	level = leq(x, calibration_factor=s) • level: Scalar (1D) or per-channel array (2D)
laeq	function	A-weighted Leq (LAeq). • x: Signal array (1D or 2D) • fs: Sample rate [Hz] • calibration_factor / dbfs: as leq	level = laeq(x, fs, calibration_factor=s) • level: Scalar (1D) or per-channel array (2D)
ln_levels	function	Statistical levels (LN). • x: Signal array (1D or 2D) • fs: Sample rate [Hz] • n: Exceedance percentiles (Default: (10, 50, 90)) • mode: ‘fast’, ‘slow’, ‘impulse’ (Default: ‘fast’) • weighting: ‘A’, ‘C’, ‘G’, ‘Z’ or None (Default: None) • calibration_factor / dbfs: as leq	stats = ln_levels(x, fs, n=(10, 50, 90), weighting='A') • stats: Dict {10: L10, 50: L50, 90: L90}
lc_peak	function	C-weighted peak (LCpeak). • x: Signal array (1D or 2D) • fs: Sample rate [Hz] • calibration_factor: as leq • dbfs: 0 dBFS = full-scale peak (amplitude 1.0), unlike the RMS reference of leq	peak = lc_peak(x, fs) • IEC 61672-1 §5.13; verified against Table 5
sel	function	Sound exposure level (SEL/LAE). • x: Whole-event signal (1D or 2D) • fs: Sample rate [Hz] • weighting: ‘A’, ‘C’, ‘G’, ‘Z’ or None (Default: None) • calibration_factor / dbfs: as leq	lae = sel(x, fs, weighting='A') • Event level normalized to 1 s
sound_exposure	function	A-weighted exposure E (IEC 61252). • x: Signal (1D or 2D) • fs: Sample rate [Hz] • duration_hours: exposure period represented (Default: recording length) • calibration_factor	E = sound_exposure(x, fs, duration_hours=8) • E: Pa²·h
lex_8h	function	Daily exposure LEX,8h / LEP,d. • Same params as sound_exposure	lex = lex_8h(x, fs, duration_hours=4) • Normalized 8 h level [dB]
equal_loudness_contour	function	ISO 226:2023 equal-loudness contour. • phon: Loudness level, 20-90 phon	freqs, spl = equal_loudness_contour(40.0) • SPL at the 29 preferred frequencies
loudness_level	function	Loudness level of a pure tone (phon). • spl: Tone SPL [dB] • frequency: One of the 29 Table 1 frequencies [Hz]	phon = loudness_level(73.0, 63.0)
hearing_threshold	function	Threshold of hearing (ISO 226 Table 1). • (no parameters)	freqs, tf = hearing_threshold()
tone_to_noise_ratio	function	Tone-to-noise ratio (ECMA-418-1 §11). • x: Signal (1D) • fs: Sample rate [Hz] • tone_freq: Tone to assess [Hz] (Default: highest peak) • resolution_hz: FFT bin spacing (Default: 1.0)	r = tone_to_noise_ratio(x, fs) • ToneAssessment(frequency, ratio_db, criterion_db, prominent)
prominence_ratio	function	Prominence ratio (ECMA-418-1 §12). • Same params as tone_to_noise_ratio	r = prominence_ratio(x, fs, tone_freq=1000) • ToneAssessment(...)
ToneAssessment	dataclass	Tone prominence verdict. • frequency: Assessed tone [Hz] • ratio_db: TNR or PR [dB] • criterion_db: Prominence limit at that frequency [dB] • prominent: bool	r = tone_to_noise_ratio(x, fs) if r.prominent: ...
CalibrationWarning	warning class	Unreliable calibration recording. Emitted by calculate_sensitivity — with fs given and validate=True — when the tone is unstable (IEC 60942 limit) or too short	warnings.simplefilter("error", CalibrationWarning)
lden	function	Day-evening-night level (ISO 1996-1 §3.6.4). • lday/levening/lnight: LAeq per period [dB] • hours: Period durations (Default: (12, 4, 8))	l = lden(63.2, 58.1, 51.4)
ldn	function	Day-night level (ISO 1996-1 §3.6.5). • lday/lnight: LAeq per period [dB] • hours: Default (15, 9)	l = ldn(63.2, 51.4)
composite_rating_level	function	Whole-day composite rating (ISO 1996-1 §6.5). • periods: list of (level_db, hours, adjustment_db) summing 24 h	r = composite_rating_level([(63, 12, 0), (58, 4, 5), (51, 8, 10)])
linkwitz_riley	function	Audio crossover. • x: Signal array • fs: Sample rate [Hz] • freq: Crossover frequency [Hz] • order: Any even number (Default: 4)	lo, hi = linkwitz_riley(x, fs, freq=1000, order=4) • lo: Low-pass filtered signal • hi: High-pass filtered signal
calculate_sensitivity	function	SPL Calibration. • ref_signal: Calibration signal • target_spl: Level of calibrator (Default: 94.0) • ref_pressure: Reference pressure (Default: 20e-6)	s = calculate_sensitivity(ref_signal, target_spl=94.0) • s: Float (multiplier for pressure)
verify_filter_class	function	IEC 61260-1:2014 class check. • bank: an OctaveFilterBank • num_points: frequency grid points per band (Default: 32768)	result = verify_filter_class(bank) • result["overall_class"]: 1, 2 or None • result["bands"]: per-band class and margins [dB]
getansifrequencies	function	ANSI Frequency generator. • fraction: 1, 3, etc. (Required) • limits: [f_min, f_max] (Default: [12, 20000])	f_cen, f_low, f_high, labels = getansifrequencies(fraction=3) • f_cen: List of center frequencies [Hz] • f_low: List of lower edges [Hz] • f_high: List of upper edges [Hz] • labels: IEC nominal frequency labels
normalizedfreq	function	Standard IEC Frequencies. • fraction: 1 or 3	freqs = normalizedfreq(fraction=3) • freqs: List of standard center frequencies [Hz]

Notes

• zero_phase=True (in OctaveFilterBank.filter and spectrogram) filters forward-backward (sosfiltfilt): no group delay, doubled effective attenuation, offline analysis only. Incompatible with stateful=True.
• mode='peak' includes the filter’s onset transient; a tone that starts abruptly can overshoot by ~1 dB. See Calibration and dBFS.
• octavefilter() caches filter bank designs internally (32 entries), so repeated calls with the same parameters skip the design phase. For explicit control use OctaveFilterBank.