From 4d1c31f1c95e1b7fa367ef7209233bd5578d2b63 Mon Sep 17 00:00:00 2001
From: Fisto <fisto@fisto.cccp>
Date: Wed, 16 Sep 2026 13:22:16 +0200
Subject: [PATCH] wrapper: hum bypasses high-pass chain; docs clarified

---
 docs/NOTES.md         | 2 ++
 docs/TTS-DESIGN.md    | 8 +++++---
 setup/veskslop-tts.sh | 2 ++
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/NOTES.md b/docs/NOTES.md
index 8e16d2d..fe520d4 100644
--- a/docs/NOTES.md
+++ b/docs/NOTES.md
@@ -71,6 +71,8 @@ without them.
   final -18.6 LUFS / -3.0 dBFS, apply pass +~10 ms. `VESKSLOP_TTS_HUM_MS=0` disables and
   reproduces the previous output byte-for-byte. Tuning: `_HUM_HZ` (30-200), `_HUM_DB`
   (-80..-6; raise toward -36 if a client still gates the start).
+  The hum bypasses the high-pass/trim chain, so `VESKSLOP_TTS_HIGHPASS` (up to 400 Hz)
+  cannot remove it (verified at 200 and 400 Hz).
 
 ## SAPI4 runtime engine discovery (`speech.dll`)
 
diff --git a/docs/TTS-DESIGN.md b/docs/TTS-DESIGN.md
index 80ed606..0a18845 100644
--- a/docs/TTS-DESIGN.md
+++ b/docs/TTS-DESIGN.md
@@ -240,9 +240,11 @@ record what the engine needs to interpret, add, or hide._
   `_HUM_DB` (-80..-6). It sits about 45 dB under the speech peak; raise `_HUM_DB` toward
   -36 if a client still gates the start, lower it for stealth. Generated in the same
   ffmpeg pass (no extra process) and not part of the EBU measurement, so the documented
-  loudness/peak targets still hold. Measured: hum 75.0 Hz / -48.0 dBFS, speech onset at
-  about 110 ms, final -18.6 LUFS / -3.0 dBFS; `HUM_MS=0` reproduces the previous output
-  byte-for-byte.
+  loudness/peak targets still hold. The hum is mixed on its own chain and bypasses the
+  high-pass/trim chain, so raising `VESKSLOP_TTS_HIGHPASS` (40-400 Hz) never removes it
+  (verified at 200 and 400 Hz: still 75.0 Hz / -48.0 dBFS). Measured: hum 75.0 Hz /
+  -48.0 dBFS, speech onset at about 110 ms, final -18.6 LUFS / -3.0 dBFS; `HUM_MS=0`
+  reproduces the previous output byte-for-byte.
 
 ### Voice IDs
 
diff --git a/setup/veskslop-tts.sh b/setup/veskslop-tts.sh
index db0fec3..24a6c90 100755
--- a/setup/veskslop-tts.sh
+++ b/setup/veskslop-tts.sh
@@ -397,6 +397,8 @@ if [ "$HUM_MS" -gt 0 ]; then
     HUM_AMP=$(awk -v db="$HUM_DB" 'BEGIN{printf "%.6f", 10^(db/20)}')
     HUM_FADE=$(awk -v s="$HUM_S" 'BEGIN{ f=s/4; if (f>0.02) f=0.02; if (f<0.005) f=0.005; printf "%.3f", f }')
     HUM_FADE_OUT=$(awk -v s="$HUM_S" -v f="$HUM_FADE" 'BEGIN{printf "%.3f", s-f}')
+    # The hum is mixed on its own chain and deliberately bypasses $PRE (highpass,
+    # trim, fades): VESKSLOP_TTS_HIGHPASS must never remove it.
     if ! "$MICROSLOP_FFMPEG" -hide_banner -nostats -y \
             -f lavfi -i "aevalsrc=exprs='$HUM_AMP*sin(2*PI*$HUM_HZ*t)':s=48000:d=$HUM_S" \
             -i "$RAW" \