docs(plans): calibrate how much the clip-before-duck fix actually changes

The before/after pair was listened to and the difference was barely
detectable. That is a real result, not a bad test: sweeping the chain's
overshoot shows the damage scales with it, and the pair happened to sit at the
bottom of the range.

  chain peak 0.48x -> nothing clamped, -70 dB (16-bit rounding only)
  chain peak 1.35x ->  2.1% of samples, -25.1 dB  <- what was listened to
  chain peak 2.69x -> 19.3% of samples,  -9.1 dB
  chain peak 4.00x -> 48.8% of samples,  -3.3 dB

So a chain that stays under full scale is completely unaffected — the fix
changes nothing for it — and 55f852a72's "audible distortion" framing is
overstated for mild chains. The fix is still right: it destroys data the lane
was about to scale down anyway. But it belongs with correctness work rather
than with "renders sound wrong today", and the handoff now says so plainly so
nobody re-derives the severity from the commit message alone.

The commit itself is left alone rather than rebasing 15 commits over an
adjective; the measurement lives here instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-08-09 03:06:24 -07:00
co-authored by Claude Opus 5
parent 9983bdaaaf
commit 87dc466f17
+24 -12
View File
@@ -159,18 +159,30 @@ falsified by mutating the fix out.
Three judgement calls worth knowing:
- **§4a-1 changes rendered audio** for every track with both a chain and a
lane. A before/after pair driving the real code path on real narration is at
`~/audio-fx-clip-ab/{before,after}-levelmatched.wav`, level-matched so the
only difference is what the clamp destroyed. **Nobody has listened to it
yet.** The numbers: the chain peaks at 1.346, the old order sheared 19,166
samples (1.7% of the file) flat against ±1, and level-matched the two differ
by an error signal 26.3 dB down with a worst single-sample delta of 0.242.
The generator sits beside them — `bun ~/audio-fx-clip-ab/ab-clip.mts <outdir>
<source.wav>` — so the pair can be rebuilt with a different chain, a
different duck, or the user's own audio. It drives the real
`applyAudioFxChain`, once with the envelope and once without followed by the
mixer's old second pass, so "before" is the actual previous behaviour rather
than a simulation of it.
lane — but **how much depends entirely on how far the chain overshoots**, and
the severity in `55f852a72`'s message is overstated for mild chains. Measured
on 8 s of narration through a peaking band into saturation, lane at -12 dB:
| Chain output peak | Samples changed | Error vs. correct | Verdict |
| --- | --- | --- | --- |
| 0.48x | none | -70.0 dB | nothing clamped; 16-bit rounding only |
| 1.35x | 2.1% | -25.1 dB | **the author listened and could barely tell** |
| 2.69x | 19.3% | -9.1 dB | plainly audible grit |
| 4.00x | 48.8% | -3.3 dB | not the same recording |
So: **a chain that stays under full scale is unaffected** — the fix changes
nothing for it. The bug is real and worth fixing (it destroys data that the
lane was about to scale down anyway, and there is no reason to accept that),
but it is not the everyday audible defect the commit message implies. If the
stack ever needs prioritising, this belongs with correctness fixes, not with
"renders sound wrong today".
The A/B page covering all four levels is published as an artifact; the pair
generators live at `~/audio-fx-clip-ab/ab-clip.mts` (one pair) and
`~/audio-fx-clip-ab/build-levels.mts` (the sweep above). Both drive the real
`applyAudioFxChain`, so "before" is the previous behaviour rather than a
simulation of it.
- **§4a-4 striding was tried and rejected.** Capping Welch at N windows is 27x
faster on a 5-minute voiceover (427 ms → 15 ms) but *changes the carve*: at
strength 0.9 the selected band set moved (630 Hz → 160 Hz) and it did not