| name | audit-headroom |
| description | No note, at any velocity, may clip or ride the master limiter — and every instrument sits at a matched loudness. Clipping is invisible to RMS gates and corrupts every other measurement. Usage - audit-headroom <instrument> |
audit-headroom — nothing clips, everything is level-matched
The trombone shipped ~35 dB too hot and CLIPPED ON EVERY NOTE, sitting slammed into the master
limiter its entire life. The damage was not just distortion: the limiter CRUSHED ITS DYNAMICS
FLAT (measured 15 dB pp→ff when the model produced 26), and clipping MANUFACTURES HARMONICS, so
every brightness number taken while it was hot was made on distorted audio. Headroom is a
PREREQUISITE for trusting audit-voice and audit-dynamics.
The procedure
- Render EVERY note of the instrument's range (not a coarse sample — a hot note hides between
grid points) at ≥3 velocities including 1.0.
- Measure the SAMPLE peak, never an RMS envelope. A rich waveform has 6+ dB of crest
factor: RMS 0.5 is a peak of 1.0. A gate that cannot see a clipped sample cannot see a
clipped instrument.
- Pass bar: worst sample peak < 0.95 across the full range × velocities. Reference gate:
no_instrument_clips_anywhere_in_its_range (in lib.rs) — ADD the instrument to it.
- Level match: solo notes land near the family's target loudness (the makeup_gain / per-voice
level bake). A trumpet at peak 0.06 is as wrong as one at 1.0 — too quiet to sit in a mix.
Diagnose
- A single hot NOTE (not the whole range) is usually a body/bore resonance ringing up at one
pitch, or a bad parameter at that register (the cello hit 0.964 at m63 because a stray sweep
left it at sul-ponticello beta=0.03). Find the note, fix the cause, don't just turn it down.
- The whole instrument too hot/quiet is the level bake — re-bake against the family reference.
Gotchas
- Step the gate every SEMITONE for the worst-case check, or at least verify the note the
scan flags. The clip gate steps every 3rd semitone and MISSED the cello's m63.
- Re-bake level AFTER any timbre change that alters crest factor (a warmth lowpass, a
brightness tilt, a nonlinearity all move the peak).
- The playground / façade exposure is a real ship gate too: an instrument reachable by a user
must not clip; a dormant one can wait.
