level op• Data kinds: signal → table
• Call: import acoustics; acoustics.octave_spectrum(x, rate, fraction=3, f_min=22.0, f_max=None, ref=1.0, weighting='Z', floor_db=-200.0) (or opsacoustics.get("octave_spectrum"))
Band levels in dB, summed over fractional-octave bands by Parseval.
Energy is accumulated from the single-sided periodogram into the bands
:func:octave_bands defines, so the band powers sum to the signal's
mean-square exactly (up to the bins outside the requested range). That
identity is the test: measured on 16384 samples of white noise at 16 kHz
over 22 Hz - 8 kHz at 1/3 octave, the band powers sum to 0.996367 of
`mean(x**2) while total_power` (which counts every FFT bin) comes to
1.000000 of it. The 0.36 % difference is exactly the bins outside the
requested range, and returning both numbers is what makes that visible
instead of leaving a reader to wonder where the energy went.
The reference is explicit and there is no implicit 20 uPa. `ref` is an
amplitude in the same units as the signal, and the default 1.0 means "dB
relative to one unit of whatever you passed in". This library never sees a
microphone calibration, so a number labelled dB SPL would be a fabrication;
pass `ref=20e-6` when the signal really is pascals and the result really is
dB SPL.
`weighting applies :func:apply_weighting first ("Z"` = none).
Returns a dict: `centers, nominal, lower, upper, levels`
(dB), `powers (mean-square), total_level, total_power`,
`clamped (bool mask of bands floored at floor_db), ref`,
`weighting, fraction, resolution_hz, narrow_bands` (how many
FFT bins landed in each band — a band with 0 or 1 is under-resolved and the
level is not trustworthy), and `truncated`.
`truncated` is a bool mask of bands whose upper edge is above Nyquist,
which means only the part of the band below Nyquist was measured and the
level is the level of that part, not of the band. This is not an exotic
case: `f_max` bounds band *centres*, so the top band's edge always
overhangs it by half a band width, and the **default `f_max = 22050`
against the canonical rate of 44100** puts the top third-octave band at
17782.79-22387.21 Hz over a Nyquist of 22050. Measured on 1 s of white
noise at 44100: that band collects 4268 of the 4604 bins it spans
(7.3 % missing) and reported a level with nothing in the old return value
saying it was partial. Nothing raises — the missing bins simply do not
exist. Drop the flagged bands, or lower `f_max` until
`upper[-1] <= rate/2`.
Measured exactness: a 1 kHz sine of amplitude 0.7 at 16 kHz over exactly
1000 periods, `ref=1.0`, gives the 1 kHz band level
-6.1083391564 dB against the closed form
`10*log10(0.7**2/2) = -6.1083391564` dB — the difference is
0.000e+00. 25 of the 26 bands are at the floor, and `total_level`
equals the band level to the digit shown, because there is nothing else in
the record.
Raises `ValueError: everything :func:_as_signal` and
:func:octave_bands refuse, `ref <= 0` (a dB with a zero or negative
reference is not a number), an unknown `weighting, and an f_max` above
Nyquist.
• acoustic_condition_monitoring family guide
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• The canonical algorithm (author, year) and its uses are named in the family usage guide above.
• acoustic_condition_monitoring — py -3.11 examples/acoustic_condition_monitoring.py
table as input)level)octave_bands · weighting_response · apply_weighting · equivalent_level · percentile_level
*Provenance: acoustics.py — ACOUSTICS operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.