System-Wide Dictation
Relevant source files
The following files were used as context for generating this wiki page:
System-Wide Dictation is a core feature of MacParakeet that allows users to capture voice input in any macOS application using a global hotkey. The system is designed for high-speed, local-first performance, leveraging NVIDIA's Parakeet TDT model via the Apple Neural Engine to achieve latency under 500ms. Users can activate dictation through two primary gestures: a double-tap for hands-free mode or a long-press for "push-to-talk" functionality.
The architecture is built around a robust state machine that manages transitions between recording, processing, and delivery. Once speech is captured and transcribed locally, the system utilizes a "clean pipeline" for deterministic text processing (such as filler word removal and custom word replacement) before pasting the result directly into the user's active cursor position.
Sources: spec/00-vision.md:14-25, spec/00-vision.md:57-65
Architecture and Components
The dictation system is composed of several specialized services and management layers that coordinate to handle hardware input, state transitions, and text delivery.
Global Shortcut Management
The GlobalShortcutManager handles the registration and monitoring of global hotkeys. It supports custom key combinations and chords (e.g., Fn, Control, or Option+Space) and distinguishes between short taps and long holds to trigger different dictation behaviors.
Sources: spec/adr/009-custom-hotkey.md, Sources/MacParakeet/Hotkey/GlobalShortcutManager.swift
Dictation Flow State Machine
The core logic of a dictation session is managed by DictationFlowStateMachine. This pure state machine ensures that the system moves logically between states and handles edge cases like cancellations or audio capture errors.
The diagram above illustrates the primary states of a dictation session, from initial trigger to text delivery or failure.
Sources: Sources/MacParakeetCore/DictationFlow/DictationFlowStateMachine.swift
Dictation Service
The DictationService orchestrates the lifecycle of a session. It interacts with the AudioProcessor for microphone capture and the STTClient for local transcription. It also manages the "private mode" which excludes specific dictations from the persistent history.
Sources: Sources/MacParakeetCore/Services/Dictation/DictationService.swift
Core Features and Interaction Modes
| Feature | Description | Interaction |
|---|---|---|
| Push-to-Talk | Captures audio only while the hotkey is held down. | Hold Hotkey (>400ms) |
| Hands-Free | Toggles recording on first tap and off on second tap. | Double-tap Hotkey |
| Clean Pipeline | Deterministic processing (filler removal, custom words). | Automatic post-transcription |
| Private Mode | Dictations are not saved to the local database. | Opt-in via Settings |
| Context Awareness | (Future) Reads surrounding text for better accuracy. | Automated |
Sources: spec/00-vision.md:120-135, spec/09-testing.md:195-205
Data Flow and Logic
The sequence of events from a user's physical keypress to text appearing in an application follows a strict pipeline:
- Hotkey Detection:
GlobalShortcutManagerdetects the rising edge of a registered key. - State Initiation: The state machine moves to
.recording. - Audio Capture:
DictationServicestarts theAudioProcessor. - Transcription: Upon hotkey release or second tap, audio is sent to the local STT engine.
- Text Processing: The raw transcript passes through the
TextProcessingPipelinefor cleanup (whitespace, capitalization, etc.). - Delivery: The final text is injected into the active application, typically via a paste mechanism.
The sequence diagram shows the flow of data from the initial user interaction to the final text delivery.
Sources: Sources/MacParakeetCore/Services/Dictation/DictationService.swift:180-220, spec/09-testing.md:230-245
Technical Implementation Details
Configuration and Hotkey Recording
MacParakeet supports flexible hotkey configuration. The GlobalShortcutManager filters for "bare-tap" modifiers to ensure that standard system shortcuts (like Cmd+C) do not accidentally trigger dictation.
Sources: spec/09-testing.md:215-225, spec/adr/009-custom-hotkey.md
Error Handling and Recovery
The system handles various failure modes to prevent the UI from getting stuck:
- Stale Start Race: If a stop command is received before the recording is fully active, the system defers the stop to ensure no audio is lost.
- Audio Errors: Hardware disconnects or permission denials trigger an error state that displays an actionable card to the user.
- Cancellation: Users can cancel via
Esc, which initiates a 5-second countdown on the UI pill for potential undo.
Sources: spec/09-testing.md:208-212, Sources/MacParakeetCore/DictationFlow/DictationFlowStateMachine.swift
Conclusion
System-Wide Dictation serves as the primary "activation wedge" for MacParakeet. By focusing on Apple Silicon-optimized local models and a deterministic cleanup pipeline, it provides a professional-grade alternative to cloud-based services. The system's reliability is maintained through a structured state machine and extensive integration testing across various macOS applications like VS Code, Slack, and Notes.
Sources: spec/00-vision.md:180-195, spec/09-testing.md:248-260