Dictation Overlay & Indicators
Relevant source files
The following files were used as context for generating this wiki page:
The Dictation Overlay & Indicators system provides the primary visual interface for MacParakeet's system-wide voice input. It consists of a compact, floating "pill" UI that appears near the bottom of the screen (just above the Dock) to provide real-time feedback during recording and processing. The system is designed for high performance and low latency, ensuring that the user's voice is translated into text with minimal visual friction.
The overlay serves as a status hub, transitioning through multiple states: idle, recording (with active waveform), processing (with a spinner), success (checkmark), or error (error card). It incorporates specialized components like the WaveformView for acoustic feedback and the LoadingCaptionView for engine readiness information. Sources: spec/00-vision.md:52-56, spec/09-testing.md:214-222, plans/completed/2026-05-dictation-first-load-caption.md:212-230
Visual Architecture & Positioning
The overlay is implemented as a floating NSPanel (typically 300x160 pixels) that remains bottom-anchored on the screen. The primary UI element is a pill-shaped capsule rendered via SwiftUI. Sources: plans/completed/2026-05-dictation-first-load-caption.md:212-230, spec/09-testing.md:267-270
Component Stack
The overlay uses a vertical stack to organize indicators without shifting the primary pill's position:
- Loading Caption: A floating capsule that appears 6pt above the main pill to indicate engine preparation status.
- Main Pill: Contains the core recording/processing indicators.
- Tooltips: Hover-activated labels (e.g., "Cancel Esc") that appear above the pill.
Core Visual Indicators
Waveform Real-time Feedback
The WaveformView provides live acoustic feedback. It renders a series of vertical bars (typically 8 bars) that react to audio levels provided by the AudioProcessor. Sources: Sources/MacParakeet/Views/Dictation/WaveformView.swift:11-20, spec/09-testing.md:273-275
- Bar Logic: Each bar represents an amplitude level, normalized and animated to prevent "jumps."
- Visual Polish: The bars remain visible even at low audio levels to confirm the system is active.
Sources: Sources/MacParakeet/Views/Dictation/WaveformView.swift:45-60, spec/09-testing.md:273-275
Processing & Engine Readiness
When the system enters the .processing state, a SpinnerRingView (two counter-rotating triangles) is displayed. If the speech engine is still loading (common on cold starts), a LoadingCaptionView appears above the pill. Sources: plans/completed/2026-05-dictation-first-load-caption.md:73-85, plans/completed/2026-05-dictation-first-load-caption.md:212-230
| Feature | Behavior | Source |
|---|---|---|
| Caption Grace Period | 600ms grace before showing "Preparing speech engine..." | plans/completed/2026-05-dictation-first-load-caption.md:92-95 |
| Escalation | After 4s on first install, shows "First-time setup" subcopy. | plans/completed/2026-05-dictation-first-load-caption.md:98-100 |
| Success Animation | Thin ring draws, then checkmark strokes in (Apple Pay style). | spec/09-testing.md:278-280 |
| Cancel Ring | 5s countdown ring drains smoothly when user hits Esc/X. | spec/09-testing.md:244-249, spec/09-testing.md:276 |
State Management Flow
The overlay transitions through states managed by the DictationFlowStateMachine and observed by the DictationOverlayViewModel. Sources: plans/completed/2026-05-dictation-first-load-caption.md:267-270, spec/09-testing.md:254-263
Interaction & Accessibility
Hover Behaviors and Tooltips
The overlay uses AppKit-level tracking to detect hover even on non-activating panels. Tooltips provide shortcut hints to the user. Sources: CLAUDE.md:74-76, spec/09-testing.md:281-290
- Cancel Tooltip: Hovering the 'X' button shows "Cancel Esc".
- Stop Tooltip: Hovering the stop circle shows "Stop & paste (Trigger Key)".
- Visual Transitions: All tooltips and state changes use a 220ms ease-in-out animation. Sources: plans/completed/2026-05-dictation-first-load-caption.md:28-30, spec/09-testing.md:281-290
Accessibility Support
The system respects the accessibilityReduceMotion setting. When enabled, the LoadingCaptionView and pill transitions switch to opacity-only cross-fades, disabling the sliding offset animations. Sources: plans/completed/2026-05-dictation-first-load-caption.md:120-125, plans/completed/2026-05-dictation-first-load-caption.md:234-236
Summary of Overlay Components
| Component | Responsibility | Relevant Files |
|---|---|---|
DictationOverlayView | Main SwiftUI container and layout chokepoint. | DictationOverlayView.swift |
WaveformView | Renders live amplitude bars for recording feedback. | WaveformView.swift |
LoadingCaptionView | Displays engine status (Preparing/Failed) above the pill. | LoadingCaptionView.swift |
SpinnerRingView | Provides a rotating triangle animation during STT processing. | SacredGeometry.swift |
Sources: Sources/MacParakeet/Views/Dictation/DictationOverlayView.swift:1-20, Sources/MacParakeet/Views/Dictation/WaveformView.swift:11-20, plans/completed/2026-05-dictation-first-load-caption.md:212-258
The Dictation Overlay & Indicators system provides a low-latency, high-polish feedback loop that is essential for a "voice-first" user experience, balancing real-time acoustic feedback with clear indicators of the underlying speech engine's status.