---
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](/phonometry/guides/calibration/).
- `octavefilter()` caches filter bank designs internally (32 entries), so
repeated calls with the same parameters skip the design phase. For explicit
control use `OctaveFilterBank`.