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. Copies text for pasting 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
Optional Speech Recognition
The Mac App Store build copies completed text to your clipboard for Command–V and does not request Accessibility or Input Monitoring. Speech Recognition is an optional compatibility fallback. Direct builds can enable Automatic Paste with Accessibility; Accessibility is also required for Right Command Push to Talk outside Whisp.
- 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, then press Return. Whisp keeps recording through pauses and completes only when you tell it to.
Voice activation with “Hey Whisp” is optional and off by default. Turn on Listen for wake phrases in Settings → Wake Word to enable it.
Push-to-Talk Walkie-Talkie Mode
Hold ⌥ RIn the Mac App Store build, hold Option + R while speaking, then release to transcribe and copy. Press Command–V in the target app. This shortcut works across apps without Accessibility or Input Monitoring. Direct builds default to Right Command; enable Whisp under System Settings → Privacy & Security → Accessibility to use it outside Whisp. Accessibility also enables optional Automatic Paste.
Continuous Dictation
Whisp keeps recording through silence so long-form dictation stays intact. Finish explicitly with Return, ⌥ Space, a translation shortcut, or the Stop control.
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 | ⌥ Option + R | Hold to speak like a walkie-talkie; release to transcribe and copy. |
| Finish Recording | Return | Commits the active recording. |
| Translate to English & Copy | ⌥ Option + Return | Translates non-English speech to English on-device and copies it. |
| 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 key combination. Mac App Store shortcuts need a regular key; direct builds also allow a standalone modifier for Push to Talk.
- 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?
The Mac App Store build copies text to the clipboard; press Command–V to paste. Direct builds can enable Automatic Paste with Accessibility. In direct builds, Right Command Push to Talk also needs Accessibility when another app is active.
Q: Which Push-to-Talk shortcut should I use in another app?
The Mac App Store build uses Option–R and needs no keyboard permissions. Direct builds default to Right Command; allow Whisp under System Settings → Privacy & Security → Accessibility. You can also choose a regular-key shortcut in Settings → Experience & Controls → Keyboard shortcuts.
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