Merge the SAM VOX preset tuning and comparison tool

microslopsam/README.md

@@ -73,8 +73,8 @@ Options: `-v` voice, `-t` text, `-o` output WAV, `-p` pitch, `-s` speed, `-V` vo
     export VESKSLOP_TTS_CMD="$PWD/setup/veskslop-tts.sh {out} {text_file}"
     export VESKSLOP_TTS_VOICES="$(setup/veskslop-tts.sh --voices)"
 
-The wrapper maps voice IDs (`sam`, `mary`, `mike`, `keith-bell`, `kerry-watson`, plus the
-MSTTS variants), reads `VESKSLOP_TTS_VOICE`, `VESKSLOP_TTS_SPEED` (multiplier),
+The wrapper maps voice IDs (`sam`, `mary`, `mike`, `keith-bell`, `kerry-watson`, `vox`,
+`hev`, plus the MSTTS variants), reads `VESKSLOP_TTS_VOICE`, `VESKSLOP_TTS_SPEED` (multiplier),
 `VESKSLOP_TTS_PITCH` (semitones) and `VESKSLOP_TTS_EXPRESSION` (0-100, Flextalk voices
 only), starts Xvfb when `DISPLAY` is unset, and writes a 48 kHz mono s16le WAV trimmed,
 faded and normalized to about -16 LUFS (-3 dBFS true peak).
@@ -93,9 +93,18 @@ A short low-level leading hum (80 ms, 75 Hz, -48 dBFS) primes Discord's audio pi
 so the first word is not gated; tune with `VESKSLOP_TTS_HUM_MS` (0 = off),
 `VESKSLOP_TTS_HUM_HZ`, and `VESKSLOP_TTS_HUM_DB`.
 
-**Half-Life presets** (Keith Bell): `VESKSLOP_TTS_PRESET=vox` applies the approximated
-Valve VOX profile and enables VOX prosody; `VESKSLOP_TTS_PRESET=hev` is a starting point
-for the HEV suit voice. Values are in `docs/TTS-DESIGN.md`.
+**Half-Life presets** (Keith Bell): `VESKSLOP_TTS_PRESET=vox` applies the Valve VOX
+profile (pitch 0, rate 15, head size 34, lowering 50) and enables VOX prosody;
+`VESKSLOP_TTS_PRESET=hev` is a starting point for the HEV suit voice. The `vox` and `hev`
+voice IDs select these directly. The VOX values were
+tuned against the game's word assets with `tools/vox_compare.py`; details in
+`docs/TTS-DESIGN.md`.
+
+`VESKSLOP_TTS_CRUNCH` (`hl90`, `hl90hq`, `telephone`, `adpcm`, `crush`) adds 1990s lossy
+character to the output; `VESKSLOP_TTS_CRUNCH_BITS`/`_RATE` override its bit depth and
+sample rate. `VESKSLOP_TTS_STREAM=1` makes word mode write the WAV as it goes (no
+measurement pass; `VESKSLOP_TTS_STREAM_GAIN_DB` sets the gain). Echo timing and level are
+`VESKSLOP_TTS_ECHO_DELAY_MS` and `VESKSLOP_TTS_ECHO_LEVEL`.
 
 ## Layout
 
@@ -107,7 +116,9 @@ for the HEV suit voice. Values are in `docs/TTS-DESIGN.md`.
 - `setup/inf2reg.py` — INF AddReg -> `.reg` converter
 - `setup/run.sh` — run helper (prefix + Xvfb)
 - `setup/veskslop-tts.sh` — Veskslop command-provider wrapper (post-processing included)
+- `setup/test-wrapper.sh` — wrapper regression test (stubbed Wine/host, no prefix needed)
 - `setup/vox_parser.py` — NetTTS-style VOX prosody encoder (Flextalk voices)
+- `tools/vox_compare.py` — reference-vs-synthesis metrics for preset tuning
 - `docs/NOTES.md` — registry/CLSID facts, runtime RE notes, gotchas
 - `docs/TTS-DESIGN.md` — integration contract with Veskslop plus engine clarifications