Eve library

Speech normalization probe — 2026-09-10

Guide

Revision 1

On this page

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#

text
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.