The useful part
What it does
Whisper STT is a lightweight Python desktop app built on faster-whisper, the CTranslate2-powered implementation of OpenAI Whisper. Hold Ctrl + Windows (Ctrl + Cmd on macOS) to record, then release to transcribe. The result is pasted into the active window or copied to the clipboard.
Under the hood, a global keyboard hook monitors the hotkey while audio is captured at 16 kHz. Leading and trailing silence is trimmed before transcription runs on a worker thread, keeping the keyboard hook responsive. The model loads once, uses float16 on CUDA or int8 on CPU, and falls back to CPU when a compatible GPU is unavailable.
Everything runs locally—no account, API key, or audio upload. The only network access required is the initial download of each Whisper model.
- Python 3.9+, runs from source on Windows, macOS and Linux; a prebuilt Windows exe (PyInstaller, CPU only) is attached to each release
- Whisper models from
tinytolarge-v3, auto-detected or forced language, adjustable beam size - CUDA and CPU with automatic detection and fallback, no PyTorch needed
- Push-to-talk hotkey (Ctrl + Windows / Ctrl + Cmd), plus a start/stop toggle in the tray / menu-bar icon
- Paste mode or clipboard-only mode, switchable at runtime
- Transcript history in the tray, rotating log file, per-user model directory
Inspect and adapt
The code
python main.py # model=small, auto GPU, paste mode, auto language
python main.py --model medium # bigger model, auto GPU
python main.py --cpu --model small # force CPU
python main.py --mode clipboard # copy only, no auto-paste
python main.py --lang hr # force a language
python main.py --restore-clipboard # put the old clipboard back after pastingFrom zero to working
Install & use
- 01
Windows, no Python: grab the zip from the Releases page on GitHub, unzip it and run whisper-stt-devexus.exe. Only the tray icon appears; the first run downloads the model.
- 02
macOS and Linux: there is no prebuilt binary yet, run it from source with Python 3.9+ (steps below). Start it with sudo, the global keyboard hook needs it.
- 03
From source: clone the repository, optionally create a virtual environment, then run pip install -r requirements.txt.
- 04
Start it with python main.py. Use --model, --cpu, --mode and --lang to change the defaults; the model path and log path are printed at startup.
- 05
For GPU transcription install the CUDA toolkit (11.8 or 12.1+) and cuDNN; faster-whisper picks it up automatically.
- 06
macOS only: grant Accessibility permission to Terminal (or your Python) in System Settings so the hotkey hook and auto-paste work.
- 07
Hold Ctrl + Windows (Ctrl + Cmd on macOS), speak, release. Recent transcripts are in the tray / menu bar menu.
Know before using
Caveats & FAQ
- The prebuilt binary is Windows only (CPU, about 250 MB). CI does not build a macOS or Linux bundle yet; both platforms are fully supported from source.
- Build a CUDA-enabled Windows exe yourself with WHISPER_STT_BUILD_CUDA=1 (adds roughly 1.6 GB).
- Linux and macOS need root/sudo because the keyboard package installs a global hook; the app exits with a clear error otherwise. macOS also asks for Accessibility permission.
- Models are cached per user: tiny is about 75 MB, large-v3 about 3 GB. Override the location with --model-dir or WHISPER_STT_MODEL_DIR.
- A recording started from the tray menu is only stopped from the tray menu; the hotkey does not end it.
No. Recording, transcription and clipboard handling all happen locally. The only network access is the one-time model download.
Yes. Clone the repo, pip install -r requirements.txt and run sudo python main.py. The hotkey is Ctrl + Cmd, the icon sits in the menu bar, and models go to ~/Library/Application Support/WhisperSTT/models. A prebuilt .app is not on CI yet.
Yes. The key names are plain sets in main.py (WIN_NAMES and the ctrl check); the README shows how to switch to something like Alt + Space.
small is the default and is a good balance on CPU. medium or large-v3 are noticeably better for accented speech or Croatian, but you will want a GPU for them.
The contract
Options & API
Options
| Name | Type | Default | Description |
|---|---|---|---|
WHISPER_STT_MODEL_DIR | env var | Overrides the model directory, same as --model-dir. | |
WHISPER_STT_BUILD_CUDA | env var | Set to 1 before building the Windows exe to bundle the CUDA libraries (adds about 1.6 GB). |
Flags
| Name | Type | Default | Description |
|---|---|---|---|
--model | string | small | Whisper model to load: tiny, base, small, medium or large-v3. |
--cpu | switch | off | Force CPU transcription instead of auto-detecting a GPU. |
--mode | paste | clipboard | paste | Paste the transcript into the active window, or only copy it to the clipboard. |
--lang | string | auto | Force a language code like en or hr instead of auto-detection. |
--model-dir | path | per-user data dir | Where models are stored and loaded from. |
--min-duration | number | 0.25 | Ignore recordings shorter than this many seconds. |
--no-trim | switch | off | Skip trimming leading and trailing silence before transcribing. |
--silence-thresh | number | 1e-4 | Amplitude below which audio counts as silence when trimming. |
--beam-size | number | 5 | Whisper beam size; higher is more accurate but slower. |
--restore-clipboard | switch | off | In paste mode, put the previous clipboard content back after pasting. |
--debug | switch | off | Show warnings and debug output. |
--version | Print the version and exit. |
Release notes
Changelog
- v1.0.3
Exe runs without a console window and logs to a file; CPU-only build no longer tries CUDA on NVIDIA machines; reworked tray menu with status, start/stop, transcript history and output switch; new icon.
- v1.0.2
Per-user model directory, new tuning flags (--min-duration, --no-trim, --silence-thresh, --beam-size, --restore-clipboard), proper logging, standalone Windows build from CI, renamed to Whisper STT.
- v1.0.1
Tray Exit closes the app, transcription moved to a worker thread, macOS tray fixed to run on the main thread, beam size 10 to 5 for ~2x CPU speed, NVIDIA DLL path fix.
- v1.0.0
First version: push-to-talk hotkey, faster-whisper, tray icon, paste and clipboard modes.
Why it exists
Era & lineage
I wanted dictation that works in any window, does not upload audio anywhere and does not need a subscription. Whisper made the model side trivial; the real work was the desktop plumbing: a global keyboard hook, a tray icon that behaves on Windows, macOS and Linux (Cocoa insists the tray lives on the main thread), transcription off the hook thread so keys are never blocked, and a PyInstaller build that finds its CUDA DLLs or falls back to CPU cleanly.
Feedback
Comments
No comments yet. Found a bug or used it somewhere interesting? Say so below.
Prefer an issue tracker? Report it on GitHub instead ↗