WinSTTCommand-Line and Headless Transcription
Launch flags, headless file transcription and benchmarking, and developer-only STT/TTS harnesses.
WinSTT is a single native executable. It supports desktop launch controls, actions forwarded to an already-running instance, and a headless file-transcription path for scripts and reproducible benchmarks.
WinSTT [OPTIONS]Most config lives in the UI, not the CLI
Interactive dictation settings still live in the Settings UI. Headless file transcription selects its model and device explicitly and does not change those persisted settings.
App flags
| Flag | What it does |
|---|---|
| --start-hidden | Start with the main pill window hidden (tray only). |
| --no-tray | Don't create the system-tray icon. |
| --toggle-transcription | Toggle dictation on/off. Forwarded to the running instance. |
| --toggle-post-process | Toggle dictation with LLM post-processing on/off. Forwarded to the running instance. |
| --cancel | Cancel the current operation. Forwarded to the running instance. |
| --debug | Enable verbose logging. |
| -h, --help | Print help and exit. |
The forwarded flags drive shortcuts
WinSTT runs single-instance. Launching the exe again with --toggle-transcription,
--toggle-post-process, or --cancel doesn't open a second window — it hands the flag to the
instance that's already running. Bind a global shortcut (or a stream-deck button, or a script)
to WinSTT.exe --toggle-transcription to start/stop dictation from anywhere.
Headless file transcription
--transcribe-file exits after printing the transcript and timing data. It initializes only the
media decoder, model resolver, ONNX Runtime sessions, and (for long audio) the segmentation VAD.
It does not create the Tauri app, webviews, tray, microphone capture, clipboard/paste path,
global shortcuts, or desktop background managers.
WinSTT --transcribe-file recording.wav
WinSTT --transcribe-file interview.mp3 --model small --device cpu
WinSTT --transcribe-file sample.flac --device directml --warm --repeat 3 --json
WinSTT --transcribe-file sample.wav --cold --repeat 3| Flag | What it does |
|---|---|
| --transcribe-file <PATH> | Decode and transcribe WAV, MP3, MP4, AAC, FLAC, OGG, or Vorbis media, then exit. |
| --model <ID> | Select an embedded catalog id. Defaults to tiny.en. |
| --device <DEVICE> | Select auto, cpu, directml, cuda, coreml, rocm, openvino, or webgpu. Uncompiled providers fail explicitly. |
| --repeat <N> | Run N measured decode passes. The loaded engine is reused unless --cold is set. |
| --warm | Run the production-style one-second-silence kernel warmup after each model load and report its duration. |
| --cold | Destroy and rebuild ONNX sessions before every repeated pass. This measures provider/kernel-cold launches; it does not flush the operating-system disk cache. |
| --json | Emit one machine-readable result containing transcript and all measurements. |
| --list-models | Print catalog ids, engine families, repositories, parameter counts, and quantizations, then exit. |
| --list-devices | Print the execution providers compiled into this build and the provider selected by auto, then exit. |
The resolver checks the Hugging Face cache first. If the requested model is absent, the headless route downloads it before constructing ONNX sessions. Quantization uses the same RAM/VRAM-aware automatic policy and the same per-engine provider overrides as desktop dictation.
Benchmark output
Each run reports session load time, optional warmup time, decode time, real-time factor (RTF = decode seconds / audio seconds), active ONNX execution providers, current resident memory, and the
transcript. The top-level result also reports media-decode time, model-resolution time, audio
duration, selected model/quantization/device, and peak resident memory. On Windows, peak resident
memory comes from the operating system's process peak working set; other platforms report the
highest sampled resident set.
Use a release build for performance measurements
Debug builds include compiler instrumentation and are not representative. Run benchmarks against
a packaged build or cargo run --release -- --transcribe-file ... from src-tauri/.
Developer Benchmark Binaries
Developer-only — not in the shipped app
These cargo run --example harnesses live in src-tauri/examples/ and are driven by
environment variables. You only need them if you're hacking on the inference path. They are
used to benchmark and de-risk the STT/TTS engines during the port.
stt_decode_bench — STT decode benchmark
Decodes a fixed 16 kHz JFK sample through the unified ort engine and prints the transcript +
timing, so you can A/B a model, quantization, or execution provider.
cargo run --release --example stt_decode_bench # whisper-tiny.en, CPU
cargo run --release --example stt_decode_bench -- <hf_snapshot_dir> [n_mels] [lang]
STT_BENCH_PROVIDER=dml cargo run --release --example stt_decode_bench # measure the DirectML path| Env var | What it does |
|---|---|
| STT_BENCH_PROVIDER | Execution provider: cpu (default), dml, or cuda. |
| STT_BENCH_QUANT | Override the resolved quantization (e.g. int8, fp16) to A/B precisions. |
| STT_BENCH_CACHE_ONLY | Resolve from the on-disk HF cache only (no network). |
| HF_HUB_CACHE / HF_HOME | Where to find / download model snapshots. |
kokoro_tts_bench — Kokoro TTS benchmark
Times the shipped Kokoro synthesis path (warm/cold) on CPU or DirectML.
cargo run --release --example kokoro_tts_bench
KOKORO_TTS_BENCH_DEVICE=dml cargo run --release --example kokoro_tts_bench # measure the GPU path| Env var | What it does |
|---|---|
| KOKORO_TTS_BENCH_DEVICE | Execution device: cpu (default) or dml. |
| WINSTT_KOKORO_DIR | Override the model / voicepack location. |
tts_engine_bench — exploratory TTS engines
Runs the experimental TTS engines (kitten / piper / supertonic / chatterbox) that are not
in the shipped app, loading their weights from .tts-cache/<engine>/.
rem from the repo root — wraps the MSVC env + redirects output to %TEMP%\winstt-tts-engine-bench.log
tools\windows\tts-engine-bench.bat <engine> [voice] [text]| Env var | What it does |
|---|---|
| WINSTT_TTS_CACHE | Override the cache root that holds .tts-cache/<engine>/. |
| ESPEAK_NG_LIBRARY | Path to the espeak-ng DLL (auto-resolved to the bundled copy if unset). |
dictation_prompt_cases — dictation prompt fixtures
Writes the exact dictation system/user prompts used by the app for a small set of vocabulary and replacement-pair cases. The companion runner sends them to a local Ollama model and verifies the expected terms.
cd src-tauri
cargo run --example dictation_prompt_cases > cases.json
python ../tools/bench/run_dictation_cases.py cases.json [model]Related
Settings UI
Where the model, language, device, VAD, wake words, and TTS actually live.
Choose a model
Model, device, quantization, and realtime — set from the UI.
Backend Architecture
How the benchmarked engines are loaded and run.
Dev Environment Setup
Toolchain, build helpers, and running the app from source.
Compute & Quantization
How WinSTT picks an ONNX Runtime execution provider and what the fp16 / int8 / q4 quantization labels mean for size, speed, and accuracy.
Troubleshooting
Symptom-to-fix table for the issues people actually hit — blank window, slow transcription, GPU fallback, a stuck mic, missing playback audio, failed downloads, blocked hotkeys, and Listen-mode Bluetooth.