← [Documentation index](../../README.md) # API Reference All core functionality lives in twenty-one subpackages, and every public name is reached through the one that owns it. The top-level `phonometry` package publishes those twenty-one and four names that belong to none of them: `Signal`, `ReportMetadata`, `PhonometryWarning` and `__version__`. > **Note.** This page is the curated quick table for the GitHub/PyPI audience: > one row per public name, kept complete by a CI gate > (`scripts/check_api_reference.py`). The full generated reference, with every > signature, parameter table and cross-link, lives on the site: > [phonometry API reference](https://docs.jmrp.io/phonometry/reference/api/). ## Namespaces The library is organized into twenty-one subpackages, and importing the namespace is the primary form used throughout the documentation: ```python from phonometry import aircraft contour = aircraft.noise_contour(..., x=..., y=...) # the shape of every call ``` | Subpackage | Scope | | :--- | :--- | | `phonometry.filters` | Octave and fractional-octave filter banks, frequency weightings and time weighting, parametric EQ, IEC 61260-1 and IEC 61672-1 class verification | | `phonometry.signals` | Levels (Leq, LAeq, percentiles), Welch and multitaper spectra, coherence, time-frequency, correlation, envelope, cepstrum, phase, synchronous averaging, test signals | | `phonometry.metrology` | Calibration, GUM uncertainty and Monte Carlo, data qualification (stationarity, trends, peak statistics), the ISO 1683 reference values | | `phonometry.fluids` | The state of the propagating medium: humid air from IEC 61094-2:2009 Annex F (CIPM-2007), with the conditions it was computed for and the domain its model states for itself | | `phonometry.solids` | The elastic constants of a solid and the three longitudinal wave speeds that follow from them, named apart by the shape the wave travels in (beam, plate, unbounded), with the inverse of each and the `h f_c` a materials table prints | | `phonometry.io` | Files. Measurement audio: WAV/BWF/RF64 read and write with `bext` provenance (EBU Tech 3285), headers-only `info`, block streaming, lossless conversion, calibration sidecar; FLAC, AIFF, Ogg/Opus and MP3 via the `[audio]` extra. Catalogues of materials of your own read from and written to JSON, with their provenance, into the published row classes | | `phonometry.psychoacoustics` | Two families: `loudness` (ISO 532-1 Zwicker, ISO 532-2 and ISO 532-3 Moore-Glasberg, ECMA-418-2, ISO 226 equal-loudness contours) and `quality` (sharpness, roughness, fluctuation strength, tonality, tone audibility, annoyance), plus the ERB scale both measure on | | `phonometry.speech` | Speech Transmission Index (IEC 60268-16), Speech Intelligibility Index (ANSI S3.5), STOI and ESTOI | | `phonometry.hearing` | Audiometric thresholds (ISO 7029/389-7), audiometric test methods and rooms (ISO 8253-1/-2), noise-induced hearing loss (ISO 1999), occupational exposure (ISO 9612), hearing protectors (ISO 4869-1/-2/-3/-6) | | `phonometry.emission` | Sound power (ISO 3740 family), sound intensity and the IEC 61043 instrument class it is measured with, vibration-based power | | `phonometry.room` | Room acoustics (ISO 3382), impulse responses, open-plan, room-noise criteria, reverberation prediction, EN 12354-6 | | `phonometry.building` | Three subgroups: `measurement` (field, laboratory, survey and intensity methods with their ISO 717 ratings and ISO 12999 uncertainty), `prediction` (EN 12354 global and detailed models, facades, panels, apertures, plenums and resilient layers) and `regulation` (national codes) | | `phonometry.materials` | Four families by what the material does: `absorbers` (ISO 354, ISO 11654, ISO 12999-2, impedance tube ISO 10534-2, airflow resistance ISO 9053, porous and multilayer models, Biot, slow-sound metamaterials), `diffusers` (Schroeder design, metadiffusers, scattering and diffusion ISO 17497), `surfaces` (in-situ road absorption ISO 13472) and `resilient` (dynamic stiffness EN 29052-1) | | `phonometry.vibration` | Three families: `structural` (mobility ISO 7626, plate junctions, radiation, experimental SEA, transfer stiffness ISO 10846), `human` (ISO 2631/5349/8041 exposure and multiple shocks) and `machinery` (fault frequencies and condition monitoring) | | `phonometry.environment` | Three subgroups: `sources` (CNOSSOS road and rail emission, wind-turbine apparent sound power), `propagation` (ISO 9613-1/-2, ground effect and barriers, refraction by ray tracing and the parabolic equation) and `assessment` (ISO 1996-1/-2 rating and measurement, impulsive prominence, RD 1367/2007) | | `phonometry.aircraft` | EPNL (ICAO Annex 16), SAE ARP 5534 and 866A absorption, airport contours (ECAC Doc 29) with NPD data for a non-reference atmosphere, rotorcraft (ECAC Doc 32) | | `phonometry.underwater` | Three families: `sources` (ISO 17208 ship radiated noise, traffic, pile driving, wind and thermal ambient noise), `propagation` (closed-form and Weston propagation loss, normal modes, rays, Gaussian beams and the parabolic equation, seabed reflection, sound speed) and `bioacoustics` (marine-mammal audiograms and regulatory auditory weighting), over the ISO 18405 quantities and the sonar equation at the root | | `phonometry.electroacoustics` | Distortion (IEC 60268-3 / AES17), transfer function and coherence, radiating piston | | `phonometry.noise_control` | Reactive silencers (four-pole method), HVAC duct attenuation, machine-enclosure insertion loss | | `phonometry.broadcast` | Programme loudness and true peak (ITU-R BS.1770-5, EBU R 128 with Tech 3341/3342) | | `phonometry.simulation` | 2D acoustic FDTD wave simulation (staggered grid, sources, probes, impedance boundaries, obstacles) | The table below lists each name unqualified, the way its own page titles it; the usage snippet shows the namespace to import and call it through. The module paths of every earlier layout were removed in 4.0 along with the shims that served them, so `phonometry.metrology.levels`, `phonometry.environmental` and the rest of the pre-4.0 spellings raise `ModuleNotFoundError`. The paths in force are the ones the [generated reference](https://docs.jmrp.io/phonometry/reference/api/) documents, one page per module. > **Reading the input column.** Every function that consumes a recording > accepts a `phonometry.io.Signal` wherever the table writes a signal > argument, and then `fs` is optional: the object carries it, and an > explicit value that disagrees with it raises rather than overriding it. A > bare array still requires `fs` by name. A calibrated `Signal` is analysed > in pascals, with four documented exemptions (the EBU R 128 family, the > `dbfs=True` paths, quantities that are not pressures, and > `metrology.sensitivity`, which is what produces a calibration factor). > Each function's own page states which of these applies to it. | Name | Type | Description (Inputs) | Usage Snippet (Outputs) | | :--- | :--- | :--- | :--- | | `octave_filter` | `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])
• `sigbands`: Return time signals (Default: False)
• `detrend`: Remove DC offset (Default: True)
• `mode`: 'rms' or 'peak' (Default: 'rms')
• `nominal`: IEC 61260-1 nominal labels (Default: False)
• `design`: `FilterDesign` (family, ripple, attenuation, decimation)
• `calibration`: `LevelCalibration` (factor, dBFS)
• `response_plot`: `ResponsePlot` (show, file) | `r = filters.octave_filter(x, fs, ...)`
• `r.levels`: band levels [dB]
• `r.frequencies`: band centres [Hz]
• `r.bands`: one waveform per band, or `None`

**With `sigbands=True`:**
`bands = filters.octave_filter(x, fs, sigbands=True).require_bands()`

**Calibrated usage:**
`filters.octave_filter(x, fs, calibration=filters.LevelCalibration(factor=0.05)).levels` | | `OctaveFilterResult` | `dataclass` | **What a filter bank gives back for one signal.**
• `levels`: band levels [dB], `(bands,)` or `(channels, bands)`, `None` when the call asked for no level
• `frequencies`: one band centre per level, exact or IEC 61260-1 nominal labels
• `bands`: one waveform per band, `None` unless `sigbands=True`
• `.require_levels()` / `.require_bands()`: the value, or a `ValueError` naming the argument that was missing
• `.plot()`: the band spectrum on a log frequency axis | `r = filters.octave_filter(x, fs, fraction=3)`
`r.levels[r.frequencies.index(1000.0)]`

• `ax = r.plot()` | | `OctaveFilterBank` | `class` | **Efficient bank implementation.**
• `fs`: Sample rate [Hz]
• `fraction`: 1, 3, etc.
• `order`: Filter order
• `limits`: [f_min, f_max] (Default: [12, 20000])
• `design`: `FilterDesign` (family, ripple, attenuation, decimation)
• `calibration`: `LevelCalibration` (factor, dBFS)
• `block_processing`: `BlockProcessing` (stateful, steady_ic)
• `response_plot`: `ResponsePlot` (show, file) | `bank = filters.OctaveFilterBank(fs=48000, fraction=3, order=6, design=filters.FilterDesign(filter_type='butter'))`
`r = bank.filter(x, sigbands=False, mode='rms', detrend=True, zero_phase=False)`
• `r.levels`, `r.frequencies`, `r.bands` (an `OctaveFilterResult`)

• `bank`: Instance of the filter bank
• `bank.frequencies` / `bank.lower_edges` / `bank.upper_edges` [Hz], `bank.labels`, `bank.n_bands`: the band set, read-only
• `bank.sos`: the second-order sections | | `FilterDesign` | `dataclass` | **How the band filters are designed.**
• `filter_type`: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (Default: 'butter')
• `ripple`: Passband ripple [dB] (for cheby1/ellip; Default: 0.1)
• `attenuation`: Stopband attenuation [dB] (Default: 72; cheby2 needs >= 70 dB for class 1)
• `resample`: Multirate decimation (Default: True) | `OctaveFilterBank(48000, 3, design=filters.FilterDesign(filter_type='cheby2'))` | | `LevelCalibration` | `dataclass` | **How band energy becomes a level.**
• `factor`: Sensitivity multiplier, Pa per digital unit (Default: 1.0)
• `dbfs`: Output in dBFS instead of dB SPL (Default: False) | `octave_filter(x, fs, calibration=filters.LevelCalibration(factor=0.05))` | | `BlockProcessing` | `dataclass` | **Filter state carried between calls.**
• `stateful`: Carry filter state between calls (Default: False)
• `steady_ic`: Steady-state initial conditions (Default: False) | `OctaveFilterBank(48000, 1, design=filters.FilterDesign(resample=False), block_processing=filters.BlockProcessing(stateful=True))` | | `ResponsePlot` | `dataclass` | **Response plot drawn while designing.**
• `show`: Show the plot (Default: False)
• `file`: Path to save the plot (Default: None) | `OctaveFilterBank(48000, 3, response_plot=filters.ResponsePlot(show=True))` | | `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) | `r = bank.spectrogram(x)`

• an `OctaveSpectrogramResult`: `r.levels`, `r.frequencies`, `r.times` | | `OctaveSpectrogramResult` | `dataclass` | **Band levels over time, as a record.**
• `levels` [dB]: `(bands, frames)` or `(channels, bands, frames)`
• `frequencies` [Hz]: exact mid-band frequencies, read-only
• `times` [s]: window centres
• `lower_edges` / `upper_edges` [Hz]: the edges of each band
• the level grid is checked against every axis when the record is built
• `.plot(channel=None)`: one raster on a log frequency axis, each row between its band's edges, with a dB colour bar; a multichannel result needs `channel` | `r = bank.spectrogram(x)`
`ax = r.plot()` | | `weighting_filter` | `function` | **Acoustic weighting.**
• `x`: Signal array
• `fs`: Sample rate [Hz]
• `weighting`: 'A', 'C' (IEC 61672-1), 'B' (ANSI S1.4-1983, historical), 'D' (withdrawn IEC 537, aircraft), 'G' (ISO 7196 infrasound), 'AU' (IEC 61012), '468' (ITU-R BS.468-4 psophometric) or 'Z' (Default: 'A')
• `high_accuracy`: fit the analog prototype at `fs` instead of transforming it blind, for IEC class 1 accuracy at every rate (Default: True; '468' requires it) | `y = filters.weighting_filter(x, fs, weighting='A')`

• `y`: weighted signal | | `WeightingFilter` | `class` | **Reusable weighting filter.**
• `fs`: Sample rate [Hz]
• `weighting`: 'A', 'B', 'C', 'D', 'G', 'AU', '468' or 'Z'
• `stateful`: Block processing (Default: False)
• `steady_ic`: Steady-state initial conditions (Default: False)
• `high_accuracy`: Fitted design, independent of `stateful`, a `bool` (Default: True; '468' refuses False) | `wf = filters.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 = filters.time_weighting(x, fs, mode='fast')`

• `env`: energy envelope (Mean Square), same shape as `x` | | `TimeWeightedEnvelope` | `dataclass` | **Exponentially averaged mean square of a record, with its rate.**
• `mean_square` [Pa² when calibrated], `fs` [Hz], `mode`, `calibrated`
• stands in for the bare array it replaced (`np.asarray`, indexing, `shape`)
• returned by `time_weighting`/`TimeWeighting.process` for a `Signal` input; a mean square is not a pressure record, so it is not a `Signal` | `env = filters.time_weighting(filters.weighting_filter(sig, weighting='A'), mode='fast')`
`env.plot()` # the L_pAF trace in dB | | `TimeWeighting` | `class` | **Stateful time weighting.**
• `fs`: Sample rate [Hz]
• `mode`: 'fast', 'slow', 'impulse' (Default: 'fast') | `tw = filters.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) or a `phonometry.io.Signal`
• `calibration_factor`: Sensitivity multiplier (Default: None: a calibrated `Signal`'s factor, else 1.0; explicit wins)
• `dbfs`: Output in dBFS (Default: False) | `level = signals.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) or a `phonometry.io.Signal`
• `fs`: Sample rate [Hz] (taken from `x` when `x` is a `Signal`)
• `calibration_factor` / `dbfs`: as `leq` | `level = signals.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) or a `phonometry.io.Signal`
• `fs`: Sample rate [Hz] (taken from `x` when `x` is a `Signal`)
• `n`: Exceedance percentiles (Default: (10, 50, 90))
• `mode`: 'fast', 'slow', 'impulse' (Default: 'fast')
• `weighting`: any `weighting_filter` curve, 'A', 'B', 'C', 'D', 'G', 'AU', '468' or 'Z' (Default: 'Z', unweighted)
• `calibration_factor` / `dbfs`: as `leq` | `stats = signals.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) or a `phonometry.io.Signal`
• `fs`: Sample rate [Hz] (taken from `x` when `x` is a `Signal`)
• `calibration_factor`: as `leq`
• `dbfs`: 0 dBFS = full-scale *peak* (amplitude 1.0), unlike the RMS reference of `leq`
• `oversample`: HF inter-sample peak recovery (Default: 8; 1 = on-grid, under-reads up to ~1.15 dB at 48 kHz) | `peak = signals.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) or a `phonometry.io.Signal`
• `fs`: Sample rate [Hz] (taken from `x` when `x` is a `Signal`)
• `weighting`: any `weighting_filter` curve, 'A', 'B', 'C', 'D', 'G', 'AU', '468' or 'Z' (Default: 'Z', unweighted)
• `calibration_factor` / `dbfs`: as `leq` | `lae = signals.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) or a `phonometry.io.Signal`
• `fs`: Sample rate [Hz] (taken from `x` when `x` is a `Signal`)
• `duration_hours`: exposure period represented (Default: recording length)
• `calibration_factor` | `E = signals.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 = signals.lex_8h(x, fs, duration_hours=4)`

• Normalized 8 h level [dB] | | `loudness_zwicker` | `function` | **Zwicker loudness (ISO 532-1:2017).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free' or 'diffuse' (Default: 'free')
• `stationary`: Clause 5 stationary method (Default: False)
• `time_skip`: seconds excluded from the stationary mean square (Annex B.1 uses 0.2 s; Default: 0.0)
• `calibration_factor`: Digital units to Pa (Default: 1.0) | `res = psychoacoustics.loudness_zwicker(x, fs)`

• `ZwickerLoudness`; time-varying runs add N5/N10 and the 500 Hz N(t) trace | | `loudness_zwicker_from_spectrum` | `function` | **Stationary loudness from band levels.**
• `levels`: 28 one-third-octave levels, 25 Hz-12.5 kHz [dB SPL]
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = psychoacoustics.loudness_zwicker_from_spectrum(levels)`

• `res.loudness` [sone], `res.loudness_level` [phon] | | `ZwickerLoudness` | `dataclass` | **Loudness result.**
• `loudness`: N [sone]
• `loudness_level`: LN [phon]
• `specific`: N′(z), 240 bins of 0.1 Bark
• `n5` / `n10`: percentile loudness (time-varying only)
• `times` / `loudness_vs_time`: 500 Hz trace
• `field`: sound field assumed ('free'/'diffuse'), required, the fourth field | `res.loudness, res.n5`

• Time-varying fields are `None` for stationary results | | `sharpness_din` | `function` | **Sharpness in acum (DIN 45692).**
• `x`: Signal (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free' or 'diffuse' (Default: 'free')
• `method`: 'din', 'aures' or 'bismarck' (Default: 'din')
• `calibration_factor`: Digital units to Pa (Default: 1.0) | `s = psychoacoustics.sharpness_din(x, fs)`

• `s`: sharpness [acum] | | `sharpness_din_from_specific` | `function` | **Sharpness from a specific-loudness pattern.**
• `specific`: N′(z), 240 values at 0.1 Bark (e.g. `ZwickerLoudness.specific`)
• `method`: 'din', 'aures' or 'bismarck' (Default: 'din') | `s = psychoacoustics.sharpness_din_from_specific(res.specific)`

• `s`: sharpness [acum] | | `erb_bandwidth` | `function` | **Auditory-filter equivalent rectangular bandwidth ERB_N (Glasberg & Moore 1990; Moore 6e p. 76).**
• `frequency` [Hz] (scalar or array, ≥ 0)
• `ERB_N = 24.673(0.004368 f + 1)` [Hz] | `erb_bandwidth(1000.0) # 132.4` | | `cam_from_frequency` / `frequency_from_cam` | `function` | **The Cam (ERB_N-number) frequency scale, one unit per auditory-filter width.**
• `cam_from_frequency(f)` = `21.366 log10(0.004368 f + 1)` [Cam]
• `frequency_from_cam(i)`: the exact inverse [Hz] | `cam_from_frequency(1000.0) # 15.59`
`frequency_from_cam(15.59)` | | `ERB_C1_HZ` / `ERB_C2_PER_HZ` / `CAM_C` | `constant` | **Constants of the ERB_N fit shared with the ISO 532-2 loudness model.**
• `ERB_C1_HZ` = 24.673 [Hz], `ERB_C2_PER_HZ` = 0.004368 [1/Hz], `CAM_C` = 21.366 [Cam] | `ERB_C1_HZ * (ERB_C2_PER_HZ * f + 1)` | | `loudness_moore_glasberg` | `function` | **Moore-Glasberg loudness (ISO 532-2:2017).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free', 'diffuse' or 'eardrum' (Default: 'free')
• `presentation`: 'binaural'/'diotic' or 'monaural' (Default: 'binaural') | `res = psychoacoustics.loudness_moore_glasberg(x, fs)`

• `MooreGlasbergLoudness` (roex excitation pattern) | | `loudness_moore_glasberg_from_spectrum` | `function` | **Exact loudness from sinusoidal components (ISO 532-2 §5.2/5.4).**
• `components`: sequence of (frequency [Hz], level [dB SPL]) pairs
• `field`: 'free'/'diffuse'/'eardrum' (Default: 'free')
• `presentation`: (Default: 'binaural') | `res = psychoacoustics.loudness_moore_glasberg_from_spectrum([(1000.0, 40.0)])`

• 1 kHz/40 dB → 1.000 sone | | `loudness_moore_glasberg_from_third_octave` | `function` | **Loudness from 29 one-third-octave band levels (ISO 532-2 §5.5).**
• `band_levels`: 29 levels, 25 Hz–16 kHz [dB SPL]
• `field` / `presentation`: as above | `res = psychoacoustics.loudness_moore_glasberg_from_third_octave(levels)`

• `MooreGlasbergLoudness` | | `MooreGlasbergLoudness` | `dataclass` | **Moore-Glasberg loudness result.**
• `loudness`: N [sone]
• `loudness_level`: LN [phon]
• `specific`: N′(i), 372 bins of 0.1 Cam
• `erb_number` / `frequencies`: Cam / Hz axes
• `field` / `presentation`
• `.plot()`: specific loudness N′(i) over Cam | `res.loudness, res.loudness_level` | | `loudness_moore_glasberg_time` | `function` | **Time-varying loudness (ISO 532-3:2023).**
• `x`: Calibrated Pa; 1D (diotic) or (n, 2) ears
• `fs`: Sample rate [Hz]
• `field`: 'free'/'diffuse'/'eardrum' (Default: 'free')
• `presentation`: (Default: 'binaural')
• `percentiles`: exceedance % (Default: (1,5,10,50,90,95)) | `res = psychoacoustics.loudness_moore_glasberg_time(x, fs)`

• `MooreGlasbergTimeVaryingLoudness` | | `MooreGlasbergTimeVaryingLoudness` | `dataclass` | **Time-varying loudness result.**
• `times`: 1 ms grid [s]
• `short_term_loudness` / `long_term_loudness`: S′(t)/S″(t) [sone]
• `short_term_loudness_level` / `long_term_loudness_level` [phon]
• `n_max` / `loudness_level_max`: peak long-term loudness
• `percentiles`: dict {percent: sone}
• `.plot()`: STL and LTL vs time | `res.n_max, res.percentiles[5.0]` | | `loudness_ecma` | `function` | **Sottek Hearing Model loudness (ECMA-418-2:2025).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = psychoacoustics.loudness_ecma(x, fs)`

• `EcmaLoudness`; 1 kHz/40 dB ≈ 1 sone_HMS | | `EcmaLoudness` | `dataclass` | **Sottek loudness result.**
• `loudness`: N [sone_HMS]
• `specific_loudness`: N′(z), 53 Bark_HMS bands
• `bark` / `frequencies`: z / Hz axes
• `times` / `loudness_vs_time`: N(l) at 187.5 Hz
• `field`
• `.plot()`: N′(z) + N(l) | `res.loudness, res.specific_loudness` | | `tonality_ecma` | `function` | **Sottek tonality (ECMA-418-2:2025).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free')
• `f_low` / `f_high`: optional user band [Hz] (Default: None) | `res = psychoacoustics.tonality_ecma(x, fs)`

• `EcmaTonality`; 1 kHz/40 dB ≈ 1 tu_HMS | | `EcmaTonality` | `dataclass` | **Sottek tonality result.**
• `tonality`: T [tu_HMS]
• `specific_tonality`: T′(z), 53 bands
• `tonal_frequencies`: f_ton,z per band [Hz]
• `bark` / `frequencies`
• `times` / `tonality_vs_time` / `tonal_frequency_vs_time`: T(l), f_ton(l)
• `field`
• `.plot()`: T′(z) + T(l) | `res.tonality, res.tonal_frequencies` | | `roughness_ecma` | `function` | **Sottek roughness (ECMA-418-2:2025), new capability.**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = psychoacoustics.roughness_ecma(x, fs)`

• `EcmaRoughness`; 1 kHz/70 Hz/100 %-AM/60 dB ≈ 1 asper | | `EcmaRoughness` | `dataclass` | **Sottek roughness result.**
• `roughness`: R [asper] (90th percentile of R(l50))
• `specific_roughness`: R′(z), 53 bands
• `bark` / `frequencies`
• `times` / `roughness_vs_time`: R(l50) at 50 Hz
• `specific_roughness_vs_time`: (n_times, 53)
• `field`
• `.plot()`: R(l50) + specific-roughness heatmap | `res.roughness, res.specific_roughness` | | `fluctuation_strength_ecma` | `function` | **Sottek fluctuation strength (ECMA-418-2:2025 Clause 9), new capability.**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = psychoacoustics.fluctuation_strength_ecma(x, fs)`

• `EcmaFluctuationStrength`; 1 kHz/4 Hz/100 %-AM/60 dB ≈ 1 vacil_HMS | | `EcmaFluctuationStrength` | `dataclass` | **Sottek fluctuation-strength result.**
• `fluctuation_strength`: F [vacil_HMS] (90th percentile of F(l50))
• `specific_fluctuation_strength`: F′(z), 53 bands
• `bark` / `frequencies`
• `times` / `fluctuation_strength_vs_time`: F(l50) at 50 Hz
• `specific_fluctuation_strength_vs_time`: (n_times, 53)
• `field`
• `.plot()`: F(l50) + specific-fluctuation-strength heatmap | `res.fluctuation_strength, res.specific_fluctuation_strength` | | `psychoacoustic_annoyance` | `function` | **Psychoacoustic annoyance PA (Fastl & Zwicker Eqs 16.2–16.4), exact model.**
• `n5`: percentile loudness N5 [sone]
• `sharpness` S [acum]
• `fluctuation_strength` F [vacil]
• `roughness` R [asper] | `res = psychoacoustics.psychoacoustic_annoyance(30, 2.0, 0.5, 0.3)`

• `PsychoacousticAnnoyanceResult`; `res.annoyance == 37.0478` | | `psychoacoustic_annoyance_from_signal` | `function` | **PA from a calibrated signal (convenience, engineering estimate).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free' or 'diffuse' (Default: 'free')
• `calibration_factor` (Default: 1.0)
Mixes Zwicker N5/S + Sottek R + Osses F. | `res = psychoacoustics.psychoacoustic_annoyance_from_signal(x, fs)`

• `PsychoacousticAnnoyanceResult` | | `PsychoacousticAnnoyanceResult` | `dataclass` | **Psychoacoustic annoyance result.**
• `annoyance`: PA
• `n5` [sone] / `sharpness` [acum] / `fluctuation_strength` [vacil] / `roughness` [asper]: the four inputs
• `w_s`: sharpness weighting wS
• `w_fr`: roughness/fluctuation weighting wFR
• `.plot()`: term-contribution bar | `res.annoyance, res.w_s, res.w_fr` | | `fluctuation_strength_am_noise` | `function` | **Fluctuation strength of AM broadband noise (Fastl & Zwicker Eq. 10.2), exact closed form.**
• `level` L [dB]
• `modulation_factor` m (0–1)
• `mod_frequency` fmod [Hz] | `fluctuation_strength_am_noise(60, 1.0, 4.0) # 3.6943 vacil` | | `fluctuation_strength` | `function` | **Fluctuation strength F (Osses 2016 signal model), no numeric standard, free-field.**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] | `res = psychoacoustics.fluctuation_strength(x, fs)`

• `FluctuationStrengthResult`; 1 kHz/60 dB/m=1/4 Hz AM ≈ 1 vacil | | `FluctuationStrengthResult` | `dataclass` | **Fluctuation strength result.**
• `fluctuation_strength`: F [vacil]
• `specific`: F′(z), 47 values
• `bark_axis`: z [Bark], 47 values
• `time_dependent`: F(t) per frame
• `.plot()`: specific F′(z) over the Bark axis | `res.fluctuation_strength, res.specific` | | `equal_loudness_contour` / `LoudnessContour` | `function` / `dataclass` | **ISO 226:2023 equal-loudness contour.**
• `phon`: Loudness level, 20-90 phon | `c = psychoacoustics.equal_loudness_contour(40.0)`

• `c.frequencies`, `c.levels`: SPL at the 29 preferred frequencies; `c.phon`; `.plot()` | | `equal_loudness_contours` | `function` | **ISO 226:2023 equal-loudness contour family (plottable).**
• `phons`: Loudness levels [phon] (Default: 20-90 in 10-phon steps)
• `frequencies`: Grid [Hz] (Default: the 29 preferred) | `res = psychoacoustics.equal_loudness_contours()`

• `EqualLoudnessContours`; `res.plot()` | | `EqualLoudnessContours` | `dataclass` | **Equal-loudness contour family result.**
• `frequencies`: grid [Hz]
• `phons`: contour levels [phon]
• `contours`: SPL, `(len(phons), len(frequencies))` [dB] (`nan` where undefined)
• `threshold`: hearing threshold $T_f$ [dB]
• `.plot()`: the iconic ISO 226 chart | `res.contours, res.threshold` | | `loudness_level` | `function` | **Loudness level of a pure tone (phon).**
• `spl`: Tone SPL [dB]
• `frequency`: One of the 29 Table 1 frequencies [Hz] | `phon = psychoacoustics.loudness_level(73.0, 63.0)` | | `hearing_threshold` | `function` | **Threshold of hearing (ISO 226 Table 1).**
• (no parameters)
• a `LoudnessContour` whose `phon` is `None` | `psychoacoustics.hearing_threshold().levels` | | `tone_to_noise_ratio` | `function` | **Tone-to-noise ratio (ECMA-418-1 §11).**
• `x`: Signal (1D)
• `fs`: Sample rate [Hz]
• `tone_frequency`: Tone to assess [Hz] (Default: highest peak)
• `resolution_hz`: FFT bin spacing (Default: 1.0) | `r = psychoacoustics.tone_to_noise_ratio(x, fs)`

• `ToneAssessment(frequency, ratio_db, method)` | | `prominence_ratio` | `function` | **Prominence ratio (ECMA-418-1 §12).**
• Same params as `tone_to_noise_ratio` | `r = psychoacoustics.prominence_ratio(x, fs, tone_frequency=1000)`

• `ToneAssessment(...)` | | `ToneAssessment` | `dataclass` | **Tone prominence verdict.**
• `frequency`: Assessed tone [Hz]
• `ratio_db`: TNR or PR [dB]
• `method`: 'tone_to_noise_ratio' or 'prominence_ratio', which selects the criterion
• read-only: `prominence_limit_db`, the ECMA-418-1 prominence limit at that frequency [dB], and `prominent`: bool | `r = psychoacoustics.tone_to_noise_ratio(x, fs)`
`if r.prominent: ...` | | `tone_audibility` | `function` | **Tone audibility ΔL = LT−LG−av (ISO/PAS 20065 Formulae 12–14).**
• `tone_level` LT, `mean_narrowband_level` LS [dB]
• `tone_frequency` fT [Hz], `line_spacing_hz` Δf [Hz] | `tone_audibility(67.96, 49.22, 137.3, 2.7) # 5.01 dB` | | `assess_tones` | `function` | **Audibility of a spectrum's tones (ISO/PAS 20065).**
• `tone_levels` LT, `mean_narrowband_levels` LS [dB]
• `line_spacing_hz` Δf [Hz]
• `tone_frequencies` [Hz], by name
• `extended_uncertainties`: attach the Clause 5.4 U per tone (Default: True) | `res = psychoacoustics.assess_tones(LT, LS, 2.7, tone_frequencies=fT)`

• `ToneAudibilityResult` | | `critical_bandwidth_engineering` | `function` | **Critical bandwidth Δfc about a tone (Formula 2).**
• `tone_frequency` fT [Hz] | `critical_bandwidth_engineering(137.3) # 101.36 Hz` | | `critical_band_corners` | `function` | **Corner frequencies (f₁, f₂) of the critical band (Formulae 3–5).**
• `tone_frequency` fT [Hz] | `f1, f2 = psychoacoustics.critical_band_corners(137.3)` | | `critical_band_level` | `function` | **Masking-noise level LG = LS+10lg(Δfc/Δf) (Formula 12).**
• `mean_narrowband_level` LS [dB], `tone_frequency` fT, `line_spacing_hz` Δf [Hz] | `critical_band_level(49.22, 137.3, 2.7) # 64.97 dB` | | `masking_index` | `function` | **Masking index av = −2−lg[1+(f/502)²·⁵] (Formula 13).**
• `frequency` f [Hz] | `masking_index(137.3) # -2.02 dB` | | `audibility_from_levels` | `function` | **ΔL = LT − LG − av (Formula 14).**
• `tone_level` LT, `critical_band_level` LG, `masking_index` av [dB] | `audibility_from_levels(67.96, 64.98, -2.02) # 5.0 dB` | | `energy_sum_level` | `function` | **Energy sum of lines with window correction (Formulae 7/8).**
• `line_levels` Li [dB]; a single line (K = 1) takes its level unchanged (Formula 7, no correction)
• `effective_bandwidth_factor` Δfe/Δf (Default: 1.5, Hanning; K > 1 only) | `energy_sum_level([80, 80]) # 81.25 dB` | | `mean_narrowband_level` | `function` | **Masking-noise level LS from a critical-band spectrum (Formula 6, iterative Annex D).**
• `levels` Li [dB], `frequencies` [Hz]
• `tone_frequency` fT [Hz]
• `effective_bandwidth_factor` (Default: 1.5) | `mean_narrowband_level(levels, 137.3, frequencies=freqs) # 49.22 dB` | | `tone_level` | `function` | **Tone level LT from the tonal lines about a peak (Formulae (7)/(8): single lines take (7), without the Hanning bandwidth correction).**
• `levels` Li [dB], `frequencies` [Hz]
• `tone_frequency` fT [Hz], `mean_narrowband_level` LS [dB]
• `effective_bandwidth_factor` (Default: 1.5) | `tone_level(levels, 137.3, ls, frequencies=freqs) # 67.96 dB` | | `audibility_uncertainty` / `mean_audibility_uncertainty` | `function` | **Extended uncertainty U of the audibility (ISO/PAS 20065 Clause 5.4/6, 90 % bilateral).**
• per tone: `audibility_uncertainty(tone_line_levels, noise_line_levels, tone_frequency, line_spacing)`
• mean: U of the energy-averaged audibility over the per-spectrum (ΔL, U) pairs
Mandatory when fewer than 12 spectra are averaged (Clause 6) | `u = psychoacoustics.audibility_uncertainty(lt_lines, ls_lines, 137.3, 2.7)`

• U [dB] | | `analyze_spectrum` | `function` | **Detect & rate the audible tones of a spectrum (Clause 5.3.8 + distinctness 5.3.4), incl. Step 3 same-band FG combination (Formula 17).**
• `levels` Li [dB], `frequencies` [Hz]
• `line_spacing_hz` Δf [Hz]
• `effective_bandwidth_factor` (Default: 1.5) | `res = psychoacoustics.analyze_spectrum(levels, 2.7, frequencies=freqs)`

• `ToneAudibilityResult` of detected tones + FG entries (`group_sizes`) | | `combined_tone_level` | `function` | **Multi-tone FG combined level (Formula 17).**
• `levels` Li [dB], `mean_narrowband_levels` LS [dB]
• `frequencies`, `tone_frequencies` [Hz], by name
• `effective_bandwidth_factor` (Default: 1.5) | `combined_tone_level(lv, ls, frequencies=f, tone_frequencies=[118.4,137.3,158.8]) # 72.15 dB` | | `two_tone_separation_frequency` | `function` | **Two-tone separation threshold fD = 21·10^(1.2·\|lg(fT/212)\|^1.8) Hz (Formula 19).**
• `tone_frequency` fT [Hz] (more prominent tone) | `two_tone_separation_frequency(212.0) # 21.0 Hz` | | `resolve_tones_separately` | `function` | **Rate two tones <1000 Hz separately vs combined (Formulae 18/19).**
• `tone1_frequency`, `tone2_frequency` [Hz]
• `audibility1`, `audibility2` ΔL [dB] | `resolve_tones_separately(200., 260., 3., 2.) # True` | | `mean_audibility` | `function` | **Energy-mean mean audibility over spectra (Formula 20).**
• `decisive_audibilities` ΔLj [dB]; no-tone spectra use −10 dB | `mean_audibility([9.18, 6.04, 7.46]) # dB` | | `ToneAudibilityResult` | `dataclass` | **Tonal audibility of a spectrum's tones (ISO/PAS 20065).**
• `audibilities` ΔL, `critical_band_levels` LG, `masking_indices` av [dB]
• `critical_bandwidths` Δfc, `lower_corners`/`upper_corners` [Hz]
• `audible`: ΔL > 0 mask
• `extended_uncertainties`: Clause 5.4 U per tone [dB]
• `group_sizes`: 1 = single tone, N ≥ 2 = Step 3 FG entry (None from `assess_tones`)
• `decisive_audibility` / `decisive_frequency`
• `.plot()`: per-tone ΔL vs frequency
• no truth value: `bool()` raises; read `decisive_audibility` or `audible` | `res.decisive_audibility, res.audible` | | `HANNING_BANDWIDTH_FACTOR` | `float` | **Hanning effective-bandwidth factor Δfe/Δf (ISO/PAS 20065 Annex A).**
1.5 | `HANNING_BANDWIDTH_FACTOR # 1.5` | | `NO_TONE_AUDIBILITY_DB` | `float` | **Audibility reported when no tone is found [dB] (ISO/PAS 20065 Formula 21).**
-10.0 | `NO_TONE_AUDIBILITY_DB # -10.0` | | `sti_from_impulse_response` | `function` | **Full STI, indirect method (IEC 60268-16 Ed. 5).**
• `ir`: Impulse response (1D)
• `fs`: Sample rate [Hz] (>= 22500)
• `snr`: SNR [dB], scalar or 7 bands (Default: None)
• `levels`: 7 speech band levels [dB SPL]; enables masking + reception threshold (Default: None)
• `ambient`: 7 noise band levels [dB SPL]; requires `levels` | `res = speech.sti_from_impulse_response(ir, fs, snr=25.0)`

• `STIResult` with `mtf` (7×14) | | `stipa` | `function` | **STIPA direct method (Annex B).**
• `x`: Recorded STIPA signal (1D), 15-25 s
• `fs`: Sample rate [Hz] (>= 22500)
• `reference`: Measured source signal instead of the nominal m = 0.55 (Default: None)
• `levels` / `ambient`: as `sti_from_impulse_response`
• warns (`UserWarning`) if the recording is < 15 s (STI biased low) | `res = speech.stipa(recording, fs)`

• `STIResult` with `mtf` (7×2) | | `stipa_signal` | `function` | **STIPA test-signal generator (A.4/A.6.1).**
• `fs`: Sample rate [Hz] (>= 22500)
• `duration_s`: Duration [s] (Default: 18.0)
• `level`: RMS level [dB SPL] (Default: None → RMS 0.1)
• `seed`: Pink-noise seed (Default: None) | `sig = speech.stipa_signal(48000, duration_s=18.0)`

• 1D test signal, Ed. 5 male spectrum | | `sti_adjusted_for_levels` | `function` | **Occupancy-noise and speech-level adjustment (Ed. 4 Annex M).**
• `mtf`: measured m matrix (7×n), noise and masking included
• `measured_levels`: 7 band levels [dB SPL] during the measurement
• `measured_ambient`: same, background noise (Default: None)
• `operational_levels`: 7 band levels [dB SPL] of the condition simulated
• `operational_ambient`: same, occupancy noise (Default: None) | `res = speech.sti_adjusted_for_levels(mtf, measured_levels=lm, measured_ambient=nm, operational_levels=lo, operational_ambient=no)`

• `STIResult` at the operational levels | | `STIResult` | `dataclass` | **STI result.**
• `sti`: 0 to 1
• `mti`: band indices (7,)
• `mtf`: corrected m values (7×14 or 7×2)
• `band_levels` / `ambient_levels`: levels used or None
• `rating`: Annex F letter 'A+'…'U'
• `.adjusted_for_levels(operational_levels=…, operational_ambient=…)`: the same result at another condition (Annex M) | `res = speech.stipa(x, fs)`
`print(res.sti, res.rating)` | | `sound_intensity` | `function` | **p-p sound intensity (IEC 61043).**
• `p1`, `p2`: Microphone signals [Pa], equal length
• `fs`: Sample rate [Hz]
• `spacing_m`: Microphone separation Δr [m]
• `density`: Air density (Default: 1.204)
• `speed_of_sound`: Speed of sound (Default: 343.0)
• `fraction`: None, 1 or 3 (Default: None)
• `limits`: [f_min, f_max] (Default: [12, 20000])
• `bias_correct`: undo finite-difference under-read of band/broadband totals near `max_valid_frequency` (Default: False) | `res = emission.sound_intensity(p1, p2, fs, spacing_m=0.012, fraction=3)`

• `IntensityResult` | | `plot_pp_probe_geometry` | `function` | **Face-to-face p-p probe to scale.**
• `spacing_m` dr [m] (Default: 12 mm)
• `language` | `plot_pp_probe_geometry()`

• Also `IntensityResult.plot_geometry()` | | `IntensityResult` | `dataclass` | **Intensity result.**
• Per band (with `fraction`): `frequencies`, `intensity` [W/m²], `intensity_level`, `pressure_level`, `pressure_intensity_index`, `direction` (±1), `bias_correction`
• Broadband: `total_*` counterparts
• `max_valid_frequency`: 0.1·c/Δr
• `spacing_m`: the probe spacer [m], keyword-only and required | `res.total_intensity_level`
`res.total_direction` | | `field_indicators` | `function` | **ISO 9614-1 Annex A field indicators.**
• `pressure_levels`: Lpi per position [dB]
• `normal_intensity`: Signed Ini per position [W/m²]
• `temporal_intensity`: optional M short-time Ink samples at one fixed position, filling `f1` | `fi = emission.field_indicators(lp, i_n)`

• `FieldIndicators(f2, f3, f4, f1)` | | `FieldIndicators` | `dataclass` | **ISO 9614-1 Annex A indicators.**
• `f1`: temporal variability indicator (Eq. A.1), or `None` when no `temporal_intensity` was given
• `f2`: surface pressure-intensity indicator (Eq. A.3)
• `f3`: negative partial power indicator (Eq. A.6)
• `f4`: field non-uniformity indicator (Eq. A.8)
• f3 − f2 > 0 reveals negative partial power
• `.check_field_stationarity()`: the Table B.3 check on F1, a `FieldStationarityCheck` | `fi.f2, fi.f3, fi.f4`

• Criteria: Ld > F2, N > C·F4² | | `FieldStationarityCheck` | `dataclass` | **Is the field steady enough? F1 against the ISO 9614-1 Table B.3 limit.**
• `f1`: temporal variability indicator (Eq. A.1), a number or one value per band
• result: `limit` (0.6, `TEMPORAL_VARIABILITY_LIMIT`), `stationary` per band (F1 at most the limit, since Table B.3 acts only on F1 > 0.6), `passes` over them; no truth value: `bool()` raises
• `limit`, `stationary`, `passes` are read-only, read from `f1` | `fi.check_field_stationarity().passes` | | `dynamic_capability_index` | `function` | **Dynamic capability Ld (ISO 9614-1 §3.12).**
• `pressure_residual_intensity_index`: δpI0 [dB]
• `bias_error_factor`: K [dB] (Default: 10.0) | `ld = emission.dynamic_capability_index(18.0)`

• Adequate when `Ld > F2` (criterion 1) | | `temporal_variability_indicator` | `function` | **ISO 9614-1 temporal variability F1 (Eq. A.1).**
• `short_time_intensity`: M short-time-averaged signed In samples at one fixed position [W/m²], 1D `(samples,)` or 2D `(samples, bands)` | `f1 = emission.temporal_variability_indicator(samples)`

• Coefficient of variation of the M samples; Table B.3 acts above 0.6 | | `TEMPORAL_VARIABILITY_LIMIT` | `constant` | **ISO 9614-1 Table B.3 limit on F1** (0.6): above it the field is too variable and action code (e) applies | `fi.check_field_stationarity().limit == TEMPORAL_VARIABILITY_LIMIT` | | `residual_index_limits` / `ResidualIndexLimits` | `function` / `dataclass` | **IEC 61043 Table 2 minimum δpI0.**
• `device`: `'probe'`, `'processor'` or `'instrument'` (Default: `'instrument'`)
• `spacing_m`: microphone separation [m] (Default: 0.025; Note 1 adds 10 lg(x/25))
• `frequencies`: bands to report (Default: all 22, 50 Hz to 6.3 kHz) | `lim = emission.residual_index_limits("probe", spacing_m=0.012)`

• `lim.frequencies` [Hz], `lim.class_1`, `lim.class_2` minima [dB] | | `verify_intensity_class` | `function` | **IEC 61043 Table 2 class check.**
• `residual_index`: measured δpI0 per band [dB]
• `frequencies`: band centres [Hz]
• keyword-only: `device`, `spacing_m`, as above | `res = emission.verify_intensity_class(d, frequencies=f, spacing_m=0.012)`
`res.report("iec61043.pdf")`

• `IntensityInstrumentComplianceResult` | | `IntensityInstrumentComplianceResult` | `dataclass` | **IEC 61043 instrument class verdict.**
• `overall_class`: loosest class every band meets (1/2), or `None`
• `bands` (per-band rows keyed `frequency`, `class`, `residual_index_db`, the limits and the margins), `frequencies`, `residual_index`, `spacing_m`, `device`, `range_limited`
• read-only from the device and the separation: `limit_class1`, `limit_class2`, `spacing_offset_db`; the band rows and the class are read from them and the measured index
• `.binding_margin()` / `.failing_bands()` / `.reference_class()`
• `.phase_mismatch_deg(speed_of_sound=343.0)`: equivalent channel phase error per band [deg]
• `.plot()`: measured δpI0 over the two Table 2 masks
• `.report(path, *, metadata=None)`: one-page PDF fiche
• takes `frequencies`, `residual_index`, `device`, `spacing_m`; `bands`, `overall_class`, `range_limited` are read-only, read from them
• no truth value: `bool()` raises; read `overall_class` | `res.overall_class, res.binding_margin()` | | `instrument_class_from_components` | `function` | **IEC 61043 clause 8 combination rule.**
• `probe_class`, `processor_class`: 1 or 2 | `instrument_class_from_components(1, 2)`

• 1 only when both are class 1, else 2 | | `phase_mismatch_from_residual_index` | `function` | **δpI0 → channel phase mismatch.**
• `residual_index`: δpI0 [dB]
• `frequency` [Hz], `spacing_m` [m], `speed_of_sound` (Default: 343.0)
• φs = kd·10^(−δpI0/10) | `phase_mismatch_from_residual_index(20.0, 0.025, frequency=1000.0)`

• 0.26 degrees | | `residual_index_from_phase_mismatch` | `function` | **Channel phase mismatch → δpI0.**
• `phase_mismatch_deg`: φs [deg], > 0
• `frequency` [Hz], `spacing_m` [m], `speed_of_sound` (Default: 343.0)
• δpI0 = 10 lg(kd/φs) | `residual_index_from_phase_mismatch(0.05, 0.012, frequency=1000.0)`

• 24.0 dB | | `CalibrationWarning` | `warning class` | **Unreliable calibration recording.**
Emitted by `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]
• `period_hours` (keyword-only): Period durations [h] (Default: (12, 4, 8)) | `l = environment.lden(63.2, 58.1, 51.4)` | | `ldn` | `function` | **Day-night level (ISO 1996-1 §3.6.5).**
• `lday`/`lnight`: LAeq per period [dB]
• `period_hours` (keyword-only): Period durations [h] (Default: (15, 9)) | `l = environment.ldn(63.2, 51.4)` | | `composite_rating_level` | `function` | **Whole-day composite rating (ISO 1996-1 §6.5).**
• `periods`: list of (level, hours, adjustment) summing 24 h | `r = environment.composite_rating_level([(63, 12, 0), (58, 4, 5), (51, 8, 10)])` | | `assess_tonal_audibility` | `function` | **Tonal audibility & adjustment (ISO 1996-2 Annex C).**
• `tone_level` Lpt, `masking_noise_level` Lpn [dB]
• `center_frequency` fc [Hz] | `res = environment.assess_tonal_audibility(54.1, 45.2, 430.0)`

• `TonalAssessmentResult` (`.audibility`, `.adjustment`, `.plot()`) | | `tonal_audibility` | `function` | **ΔLta = Lpt−Lpn+2+lg[1+(fc/502)²·⁵] (Formula C.3).**
• `tone_level`, `masking_noise_level` [dB], `center_frequency` [Hz] | `d = environment.tonal_audibility(54.1, 45.2, 430.0) # 11.1 dB` | | `tonal_adjustment` | `function` | **Kt(ΔLta) piecewise (Formulae C.4-C.6).**
• `audibility` ΔLta [dB] | `tonal_adjustment(7.0) # 3.0 dB` | | `tonal_adjustment_from_mean_audibility` | `function` | **Kt from mean audibility ΔL (ISO 1996-2 Table J.1).**
• `mean_audibility` [dB], `coarse` (Default: False) | `tonal_adjustment_from_mean_audibility(5.0) # 3` | | `critical_bandwidth` | `function` | **Critical bandwidth (ISO 1996-2 Table C.1).**
• `center_frequency` [Hz] (100 Hz ≤ 500 Hz, else 20 %·fc) | `critical_bandwidth(4000.0) # 800 Hz` | | `assess_tonal_survey` / `TonalSurveyAssessment` | `function` / `dataclass` | **Which bands hold a prominent tone? The one-third-octave survey method (ISO 1996-2 Annex K).**
• `levels` [dB], `frequencies` [Hz]: a band is prominent when it exceeds both neighbours by 15 dB (25–125 Hz), 8 dB (160–400 Hz) or 5 dB (500–10 000 Hz); the end bands never are
• result: `min_level_differences`, `level_differences` (NaN at the ends), `prominent`, `tone_frequencies`, `.plot()`; no truth value: `bool()` raises, read `prominent`
• `TonalSurveyAssessment` takes `levels`, `frequencies`; `min_level_differences`, `level_differences`, `prominent`, `tone_frequencies` are read-only, read from them | `environment.assess_tonal_survey(levels, frequencies=freqs).tone_frequencies` | | `NoisePhase` | `dataclass` | **Noise phase Ti of steady emission (RD 1367/2007 Annex IV A.3.4.2 b).**
• `duration_hours` Ti [h], `laeq` background-corrected LAeq,Ti [dB]
• `kt`, `kf`, `ki` corrections [dB]; `label`
• `.correction` (capped at 9 dB), `.lkeq` | `NoisePhase(duration_hours=6, laeq=50.0, kt=6, kf=3) # LKeq,Ti = 59 dB` | | `tonal_correction` | `function` | **Kt from an unweighted 1/3-octave spectrum (Annex IV A.3.3).**
• `levels` [dB], `frequencies` [Hz]
• Lt = Lf − Ls against the arithmetic mean of the two neighbours; 8/12, 5/8 and 3/5 dB thresholds by band range | `res = environment.tonal_correction(levels, frequencies=freqs)`

• `TonalCorrectionResult` (`.correction`, `.plot()`) | | `TonalCorrectionResult` | `dataclass` | **RD 1367/2007 tonal correction.**
• `correction` Kt [dB] (0/3/6), `governing_frequency`
• `differences` Lt and `band_corrections` per band (NaN where not evaluable)
• `frequencies`, `levels` | `res.correction, res.governing_frequency` | | `low_frequency_correction` | `function` | **Kf from Lf = LCeq,Ti − LAeq,Ti (Annex IV A.3.3).**
• `lceq`, `laeq` [dB], background-corrected | `low_frequency_correction(63.0, 50.0) # 3.0 dB` | | `impulsive_correction` | `function` | **Ki from Li = LAIeq,Ti − LAeq,Ti (Annex IV A.3.3).**
• `laieq`, `laeq` [dB], background-corrected | `impulsive_correction(67.0, 50.0) # 6.0 dB` | | `total_correction` | `function` | **K = Kt + Kf + Ki, capped at 9 dB (Annex IV A.3.3).**
• `kt`, `kf`, `ki` [dB] | `total_correction(6, 3, 0) # 9.0` | | `corrected_level` | `function` | **LKeq,T = LAeq,T + Kt + Kf + Ki (Annex I A.2 c).**
• `laeq` [dB]; `kt`, `kf`, `ki` [dB] | `corrected_level(50.0, kt=6, kf=3) # 59.0 dB` | | `evaluation_period_level` | `function` | **LKeq,T from its noise phases (Annex IV A.3.4.2 b).**
• `phases`: `NoisePhase` list
• `duration_hours` T [h] (None = sum of Ti) | `evaluation_period_level(phases, duration_hours=12)` | | `long_term_corrected_level` | `function` | **Annual LK,x, energy mean of the daily levels (Annex I A.2 d).**
• `daily_levels` [dB]; `weights`: days each level represents | `long_term_corrected_level([57, 0], weights=[303, 62]) # 56.2` | | `round_reported_level` | `function` | **Rounding of Annex IV A.3.4.2: add 0,5 dB, take the integer part.**
• `value` [dB] | `round_reported_level(56.82) # 57` | | `outdoor_quality_objectives` | `function` | **Outdoor quality objectives Ld/Le/Ln (Annex II Table A).**
• `area_type`: 'e','a','d','c','b' or an alias
• `urbanization`: 'existing' or 'new' (−5 dB, Article 14.2) | `outdoor_quality_objectives("a") # 65/65/55 dB` | | `indoor_quality_objectives` | `function` | **Indoor quality objectives (Annex II Table B).**
• `building_use`: 'residential','sanitary','educational'
• `room_type`: 'living','bedrooms','classrooms','reading_rooms' | `indoor_quality_objectives("residential", "bedrooms")` | | `vibration_quality_objective` | `function` | **Indoor vibration objective Law [dB] (Annex II Table C).**
• `building_use` | `vibration_quality_objective("residential") # 75.0` | | `infrastructure_limits` | `function` | **Immission limits for new transport infrastructure (Annex III Table A1).**
• `area_type` | `infrastructure_limits("a") # 60/60/50 dB` | | `max_infrastructure_limit` | `function` | **LAmax limit for rail and airport infrastructure (Annex III Table A2).**
• `area_type` | `max_infrastructure_limit("a") # 85.0 dB` | | `activity_limits` | `function` | **Outdoor limits for activities and ports (Annex III Table B1).**
• `area_type` | `activity_limits("a") # LK,d/e/n = 55/55/45 dB` | | `adjacent_premises_limits` | `function` | **Noise transmitted to acoustically adjacent premises (Annex III Table B2).**
• `building_use`, `room_type` | `adjacent_premises_limits("residential", "bedrooms")` | | `RegulationLimits` | `dataclass` | **A day/evening/night limit triple of RD 1367/2007.**
• `day`, `evening`, `night` [dB]; `index`, `reference`, `description`
• Indexable by period, the key matched exactly; another key is a `KeyError`; `.as_dict()` | `lim["night"]` | | `assess_activity` | `function` | **Article 25 compliance of an activity or port.**
• `measurements`: phases keyed by period
• `limits`: a `RegulationLimits` row
• `long_term_levels` or `operating_days` / `year_days` / `closed_level`
• `new_activity` (Default: True; False = Article 25.2)
• `period_hours` | `v = environment.assess_activity({"day": day}, environment.activity_limits("a"), operating_days=303)`

• `ActivityAssessment` | | `ActivityAssessment` | `dataclass` | **RD 1367/2007 activity verdict.**
• `periods`: `PeriodAssessment` tuple; `limits`; `new_activity`
• `.passes`; no truth value: `bool()` raises
• `.plot()`; `.report(path, language='es')`: one-page inspection fiche → PDF | `v.passes`
`v.report("acta.pdf")` | | `PeriodAssessment` | `dataclass` | **One evaluation period against its limit.**
• `evaluation_period_level`, `reported_level` (rounded)
• `long_term_corrected_level`, `reported_long_term`
• `limit`, `daily_limit` (+3), `phase_limit` (+5), `max_phase_level`
• `phase_pass`, `daily_pass`, `long_term_pass`, `.passes`; no truth value: `bool()` raises
• takes `period`, `phases`, `duration_hours`, `evaluation_period_level`, `long_term_corrected_level`, `limit`, `new_activity`; `reported_level`, `reported_long_term`, `max_phase_level`, `phase_pass`, `daily_pass`, `long_term_pass` are read-only, read from them | `p.reported_level, p.long_term_pass` | | `ACOUSTIC_AREA_TYPES` | `constant` | **Acoustic area types of Article 7 of Ley 37/2003, keyed by letter.**
e sanitary/educational/cultural, a residential, d tertiary, c recreational, b industrial, f transport systems | `ACOUSTIC_AREA_TYPES["a"]` | | `RD1367_EVALUATION_PERIODS` | `constant` | **The three daily evaluation periods (Annex I A.1).** | `("day", "evening", "night")` | | `RD1367_PERIOD_HOURS` | `constant` | **Default period durations [h] (Annex I A.1 a).** | `{"day": 12, "evening": 4, "night": 8}` | | `RD1367_PERIOD_CLOCK_LIMITS` | `constant` | **Local-time start/end hour of each period (Annex I A.1 b).** | `{"day": (7, 19), ...}` | | `RD1367_CORRECTION_VALUES` | `constant` | **The only values a single correction takes (Annex IV A.3.3).**
Each table grades its parameter 0, 3 or 6 dB | `RD1367_CORRECTION_VALUES # (0.0, 3.0, 6.0)` | | `RD1367_MAX_CORRECTION` | `constant` | **Cap on Kt + Kf + Ki [dB] (Annex IV A.3.3).** | `9.0` | | `residual_sound_correction` | `function` | **Residual-noise correction L = 10 lg(10^(L'/10)−10^(Lres/10)) (Formula 16).**
• `measured_level` L', `residual_level` Lres [dB] | `res = environment.residual_sound_correction(58.0, 50.0)`

• `ResidualCorrectionResult` (`.corrected_level`, `.reportable_upper_bound`, `.reliable`) | | `gaussian_residual_level` | `function` | **Residual Leq from percentiles (ISO 1996-2 Annex I).**
• `l50` [dB]; exactly one of `l90` / `l95` (must not exceed `l50`) | `gaussian_residual_level(50.0, l90=40.0)` | | `environmental_expanded_uncertainty` | `function` | **U = k·u (ISO 1996-2 §4).**
• `standard_uncertainty` [dB], `coverage` probability 0.95 (k=2) / 0.80 (k=1.3) | `environment.environmental_expanded_uncertainty(2.18) # 4.36` | | `residual_correction_uncertainty` | `function` | **Uncertainty of the residual-corrected level (Formulae F.7-F.9).**
• `measured_level`, `residual_level`, `measured_uncertainty`, `residual_uncertainty` [dB] | `residual_correction_uncertainty(58, 50, 0.5, 2.0)` | | `uncertainty_from_repeated_measurements` | `function` | **Energy mean & uncertainty from repeats: primary Formulae (17)+(19) route, Formula (20) approximation alongside.**
• `levels` [dB] (≥ 2); warns when they spread > 3 dB | `res = environment.uncertainty_from_repeated_measurements(levels)`

• `RepeatedMeasurementResult` | | `TonalAssessmentResult` | `dataclass` | **Tonal assessment (ISO 1996-2).**
• `audibility` ΔLta, `adjustment` Kt [dB]
• `center_frequency`, `critical_bandwidth`; `.plot()`
• no truth value: `bool()` raises; read `adjustment` | `res.audibility, res.adjustment` | | `ResidualCorrectionResult` | `dataclass` | **Residual-corrected level (ISO 1996-2).**
• `corrected_level` [dB], `reportable_upper_bound` = measured L' [dB], `margin` [dB], `reliable` (> 3 dB; when False report the upper bound, not the correction)
• takes `corrected_level`, `reportable_upper_bound`, `margin`; `reliable` is read-only, read from them | `res.corrected_level, res.reliable` | | `EnvironmentalMeasurementWarning` | `warning class` | **Unreliable environmental-noise determination (ISO 1996-2:2017).**
• Residual within 3 dB of the measured level: no correction is allowed and only `reportable_upper_bound` may be reported (10.4)
• Repeated levels spreading more than 3 dB: `approximate_uncertainty` (Formula (20)) is unreliable there (10.5 Note 2)
• Subclass of `PhonometryWarning` | `warnings.simplefilter('error', EnvironmentalMeasurementWarning)`
Emitted by `environment.assessment.measurement` | | `RepeatedMeasurementResult` | `dataclass` | **Repeat-measurement mean & uncertainty (ISO 1996-2).**
• `mean_level`, `standard_uncertainty` (Formulae (17)+(19)), `approximate_uncertainty` (Formula (20)) [dB], `n` | `res.mean_level, res.standard_uncertainty` | | `linkwitz_riley` | `function` | **Audio crossover.**
• `x`: Signal array
• `fs`: Sample rate [Hz]
• `frequency`: Crossover frequency [Hz]
• `order`: Any even number (Default: 4) | `lo, hi = filters.linkwitz_riley(x, fs, frequency=1000, order=4)`

• `lo`: Low-pass filtered signal
• `hi`: High-pass filtered signal | | `parametric_eq` | `function` | **Parametric EQ, one shot (RBJ Audio EQ Cookbook).**
• `x`: Signal array (1D or 2D `[channels, samples]`)
• `fs`: Sample rate [Hz]
• `sections`: an `EQSection` or a sequence of them | `y = filters.parametric_eq(x, fs, sections=filters.EQSection(filter_type="peaking", f0=1000, gain_db=6.0))` | | `ParametricEQ` | `class` | **Reusable parametric-EQ cascade (RBJ Audio EQ Cookbook).**
• `fs`: Sample rate [Hz]
• `sections`: `EQSection` or sequence of them (cascade order)
• `stateful`: Block processing (Default: False)
• `steady_ic`: Steady-state initial conditions (Default: False)
• `.sos`: the designed cascade, `.filter(x)`, `.response()` | `eq = filters.ParametricEQ(fs, sections)`
`y = eq.filter(x)`
`res = eq.response()` | | `EQSection` | `dataclass` | **One cookbook biquad specification.**
• `filter_type`: 'peaking', 'lowshelf', 'highshelf', 'lowpass', 'highpass', 'bandpass', 'bandpass_skirt', 'notch', 'allpass'
• `f0`: Centre/corner frequency [Hz]
• `gain_db`: Gain (peaking/shelves) [dB]
• One of `q` (Default: 1/√2), `bw` [octaves] or `slope` (shelves) | `EQSection(filter_type="peaking", f0=1000.0, gain_db=-6.0, bw=1.0)` | | `EQResponseResult` | `dataclass` | **Parametric-EQ cascade response.**
• `frequencies` [Hz], `magnitude_db` [dB], `phase_rad` [rad]
• `section_magnitude_db`: per-section magnitudes [dB]
• `sos`: the cascade, `fs`, `sections`; `.plot()` magnitude + phase | `res = eq.response()`
`res.plot()` | | `sensitivity` | `function`| **SPL Calibration.**
• `reference_signal`: Calibration signal
• `target_spl`: Level of calibrator (Default: 94.0)
• `reference_pressure_pa`: Reference pressure (Default: 20e-6)
• `frequency`, `calibrator_class`: select the IEC 60942 Table 2 fluctuation limit the take is screened with (Default: 1000.0, `'1'`)
• `narrowband`: coherent Goertzel tone estimate that rejects broadband hum/noise (needs `fs`; Default: False) | `s = sensitivity(reference_signal, target_spl=94.0)`

• `s`: Float (multiplier for pressure) | | `read` | `function` | **Read a measurement audio file into a `Signal`.**
• `path`: WAV/BWF/RF64 in the base install; FLAC, AIFF, Ogg/Opus, MP3 with `[audio]`
• `calibration_factor`: digital units → Pa (Default: None; an existing sidecar is applied automatically, an explicit value wins)
Native fs kept, no downmix, no normalization; int PCM scaled by 2^(bits−1); lossy sources raise `LossyCompressionWarning` | `sig = io.read("night.wav")`

• `sig`: `Signal` (float64, (channels, samples), with fs, calibration, `bext`, labels) | | `info` | `function` | **Describe a file from its headers alone.**
• `path`: any supported container
No sample is decoded, so a 12-hour RF64 answers instantly; compressed WAV that `read` refuses still describes itself | `meta = io.info("night.wav")`

• `meta`: `AudioFileInfo` | | `read_blocks` | `function` | **Stream a file block by block.**
• `path`, `block_size` [samples]
• `overlap`: samples shared between consecutive blocks (Default: 0)
• `calibration_factor`: as in `read`; `None` takes the sidecar's (Default: `None`)
Yields exactly what `read` returns, in slices: feeds `BlockProcessing(stateful=True)` unchanged | `for block in io.read_blocks(p, 65536): ...`

• each `block`: a `Signal` with the rate, calibration, labels and provenance `read` gives | | `write` | `function` | **Write WAV/BWF (FLAC with `[audio]`) without touching the level.**
• `path`, `x` (array or `Signal`), `fs` (taken from `x` when `x` is a `Signal`)
• `subtype`: 'PCM_16'/'PCM_24'/'PCM_32'/'FLOAT'/'DOUBLE' (Default: FLOAT for float data, the matching depth for integer pass-through; FLAC: PCM up to 24)
• `bext`: None (Default) carries a `Signal`'s own provenance; `"loudness"` also measures the five EBU R 128 fields in-house; a `BroadcastMetadata` is written as given
• `dither`: 'tpdf' at PCM_16 only (Default: None)
• `rng`: `numpy.random.Generator` or int seed for the dither noise, for byte-reproducible writes (Default: None = fresh entropy)
• `sidecar`: write the calibration sidecar too (Default: False)
Never normalizes; clipping saturates, is counted and warns (`ClippingWarning`); RF64 automatic past 4 GiB | `io.write("out.wav", sig, subtype="PCM_24")` | | `convert` | `function` | **Convert between lossless containers with the measurement intact.**
• `src`, `dst`: WAV/BWF/RF64 ↔ FLAC (lossy targets refused)
Samples bit-exact at full precision, `bext` carried (into FLAC via the `riff` APPLICATION block), sidecar copied byte for byte, CodingHistory extended one line; streams, so an hour of RF64 converts flat | `io.convert("night.wav", "night.flac")` | | `Signal` | `dataclass` | **Samples plus the metadata they need.**
• `data`: (channels, samples) float64
• `fs` [Hz]
• `calibration_factor`: Pa per digital unit, or None until known
• `channel_labels`, `provenance` (`bext`), `source` (`SignalOrigin`)
`np.asarray(sig)` yields the bare array (1D mono), so every `(x, fs, ...)` function accepts it; `leq`/`laeq`/`ln_levels`/`sel`/`lc_peak`/`sound_exposure`/`lex_8h` read fs and calibration from it directly | `sig.duration_s`, `sig.n_channels`
`sig.plot()` draws the calibrated waveform | | `SignalOrigin` | `dataclass` | **Where a `Signal` came from.**
• `path`, `container`, `format_name`
• `bit_depth`: valid bits, None for lossy codecs
• `lossy`: the read-time warning, kept attached to the data | `sig.source.lossy` | | `AudioFileInfo` | `dataclass` | **Everything `info()` reads from the headers.**
• `container`, `format_name`, `fs`, `n_channels`, `n_samples`, `duration_s` [s], `bit_depth`, `lossy`
• `channel_mask` / `channel_labels` (EXTENSIBLE speaker positions)
• `bext`, `has_ixml`, `cue_points` | `io.info(p).duration_s` | | `BroadcastMetadata` | `dataclass` | **The `bext` chunk of EBU Tech 3285 v2, field by field.**
• `description`, `originator`, `originator_reference`, `origination_date`/`_time`
• `time_reference`: 64-bit samples since midnight
• `version`, `umid`
• v2 loudness: `loudness_value`, `loudness_range`, `max_true_peak_level`, `max_momentary_loudness`, `max_short_term_loudness` (0x7FFF sentinel → None)
• `coding_history` (EBU R98) | `io.info(p).bext.time_reference` | | `CuePoint` | `dataclass` | **One marker of a WAV `cue ` chunk.**
• `cue_id`, `position` [samples], plus the raw `chunk_id`/`chunk_start`/`block_start`/`sample_offset` fields of the spec | `io.info(p).cue_points` | | `CalibrationSidecar` | `dataclass` | **The versioned JSON sidecar that carries the calibration.**
• `calibration_factor`, `reference_spl`, `calibrator_frequency`, `calibrator_model`, `channel_labels`, `phonometry_version`
Lives at `