setup: one-shot install.sh; docs: install, fixed-gain normalization, latency

docs/TTS-DESIGN.md

@@ -214,9 +214,17 @@ record what the engine needs to interpret, add, or hide._
   so one shared level target is required. The engine post-processes every line:
   resample to 48000 Hz, trim leading silence (<100 ms), 5-10 ms fades, DC removal, and
   level normalization (peak about -3 dBFS, integrated loudness -16 to -20 LUFS).
-- Proposed implementation, engine-side, with ffmpeg (already installed on the dev host):
-  `ffmpeg -i raw.wav -af "highpass=f=40,<trim><fade>,loudnorm=..." -ar 48000 -ac 1 out.wav`.
-  The WAV handed to Veskslop is then compliant; the "Veskslop does not normalize" rule holds.
+- Implemented in `setup/vekslop-tts.sh` with ffmpeg: high-pass at 40 Hz, silence trim at
+  both ends (trim-start, reverse, trim-start, reverse), 8 ms fades, then a **fixed gain**
+  computed from an EBU R128 measurement (`ebur128=peak=true`):
+  `gain = min(-16 LUFS target, -3 dBFS true-peak clamp)`, then 48 kHz mono s16le.
+- `loudnorm` was rejected: on short lines (under about 3 s) the loudness range is 0 and
+  dynamic mode attenuated a 2.8 s line to -37.9 LUFS instead of about -18 LUFS; two-pass
+  linear mode showed the same result. The fixed gain is steady for one-line utterances,
+  as Veskslop suggested.
+- Verified: Keith Bell -18.4 LUFS, Kerry Watson -17.9 LUFS, Sam -20.6 LUFS; every file is
+  48 kHz mono s16le at -3.0 dBFS true peak. The WAV handed to Veskslop is compliant; the
+  "Veskslop does not normalize" rule holds.
 
 ### Voice IDs
 
@@ -258,15 +266,22 @@ record what the engine needs to interpret, add, or hide._
 
 ### Transport and latency
 
+- Installation is one command: `setup/install.sh` (system dependencies with sudo, wine
+  prefix + SAPI4 runtime + MSTTS voices, Flextalk extraction/registration, host build).
+  Re-running is safe; a fresh machine needs nothing else.
 - Command provider, implemented as `setup/vekslop-tts.sh`:
   `VESKSLOP_TTS_CMD="<repo>/setup/vekslop-tts.sh {out} {text_file}"` and
   `VESKSLOP_TTS_VOICES="$(<repo>/setup/vekslop-tts.sh --voices)"`. The wrapper reads the
   text file, transliterates UTF-8 to CP1252, starts or reuses an Xvfb when `DISPLAY` is
-  unset, calls the engine, then post-processes (trim, fades, two-pass `loudnorm`, 48 kHz
-  mono s16le). Verified: -17.7 LUFS integrated, -3.0 dBFS true peak.
-- Measured on the dev host (warm Wine): Sam line about 288 ms wall, Flextalk line about
-  41 ms wall, including process start, synthesis, and file write. Both are inside the
-  500 ms budget.
+  unset, calls the engine, then post-processes (trim, fades, measured fixed gain, 48 kHz
+  mono s16le). A stale private Xvfb is retried once.
+- Measured on the dev host: engine-only synthesis is about 290 ms wall for Sam and about
+  40 ms for Flextalk, including process start; the full wrapper adds the ffmpeg
+  measure/apply passes, about 630-880 ms per short line. That is above the 500 ms target;
+  the known optimization is a per-voice static gain (skip the measurement pass), expected
+  to land around 400-500 ms.
+- Manual checks: `setup/run.sh -l`, `setup/run.sh -v "Keith Bell" -t "Hello." -o out.wav`
+  (raw engine WAV), and the wrapper above for normalized output.
 - HTTP provider (later): a persistent process returning `audio/wav` bytes and `/voices`,
   with optional caching by `hash(text + voice + speed + pitch)`.