feat: experimental real-time streaming transcription (fixes #320)

[jatinkrmalik]

Summary

Implements real-time streaming transcription as an experimental feature (off by default) that shows text as you speak, rather than waiting until you stop recording.

Fixes #320
Related discussions: #382, #94

Changes

Phase 1: Config & Engine Plumbing

• config_manager.py: Added experimental_streaming, streaming_chunk_duration_ms, streaming_overlap_ms to DEFAULT_CONFIG (all off/default)
• common_types.py: Added StreamingCallbackProtocol and extended SpeechRecognitionManagerProtocol with streaming methods
• main.py: Passes streaming config from settings to SpeechRecognitionManager constructor

Phase 2: TranscriptBuffer (LA-2 Dedup)

• transcript_buffer.py: New file implementing Local Agreement (LA-2) policy for word-level dedup across overlapping audio segments. Prevents flickering and duplicate text injection.

Phase 3: Streaming Engine

• recognition_manager.py:
  • Timer-based audio chunking with configurable overlap
  • Vosk path: uses native PartialResult() API
  • Whisper path: uses TranscriptBuffer with sliding window
  • add_streaming_callback / remove_streaming_callback for external consumers
  • reconfigure accepts streaming params with validation

Phase 4: UI & Integration

• settings_dialog.py: Added streaming toggle and chunk duration spin in Recognition Settings
• tray_indicator.py: Registers streaming callback for live text injection

Tests

• test_streaming.py: 23 unit tests covering TranscriptBuffer logic (basic, flush, reset, overlap, case-insensitive), config defaults, and config manager round-trip integration
• test_main.py: Updated for new constructor kwargs

Architecture

┌─────────────┐    timer    ┌──────────────────┐    callback        ┌──────────────┐
│ Recording   │───enqueue──▶│ Streaming Engine │───(text,is_final)─▶│ TrayIndicator│
│ Loop        │  (overlap)  │ (Vosk/Whisper)   │                    │ → inject_text│
└─────────────┘             └──────────────────┘                    └──────────────┘
                                     │
                            ┌────────┴────────┐
                            │ TranscriptBuffer│
                            │ (LA-2 dedup)    │
                            └─────────────────┘

Testing

• ✅ 23 new streaming tests pass
• ✅ 1455 existing tests pass (8 pre-existing failures in xkb_layout/ibus unrelated to this PR)
• ✅ All changed files formatted with black --line-length 100
• ✅ flake8 clean on all changed files
• ✅ All files compile without syntax errors

How to Test

1. Open Settings → Recognition Settings
2. Enable "Real-time Streaming" toggle
3. Start dictation — text should appear incrementally as you speak
4. Adjust "Chunk Duration" (0.2s–5.0s) to balance latency vs accuracy

Notes

• Feature is OFF by default behind experimental_streaming config key
• Vosk streaming uses native PartialResult() — fast and well-tested
• Whisper streaming uses a sliding window with TranscriptBuffer dedup — experimental and may be less accurate
• The TranscriptBuffer LA-2 policy ensures words are only committed when seen in consecutive passes, preventing duplicates from overlapping audio segments

[codecov]

Codecov Report

❌ Patch coverage is 84.02204% with 58 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.64%. Comparing base (0556d16) to head (6944303).
⚠️ Report is 23 commits behind head on main.

Files with missing lines	Patch %	Lines
...ocalinux/speech_recognition/recognition_manager.py	80.81%	38 Missing and 9 partials ⚠️
.../vocalinux/speech_recognition/transcript_buffer.py	94.17%	3 Missing and 3 partials ⚠️
src/vocalinux/common_types.py	50.00%	2 Missing and 1 partial ⚠️
src/vocalinux/main.py	66.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #387      +/-   ##
==========================================
+ Coverage   79.91%   80.64%   +0.73%     
==========================================
  Files          30       31       +1     
  Lines        4615     4955     +340     
  Branches      699      770      +71     
==========================================
+ Hits         3688     3996     +308     
- Misses        779      799      +20     
- Partials      148      160      +12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jatinkrmalik]

A note from local testing/investigation:

The streaming behavior is much more straightforward for Vosk than for Whisper/whisper.cpp. Vosk has a native incremental recognizer API: we can feed audio continuously via AcceptWaveform(), show PartialResult() as a live hypothesis, and commit Result() / FinalResult() when the recognizer endpoints. That model maps pretty naturally to dictation.

Whisper is different. It is fundamentally a windowed transcription model, not a true streaming decoder. For the experimental mode here we are repeatedly transcribing short overlapping chunks and then trying to decide what text is stable enough to inject. That creates a few practical problems:

• Very short chunks improve latency but make punctuation and phrase boundaries worse.
• Overlapping chunks often repeat boundary words, e.g. are... are, of... of, so we need tail/head deduping.
• Chunks can be sequential rather than revisions of the same phrase, so a strict Local Agreement policy can accidentally hold all text until stop.
• Injecting partial text directly into arbitrary apps is risky because replacing previous partials reliably across IBus/X11/Wayland/clipboard paths is a much bigger UI/input problem than just recognizing speech.

So my current read is: keeping this as an opt-in experimental mode is the right shape. Vosk streaming can be treated as closer to "native streaming". Whisper/whisper.cpp streaming should be framed as a best-effort low-latency chunking mode, where users may need to tune chunk duration upward for better punctuation and flow.