phonometry Documentation#

Full documentation for phonometry. Also available as a website: https://jmrplens.github.io/phonometry/

Guides#

• Getting Started: installation and first analysis
• Build a sound level meter: an end-to-end walk-through that composes the core API into a working meter: calibrate against an IEC 60942 tone, apply the IEC 61672-1 frequency and time weightings, integrate into Leq, SEL and percentile levels, split into IEC 61260-1 octave bands, and verify the class of every stage
• Filter Banks: architectures, responses, band decomposition
• Block Processing: stateful real-time workflows
• Multichannel: vectorized multichannel analysis
• Calibration and dBFS: physical SPL and digital analysis
• Integrated & Statistical Levels: Leq, LAeq, L10/L50/L90, LCpeak/SEL, noise dose (IEC 61252), Lden and rating levels (ISO 1996-1), octave spectrogram
• Frequency Weighting: A, C, Z curves
• Time Weighting: Fast, Slow, Impulse ballistics
• Loudness: Zwicker (ISO 532-1), Moore-Glasberg (ISO 532-2/3) and Sottek (ECMA-418-2) loudness in sones, plus the equal-loudness contours (ISO 226)
• Sound Quality Metrics: sharpness (DIN 45692) and the ECMA-418-2 Sottek Hearing Model tonality, roughness and fluctuation strength
• Prominent discrete tones: the ECMA-418-1 tone-to-noise and prominence ratios that decide whether a discrete tone is prominent and justify tonal rating adjustments
• Tonal audibility of tones in noise: the ISO/PAS 20065 engineering method for the audibility ΔL of a tone above the masking threshold: the critical band about the tone, the critical-band masking level, the masking index, and the decisive and mean audibility
• Psychoacoustic annoyance & fluctuation strength: the Fastl & Zwicker annoyance PA = N5·(1 + √(wS² + wFR²)) from loudness, sharpness, roughness and fluctuation strength (Eqs 16.2–16.4), the closed form for AM broadband noise (Eq. 10.2) and the Osses 2016 fluctuation-strength signal model
• Speech Transmission Index: how much of the speech envelope a room or sound system preserves: the IEC 60268-16 modulation transfer function, indirect method and direct STIPA measurement
• Speech Intelligibility Index: the ANSI S3.5-1997 one-third-octave-band SII: band-importance weighting (Table 3), self-speech and upward spread of masking, band audibility, and the index in noise and hearing loss
• Objective intelligibility (STOI & ESTOI): the correlation-based intelligibility measures for time-frequency weighted noisy speech from a clean/degraded pair: STOI (Taal et al. 2011), the clipped per-band envelope correlation, and ESTOI (Jensen & Taal 2016), the row- and column-normalised spectral correlation that tracks modulated maskers
• Electroacoustics: distortion & frequency response: the IEC 60268-3 distortion set (THD, nth-order harmonic, THD+N and SINAD via AES17, SMPTE and CCIF intermodulation, dynamic intermodulation and weighted THD), the AES17 dynamic range and idle channel noise, and the Bendat & Piersol H1/H2 frequency-response estimators with the ordinary coherence γ²
• Swept-sine distortion and phase utilities: harmonic separation from one exponential sweep (Farina 2000) with the synchronized swept-sine of Novak et al. 2015 for coherent harmonic phases, THD as a function of the excitation frequency, and minimum phase from |H| (real cepstrum), group delay and excess phase
• Industrial noise control: silencers, HVAC & enclosures: reactive silencers by the four-pole transmission-matrix method (expansion chambers, Helmholtz and quarter-wave resonators, extended tubes) with transmission and insertion loss, the HVAC duct methods (end reflection, elbows, plenums and flow-generated noise) and machine-enclosure insertion loss from a supplied panel R and the interior room constant (Bies, Hansen & Howard)
• Programme loudness & true peak: the ITU-R BS.1770-5 programme loudness (K-weighting, gated 400 ms blocks, channel weights including the Annex 3 positions) and the oversampled true-peak level in dBTP, with the EBU R 128 −23 LUFS practice, the Tech 3341 EBU Mode momentary/short-term/integrated meters and the Tech 3342 loudness range, validated against the official EBU test signals
• Underwater acoustics: radiated noise & pile driving: the ISO 18405 reference levels (SPL, SEL, peak re 1 µPa), the ISO 17208 ship radiated noise level and equivalent monopole source level via the Lloyd's-mirror correction, and the ISO 18406 single-strike, peak and cumulative pile-driving sound exposure
• Underwater sound propagation: closed-form transmission loss (geometrical spreading plus volume absorption by Francois-Garrison, Ainslie-McColm or Thorp), the speed of sound in sea water (UNESCO/Chen-Millero, Del Grosso, Mackenzie) with the sound-speed profile, the passive/active sonar equation, seabed reflection loss (Rayleigh), the ocean ambient-noise spectrum (Wenz wind/thermal plus JOMOPANS-ECHO ship-traffic source levels) and numerical solvers (normal modes, ray tracing, parabolic equation)
• Aircraft noise: Effective Perceived Noise Level: the ICAO Annex 16 Vol. I Appendix 2 EPNL (perceived noisiness and PNL, the tone correction by the slope method, and the 10 dB-down duration correction), the IEC 61265 measurement-system verifier, the SAE ARP 5534 one-third-octave-band atmospheric absorption (SAE Method), and the ECAC Doc 29 noise-power-distance (NPD) event-level interpolation
• Rotorcraft noise: the hemisphere method: the ECAC Doc 32 / NORAH2 helicopter noise hemisphere source model, its propagation adjustments (spherical spreading, ISO 9613-1 / Table 4 atmospheric absorption, Chien-Soroka ground effect over CNOSSOS impedance ground), the flight-condition interpolation and track kinematics, the single-event SEL/LASmax/EPNL with ground-grid contours, and the terrain machinery (mean ground plane, log-mean flow resistivity, rubber-band screening, digital elevation models)
• Wind-turbine noise: apparent sound power & tonal audibility: the IEC 61400-11 apparent sound power level referred to the rotor centre and the tonal-audibility chain (Zwicker critical band, masking-noise level and audibility criterion)
• Hearing threshold: the age-related hearing threshold distribution (ISO 7029:2017) and the free-field/diffuse-field reference threshold of hearing (ISO 389-7:2005)
• Noise-induced hearing loss: the ISO 1999:2013 noise-induced permanent threshold shift (NIPTS) and its population distribution, and the combination with age into the hearing threshold level associated with age and noise (HTLAN)
• Occupational noise exposure: the ISO 9612 task-based, job-based and full-day measurement strategies and the Annex C uncertainty budget behind every LEX,8h report
• Sound Intensity (p-p): two-microphone intensity and field indicators
• Sound Power: sound power level by enveloping surface (ISO 3744/3746), reverberation room (ISO 3741), intensity scanning (ISO 9614-2), and the precision grades in an anechoic room (ISO 3745) and by precision intensity scanning (ISO 9614-3)
• Room Acoustics: impulse-response acquisition (ISO 18233), reverberation and room parameters (ISO 3382-1/2), open-plan speech metrics (ISO 3382-3), reverberation-room sound absorption (ISO 354)
• Sound absorption in enclosed spaces: the EN 12354-6:2003 prediction of a room's total equivalent absorption area and reverberation time from its surfaces and objects (Clause 4)
• Reverberation-time prediction: the reverberation time from a room's volume and surface absorption by five statistical models (Sabine, Eyring, Millington-Sette, Fitzroy, Arau-Puchades), with the air-absorption term
• Image sources and the steady-state room field: the deterministic image-source room impulse response of a rectangular room (Kuttruff/Vorländer) and the statistical steady-state level with the room constant, critical distance and Schroeder frequency (Bies)
• Dynamic stiffness of resilient materials: the EN 29052-1:1992 dynamic stiffness per unit area of floating-floor resilient layers from the load-plate resonance, and the floating-floor natural frequency
• Mechanical mobility and the FRF family: the ISO 7626-1:2011 family of motion-per-force frequency-response functions (receptance, mobility, accelerance and their reciprocals, Table 1), conversion through the receptance pivot, and the single-degree-of-freedom reference resonator (Annex A)
• Dynamic transfer stiffness of resilient elements: the ISO 10846 dynamic transfer stiffness k₂₁ of vibration isolators: the level Lₖ re 1 N/m and loss factor, the direct and indirect (transmissibility) determination methods, and the Annex-A relation to mechanical impedance and effective mass
• Sound power from surface vibration: the ISO/TS 7849 estimation of a machine's radiated airborne sound power from its surface vibratory velocity and a radiation factor: the velocity level and calibration, the surface mean, and the Part 1 upper limit (ε=1) versus the Part 2 engineering value
• Structure-borne sound power of building equipment: the EN 15657 reception-plate method with the plate-injected power level, the spatial mean plate velocity, the loss factor from the structural reverberation time, and the blocked-force / characteristic-level / free-velocity source quantities from the low- and high-mobility plates
• Installed structure-borne sound from equipment: the EN 12354-5 prediction of the receiving-room sound pressure level from service equipment: the coupling term from source and receiver mobilities, the installed structure-borne power, and the per-path transmission with its energetic total
• Bending-wave transmission at plate junctions: the wave-approach (Cremer/Craik/Hopkins 5.2.1.3) frequency-independent bending-wave transmission coefficients for rigid X, T, L and in-line plate junctions, their diffuse-field angular average, and the derived coupling loss factor and vibration reduction index Kij
• Room-noise criteria: the ANSI/ASA S12.2-2019 room-noise ratings: the NC tangency method (Table 1) and the RC Mark II rating with its rumble/hiss/neutral spectral tag (Annex D)
• Acoustic Materials: sound-absorption rating α_w and classes (ISO 11654), airflow resistance static and alternating methods (ISO 9053-1/-2), and impedance-tube measurement of absorption, surface impedance and transmission loss (ISO 10534-1/-2, ASTM E2611)
• Porous and Multilayer Absorbers: the Delany-Bazley, Miki and Johnson-Champoux-Allard porous models, the transfer-matrix multilayer solver with perforated, microperforated (Maa) and membrane layers, and the random-incidence Paris integral
• Surface Scattering, Diffusion and In-situ Absorption: random-incidence scattering (ISO 17497-1), free-field diffusion coefficient (ISO 17497-2), and in-situ road-surface absorption by the extended-surface subtraction technique (ISO 13472-1) and the spot method (ISO 13472-2)
• Field Insulation Measurement and Ratings: field airborne/impact/façade insulation and weighted ratings (ISO 16283-1/2/3, ISO 717-1/2), measurement uncertainty (ISO 12999-1) and the ISO 10052 survey method
• Laboratory Insulation Measurement: laboratory characterisation (ISO 10140), sound insulation by intensity (ISO 15186), floor-covering impact improvement (ISO 16251-1) and laboratory flanking transmission (ISO 10848)
• Predicting Sound Insulation (EN 12354): flanking-transmission prediction (EN 12354-1/2), façade insulation and outdoor radiation (EN 12354-3/4)
• Predicting Panel Sound Insulation: theoretical airborne insulation of single panels (mass law and coincidence, Sharp) and double walls (mass-spring-mass, Bies), transmission through slits and apertures (Gomperts/Wilson-Soroka), plate radiation efficiency (Leppington/Maidanik) and the point mobilities of infinite plates and beams (Cremer)
• Outdoor Sound Propagation: atmospheric absorption α(f) (ISO 9613-1) and the ISO 9613-2 general method: divergence, atmospheric absorption, ground effect and barrier screening
• Spherical ground effect and advanced barriers: the Weyl-Van der Pol spherical-wave reflection coefficient over a finite-impedance ground, and wave-theoretic barriers (Kurze-Anderson Fresnel number, exact rigid half-plane, thick barriers and the coherent four-path barrier on the ground)
• Atmospheric refraction: rays and the parabolic equation: effective sound-speed profiles (linear and logarithmic), ray tracing through a refracting atmosphere (curved paths, turning points, closed-form curvature radius and shadow-zone distance) and the Green's Function parabolic equation (GFPE) for the relative-level field over the range-height plane, anchored to the spherical ground effect in the homogeneous limit
• Impulsive-sound prominence: the NT ACOU 112:2002 predicted prominence of impulsive sounds (onset rate and level difference) and the graduated adjustment KI added to LAeq
• Human Vibration: whole-body and hand-arm frequency weightings (ISO 8041-1), weighted r.m.s. acceleration, running r.m.s./MTVV/VDV and crest factor (ISO 2631-1), vibration in buildings (ISO 2631-2), vibration total value and daily exposure A(8) (ISO 5349-1/-2), and the exposure action/limit values of Directive 2002/44/EC
• Multiple-shock whole-body vibration: the ISO 2631-5:2018 spinal-response model: the seat-to-spine transfer function, the acceleration and daily dose from the response peaks (Clause 5), and the compressive stress, stress variable R and Weibull probability of lumbar injury (Annex C)
• Measurement uncertainty: the GUM law of propagation of uncertainty and the Monte Carlo method (ISO/IEC Guide 98-3:2008 and Supplement 1): combined and expanded uncertainty, Welch–Satterthwaite effective degrees of freedom, and probabilistically symmetric coverage intervals
• Data qualification: the Bendat & Piersol stationarity tests (reverse arrangements with the Table A.6 acceptance regions, runs about the median with the exact Wald-Wolfowitz distribution) on segment mean squares, and the Rice statistics of level crossings, apparent frequency, peak rates and the irregularity factor that places the peak-height distribution between Rayleigh and Gaussian
• Calibrated spectral analysis: the Bendat & Piersol Welch estimators with their statistical quality: PSD and cross-spectral density with the effective number of averages, normalized random errors and chi-square confidence intervals, the coherent output spectrum with the spectral SNR, constant-power 1/n-octave smoothing, colored-noise generators with an exact power-law slope, and the Harris window figures of merit for choosing the taper
• Time-frequency analysis: the calibrated STFT spectrogram in absolute dB SPL with the exact Welch-module scaling and the time-versus-frequency resolution trade-off, and the zoom FFT that resolves tones closer than a practical FFT bin
• 2D FDTD wave simulation: the deterministic staggered-grid pressure-velocity FDTD solver (Attenborough & Van Renterghem 2021, chapter 4) with Gaussian, tone and arbitrary-signal sources, pressure probes, rasterised obstacles, rigid/impedance/absorbing boundaries, and a result object with probe histories and field snapshots
• Multiple and partial coherence: the Bendat & Piersol multiple-input/output coherence functions for several correlated sources and one output, with the Gaussian-elimination conditioning that separates a genuine cause from a source that merely correlates with it, and the partial coherent output spectra that say which source dominates each band
• Correlation, time delay and envelope: auto- and cross-correlation with the Bendat & Piersol normalizations and random errors, time-delay estimation by the direct correlator, the cross-spectrum phase slope and the Knapp & Carter GCC (Roth, SCOT, PHAT, maximum likelihood) with the Eq. 8.129 peak-location uncertainty, sub-sample impulse-response delay and alignment, and the Hilbert envelope with instantaneous phase and frequency
• Test signals and sample-rate tools: IEC 60268-1 tone bursts with exact gating (zero-crossing start, integral full periods, repetitive trains), polyphase resampling behind an explicit anti-alias specification whose designed Kaiser filter travels with the result, and band-limited fractional delay with a linear or circular boundary
• Cepstrum, echoes and the envelope spectrum: the power, real and complex cepstrum with quefrency analysis, echo detection with the reflection coefficient read off the cepstral peak, lowpass/highpass liftering of a log spectrum, the homomorphic round trip of the complex cepstrum, and the envelope spectrum that turns amplitude modulations into discrete lines
• Time synchronous averaging: extraction of a periodic waveform of known period by time domain averaging (McFadden 1987), the comb filter that describes the operation in the frequency domain with unit teeth at the harmonics and nodes between them, the square-root noise-reduction law, and the choice of the number of averages that places a comb node on an interfering order
• System measurement: Golay, shaped sweeps, inversion: complementary Golay pairs whose periodic autocorrelations sum to an exact delta and deconvolve a noiseless system to machine precision, sweeps synthesized to follow an arbitrary target magnitude spectrum by group-delay shaping (Mueller & Massarani) with a near-ideal crest factor, and the regularized spectral inversion of a measured response with Kirkeby frequency-dependent regularization, achieved flatness and a capped out-of-band gain

Reference#

• API Reference: curated quick table of every public function and class
• Generated API reference: one page per public module, generated from the source docstrings (make api-docs). English only; the Spanish site serves it via locale fallback
• Theory: standards, math and design decisions, split by domain
  • Signal analysis: filter banks, weightings, time integration, level and exposure metrics, sound intensity, GUM uncertainty
  • Perception and hearing: equal-loudness contours, loudness models, sound quality, tone prominence, STI/SII, hearing statistics
  • Rooms and buildings: room acoustics, noise criteria, insulation and ratings, flanking prediction
  • Materials and surfaces: scattering and diffusion, in-situ road-surface absorption, absorption ratings, airflow resistance, impedance tube
  • Environment and transport: environmental descriptors, impulsive adjustment, outdoor propagation, occupational exposure, sound power
  • Vibration: human vibration weightings and metrics, multiple-shock spinal model
• Why phonometry: IEC compliance vs other libraries
• Bibliography: the books and papers behind the guides, grouped by domain, every entry with a verified DOI or official publisher link
• Conformance report: auto-generated numerical validation: every check pins a standard clause's expected value against the library's computed value, regenerated in CI
• Standards errata: defects found in the published standards themselves during implementation: misprints, examples contradicting their own normative text, ambiguous wording, each with evidence and the library's disposition

Development#

Run the test suite with pytest tests/, the full quality gate with make check (ruff + mypy + bandit + tests), and regenerate the documentation images with make graphs. See CONTRIBUTING.md.