# Speech normalization probe — 2026-09-10

Evidence for `182.C.08.06`, and two bugs it caught that the unit tests could
not: the module's own ffmpeg chain, run against a real clip.

## Method

A synthetic source with the shape a normalizer has to handle — 22.05 kHz,
stereo, quiet, 0.9 s of leading silence and 0.6 s of trailing silence around 3.5
s of tone:

```sh
ffmpeg -f lavfi -i "sine=frequency=220:duration=3.5:sample_rate=22050" \
  -af "adelay=900|900,apad=pad_dur=0.6,volume=-8dB" -ac 2 in.wav   # 5.000 s
```

Targets: −16 LUFS, −1.5 dBTP, 48 kHz, mono, 0.1 s lead-in, 0.2 s tail. The plan
that produces is: trim 0.8 s off the head, 0.4 s off the tail, resample,
downmix, correct loudness.

## Bug 1 — the planned tail trim was never emitted

The first version of `buildSpeechNormalizationArgs` emitted `atrim=start=…`
only. Run for real:

| Chain                             | Output duration | Expected |
| --------------------------------- | --------------- | -------- |
| `atrim=start=0.8` (as emitted)    | **4.200 s**     | 3.800 s  |
| `atrim=start=0.8:end=4.6` (fixed) | **3.800 s**     | 3.800 s  |

`verifySpeechNormalization` subtracts BOTH trims when computing the expected
length, so the original chain would have thrown `SpeechTimingShiftError` on a
perfectly correct clip — a timing guard failing on the one case it exists to
allow. Every string-level test passed, because the string it asserted was the
string being emitted.

## Bug 2 — loudness was corrected before the downmix

With the trim fixed, the output measured **−19.0 LUFS** against a −16 target.
The cause is filter order, not the filter:

| Order                                     | Landed loudness |
| ----------------------------------------- | --------------- |
| `loudnorm` → `aresample` → `aformat` mono | **−19.0 LUFS**  |
| `aresample` → `aformat` mono → `loudnorm` | **−15.9 LUFS**  |

Summing two correlated channels into one changes the level `loudnorm` just set,
by about 3 LU here. The module now orders trim → resample → channel layout →
loudness → peak limit → pad, with the reason recorded beside the code and a test
asserting the order rather than only the presence of each filter.

## Single-pass `loudnorm` convergence

The 3 LU miss above raised the question of whether single-pass `loudnorm` is
simply loose on short clips. Measured separately, with nothing else in the
chain:

| Clip            | Before     | After single pass |
| --------------- | ---------- | ----------------- |
| 3.5 s sine      | −29.9 LUFS | **−16.0**         |
| 4 s pink noise  | −23.5 LUFS | **−16.0**         |
| 20 s pink noise | −23.5 LUFS | **−16.0**         |

It is not loose. `LOUDNESS_TOLERANCE_LU` is 1 because that sits comfortably
outside the observed 0.0–0.1 error and comfortably inside the 3 LU that a wrong
filter order produced — a tolerance wide enough to hide that bug would not have
been worth having.

## Final chain, end to end

```
atrim=start=0.8:end=4.6, asetpts=PTS-STARTPTS,
aresample=48000:resampler=soxr, aformat=channel_layouts=mono,
loudnorm=I=-16:TP=-1.5:LRA=11
```

| Property    | Source     | Normalized                      |
| ----------- | ---------- | ------------------------------- |
| Duration    | 5.000 s    | **3.800 s** (= 5.0 − 0.8 − 0.4) |
| Sample rate | 22 050 Hz  | **48 000 Hz**                   |
| Channels    | 2          | **1**                           |
| Loudness    | −29.9 LUFS | **−15.9 LUFS**                  |

The duration is exactly what the plan predicted, which is the claim
`182.C.08.06` turns on: word onsets move by the head trim and by nothing else.
