WhisprStream is an open-source macOS dictation app that types at your cursor while you speak. It runs locally, keeps the model warm for low latency, and follows mixed-language sentences without uploading audio. Use it in any app—from notes and email to your terminal and coding agent.
Highlights
- Live transcription with a floating HUD
- Multilingual dictation: switch languages mid-sentence, without being limited to Chinese and English—or to two languages at a time
- Custom vocabulary for names, technical terms, and jargon
- Voice shortcuts that expand a spoken phrase into a URL, signature, address, reusable reply, or any text you type often
- A configurable recording shortcut, including custom modifier chords and F13–F24
- Non-streaming models can still produce a live preview: WhisprStream repeatedly re-reads the growing utterance and settles the stable words
- No account, server, or audio upload
Install WhisprStream
Requirements
- macOS 14 or later
- Apple silicon Mac
- Approximately 4 GB free for the speech engine and recommended 0.6B model
Install with Homebrew
brew install --cask Leo6Leo/tap/whispr-stream
The custom Cask pins the release checksum and removes quarantine only from the
installed WhisprStream app. It does not disable Gatekeeper. Public builds are
self-signed and not notarized by Apple.
Download and first launch
- Open GitHub Releases, download
WhisprStream-macos-arm64.zip from the latest published release, extract it, and move WhisprStream to Applications.
- Open the app. Public builds are self-signed but not notarized, so the first launch may require System Settings → Privacy & Security → Open Anyway. Do not disable Gatekeeper.
- Follow Setup Guide to download the private speech engine. The app checks free space, verifies the archive, installs it in Application Support, and runs a health check before using it.
- Choose a speech model. Qwen3-ASR 0.6B is the recommended download at approximately 1.9 GB. Qwen3-ASR 1.7B is approximately 4.3 GB and is best suited to Macs with at least 16 GB of unified memory.
- Grant Microphone and Accessibility access, or finish those steps later from Settings → Permissions. Two later steps are optional: Screen & System Audio Recording, which macOS requires only for system-audio dictation, and Learn from edits, which keeps corrected sentences and their recordings on this Mac (off by default).
The native app, speech engine, and model are separate. The engine and model are downloaded only when needed, remain on your Mac, and survive normal app updates. The direct-download path requires no Python, Homebrew, pip, Xcode, Terminal, account, or audio upload. See the full installation and recovery guide.
Transcribing system audio
WhisprStream can transcribe what your Mac is playing — a video, a call, a podcast — instead of your microphone. Choose Settings → General → Audio source → System audio, or press ⌥S during a live dictation to switch between the microphone and system audio without restarting. While system audio is the source, the live preview turns a soft rainbow so you always know which one is being heard. macOS routes system audio through the Screen & System Audio Recording permission; WhisprStream registers only an audio output and keeps no screen image. Audio is still transcribed on this Mac.
Experimental optional models
Custom Qwen3-ASR and MLX Whisper models are still under development. They are behind a compile-time feature gate and are not available in the public 1.0.5 build. Local source builds enable the experimental UI by default; use ENABLE_OPTIONAL_MODELS=0 WhisprStream/build.sh to reproduce the public behavior.
Interrupted downloads and repair
- If an engine installation fails, open Settings → Engine and use Install or Repair / Reinstall. This replaces only the managed engine.
- If a model download is interrupted, open Settings → Model and choose Clear Partial Data. Cleanup is limited to unfinished files for that model; installed models and settings are untouched.
- A cancelled or crashed model download releases its lock automatically, so stale state cannot permanently block cleanup.
- WhisprStream checks for stable updates after launch and periodically while it is running. A new release gets one friendly prompt plus a persistent accent-colored dot beside the menu bar icon and a banner in Settings until it is installed. Update & Relaunch downloads, verifies, installs, and reopens the app in place; Settings → About still supports manual checks. The engine, model cache, preferences, vocabulary, and shortcuts are preserved.
Build from source
Source builds require:
The developer setup remains:
./setup-mac.sh
WhisprStream/build.sh
open WhisprStream.app
Source builds use the prepared local development engine and show Development engine ready in Settings. Open Settings → Model to download a model. To exercise the download UI without changing real runtime or model files, quit the app and launch it with:
WHISPR_TEST_FIRST_RUN=1 WhisprStream.app/Contents/MacOS/WhisprStream
Hold the Right Option key, speak, and release; the transcript is inserted into the active app. To choose another trigger, open Settings → General → Recording shortcut and record a modifier chord or F13–F24. Right Option remains the default.
Open source and model flexibility
WhisprStream is MIT licensed and designed to be inspected, adapted, and extended. The public 1.0.5 app offers the built-in Qwen3-ASR models. Experimental adapters for custom Qwen3-ASR and MLX Whisper checkpoints remain available to source-build developers behind a compile-time gate. A model does not need native streaming support: WhisprStream can repeatedly transcribe the full utterance, preserve context across language switches, and turn stable output into a live stream.
The native Swift front end and Python ASR sidecar communicate locally over a small newline-delimited JSON protocol. See HANDOFF.md for architecture notes and troubleshooting.
License
WhisprStream is available under the MIT License.
