_{Want a real screen-recording demo here? See docs/demo-recording.md — drop a docs/demo.gif in and uncomment the line below.}

Whisper Local is a free, open-source, fully offline alternative to Wispr Flow, Dragon, and Otter for power users who want AI dictation without sending audio to the cloud. Built on faster-whisper (CTranslate2), it delivers push-to-talk speech-to-text in any application — chat apps, code editors, browsers, terminals, design tools, anywhere a cursor blinks. Self-hosted, hackable, MIT-licensed.

Looking for: Wispr Flow alternative, offline voice typing, local Whisper dictation, free Dragon NaturallySpeaking alternative, privacy-first speech-to-text, Windows voice dictation without cloud, macOS push-to-talk transcription. You found it.

🌟 Why this exists

Most AI dictation tools are great — until you check the privacy policy. Your audio goes to a server, gets processed, and (sometimes) stored. You pay a monthly fee or get cut off.

Whisper Local exists because you shouldn't have to choose between accuracy and privacy.

• 🔒 Your voice never leaves your machine — not even metadata
• 🆓 Free forever — no account, no API key, no subscription
• 🔌 Works offline, air-gapped, after the internet is gone
• 🛠️ Fork it, hack it, ship your own version — MIT licensed
• 💡 Same Whisper model quality as cloud services, running on your own GPU

This is a community tool, not a product. There's no support SLA, no roadmap committee, no marketing. If it's useful to you, great. If something's broken, PRs are welcome.

A note from the maintainer: I built this for myself, then realised it might help others. So I'm releasing it for anyone who wants it — no strings attached. Use it. Fork it. Rebrand it. Ship your own version. The only thing I ask is that you keep the LICENSE notice intact. If you build something cool on top of it, I'd love to hear about it via a Discussion — but you don't owe anyone anything.

— Rohit Burani

✨ Why Whisper Local?

🎯 Features

• 🎙️ Global push-to-talk hotkey — start recording from any app with Ctrl+Win (Windows) or Fn+Ctrl (macOS)
• ⚡ Pre-roll buffer + warmup — captures the 500 ms before you press the key and pre-loads Whisper at boot, so the first word is never clipped and the first recording feels instant
• 🏷️ Terminal tab title status — the tab shows what the app is doing (idle / recording / processing), handy when the tray icon is hidden in the overflow area
• 🔵 Floating level overlay — a small pill at the screen edge shows you're being heard, with the transcript appearing next to the level bar (Wispr Flow–style). Optional real-time streaming preview shows words as you speak. (Windows; the macOS menu-bar icon shows status instead.)
• 📝 Inline voice formatting — say "comma", "period", "question mark", "new paragraph", "open quote", etc. mid-sentence. Fully customizable for any language via postprocess.inline_formatting_replacements (e.g. map Polish phrases to punctuation, or "arrow" → →)
• 🧽 One cleanup setting — none / light / medium / high decides how much gets tidied: stutters and "um" go by default, "scratch that" and "meet at 2, actually 3" from medium up. See Smart editing
• 🧾 Spoken lists — "first, milk. second, eggs" becomes a numbered or bulleted list (postprocess.list_formatting, opt-in)
• ✨ Snippets — say "my signature" (or any trigger you define) mid-dictation and the full text is typed, with ${date} / ${time} / ${clipboard} filled in
• 🎨 Writing styles — formal, casual, very casual or verbatim, globally or per app (email formal, chat casual, code verbatim out of the box)
• 📌 Paste last dictation — Alt+Shift+Z types your last dictation again when it landed in the wrong window
• 🙌 Hands-free lock — double-tap the record hotkey to keep recording without holding it; tap again to stop (hotkey.double_tap_to_lock, opt-in)
• 🤫 Whisper mode — boosts quiet speech so you can dictate in an open office (audio.whisper_mode, opt-in)
• 🔢 Smart formatting — deterministic, offline: "3 p.m." → "3 PM", "john at example dot com" → "john@example.com" (postprocess.smart_formatting, each toggle opt-in)
• 🤖 AI rephrase — dedicated Ctrl+Shift+Win hotkey: select text, hold, speak your instruction, release — local Ollama rewrites it in place
• 🌐 Translation mode — speak any language, get English; tray → Profile → Translate
• 🔁 Continuous dictation mode — for long-form notes, the app auto-restarts recording after each delivery
• 📋 Fallback window — if no text field is focused, the transcript appears in a small window (pre-selected, copy button, already on clipboard)
• ⏸ Pause-all hotkey — Ctrl+Alt+Win (or the tray's Pause hotkeys) disables every Whisper Local hotkey until you press it again
• 🗓️ History retention — keep your dictation history for N days, or store none at all (history.retention_days)
• 📋 Auto-paste at cursor — transcript lands wherever you're typing, optionally followed by Enter (auto-send)
• 🔒 100 % local & private — no network calls during use; Whisper models cached on disk
• 🚀 GPU acceleration — NVIDIA CUDA and AMD ROCm supported, CPU works out of the box
• 🗣️ Voice commands — say a trigger phrase to send a hotkey, type pre-written text, or run a shell command
• 🔁 Hot-reload — edit commands.yaml and your change applies on the next transcription, no restart
• 🩺 Built-in diagnostics — whisper-local --doctor checks audio devices, model cache, hotkeys, and recent errors
• 🎛️ Profiles — switch between Dictation / Chat / Code / Notes presets from the tray
• 🪟 Per-app rules — different behaviour and formatting per foreground app: auto-send in Slack, copy-only + verbatim (no auto-caps/periods) in VS Code, full sentences in email, suppress in 1Password
• ⌨️ Type-as-you-speak (experimental, opt-in) — streaming.deliver_to_cursor commits finalized phrases to the cursor live, Wispr-Flow style (trades full-Whisper accuracy for latency; see docs/streaming.md)
• 🧹 Optional LLM cleanup — pipe transcripts through a local Ollama model for punctuation / capitalisation polish (off by default, fully local)
• 📜 Recent transcriptions — last 10 results in the tray menu, click to copy back
• 🔧 Settings backup/restore — --export-settings / --import-settings for portability
• 🖥️ Settings UI — whisper-local --settings opens a GUI settings window (no YAML editing required)
• 📜 Transcript history — whisper-local --history opens a searchable log of everything you've dictated
• 📖 Vocabulary corrections — map one canonical spelling to every way Whisper mishears it (CAPEX: [cap x, copics]), applied in a single pass with longest-match-wins
• 🧠 Self-improving accuracy — from the history window, turn any misrecognition into a permanent correction ("Fix this everywhere…"), or let it mine your own history for names to add to your dictionary ("Suggest hotwords"). All offline; corrections apply on your next dictation, no restart
• 🔊 System-audio capture (experimental) — whisper-local --transcribe-system transcribes what you hear (meetings, videos), not just the mic (pip install 'whisper-local[loopback]', Windows-first)
• 🔔 Opt-in update notifications — daily GitHub release check, fully offline by default (update_check.enabled: true to opt in)
• 🎚️ Noise suppression — spectral gating via noisereduce, off by default (pip install 'whisper-local[noise]')
• 🩺 --selftest — one-command sanity check (mic, model, transcription, clipboard) — perfect for first-launch
• 🎯 Hotkey cheat sheet — whisper-local --cheat-sheet or tray menu — shows your current configured hotkeys at a glance
• 📦 --bundle-logs — zip up redacted logs + diagnostics for bug reports with one command
• 🌐 Local OpenAI-compatible API — whisper-local --serve exposes POST /v1/audio/transcriptions on localhost:7777 for Cursor, Open WebUI, anything that speaks OpenAI Whisper API
• 🛡️ Auto-recovery — silently reconnects when a USB mic is unplugged mid-recording
• 🛡️ Crash reports — uncaught errors write a self-contained dump to disk
• 🪟 System tray UI — model selection, mic selection, profile switch, diagnostics
• 🍎 Cross-platform — Windows 10+, macOS

🚀 Quick Start

Option 1 — Standalone Windows app (no Python needed)

1. Download whisper-local.exe from the latest release.
2. Double-click it. Windows SmartScreen will warn because the app isn't code-signed (a paid certificate) — click More info → Run anyway. The source is fully open if you'd rather audit first.
3. First launch takes a few minutes: Python is built in, so it installs the app's libraries from PyPI and downloads the Whisper model. Every launch after that is instant.

Every .exe is built by GitHub Actions from this repository and carries a signed build-provenance attestation. To confirm a download is genuine, run gh attestation verify whisper-local.exe --repo drajb/whisper-local, or compare its SHA-256 with the .sha256 file on the release page.

Option 2 — pipx / pip (Windows / macOS, Python 3.11–3.13)

pipx install whisper-local        # or: uv tool install whisper-local
whisper-local

Plain pip install whisper-local works too. pipx (or uv tool) gives the app its own environment, which keeps it clear of whatever else is installed; a PyTorch install in a shared environment, for example, is the usual reason a Python app takes a minute to start.

Option 3 — from source

git clone https://github.com/drajb/whisper-local.git
cd whisper-local
pip install -e .

Launch

First launch downloads the default base Whisper model (~141 MB) into your HuggingFace cache. After that, everything runs offline. (Prefer a smaller/faster download? Set whisper.model: tiny — ~75 MB.)

huggingface.co blocked at work? Common on corporate networks. Export the model from a machine that has internet and import it on the one that doesn't — no admin rights needed:

whisper-local --export-model            # machine WITH internet — writes to your Desktop
whisper-local --import-model "<the folder you copied over>"   # the offline machine

Pass a path to --export-model (a USB drive, say) to put it somewhere else. Network-share and internal-mirror setups are covered in docs/offline-models.md.

Use it

Verify everything works

whisper-local --doctor

Runs through Python version, dependencies, config validation, audio devices, model cache, hotkey backend, and recent log errors. Exit 0 = clean.

✍️ Smart editing

Say it naturally; it gets typed the way you'd have written it. Everything runs offline, with no LLM. One setting, Cleanup (Settings → Post-process, or postprocess.cleanup), picks how much gets tidied:

Any single toggle can still be pinned on or off in user_settings.yaml regardless of the level. Backtrack only acts when a cue ("actually", "I mean", "no wait", "sorry", …) is followed by a number, time, weekday or month that replaces an earlier one in the same sentence, so everyday prose like "I actually like it" is never changed.

Snippets are defined once:

postprocess:
  snippets:
    - trigger: my signature
      expansion: "Best,\nRohit"
    - trigger: my address          # mode: alone = only when it's the whole dictation
      expansion: "1 Main St, Dallas, TX 75201"
      mode: alone

Styles set capitalization and punctuation in one choice: formal (full sentences), casual (no trailing period), very_casual (all lowercase except acronyms and your own terms) and verbatim (no automatic capitals, periods or lists). Set postprocess.style globally, or style: on a rule in app_rules.yaml. The shipped rules make email formal, chat casual, and code editors and terminals verbatim.

🗣️ Voice Commands

Speak a trigger to run keyboard shortcuts, type snippets, or launch programs. Defined in:

• Windows: %APPDATA%\whisperkey\commands.yaml
• macOS: ~/.whisperkey/commands.yaml

commands:
  # Send a keyboard shortcut
  - trigger: "undo"
    hotkey: "ctrl+z"

  # Deliver pre-written text
  - trigger: "my email"
    type: "user@example.com"

  # Run a shell command
  - trigger: "open notepad"
    run: 'notepad.exe'

Edits hot-reload — no app restart required. See docs/voice-commands.md for the full guide.

⚠️ Voice commands with run: execute through your system shell with your user privileges. Only add commands you trust.

⚡ GPU Acceleration

On first launch, Whisper Local detects your GPU and offers one-press install of the required runtime libraries. Supports NVIDIA CUDA and AMD ROCm.

For manual setup or AMD RDNA 1, see docs/gpu-setup.md.

🌐 Local OpenAI-Compatible API

Whisper Local doubles as a drop-in local replacement for the OpenAI Whisper API — fully offline. Point any tool that speaks POST /v1/audio/transcriptions at it (Cursor, VS Code Continue, Open WebUI, n8n, custom scripts, anything else).

whisper-local --serve            # listens on http://127.0.0.1:7777
whisper-local --serve --serve-port 8080

# Drop-in compatible with the OpenAI SDK:
curl -X POST http://127.0.0.1:7777/v1/audio/transcriptions \
  -F file=@audio.wav -F model=whisper-1 -F response_format=text

Same Whisper model you use for dictation. Same GPU. No API key. No rate limit. No outgoing traffic.

🎛️ Profiles

Switch between presets from the tray icon → Profile:

Edit or add new profiles in %APPDATA%\whisperkey\profiles.yaml.

🪟 Per-app rules

Different apps want different behaviour. Whisper Local detects the foreground window before delivering each transcription and matches it against rules in %APPDATA%\whisperkey\app_rules.yaml:

rules:
  # Chat apps: send the message immediately
  - match: ["slack.exe", "discord.exe"]
    auto_send: true

  # Code editors: copy only, and keep it verbatim (no auto-caps or trailing period)
  - match: ["code.exe", "cursor.exe"]
    auto_paste: false
    capitalize_first: false
    ensure_punctuation: false

  # Password managers: skip delivery entirely
  - match: ["1password.exe", "bitwarden.exe"]
    suppress: true

A rule can override delivery (auto_send, auto_paste, suppress), Whisper context (initial_prompt, language, task), and formatting (capitalize_first, ensure_punctuation, strip_trailing_period, inline_formatting). Hot-reloads — edit and the next transcription picks it up.

🧹 Optional LLM cleanup

If you have Ollama running locally, Whisper Local can pipe each transcript through a small local model for punctuation and capitalisation polish. Off by default and fully local — set postprocess.ollama.enabled: true in user_settings.yaml to enable.

postprocess:
  capitalize_first: true        # works without Ollama
  ensure_punctuation: true      # works without Ollama
  strip_filler_words: true      # works without Ollama
  ollama:
    enabled: false              # set true to opt in
    endpoint: http://localhost:11434
    model: llama3.2
    timeout: 5

⚙️ Configuration

Local settings live at:

• Windows: %APPDATA%\whisperkey\user_settings.yaml
• macOS: ~/.whisperkey/user_settings.yaml

Delete the file and restart to reset to defaults. Highlights:

Full reference: config.defaults.yaml.

🛠️ CLI Reference

whisper-local                      # Run the app (or use `wl`)
whisper-local --setup              # Interactive setup wizard (model, mode, mic)
whisper-local --doctor             # Run diagnostics
whisper-local --stats              # Transcription history & time saved
whisper-local --version            # Print version
whisper-local --quit               # Stop the running instance
whisper-local --export-settings DIR        # Back up user_settings + commands
whisper-local --import-settings DIR        # Restore from a backup
whisper-local --export-transcripts FILE    # Dump history (.txt/.md/.csv)
whisper-local --import-vocab FOLDER        # Mine a folder for hotwords
whisper-local --settings           # Open the settings GUI (no YAML editing required)
whisper-local --history            # Browse and search transcript history
whisper-local --cheat-sheet        # Show your currently configured hotkeys
whisper-local --selftest           # Run an automated self-test (mic, model, transcription)
whisper-local --bundle-logs        # Create a redacted diagnostic zip for bug reports
whisper-local --serve              # Run a local OpenAI-compatible Whisper API on :7777
whisper-local --enable-autostart   # Launch automatically at login (--disable-autostart to undo)
whisper-local --test               # Run a separate test instance (own mutex)

Launching while an instance is already running takes over — the old one is replaced cleanly, no manual quit needed.

🏗️ How it works

┌─────────────────────┐  ┌──────────────────┐  ┌─────────────────────┐
│  global-hotkeys /   │  │   sounddevice +  │  │  faster-whisper /   │
│  NSEvent (macOS)    │─▶│  500ms ring buf  │─▶│  ctranslate2 (GPU)  │
└─────────────────────┘  │  + TEN VAD       │  └──────────┬──────────┘
                         └──────────────────┘             │
                                                          ▼
                         ┌──────────────────┐  ┌─────────────────────┐
                         │  Voice command   │◀─│  Transcribed text   │
                         │  matcher         │  │                     │
                         └──────────────────┘  └──────────┬──────────┘
                                                          ▼
                                                ┌─────────────────────┐
                                                │  ctypes SendInput / │
                                                │  Quartz CGEvent     │
                                                │  → cursor           │
                                                └─────────────────────┘

🔒 Privacy pledge

Whisper Local makes the following network calls and no others:

1. First launch only: downloads the Whisper model from huggingface.co into your local cache.
2. GPU onboarding (opt-in): if you accept the GPU setup prompt, pip install pulls CUDA / ROCm runtime packages from PyPI / repo.radeon.com.
3. Update check (opt-in, off by default): once a day asks api.github.com for the latest release tag. Nothing but the app version leaves the machine.
4. Ollama (opt-in, off by default): text goes to whatever Ollama endpoint you configure, localhost unless you change it.

During dictation, zero network traffic. Every entry point is in onboarding.py, update_check.py and text_postprocess.py, and each is gated behind an explicit setting or prompt. Search the source for urllib if you'd rather check.

📦 Tech stack

faster-whisper · ctranslate2 · sounddevice · ten-vad · pyperclip · pystray · ruamel.yaml · playsound3 Windows-only: global-hotkeys · pywin32 · ctypes SendInput macOS-only: pyobjc-framework-Quartz · pyobjc-framework-ApplicationServices

📚 Documentation

• docs/troubleshooting.md — symptom → cause → fix table for the most common issues
• docs/faq.md — privacy, comparisons (Whisper.cpp / WSR / Wispr Flow / Dragon), model picks, GPU notes
• docs/distribution.md — how releases work (standalone .exe, PyPI, winget, Homebrew) and how to ship one
• docs/voice-commands.md — the full voice command DSL
• docs/gpu-setup.md — manual GPU setup for NVIDIA / AMD
• CHANGELOG.md — release notes

Hit a wall? Run whisper-local --doctor or whisper-local --selftest first — they catch 90% of issues.

🤝 Contributing

Contributions of all kinds are welcome — bug fixes, new features, docs improvements, or just opening an issue with a clear reproduction. This project is maintained on a best-effort basis with no SLA; please be patient with response times.

git clone https://github.com/drajb/whisper-local.git
pip install -e .
python -m unittest tests.test_smoke   # smoke suite — should report OK

See CONTRIBUTING.md for the full guide and CODE_OF_CONDUCT.md for community standards. By contributing you agree your code will be MIT licensed. Found a security issue? See SECURITY.md — please don't open a public issue.

Good first issues are tagged here. The full credit list is in AUTHORS.md.

☕ Support

Whisper Local is free and always will be. If it saves you time or a monthly subscription, consider starring the repo and sharing it with people who'd find it useful — it helps the project grow.

No pressure. Starring the repo and sharing it with people who'd find it useful is just as helpful.

🙏 Credit

Whisper Local builds on a lot of excellent open-source work. The full list is in AUTHORS.md.

MIT licensed; see LICENSE.