Wisper

Open-source, local-first voice dictation for your desktop.
Hold a hotkey, speak, release — your words are transcribed on-device with Whisper and typed straight into whatever app you're using.

🌐 Website & downloads

Download · Quick start · Build from source · Troubleshooting · Contributing · License

---

Contents

• What it is
• Why Wisper
• Features
• Quick start
• Install
• Permissions
• Usage
• Configuration
• Models
• Languages
• How it works
• Privacy
• Build from source
• Project layout
• Tech stack
• Updates & releases
• Troubleshooting
• Contributing
• License
• Acknowledgements

What it is

Wisper is a free, open alternative to cloud dictation tools like Wispr Flow. Everything runs on your machine — no cloud, no account, no telemetry, no subscription. Your audio never leaves your computer; transcription happens entirely on-device via whisper.cpp, with Metal GPU acceleration on Apple Silicon.

It lives in your system tray as a small floating "pill" and stays out of the way until you press your hotkey.

Why Wisper

	Wisper	Typical cloud dictation
Where audio goes	Stays on your device	Uploaded to a server
Account required	No	Usually yes
Cost	Free & open source (MIT)	Subscription
Works offline	Yes	No
Telemetry	None	Common
Languages	99 (Whisper)	Varies
Customizable	Source is yours	Closed

✨ Features

• 🎙️ Push-to-talk & hands-free — hold the hotkey to dictate while held, or double-tap to keep recording without holding; a later single press stops and inserts.
• ⌨️ Any hotkey you want — bind a combo (Ctrl+Shift+Z) or a single modifier on its own (just Option, Ctrl, or Shift, push-to-talk style).
• 🔒 100% local — on-device Whisper inference; nothing is ever sent anywhere.
• ⚡ GPU-accelerated — Metal on Apple Silicon for near-instant transcription.
• 🌍 99 transcription languages — pick one or let Whisper auto-detect.
• 🗣️ Localized interface — UI, tray menu, and error messages in 15 languages (English, Português, Español, Français, Deutsch, Italiano, Nederlands, Русский, Polski, Türkçe, 日本語, 한국어, 中文, العربية, हिन्दी).
• 📦 Built-in model manager — download, switch, and remove Whisper models from inside the app, with live progress and cancel.
• 📖 Custom dictionary — teach it names and jargon so they're spelled right.
• 🔁 Text replacements — auto-rewrite snippets in every transcript (e.g. omw → on my way).
• 📊 Insights & history — a local, honest log of what you dictated with words-per-minute and daily stats. Nothing fabricated, nothing uploaded.
• 🖱️ Two injection modes — synthetic keystrokes or clipboard paste.
• 🔊 Dictation sounds & music ducking — optional start/stop cues; optionally mute playing music while you talk.
• 🪟 Tray-native — closing the window keeps it running; quit from the tray.
• 🚀 Launch at login and optional menu-bar-only (hide the Dock icon).
• 🌗 Light & dark theme.
• 🔄 Automatic updates — signed over-the-air updates via GitHub Releases.

🚀 Quick start

1. Download and install for your OS.
2. Launch it and complete the short onboarding.
3. Grant Microphone (and on macOS, Accessibility) permission — see Permissions.
4. Download a model (start with base) and pick your language.
5. Anywhere you can type, hold your hotkey, speak, release — your words appear in the focused app.

📥 Install

Grab the installer for your platform from the latest release:

Platform	Asset
macOS (Apple Silicon / Intel)	.dmg
Windows	.msi / .exe
Linux	.AppImage / .deb

Note

macOS builds are ad-hoc signed (no paid Developer ID yet). On first launch, right-click the app → Open, or allow it under System Settings → Privacy & Security. After that it opens normally and updates itself.

🔐 Permissions

Wisper needs OS-level permissions to hear you and to type for you:

Permission	Why	Where
Microphone	Capture your voice	macOS/Win/Linux prompt on first record
Accessibility (macOS)	Insert text into other apps and read the global hotkey	System Settings → Privacy & Security → Accessibility

On macOS, after an app update the system can occasionally drop the Accessibility grant. Wisper detects this and re-prompts; if text stops inserting after an update, re-enable it under Accessibility (see Troubleshooting).

🧭 Usage

1. Open Settings from the tray icon.
2. Download a model — start with base for a good size/quality balance; use small or large-v3-turbo for higher accuracy, especially in non-English.
3. Choose your language (or Detect automatically) and set your hotkey (a combo or a single modifier).
4. Dictate:
   • Push-to-talk — hold the hotkey, speak, release.
   • Hands-free — double-tap the hotkey to start, single-press to stop.
5. The floating pill shows recording state and a quick language switcher. Closing the main window keeps Wisper running in the tray.

⚙️ Configuration

Everything is in Settings, persisted to a local config.toml:

Setting	What it does
Hotkey	Click to capture any combo, or a lone modifier (Option/Ctrl/Shift).
Model	Active Whisper model; manage downloads here.
Language	Transcription language, or auto-detect.
Interface language	UI, tray, and error-message language (15 options).
Microphone	Input device, or system default.
Injection mode	type (synthetic keystrokes) or paste (clipboard).
Dictionary	Bias words so names/jargon transcribe correctly.
Replacements	from → to rewrites applied to every transcript.
Dictation sounds	Start/stop audio cues.
Mute music	Duck other audio while recording.
Show pill	Keep the floating pill on screen, or hide until dictating.
Show in Dock	Toggle Dock icon vs. menu-bar-only (macOS).
Launch at login	Start Wisper automatically.
Theme	Light or dark.

🧠 Models

Whisper's multilingual models transcribe all languages from a single file; the .en variants are English-only but a little faster. Bigger = more accurate and slower.

Model	Size	Languages
tiny / tiny.en	~75 MB	all / English
base / base.en	~142 MB	all / English
small / small.en	~466 MB	all / English
medium / medium.en	~1.5 GB	all / English
large-v3-turbo	~1.6 GB	all (near-large accuracy, fast)

Models are downloaded on demand from inside the app and stored locally; you can remove them anytime to reclaim space.

🌍 Languages

• Transcription: 99 languages supported by Whisper, plus automatic detection.
• Interface: English, Português, Español, Français, Deutsch, Italiano, Nederlands, Русский, Polski, Türkçe, 日本語, 한국어, 中文, العربية, हिन्दी — applied to the window UI, the tray menu, and error toasts.

🔧 How it works

   ┌──────────┐   hold/double-tap   ┌─────────────┐   PCM audio   ┌──────────────┐
   │  Hotkey  │ ──────────────────▶ │   Recorder  │ ───────────▶ │ whisper.cpp  │
   │ (global) │                     │   (cpal)    │              │  (on-device) │
   └──────────┘                     └─────────────┘              └──────┬───────┘
                                                                        │ text
                                          ┌──────────────┐   keystrokes │
   focused app  ◀───────────────────────  │  Injector    │ ◀────────────┘
                                          │ (type/paste) │
                                          └──────────────┘

A global shortcut (or single-modifier event tap) starts capture, audio is recorded with cpal, transcribed locally by whisper.cpp, run through your dictionary/replacements, and injected into the focused app as keystrokes or a clipboard paste. The floating pill is a non-activating overlay so it never steals focus from the app you're typing into.

🛡️ Privacy

• Audio is processed entirely on your device and is not stored after transcription.
• No account, no telemetry, no network calls for transcription.
• The only network activity is downloading models you ask for and checking for app updates from GitHub Releases.
• History and insights are kept locally and never leave your machine.

🏗️ Build from source

Prerequisites: Rust, Node.js, pnpm, and the Tauri system dependencies for your OS.

git clone https://github.com/99labdev/wisper.chat.git
cd wisper.chat
pnpm install
pnpm tauri dev      # run in development
pnpm tauri build    # produce a release bundle for your platform

Checks

# Frontend
pnpm lint           # ESLint
pnpm typecheck      # tsc --noEmit
pnpm test           # Vitest
pnpm format:check   # Prettier

# Backend (Rust)
cd src-tauri
cargo test
cargo clippy -- -D warnings
cargo fmt --check

📁 Project layout

wisper/
├── src/                 # React + TypeScript settings UI
│   ├── routes/          # Home, Settings, Insights, Dictionary, Snippets, Overlay…
│   └── lib/             # api bindings, i18n, theme, hotkey helpers
├── src-tauri/           # Rust backend
│   └── src/
│       ├── audio.rs     # microphone capture (cpal)
│       ├── stt.rs       # Whisper transcription (whisper.cpp)
│       ├── inject.rs    # text injection (keystrokes / paste)
│       ├── modtap.rs    # single-modifier hotkey (macOS event tap)
│       ├── uitext.rs    # localized tray + error strings
│       ├── overlay.rs   # pill geometry & hit-testing
│       └── lib.rs       # app wiring, tray, shortcuts, windows
├── site/                # marketing website (GitHub Pages)
└── .github/workflows/   # CI + cross-platform release

🧩 Tech stack

• Tauri 2 — native shell, tray, global shortcuts, OTA updater
• React + TypeScript + Vite — settings UI
• Rust — audio capture, Whisper inference, text injection, hotkey handling
• whisper.cpp (via whisper-rs) — on-device speech-to-text, Metal-accelerated on macOS
• cpal — cross-platform audio capture

🔄 Updates & releases

Wisper updates itself: it checks GitHub Releases and applies signed over-the-air updates in the background.

For maintainers, pushing a v* tag triggers the release workflow, which builds and publishes installers for macOS, Linux, and Windows plus the updater manifest:

git tag v1.0.0
git push origin v1.0.0

🩺 Troubleshooting

It records but no text is inserted

Grant Accessibility permission (macOS: System Settings → Privacy & Security → Accessibility) so Wisper can type into other apps. After a macOS update the grant can reset — toggle Wisper off and on in that list. As a fallback, switch the injection mode to paste in Settings.

The microphone isn't capturing audio

Allow Microphone access when prompted (or in your OS privacy settings), and make sure the right input device is selected in Settings → Microphone. On macOS, a permission can need re-granting right after installing or updating.

Transcription is slow

Use a smaller model (base or small), or large-v3-turbo for a good speed/accuracy trade-off. On Apple Silicon, Metal acceleration is enabled automatically.

macOS won't open the app ("unidentified developer")

Right-click the app → Open, then confirm. Builds are ad-hoc signed; this is a one-time step.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md, keep changes focused, and run the checks above before opening a PR. Bug reports and feature ideas are great as issues.

📄 License

MIT © Hudson Brendon

🙏 Acknowledgements

• whisper.cpp and OpenAI's Whisper for on-device speech recognition
• Tauri for the native cross-platform shell
• Everyone who tests Wisper and files issues