WhisperDictate/README.md

WhisperDictate

A simple menu bar app for voice dictation using OpenAI Whisper (local, offline).

Platforms

Platform	Language	Status
macOS	Swift	✅ Ready
Linux	Rust	🔜 Planned
Windows	C#	🔜 Planned

macOS

What's new in 1.4.1

• 🎨 Native icons instead of emoji — the menu bar icon, recording overlay, download window, menus and Settings now use macOS SF Symbols: sharp at any size, matching light/dark menu bars, and the menu bar microphone turns red while recording

What's new in 1.4.0

• 💬 Live preview while recording — the recording overlay shows what you're saying as you speak, using macOS's on-device dictation model (works in Hungarian too). It's a preview: the pasted text still comes from Whisper, so it can differ slightly. Toggle it in Settings.

What's new in 1.3.1

• 🪶 Quantized models — Large v3 Turbo q5_0 keeps the transcription server at ~0.7 GB RAM instead of ~1.75 GB, at the same speed (also Small q5_1, Medium q5_0, Turbo q8_0 and Large v3 q5_0)
• 📥 Download progress window — progress bar, size, speed, time remaining, Cancel/Retry; progress also shows in the menu bar and Settings
• 🔥 Model warm-up at recording start — if the model was paged out after a pause, it starts loading as soon as you start talking, not after you stop; the HUD tells you when a transcription is slower because the model is still loading

What's new in 1.3.0

• ⚡ Warm transcription server — the Whisper model stays loaded in a background whisper-server, so each dictation is a fast local call (~0.5s) instead of reloading the 1.5–1.6 GB model on every utterance
• 📊 Live mic-level HUD while recording, which warns ("No audio input?") if the microphone stays silent
• 📖 Custom dictionary — an editable Heard → Replacement table that fixes names/jargon in the transcript and also biases recognition

Features

• 🎤 Global hotkey (⌃⌥D) to start/stop recording
• ⚡ Fast transcription via a warm whisper-server (model stays loaded — no per-dictation reload), with automatic fallback to whisper-cli
• 📊 Live mic-level meter while recording, with a "no audio input" warning
• 💬 Live transcript preview in the recording overlay (on-device Apple dictation model; Whisper still produces the pasted text)
• 📖 Custom dictionary (heard → replacement) that also biases recognition
• 🔒 Fully offline - uses local Whisper model
• ⌨️ Automatic paste into any focused app
• 📋 Clipboard preservation - your copied content is restored after paste
• ⚙️ Settings window with model selection dropdown
• 📥 Built-in model downloader with a progress window (speed, time remaining, cancel/retry)
• 🪶 Quantized model options for much lower memory use
• 🚀 Launch at login support
• 🔊 Sound feedback (optional)
• 📦 Self-contained - whisper-cli and whisper-server bundled in the app

Requirements

• macOS 26 (Tahoe) or later
• Apple Silicon (M1/M2/M3) or Intel Mac

Quick Install (Download)

1. Download the latest DMG from Releases
2. Open the DMG and drag WhisperDictate to Applications
3. Launch WhisperDictate
4. On first run, select and download a Whisper model
5. Grant permissions (Microphone + Accessibility)

Build from Source

# Clone the repository
git clone https://github.com/hariel1985/WhisperDictate.git
cd WhisperDictate/macos

# Install whisper-cpp (required for bundling)
brew install whisper-cpp

# Build and install to /Applications
make install

Build Commands

Command	Description
make build	Compile the app and bundle whisper-cli
make install	Build and install to /Applications
make run	Build and run
make dmg	Create distributable DMG
make clean	Remove build artifacts

Usage

1. Launch WhisperDictate from Applications
2. Look for the microphone icon in your menu bar
3. Press ⌃⌥D (Control + Option + D) to start recording
4. Speak (the menu bar microphone turns red)
5. Press ⌃⌥D again to stop and transcribe
6. Text is automatically pasted where your cursor is

Settings

Click the menu bar icon → Settings to configure:

• Language: Auto-detect or 31 supported languages
• Model: Select from installed models or download new ones (✓ marks models already downloaded)
• Dictionary: Add Heard → Replacement pairs to fix names/jargon (use \n for a newline); the replacement terms also improve recognition
• Sound feedback: Toggle audio feedback on/off
• Live preview while recording: Show a rough live transcript in the recording overlay (on by default)
• Launch at login: Start automatically when you log in

Whisper Models

Download models directly from the app or manually:

Model	Size	Speed	Accuracy	Best For
Tiny	75 MB	~1 sec	Basic	Quick tests, simple phrases
Base	142 MB	~2 sec	Good	Clear speech, quiet environment
Small	466 MB	~3 sec	Better	General use, some accents
Medium	1.5 GB	~5 sec	Great	Accents, noisy audio
Large v3 Turbo	1.6 GB	~4 sec	Best	Recommended - fast like Medium, accurate like Large
Large v3	3.1 GB	~8 sec	Maximum	Difficult audio, max accuracy

Quantized variants (q5/q8) have much smaller weights, so the model uses far less memory, with a small accuracy trade-off:

Model	Size	Full-size equivalent
Small q5_1	181 MB	Small (466 MB)
Medium q5_0	514 MB	Medium (1.5 GB)
Large v3 Turbo q5_0	547 MB	Large v3 Turbo (1.6 GB) — measured ~0.7 GB RAM vs ~1.75 GB, same speed
Large v3 Turbo q8_0	833 MB	Large v3 Turbo (1.6 GB) — near-identical accuracy
Large v3 q5_0	1.0 GB	Large v3 (3.1 GB)

Models are stored in ~/.whisper-models/

With the warm server (1.3.0+), the selected model loads once at startup (a few seconds); after that each dictation skips the reload, so the speeds above are roughly the per-dictation transcription time.

The server keeps the whole model in memory while it runs. If macOS pages it out after a long pause, 1.3.1+ starts loading it back as soon as you start recording, and the HUD shows "Loading model into memory…" if that takes a moment.

Audio Feedback

• 🔔 Tink - Recording started
• 🔔 Pop - Recording stopped, processing
• 🔔 Glass - Success, text pasted
• 🔔 Basso - Error

Permissions

Grant these in System Settings → Privacy & Security:

Permission	Why it's needed
Microphone	To record your voice for transcription
Accessibility	To simulate ⌘V keystroke and paste text into any app. macOS requires this permission for apps that send keyboard events to other applications.

Note

: After reinstalling or updating, you may need to remove and re-add the app in Accessibility settings.

Security

• All processing is done locally - no data leaves your device
• The live preview uses macOS's on-device dictation model (SpeechAnalyzer); it needs no extra permission beyond the microphone
• The bundled whisper-server is bound to 127.0.0.1 (loopback only) and is never exposed on the network
• Audio files are stored in private temp directory and deleted after transcription
• Clipboard is cleared after paste (transcript doesn't remain accessible)
• Original clipboard content is preserved and restored after paste
• Input validation prevents command injection
• No network access except for optional model downloads from Hugging Face

License

MIT License