Whisp Documentation
Complete reference manual for Whisp: native macOS workflows, keyboard shortcuts, speech recognition, on-device translation language setup, developer vocabulary, and AI agent integration.
Introduction & Core Architecture
Whisp is a native macOS voice-to-text input utility built for programmers, terminal users, vibe coders, and AI coding agents. Unlike generic dictation apps, Whisp is engineered around developer workflows:
100% On-Device Neural Speech
Runs via Apple's native SpeechAnalyzer and SpeechTranscriber. 0 GB of model weight downloads required, zero battery drain, and instant startup.
Focus-Lock Terminal Safety
Locks onto the frontmost app at recording start. Transcribes directly into that target window and never sends an Enter/Return keystroke, preventing premature CLI command execution.
Installation & First-Run Setup
Whisp is distributed through the official Mac App Store for macOS 26.5 and later (compatible with Apple Silicon M1/M2/M3/M4 and Intel Macs). Upon first launch, Whisp guides you through a 3-step setup:
- 1
Microphone Access (Required)
Required to capture audio when recording via Option–Space, the floating dial, or push-to-talk. Click Allow when prompted by macOS.
- 2
Accessibility / Auto-Paste (Recommended)
Allows Whisp to inject your transcribed text directly into the focused input field or terminal prompt. If skipped, Whisp safely falls back to automatically copying every transcript to your clipboard.
- 3
Audio Input Device Verification
Select your preferred microphone (built-in, AirPods, or USB mic) and verify responsiveness with the live sound level meter.
How to Use Whisp (Workflows)
Hands-Free Dictation
⌥ Option + SpacePlace your cursor anywhere (Terminal prompt, Claude Code, Cursor Composer, Slack, or Notes). Press ⌥ Space. Speak your thought. Pause for 4 seconds (or press Return), and Whisp types your words directly into the active field.
Push-to-Talk Walkie-Talkie Mode
Hold Right ⌘Hold down the physical Right Command (Right ⌘) key while speaking your prompt or command; release it to transcribe and paste immediately. It uses a low-level hardware listener that never interferes with Left ⌘ chords (⌘C, ⌘V).
Silence Auto-Finish vs. Continuous Dictation
By default, Whisp finishes capture after 4.0 seconds of silence (configurable from 1.0s to 8.0s in Settings). For uninterrupted long-form dictation, turn off "Finish after silence" in Settings—recording stays open indefinitely until you press Return or ⌥ Space.
Floating Widget HUD Presentations
Configure your preferred HUD presentation in Settings → Experience & Controls:
Keyboard Shortcuts & Customization
Whisp is built for muscle memory. Every global shortcut can be customized, conflict-checked, or reset to defaults.
| Action | Default Shortcut | Behavior |
|---|---|---|
| Start / Toggle Capture | ⌥ Option + Space | Activates recording & locks frontmost app. Press again to commit. |
| Push-to-Talk | Right ⌘ Command | Hold to speak like a walkie-talkie; release to transcribe and paste. |
| Finish Recording | Return | Immediately commits current speech without waiting for silence timer. |
| Translate to English & Paste | ⌥ Option + Return | Translates non-English speech to English via on-device model and pastes. |
| Discard & Cancel | Escape | Discards active audio and transcript without pasting or copying. |
| Quick Language Picker | ⌥ Option + L | Opens floating HUD modal of installed speech languages. |
| Quick Microphone Picker | ⌥ Option + M | Opens floating HUD modal to switch input audio hardware. |
| Toggle Widget Visibility | ⌥ Option + B | Shows or hides the floating HUD when recording is idle. |
How to Configure & Remap Shortcuts
- Open Whisp's main window and select Settings from the sidebar.
- Under Experience & Controls, find Keyboard shortcuts and click Configure Shortcuts….
- Click Change next to the action you wish to modify.
- Press your desired physical key combination (e.g., F19, Ctrl+Space, or a modifier key like Right ⌘).
- Whisp validates conflicts in real-time. Click Save Changes to apply globally.
Languages & On-Device Translation
Whisp allows you to speak in your native language and have it translated to fluent English before typing into code files, commit messages, or terminal prompts.
Understanding Speech Recognition vs. Translation Models
macOS uses two independent engines:
- Speech Recognition Models (Apple Speech): Transcribe audio acoustic waves into text in the spoken language (e.g. Spanish speech → Spanish text).
- Translation Models (Apple Translation): Translate written text between language pairs locally (e.g. Spanish text → English text).
How to Download & Switch Speech Recognition Languages
Whisp only allows selecting speech models installed on your Mac, preventing capture errors:
- Open Whisp → Settings → Capture & Audio.
- Click the "Download speech language" dropdown menu (dynamically populated from macOS).
- Select your target language (German, French, Japanese, Mandarin, Spanish, Hindi, etc.).
- macOS downloads the Apple Speech asset. Once installed, Whisp selects it for your next capture.
- Press ⌥ Option + L anytime to switch between installed spoken languages on the fly.
How to Download Translation Models in macOS
To enable on-device English translation (⌥ Option + Return):
- Open System Settings on your Mac.
- Go to General → Language & Region.
- Scroll to the bottom and click Translation Languages.
- Ensure "On-Device Mode" is toggled ON.
- Find your language and click the Download icon next to it.
- Alternative: In Whisp → Settings → Capture & Audio, click "Prepare English translation" to prompt macOS to download the missing pair.
Code Token Preservation (CodeTokenPreserver)
Standard translation tools mangle code terms (translating package.json into Spanish or changing userAuthToken to fichaDeAutenticacion). Whisp's CodeTokenPreserver identifies programming tokens, file paths (*.swift, *.ts), camelCase/snake_case tokens, and CLI flags, shields them before translation, and rehydrates them with exact syntax intact.
Developer Vocabulary & Phrase Replacements
Ensure 100% precision for project-specific terms, acronyms, and shortcuts.
Contextual Speech Hints (Up to 100)
Add domain-specific jargon (e.g. Supabase, ClaudeCode, Prisma, team names). These terms are supplied directly to Apple's speech recognizer as contextual hints before recording begins.
Phrase Replacements (Up to 100)
Deterministic regex word-boundary replacements. Say "by the way" → outputs "btw", or say "arrow function" → outputs "=>". Includes real-time testing preview.
Dual-Transcript History & Search
Whisp automatically stores your last 250 transcriptions locally in an encrypted JSON file (~/Library/Application Support/Whisp/history.json).
Dual-Transcript Architecture
When translating non-English speech via ⌥ Option + Return, Whisp preserves both the translated English text and the original spoken native transcript.
- Primary English Text: Ready for instant copying or pasting into code.
- Native Badge (e.g. 🌐 Spanish ▾): Click to expand the drawer and inspect or copy the original native transcription.
- Multi-Action Copying: Copy English translation, copy original speech, or copy both combined.
Troubleshooting & Frequently Asked Questions
Q: Text is copying to clipboard instead of pasting into my terminal. Why?
Direct text injection requires macOS Accessibility permission. Open System Settings → Privacy & Security → Accessibility, toggle Whisp OFF and back ON, and ensure "Automatically paste into the focused app" is enabled in Whisp Settings.
Q: How do I prevent YouTube or music audio from leaking into my dictation?
In Whisp → Settings → Capture & Audio, enable "Pause other audio while recording". Whisp will temporarily mute system output speakers during speech and restore your volume when done.
Q: How do I restore my Lifetime purchase on a new Mac?
Install Whisp from the Mac App Store using the same Apple ID. Open Whisp → Settings, and click Restore Purchases in the top Lifetime card.
AI Coding Agent Ingestion & Integration
Whisp is designed to pair seamlessly with autonomous AI agents (Claude Code CLI, Devin, Codex, Gemini CLI, Cursor Composer, and Antigravity). Agents can ingest the full canonical documentation using the machine-readable endpoints below:
curl -s https://whisp.horizam.com/docs.md