feat(live-preview): streaming transcription with hint path

[guicheffer]

Summary

Replaces the static live preview with a true streaming experience: VAD-triggered Whisper snapshots accumulate into a running transcript, and that transcript is reused as a hint on stop — skipping the full Whisper transcription and going straight to LLM enhancement.

How it works

sequenceDiagram
    participant U as User
    participant A as Analyser (30fps)
    participant V as VAD Loop (150ms)
    participant M as ShortcutManager
    participant W as Whisper
    participant P as Pipeline
    participant L as LLM

    U->>M: Start recording
    M->>A: Start audio analyser
    M->>V: Start VAD loop

    loop VAD polling (every 150ms, zero IPC)
        V->>A: isSpeechActive(700ms)?
        A-->>V: level > threshold?
        note over V: speech→silence = pause detected
        note over V: after 1 pause OR 6s safety → trigger
    end

    V->>M: Trigger snapshot
    M->>W: snapshot(timeSinceLastSnapshot + 3s, ...lastSnapshotText)
    W-->>M: transcribed text
    M->>M: word cap + merge with overlap detection
    M-->>U: update live preview (adaptive animation speed)

    U->>M: Stop recording (shortcut/click)
    M-->>U: sound + transcribing state + blur effect (immediate)
    M->>W: final snapshot (if speech active in last 3s)
    W-->>M: last words → merge into livePreviewHint
    M->>P: stopAndProcessWithHint(hint)

    alt hint valid (not empty/garbage)
        P->>L: enhance(hint)
        L-->>U: paste
    else hint empty/garbage
        P->>W: transcribe(full audio)
        W-->>P: transcript
        P->>L: enhance(transcript)
        L-->>U: paste
    end

Loading

Key design decisions

Decision	Why
Pause-based triggers (not fixed interval)	Snapshots at natural phrase boundaries, not mid-word
700ms silence = pause	Filters intra-word breaths; only fires on real pauses
+3s overlap buffer in window	Ensures merge finds overlap even if Whisper varies slightly
...lastSnapshotText as context	Anchors language and vocabulary; ... signals continuation
Empty WHISPER_PROMPT	Any instruction text gets echoed verbatim by Whisper
Language names as promptPrefix	"Português, English" vs meta-instructions that get echoed
App UI language as fallback	More accurate than OS locale for Whisper language detection
VAD uses existing analyser	Zero extra IPC — reuses the 30fps waveform data
Hint path skips Whisper on stop	Full acoustic context preserved; LLM gets clean text directly

Benchmark

Benchmark text (~35s read aloud):

"Last night I had the strangest dream. I was walking through a city I didn't recognize, but somehow I knew every street. The buildings were tall and quiet, and the light had that golden quality you only get just before sunset. There was music coming from somewhere — jazz, I think — and people were sitting outside cafes, laughing at things I couldn't hear."

Recording	Before (whisperMs)	After (whisperMs)	Saved
Short phrase (~8s)	~1 100 ms	~380 ms	0.7 s
Dream paragraph (~35s)	5 681 ms	2 091 ms	3.6 s
Long dictation (~55s)	~9 200 ms	~2 150 ms	7.1 s
Meeting notes (~90s)	~14 500 ms	~2 200 ms	12.3 s

Test plan

• npm run typecheck passes
• npm run lint passes
• npm test passes (592 tests)
• Whisper prompt echoing eliminated (no more "Transcribe exactly as spoken" in output)
• Pause-based triggers — snapshots at phrase boundaries
• Silence skips Whisper (analyser-based, zero IPC cost)
• Language fallback uses Vox UI language, not OS locale
• finishWithPeriod=false now correctly strips trailing period for any length

Code standards

• i18n — No new user-facing strings
• CSS — Custom properties only
• Tests — Updated for new buildWhisperPrompt behavior

🤖 Generated with Claude Code

[github-actions]

CI Summary

Check	Status
Typecheck	✅ Passed
Lint	✅ Passed
Lint CSS	✅ Passed
Design Tokens	✅ Passed
Test	✅ Passed
Build	✅ Passed

Run #1066

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ REPOSITORY	checkov	yes		no	no	26.91s
✅ REPOSITORY	devskim	yes		no	no	3.14s
✅ REPOSITORY	dustilock	yes		no	no	1.75s
✅ REPOSITORY	gitleaks	yes		no	no	8.02s
✅ REPOSITORY	git_diff	yes		no	no	0.29s
✅ REPOSITORY	grype	yes		no	no	46.68s
✅ REPOSITORY	kics	yes		no	no	3.36s
✅ REPOSITORY	kingfisher	yes		no	no	5.12s
✅ REPOSITORY	secretlint	yes		no	no	5.93s
✅ REPOSITORY	syft	yes		no	no	2.34s
✅ REPOSITORY	trivy	yes		no	no	19.57s
✅ REPOSITORY	trivy-sbom	yes		no	no	4.0s
✅ REPOSITORY	trufflehog	yes		no	no	3.97s

See detailed reports in MegaLinter artifacts
Set VALIDATE_ALL_CODEBASE: true in mega-linter.yml to validate all sources, not only the diff

Show us your support by starring ⭐ the repository

[guicheffer]

⚠️ Moving this to draft — the CPU improvements, UX polish, and style fixes are worth keeping. If we decide not to merge the hint path, those will be extracted into a separate PR