[READ-ONLY] Mirror of https://github.com/jmrplens/phonometry. Standards-conformant acoustics library for Python: measurement and metrology, docs.jmrp.io/phonometry


title: "API Reference" description: "Every public function and class in phonometry." #

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.