Home

🎙️ TRWhisper Wiki

TRWhisper is a completely local (offline), zero-telemetry, and low-latency "push-to-talk" voice dictation application built for Windows 11 as an alternative to Superwhisper.

This wiki page provides detailed technical information regarding TRWhisper's architecture, installation requirements, configuration options, and current development status.

---

📑 Table of Contents

1. Key Features
2. System Architecture and Flow Diagram
3. Components and Code Structure
4. Installation and Getting Started
5. Configuration (config.json)
6. Known Issues and Troubleshooting

---

🚀 Key Features

• Hardware-Level Push-to-Talk: Utilizing the WH_KEYBOARD_LL Win32 API, holding down system-wide Right Ctrl records audio from the microphone, and releasing it immediately initiates transcription.
• Smart Clipboard Injection:
  1. Backs up current Windows clipboard content into memory.
  2. Copies the transcribed text to the clipboard.
  3. Uses the Win32 SendInput API to simulate Ctrl + V, instantly pasting into the active window.
  4. Restores your previous clipboard content (text, images, etc.) after 150 ms.
• Privacy-First & Local Engine: Voice data is never transmitted to any cloud. Transcription is processed entirely locally on CPU/GPU via the whisper.cpp engine using the ggml-large-v3-turbo-q5_0.bin model.
• Optional LLM Cleanup: When performing push-to-talk with the Right Ctrl + Right Shift combination, filler words (um, uh, like, you know / ııı, eee, şey) are eliminated and punctuation/spelling is corrected via Gemini or OpenAI API before pasting.
• WPF Pill Overlay: A sleek, animated overlay window positioned at the center of the screen or aligned with the cursor to provide instant real-time status feedback.
• Markdown Journaling: Successful dictations are automatically archived with timestamps into %USERPROFILE%\Dictation\YYYY-MM.md.

---

🔄 System Architecture and Flow Diagram

The end-to-end data flow when push-to-talk is triggered is as follows:

sequenceDiagram
    autonumber
    actor User as User
    participant Hook as Win32 Keyboard Hook
    participant Audio as WASAPI Recorder (NAudio)
    participant Coord as DictationCoordinator
    participant STT as Whisper.cpp (CLI)
    participant LLM as LLM Cleaner (Optional)
    participant Clip as Clipboard Paster

    User->>Hook: Presses Right Ctrl Key
    Hook->>Coord: HotkeyDown Event
    Coord->>Audio: StartRecording(temp.wav)
    Note over Audio: 16kHz 16-bit Mono WAV Recording Begins

    User->>Hook: Releases Right Ctrl Key
    Hook->>Coord: HotkeyUp Event (IsLlmModifierActive?)
    Coord->>Audio: StopRecordingAsync()
    Audio-->>Coord: temp.wav file is ready

    Coord->>STT: TranscribeAsync(temp.wav)
    STT-->>Coord: Raw Transcript Text

    opt If Right Shift was held down (LLM Cleanup)
        Coord->>LLM: CleanTranscriptAsync(Raw Text)
        LLM-->>Coord: Corrected / Cleaned Text
    end

    Coord->>Clip: PasteTextAsync(Final Text)
    Note over Clip: 1. Backup Clipboard<br/>2. Copy Text & Paste with Ctrl+V<br/>3. Restore Clipboard After 150ms
    Clip-->>User: Text Pasted into Cursor Area

Loading