A lightweight, fully offline hold-to-record voice-to-text app for Windows
(macOS support included; Linux untested but should work).

Sits in your system tray. Hold Right Alt, speak, release → transcribed text
is pasted into whatever window is focused.

Powered by faster-whisper — no API
keys, no cloud, everything runs locally.

🌐 Project page: marksoft.ro/stt

Pre-built binaries for the latest release — no Python install required. Or grab them from marksoft.ro/stt.

Browse every version on the Releases page.

First launch downloads the Whisper base model (~150 MB) into your HuggingFace cache. Everything after that is fully offline.

On first launch Windows shows "Windows protected your PC — unrecognized app." This happens because the exe isn't code-signed (signing certs cost ~100ドル–500/yr for an open-source hobby project, so for now it's unsigned).

To run it anyway — once per version:

1. In the blue SmartScreen dialog, click More info (under the big message).
2. A new Run anyway button appears in the bottom-right. Click it.
3. Windows remembers your choice; subsequent launches skip the dialog.

The exe is built in public on GitHub Actions — you can inspect every build step at the Actions tab and compute the checksum yourself against what Actions produced.

pip install -r requirements.txt

Windows note: if you see a CTranslate2 / ONNX error, make sure you have the
Microsoft Visual C++ Redistributable (x64) installed.

# Windows – must be run as Administrator for global hotkeys
python stt.py
# macOS
python3 stt.py

The app will:

1. Start and appear in the system tray (blue microphone icon)
2. Download the base Whisper model on first run (~150 MB, one-time)
3. Turn amber while loading the model
4. Turn blue (idle) once ready

• Hotkey – shows the currently configured hotkey (read-only)
• Switch Model → base / small – hot-switch the Whisper model (downloads if needed)
• Quit – exit the app

{
 "model": "base",
 "hotkey": "right alt",
 "language": "en",
 "sample_rate": 16000,
 "channels": 1,
 "beam_size": 5
}

To use medium or large-v3, add them to the Switch Model sub-menu in
_build_menu() inside stt.py.

pip install pyinstaller==6.10.0

pyinstaller \
 --onefile \
 --noconsole \
 --name stt \
 --icon stt.ico \
 --add-data "config.json;." \
 stt.py

Remove --icon stt.ico if you don't have an icon file.
The --noconsole flag suppresses the console window on Windows.

The executable will be at dist\stt.exe. Copy config.json next to it
(it will be created automatically on first run if absent).

pyinstaller \
 --onefile \
 --windowed \
 --name STT \
 --add-data "config.json:." \
 stt.py

Bundle is at dist/STT.app.
You may need to sign it: codesign --deep --force --sign - dist/STT.app

stt.py detects whether it is running as a PyInstaller bundle via
sys._MEIPASS / sys.frozen and resolves config.json relative to the
executable (not the bundle's temp directory) so settings persist between
runs.

Pre-built binaries for Windows, macOS, and Linux are produced automatically by .github/workflows/release.yml whenever a v* tag is pushed.

# 1. Tag the commit you want to ship
git tag v0.1.0
git push origin v0.1.0
# 2. GitHub Actions builds STT on windows-latest / macos-latest / ubuntu-latest
# and attaches the three binaries to a new release for that tag.
# Watch progress: https://github.com/NYOGamesCOM/STT/actions

Resulting release assets:

The workflow can also be triggered manually from the Actions tab (Run workflow → enter the tag name).

GitHub exposes a releases/latest/download/<asset> redirect that always points to the newest tagged release — use these on your website so links never go stale:

https://github.com/NYOGamesCOM/STT/releases/latest/download/STT-windows-x64.exe
https://github.com/NYOGamesCOM/STT/releases/latest/download/STT-macos.zip
https://github.com/NYOGamesCOM/STT/releases/latest/download/STT-linux-x64

Version-pinned URLs are also available at releases/download/v0.1.0/<asset> if you need reproducibility.

We publish reproducible transcription benchmarks — latency, real-time factor, and word-error rate — for the tiny, base, and small models on CPU with int8 quantisation. The benchmark is a regular Python script; anyone can record their own reference clips and run it. See BENCHMARKS.md for methodology, how to run it, and results.

• NYOGamesCOM — creator & maintainer
• Claude (Anthropic Opus 4.7) — overlay indicator, history UI, performance pass, build/release plumbing
  • assisted by Cursor — editor & pair-programming companion

Built with ❤️ by MarkSoft.

MIT – do whatever you like.