The useful part
What it does
Whisper STT is a small Python desktop app built on faster-whisper, the fast CTranslate2 port of OpenAI Whisper. Hold Ctrl + Windows (Ctrl + Cmd on macOS) to record, release to transcribe. The text is pasted straight into the active window, or just copied to the clipboard if you prefer to paste it yourself.
Under the hood a global keyboard hook watches the hotkey, audio is captured at 16 kHz while the keys are held, silence is trimmed off the ends, and the clip is transcribed on a worker thread so typing is never blocked. The model loads once (float16 on CUDA, int8 on CPU) and falls back to CPU automatically if the GPU is not usable. Everything runs locally: no account, no API key, no network traffic beyond the one-time model download.
- 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.
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 ↗