fix(voice): anti-hallucination, clipboard paste, Fn key reliability

[senamakel]

Summary

• Add silence/energy detection (RMS threshold) to skip transcription of silent audio — the Feat/gitbooks #1 cause of whisper hallucinations
• Add hallucination output filtering (40+ patterns: [BLANK_AUDIO], "thank you", repeated words, single noise words)
• Add whisper initial_prompt support with custom dictionary and recent transcript context for better accuracy across consecutive recordings
• Switch text insertion from character-by-character typing (enigo text()) to clipboard-paste (Cmd+V) — fixes garbled/repeated output
• Fix Fn key reliability on macOS — missed release events no longer break subsequent presses
• Enable LLM cleanup by default (skip_cleanup: false) and align cleanup prompt with OpenWhispr's CLEANUP_PROMPT
• Add silence_threshold and custom_dictionary to voice server config (TOML + RPC + UI)

Problem

The voice server had several issues making it unreliable for production use:

1. Hallucinations: Pressing Fn with no speech produced "Thank you", "Hello world" repeated dozens of times, or other fabricated text. Whisper.cpp hallucinates when fed silent/noisy audio.
2. Garbled output: Text insertion via enigo.text() typed character-by-character, causing macOS to duplicate/reorder characters at speed.
3. Missed Fn presses: macOS doesn't reliably deliver KeyRelease for the Fn key. The is_active state machine got stuck, eating every other press.
4. No LLM cleanup: skip_cleanup defaulted to true, so the LLM post-processing pass never ran — raw whisper output went straight to the text field.
5. No vocabulary bias: Whisper had no context about what words to expect, making it guess wildly on ambiguous audio.

Solution

Anti-hallucination (inspired by OpenWhispr):

• Compute peak RMS energy during recording via lock-free atomic tracking in the audio capture callback
• Skip transcription entirely when peak_rms < silence_threshold (default 0.002, matching OpenWhispr)
• Filter whisper output against 40+ known hallucination patterns before insertion
• Set whisper.cpp temperature_inc=0 to disable temperature fallback (was retrying with randomness, producing "Thank you")
• Enable suppress_blank, suppress_nst, single_segment mode, and explicit no_speech_thold=0.6
• Pass initial_prompt to whisper with custom dictionary words + rolling recent transcripts

Clipboard-paste insertion (matching OpenWhispr's approach):

• Save clipboard → write text → 120ms settle delay → simulate Cmd+V → 450ms restore delay → restore clipboard
• Uses arboard crate for clipboard access, enigo only for the single Cmd+V keystroke

Fn key fix:

• Simplified hotkey callback: is_active tracks press/release normally
• When release IS delivered (your logs showed it does sometimes), it works
• When release is missed, next press sees is_active=true and sends fallback Released
• Transcription runs in background (tokio::spawn) so the hotkey loop is never blocked

LLM cleanup:

• Changed skip_cleanup default to false
• Replaced 2-line cleanup prompt with OpenWhispr's full CLEANUP_PROMPT (handles self-corrections, spoken punctuation, prompt injection protection)
• Added info!-level logs showing LLM state so issues are diagnosable

Config & UI:

• Added silence_threshold and custom_dictionary to VoiceServerConfig (TOML schema, RPC, controller schema inputs)
• VoicePanel: custom dictionary tag editor, silence threshold control
• Fixed 2s polling timer overwriting in-progress form edits

Submission Checklist

• Unit tests — 57+ voice tests pass (cargo test -p openhuman -- voice::)
• E2E / integration — Manual testing of Fn key press/release, silence detection, hallucination filtering, clipboard paste
• Doc comments — All new public functions and config fields documented
• Inline comments — Whisper params, hallucination patterns, clipboard timing documented with rationale

Impact

• Desktop only — all changes in Rust core (src/openhuman/voice/) and React settings UI
• New dependency: arboard = "3" for cross-platform clipboard access
• Config migration: existing configs with skip_cleanup: true will keep that value (serde default only applies to missing fields)
• Breaking behavior: LLM cleanup now runs by default if local LLM is ready. Users who prefer raw output can set skip_cleanup: true in settings.

Related

• Reference: OpenWhispr (/references/openwhispr) — silence detection, clipboard paste, CLEANUP_PROMPT, custom dictionary patterns