docs: record the voice-loop traps

Three that each cost a debugging round, and none of which looks like its
cause: terra's mic levels (every default threshold was above the user's
speech), the noise floor chasing a rising sound, and `try_recv()` popping
a command that an `if let Ok(Cancel)` then throws away — which is why
SUPER+V during her reply did nothing at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-20 23:38:06 +02:00
co-authored by Claude Opus 5
parent ef1be8a7d9
commit b3200d965d
+19
View File
@@ -219,6 +219,25 @@ kept its ssh host key. Run it after ANY change to the kexec paths.
documents) rather than relaying audio through mars, so rotating that key means documents) rather than relaying audio through mars, so rotating that key means
editing two files. `hermes_api_server_key` is duplicated for the same reason: editing two files. `hermes_api_server_key` is duplicated for the same reason:
mars serves the API, terra is its only client. mars serves the API, terra is its only client.
- **terra's mic is QUIET, and every voice threshold is sized for it.** Measured on
the AIR 192|4 (`luna-voice level`): ~0.001–0.002 RMS ambient, only 0.0045–0.005
for normal speech — about 6dB of separation. Consequences, all of which looked
like "the daemon is broken": a VAD multiplier above ~2 can never fire, an
absolute trigger floor of 0.006 sits *above* the user's voice, and whisper's own
gate at 0.015 discarded every word the VAD did capture. Hence `vadMult = 1.8`,
`vadFloor = 0.0025`, and `stt::normalize` scaling the clip up (capped at 30x)
before whisper sees it. Raising the gain on the interface is worth more than any
of these; tune via `homelab.lunaVoice.vad*` rather than editing Rust.
- **`try_recv()` POPS — an `if let Ok(Cancel)` destroys every other command.**
luna-voiced polls for a cancel while she speaks; written as a single `if let`,
any `say`/`toggle`/`mode off` arriving mid-reply was taken off the channel and
dropped, so SUPER+V during her answer did nothing at all and the next turn never
ran. Non-cancel commands are collected and re-sent into the channel after the
turn instead (`requeue` in `turn()`).
- **A rising sound must not update the noise floor.** Feeding every sample into the
floor EMA lets speech drag its own threshold up faster than it rises — measured,
a tone peaking at 0.029 was chased by a threshold that reached 0.018 and never
triggered. Only samples *below* the current trigger update the floor.
- **whisper invents words out of silence** — "you", "Thank you.", "Bye." — and a - **whisper invents words out of silence** — "you", "Thank you.", "Bye." — and a
held push-to-talk key over a quiet room is long AND empty, so duration alone held push-to-talk key over a quiet room is long AND empty, so duration alone
does not catch it. `stt::has_speech` gates on the loudest 100ms window instead; does not catch it. `stt::has_speech` gates on the loudest 100ms window instead;