# Whisp Documentation & User Guide > **Official User Guide, Technical Specifications, and Reference Manual for Whisp** > *Private, Native macOS Voice Input for Developers and Vibe Coders.* > Canonical URL: [https://whisp.horizam.com/docs](https://whisp.horizam.com/docs) > Raw Markdown: [https://whisp.horizam.com/docs.md](https://whisp.horizam.com/docs.md) > LLM / Agent Context: [https://whisp.horizam.com/llms.txt](https://whisp.horizam.com/llms.txt) > App Store: [https://apps.apple.com/app/id6810185906](https://apps.apple.com/app/id6810185906) --- ## Table of Contents 1. [Introduction & Core Architecture](#1-introduction--core-architecture) 2. [System Requirements & Installation](#2-system-requirements--installation) 3. [First-Run Setup & Permissions](#3-first-run-setup--permissions) 4. [How to Use Whisp (Core Workflows)](#4-how-to-use-whisp-core-workflows) - [Hands-Free Dictation (`⌥ Option + Space`)](#41-hands-free-dictation--option--space) - [Push-to-Talk Walkie-Talkie Mode (`Right ⌘`)](#42-push-to-talk-walkie-talkie-mode-right-) - [Long-Form Dictation & Silence Detection](#43-long-form-dictation--silence-detection) - [Focus-Lock & Safe Insertion](#44-focus-lock--safe-insertion) - [Floating Widget Presentations](#45-floating-widget-presentations) 5. [Keyboard Shortcuts & Configuration](#5-keyboard-shortcuts--configuration) - [Default Global Shortcuts](#51-default-global-shortcuts) - [How to Configure & Remap Shortcuts](#52-how-to-configure--remap-shortcuts) 6. [Languages & Translation](#6-languages--translation) - [Speech Recognition Models vs. Translation Models](#61-speech-recognition-models-vs-translation-models) - [How to Download & Switch Speech Recognition Languages](#62-how-to-download--switch-speech-recognition-languages) - [How On-Device Translation Works (`⌥ Option + Return`)](#63-how-on-device-translation-works--option--return) - [How to Download Translation Languages in macOS](#64-how-to-download-translation-languages-in-macos) - [Code Token Preservation (`CodeTokenPreserver`)](#65-code-token-preservation-codetokenpreserver) 7. [Developer Vocabulary & Phrase Replacements](#7-developer-vocabulary--phrase-replacements) - [Built-In Curated Dictionary](#71-built-in-curated-dictionary) - [Custom Contextual Speech Hints](#72-custom-contextual-speech-hints) - [Phrase Replacement Rules](#73-phrase-replacement-rules) 8. [Transcription History & Dual-Transcript Architecture](#8-transcription-history--dual-transcript-architecture) - [Dual-Transcript Architecture](#81-dual-transcript-architecture) - [Search, Copy Actions & Storage](#82-search-copy-actions--storage) 9. [Troubleshooting & Frequently Asked Questions](#9-troubleshooting--frequently-asked-questions) 10. [AI Coding Agent Reference & Machine Ingestion](#10-ai-coding-agent-reference--machine-ingestion) --- ## 1. Introduction & Core Architecture Whisp is a native, ultra-lightweight macOS voice-to-text utility engineered specifically for software engineers, CLI users, terminal AI agents (such as Claude Code, Devin, Codex CLI, Gemini CLI), and vibe coders. ### Core Architectural Pillars - **100% On-Device Speech Recognition**: Whisp leverages Apple's native on-device Speech framework (`SpeechAnalyzer` / `SpeechTranscriber` in macOS 26.5+, with `DictationTranscriber` and `SFSpeechRecognizer` fallbacks). Your voice audio never leaves your Mac and is never uploaded to Horizam, Apple, or any third-party cloud. - **Zero Heavy Model Downloads**: Unlike Whisper-based wrappers that require downloading 1.5 GB to 3.5 GB model weights that spin up your Mac's fans and drain battery, Whisp utilizes Apple Silicon's built-in neural speech engine. It requires **0 GB** of extra local model weight downloads and uses negligible RAM (~30–45 MB). - **Focus-Lock & Terminal Safety**: When dictation starts, Whisp captures the frontmost external application window identity. When transcription finishes, text is injected into that exact window. Whisp **never sends an Enter/Return key event** to your terminal, eliminating accidental command execution or runaway shell scripts. - **Developer-Tuned Formatting**: Spoken terms like `"package dot json"`, `"docs dot md"`, `"git checkout dash b"`, `"npm run dev"`, and `"yaml"` are deterministically formatted as `package.json`, `DOCS.md`, `git checkout -b`, `npm run dev`, and `YAML`. - **One-Time Lifetime License**: Whisp is distributed through the Mac App Store with a 7-day unrestricted trial and a single $9.99 lifetime purchase backed by StoreKit & RevenueCat. Zero recurring monthly or annual subscriptions. --- ## 2. System Requirements & Installation ### Requirements - **Operating System**: macOS 26.5 or later (macOS Tahoe/Ventura/Sonoma/Sequoia updates where applicable). - **Hardware**: Compatible with all Apple Silicon Macs (M1, M2, M3, M4 series) as well as modern Intel Macs supporting Apple on-device dictation. - **Storage**: < 20 MB disk space for the application bundle. ### Installation 1. Open the [Mac App Store](https://apps.apple.com/app/id6810185906) listing for Whisp. 2. Click **Get** / **Install**. 3. Once installed, launch Whisp from `/Applications` or via Spotlight (`⌘ Space` → `Whisp`). 4. Whisp runs in your macOS Menu Bar, Dock, and floating HUD overlay. --- ## 3. First-Run Setup & Permissions When Whisp is launched for the first time, it presents a 3-step native Liquid Glass onboarding flow to guide system permissions: ### Step 1: Microphone Permission (`NSMicrophoneUsageDescription`) - **Required**: Essential for voice capture. - Click **Allow Microphone Access** when prompted by macOS. - If previously denied, navigate to **macOS System Settings → Privacy & Security → Microphone** and toggle **Whisp** ON. ### Step 2: Speech Recognition & Auto-Paste (Accessibility) - **Speech Recognition (`NSSpeechRecognitionUsageDescription`)**: Optional compatibility fallback. Whisp defaults to macOS 26's installed on-device SpeechAnalyzer, but requesting permission ensures older fallback paths work seamlessly. - **Accessibility / Input Injection**: - Whisp uses macOS Accessibility APIs to inject transcribed text directly into the focused input field or terminal cursor without touching your clipboard. - Click **Configure Auto-Paste** to open **macOS System Settings → Privacy & Security → Accessibility** and toggle **Whisp** ON. - *Fallback*: If you choose not to grant Accessibility permission, Whisp functions in **Auto-Copy mode**—every completed transcript is automatically copied to your macOS clipboard, ready to paste with `⌘V`. ### Step 3: Audio Input Verification - Select your preferred physical or virtual microphone (e.g., MacBook Built-in Microphone, Studio Display, AirPods, USB Condenser Mic). - Speak a test phrase to see the live audio level meter respond in real time. - Click **Get Started** to finish onboarding. --- ## 4. How to Use Whisp (Core Workflows) ### 4.1. Hands-Free Dictation (`⌥ Option + Space`) 1. Position your cursor in any text field, terminal prompt (zsh, bash, fish), IDE (Cursor, VS Code, Xcode), or chat app (Slack, Discord). 2. Press **`⌥ Option + Space`** (or click the floating microphone dial). 3. The floating widget transitions immediately into the **Listening…** state with an active coral/red audio waveform. 4. Speak naturally. Live words stream onto your screen in real time. 5. Finish recording by: - Pausing speaking (if silence auto-finish is enabled, default 4.0s). - Pressing **`Return`** (commits immediately). - Pressing **`⌥ Option + Space`** again. 6. The transcript is instantly typed into your target window (or copied to clipboard). ### 4.2. Push-to-Talk Walkie-Talkie Mode (`Right ⌘`) Whisp includes a walkie-talkie mode using your physical **Right Command (`Right ⌘`)** key: 1. Press and **hold** `Right ⌘`. 2. Speak your command, prompt, or explanation. 3. **Release** `Right ⌘`. 4. Whisp immediately stops recording, transcribes, and injects the text. *Note: This utilizes a dedicated low-level hardware hook that does not interfere with standard Left Command (`Left ⌘`) keyboard chords like `⌘C`, `⌘V`, or `⌘S`.* ### 4.3. Long-Form Dictation & Silence Detection - **Silence Auto-Finish**: Enabled by default with a 4.0-second timer (configurable from 1.0s to 8.0s in Settings). When you stop speaking for the set duration, Whisp finalizes the recording automatically. - **Continuous / Uninterrupted Dictation**: In **Settings → Capture & Audio**, turn off **"Finish after silence"**. In this mode, recording stays open indefinitely through long pauses until you explicitly press `Return`, `⌥ Option + Space`, or click Stop. ### 4.4. Focus-Lock & Safe Insertion - When capture begins, Whisp records the active window bundle identifier and window index. - If you accidentally switch windows or click another app while speaking, Whisp verifies whether the original app is still frontmost before writing Unicode text. - If target focus was lost or the app has no editable text field, Whisp quietly copies the transcript to your clipboard and notifies you with a brief toast, rather than pasting into the wrong application. - Whisp **never sends Enter**, so shell commands are typed safely without execution. ### 4.5. Floating Widget Presentations Whisp offers three floating HUD presentation styles (configurable in **Settings → Experience & Controls**): 1. **Default Bar (430 × 118 pt)**: Stable Liquid Glass bar displaying live audio signal track, latest words, and expandable paragraph chevron. 2. **Mini Capsule (76 × 32 pt)**: Minimalist micro-capsule with an audio waveform and a detached hovering live-caption bar (176 × 28 pt) that streams the latest 4 spoken words above your active work. 3. **None**: Disables the floating widget entirely for users who prefer working exclusively via global shortcuts and the menu bar. *Auto-hide behavior: By default, the floating bar only appears while actively recording or processing, then smoothly disappears when idle. Enable **"Keep floating bar always visible"** if you prefer a permanent HUD.* --- ## 5. Keyboard Shortcuts & Configuration ### 5.1. Default Global Shortcuts | Action | Default Shortcut | Description | Remappable | | :--- | :--- | :--- | :--- | | **Start / Toggle Voice Capture** | `⌥ Option + Space` | Activates microphone & locks frontmost app. Press again to commit. | Yes | | **Push-to-Talk (Walkie-Talkie)** | `Right ⌘ Command` (Hold) | Hold while speaking; release to commit and paste. | Yes | | **Finish Recording Immediately** | `Return` | Finalizes live speech without waiting for silence timer. | Yes | | **Translate & Force-Paste** | `⌥ Option + Return` (or `⇧ Return`) | Translates non-English speech to English via local model and pastes. | Yes | | **Discard / Cancel Recording** | `Escape` | Immediately terminates capture; discards audio and live transcript. | Yes | | **Quick Spoken Language Picker** | `⌥ Option + L` | Opens floating Liquid Glass modal showing installed speech models. | Yes | | **Quick Microphone Source Picker**| `⌥ Option + M` | Opens floating modal to switch input audio hardware on the fly. | Yes | | **Toggle Floating Widget HUD** | `⌥ Option + B` | Shows or hides the floating HUD when recording is inactive. | Yes | | **Recent Transcriptions Modal** | Configurable | Floating clipboard-style view of your last 10 dictations. | Yes | ### 5.2. How to Configure & Remap Shortcuts 1. Open Whisp's main window (click dock icon, menu bar icon, or launch Whisp). 2. Go to **Settings** in the left sidebar. 3. In the **Experience & Controls** card, locate the **Keyboard shortcuts** row. 4. Click **Configure Shortcuts…** to open the floating Liquid Glass shortcuts manager. 5. Click **Change** next to any shortcut. 6. Press your desired physical key combination or standalone modifier key (such as `Right ⌘`, `F19`, `Ctrl+Space`, etc.). 7. Whisp validates the shortcut against system and internal conflicts in real time. 8. Click **Save Changes** (or click **Reset** next to any row, or **Reset All** to restore defaults). --- ## 6. Languages & Translation ### 6.1. Speech Recognition Models vs. Translation Models It is crucial to understand the difference between these two distinct technologies in macOS: - **Speech Recognition Models** (`Apple Speech framework`): Convert your physical voice acoustic waveforms into written text in the spoken language (e.g. speaking Spanish → Spanish text, speaking Japanese → Japanese text). - **Translation Models** (`Apple Translation framework`): Convert written text from one language into English (e.g. Spanish text → English text). ### 6.2. How to Download & Switch Speech Recognition Languages Whisp only lists speech models that are physically installed on your Mac, ensuring you never encounter failed captures. 1. Open Whisp → **Settings** → **Capture & Audio**. 2. Locate the **Download speech language** menu. 3. This menu dynamically lists all language packages supported by your macOS version (e.g., German, French, Japanese, Mandarin, Spanish, Italian, Portuguese, Korean, etc.). 4. Select the language you wish to download. 5. macOS will download the Apple Speech asset in the background. 6. Once installation finishes, Whisp automatically refreshes and activates the language for your next capture. 7. *Fast Switching*: Press **`⌥ Option + L`** anytime to switch between installed spoken languages without opening Settings. ### 6.3. How On-Device Translation Works (`⌥ Option + Return`) Whisp enables you to speak your thoughts in your native language (e.g. Hindi, Spanish, Mandarin, German, French, Arabic) and have it automatically translated to fluent English before typing into your code editor or terminal. 1. Set your Spoken Language in Whisp (e.g. Spanish). 2. Position your cursor in your IDE or terminal. 3. Press **`⌥ Option + Space`** and speak your prompt in your native language. 4. Instead of pressing normal finish, press **`⌥ Option + Return`** (or `Shift + Return`). 5. Whisp translates the speech to English entirely on-device and injects the English translation directly into your editor! *Note: If your active spoken language is already English, pressing `⌥ Option + Return` bypasses translation and executes a direct force-paste.* ### 6.4. How to Download Translation Languages in macOS Whisp uses Apple's native local Translation framework. To prepare the language pair: - **Method A (Within Whisp)**: 1. Open Whisp → **Settings** → **Capture & Audio**. 2. Under the Spoken Language selection, click **Prepare English translation**. 3. macOS will prompt you to download the required offline translation model pair if not already present. - **Method B (macOS System Settings)**: 1. Open **System Settings** on your Mac. 2. Navigate to **General → Language & Region**. 3. Scroll down and click **Translation Languages**. 4. Ensure **"On-Device Mode"** is toggled ON (Downloaded languages will be used for translation even without internet). 5. Find your spoken language (e.g., Spanish, French, German, Italian, Japanese, Chinese, etc.) and click the Download icon next to it. ### 6.5. Code Token Preservation (`CodeTokenPreserver`) Standard translation engines (like Google Translate or raw Apple Translation) often break code by translating technical identifiers (e.g. translating `UserRepository` to `RepositorioDeUsuario`, or `package.json` to `paquete.json`). Whisp solves this with its proprietary **`CodeTokenPreserver`**: - Before handing text to the translation engine, Whisp scans for programming terms, file extensions (`*.swift`, `*.ts`, `*.py`, `*.rs`, `*.vue`, `*.go`), camelCase tokens, snake_case identifiers, HTTP endpoints (`POST /api/v1/users`), CLI flags (`--dry-run`, `-rf`), and URLs. - These tokens are masked with deterministic semantic anchors. - The prose is translated by Apple Translation. - Whisp re-hydrates the original intact code tokens into the final English output with correct syntax casing and formatting intact. --- ## 7. Developer Vocabulary & Phrase Replacements ### 7.1. Built-In Curated Dictionary Whisp's speech engine includes an embedded context dictionary containing thousands of modern software engineering terms: - **Package Managers & Tools**: `npm`, `pnpm`, `yarn`, `bun`, `cargo`, `brew`, `pip`, `poetry`, `composer`, `gem`, `docker`, `kubernetes`, `kubectl`. - **Languages & Frameworks**: `SwiftUI`, `TypeScript`, `Next.js`, `Nuxt`, `Tailwind`, `React`, `Vue`, `FastAPI`, `GraphQL`, `PostgreSQL`, `SQLite`, `Redis`. - **Common Files**: `package.json`, `composer.json`, `Cargo.toml`, `tsconfig.json`, `DOCS.md`, `README.md`, `.gitignore`, `.env.example`, `Dockerfile`. - **Command patterns**: `git status`, `git checkout -b`, `npm run dev`, `cargo build --release`. ### 7.2. Custom Contextual Speech Hints Add domain-specific product names, internal microservice names, or coworker names that Apple Speech might not recognize by default. 1. Open Whisp → **Vocabulary** in the sidebar. 2. In the **Contextual Speech Hints** card, click **Add Term**. 3. Type your term (e.g., `Horizam`, `Supabase`, `PrismaClient`, `LangChain`, `ClaudeCode`). 4. You can store up to **100 custom terms**. These are passed as high-priority recognition hints directly to Apple's speech engine before audio capture starts. ### 7.3. Phrase Replacement Rules Deterministic regex-powered word boundary replacements executed after speech recognition and translation. 1. Open Whisp → **Vocabulary** in the sidebar. 2. In the **Phrase Replacements** card, click **Add Replacement**. 3. Enter: - **Spoken phrase**: What you say (e.g. `"by the way"`, `"pull request"`, `"arrow function"`). - **Replacement text**: What gets typed (e.g. `"btw"`, `"PR"`, `"=>"`). 4. The modal includes a real-time interactive preview testing your input against sample text. 5. Whisp stores up to **100 custom replacement rules**. Replacements match with case-insensitive Unicode word boundaries without recursive cascading. --- ## 8. Transcription History & Dual-Transcript Architecture Whisp automatically saves completed dictations locally on your Mac: - **Storage Location**: `~/Library/Application Support/Whisp/history.json`. - **Capacity**: Bounded to the last **250 transcriptions** (serialized asynchronously to disk). - **Privacy**: History is stored exclusively on your local sandboxed disk and is never uploaded anywhere. ### 8.1. Dual-Transcript Architecture When you use translation mode (`⌥ Option + Return`), Whisp saves **both** versions: 1. **Primary Text**: The translated English text (displayed front-and-center, ready for instant copying or insertion). 2. **Native Transcript**: The original spoken words in the native language (accessible via an interactive badge in the card, e.g., `🌐 Spanish ▾`). Clicking the badge smoothly expands an inline drawer displaying the original transcript. ### 8.2. Search & Multi-Action Copying - **Instant Search**: The History view features an ultra-responsive search bar that searches both English translations, original native speech, dates, and language tags. - **Multi-Action Copying**: - Double-click any row to copy the primary text. - Click the primary **Copy** button. - Open the row ellipsis menu to choose: - *Copy English Translation* - *Copy Original ([Language])* - *Copy Both (Original & Translation)* - **Bulk & Individual Deletion**: Delete individual entries or click "Clear History" to purge all records. --- ## 9. Troubleshooting & Frequently Asked Questions ### Q: Why is text copying to my clipboard instead of typing into my app? **A**: Direct typing requires macOS Accessibility permission. 1. Open **System Settings → Privacy & Security → Accessibility**. 2. Make sure **Whisp** is toggled ON. 3. If Whisp is already ON, toggle it OFF and ON again. 4. Also verify in Whisp → **Settings → Experience & Controls** that **"Automatically paste into the focused app"** is enabled. ### Q: Why did translation fail with an error? **A**: Translation requires the offline language pair to be downloaded in macOS. 1. Open **System Settings → General → Language & Region → Translation Languages**. 2. Download your spoken language asset. 3. Ensure **"On-Device Mode"** is enabled. ### Q: Can Whisp pause music or YouTube playing on my Mac while I speak? **A**: Yes! In Whisp → **Settings → Capture & Audio**, turn on **"Pause other audio while recording"**. Whisp will automatically mute/duck your Mac's output speakers the moment you start speaking and restore your exact prior volume the moment capture finishes. ### Q: How do I restore my Lifetime purchase on a new Mac? **A**: 1. Install Whisp from the Mac App Store using the same Apple ID. 2. Open Whisp → **Settings**. 3. In the top Lifetime card, click **Restore Purchases**. 4. StoreKit will validate your receipt with Apple and unlock the app immediately. --- ## 10. AI Coding Agent Reference & Machine Ingestion If you are an autonomous AI coding agent (e.g., Claude Code, Devin, Codex CLI, Cursor Composer, Gemini CLI, Antigravity) reading this documentation to integrate with or troubleshoot Whisp: ### Direct Machine Endpoints - Canonical LLM Manifest: `https://whisp.horizam.com/llms.txt` - Full Raw Markdown: `https://whisp.horizam.com/docs.md` - Application Bundle ID: `com.ai.whisp` - StoreKit Product ID: `com.ai.whisp.lifetime` - Local Storage Directory: `~/Library/Application Support/Whisp/` - History File: `~/Library/Application Support/Whisp/history.json` - Preferences: `~/Library/Preferences/com.ai.whisp.plist` ### Programmatic Dictation Flow Summary ```text User speaks │ ├──► Push-to-Talk (Hold Right ⌘) OR Option-Space │ ▼ Apple SpeechAnalyzer (On-Device Streaming) │ ├──► Developer Vocabulary Biasing (Curated + Custom Hints) │ ▼ Final Recognition Event │ ├── Standard Dictation ──► Deterministic Code Formatter │ │ └── Option-Return (Translation) ▼ │ CodeTokenPreserver (Mask tokens) │ │ │ ▼ │ Apple Translation Framework │ │ │ ▼ └───────────────► Restore tokens & format │ ▼ Focus-Lock Window Verification │ ┌────────────┴────────────┐ ▼ ▼ Accessibility Clipboard Fallback Unicode Injection (Auto-Copy) │ │ ▼ ▼ App Target macOS Clipboard │ │ └────────────┬────────────┘ ▼ Saved to Local history.json (Dual-Transcript) ```