WinSTTTroubleshooting
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.
Match your symptom in the table below, then jump to the section for the full fix. Almost every reported issue resolves here; when one doesn't, Debug Mode gathers the logs you'll attach to a bug report.
Attach a diagnostic bundle to every report
Settings → About → Diagnostics → Save Diagnostic Bundle writes one zip with the available app logs, system info, and redacted diagnostics. It shortcuts at least three rounds of back-and-forth — see Debug Mode.
Symptom → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| Window flashes and closes | Native backend startup failed or a runtime dependency is missing | Install VC++ x64; check logs — see Blank or black window |
| Main window opens but stays black | Vite chunk-split regression (React / Base UI) | Re-pull main — see Blank or black window |
| Live preview lags 5+ seconds | Server fell back to CPU; realtime model too big | Confirm the accelerator, pick a smaller realtime model — see Transcription is slow |
| First turn after launch is slow | Lazy model load on first transcription | Expected once; later turns are sub-second |
| GPU present but server uses CPU | GPU not D3D12-capable, or incomplete CUDA wheels | Read the accelerator line — see GPU fallback |
| Mic missing / overlay stuck recording | Device enumerated once at boot; phantom device state | Restart the server; run Fix-Audio.ps1 — see Mic stuck |
| “Reconnecting…” forever | Engine failed during warmup / session create | Check the diagnostic logs; switch quant or device — see Reconnecting forever |
| No audio when playing back a recording | Recording muted at OS level, or wrong output device | Unmute WinSTT; pick the right playback device — see No audio on playback |
| Model download stalls at 0% | huggingface.co blocked by proxy / firewall | Set HTTPS_PROXY or install manually — see Model downloads fail |
| PTT hotkey never fires | Low-level hooks blocked by group policy | Use Toggle mode or run as Admin — see Hotkeys blocked |
| Listen mode sounds mono / muffled | Bluetooth headset in mono headset profile | Switch to A2DP or a wired/loopback device — see Bluetooth mono in Listen |
Blank or black window
Window flashes and disappears (packaged build)
The native backend failed during startup. Open the logs folder and inspect the latest log — the last lines name the cause, usually a missing Visual C++ Redistributable or a virus-scanner quarantine. Then:
- Install the latest VC++ x64 redistributable.
- Whitelist the WinSTT executable and its bundled native libraries in your antivirus.
- Run the installer as Administrator if
%APPDATA%/WinSTT/is on a path your user can't write to.
If the window opens but stays black while dev mode looks fine, open the renderer console (Settings → Advanced → Open DevTools). The tell is Cannot read properties of undefined (reading 'useLayoutEffect') — a Vite chunk-split regression that separates @base-ui/react from react / react-dom into a circular ESM import.
Fix for the black window
Re-pull main. vite.config.ts keeps @base-ui/react and React in the same manualChunks group; the black screen returns only if that grouping regresses. If you're on a release build, update to the latest installer.
In dev mode, a blank window usually means the renderer dev server did not start or Tauri is pointing at the wrong URL. Launch through tools\windows\tauri-dev.ps1 and confirm Vite is serving port 1420.
Transcription is slow
The first transcription after a fresh launch or a model swap pays the model-load cost — that one is expected. If every turn is slow, the server is almost always running on the wrong device.
Confirm which device the backend picked
Launch with
--debugand read the first second of the app log for a line likeAccelerator: directmlorAccelerator: cpu.If it says cpu but you want GPU
On Windows, a DirectML build that reports
cpumeans your GPU isn't D3D12-capable — see GPU fallback. On other platforms, the current public alpha may be CPU-only unless you are running a custom accelerator build.Shrink the live-preview model
Pick a smaller realtime model in Settings → Model.
whisper-tiny.enruns roughly 4× faster thanwhisper-base.enand is fine for the preview; the main model still produces the accurate final text.Right-size the main model
Whisper
large-v3-turboon a 4–6 GB GPU spills into CPU memory — drop towhisper-smallorwhisper-medium. On CPU, quantize toq4(small quality loss ontiny/base, larger onlarge).
Smart Endpoint adds ~50 ms per turn
The DistilBERT turn-boundary classifier costs about 50 ms per utterance. If you don't need automatic turn detection, turn it off under Settings → Quality.
GPU fallback
WinSTT's accelerator auto-degrades to CPU whenever the requested GPU path isn't viable. The DirectML build does this silently and safely, but it means a slow session can look like a software bug when it's really a hardware or driver mismatch.
| You see | Why | What to do |
|---|---|---|
| DirectML build logs Accelerator: cpu | GPU isn't DirectX 12-capable | Update the GPU driver; otherwise accept CPU speeds or use a smaller model |
| NVIDIA GPU on Windows, still on CPU | The Windows build uses DirectML by default, not CUDA | Use the DirectML path or a custom CUDA build |
| GPU works then drops to CPU mid-session | ORT session-create failure on a quant (e.g. Canary + int8 on DML) | Switch quantization or device in Settings → Model |
The released Windows packages ship no CUDA — DirectML is faster and much lighter on this workload. CUDA is a development-only path for custom builds.
Mic stuck or missing
PortAudio enumerates input devices once when the server starts. A mic plugged in afterwards won't appear, and a device left in a phantom state (CM_PROB_PHANTOM) blocks enumeration entirely. The overlay can also appear stuck "recording" if the device handle never returns audio.
Restart WinSTT
Quit and relaunch WinSTT. This re-enumerates devices and clears most stuck-recording states.
Re-pick the device
Open the input-device picker and select your microphone by name. Some headsets (Logitech, Razer) expose a virtual "Stereo Mix" that maps to your speakers rather than the mic.
Clear phantom device states
From an elevated PowerShell, run
Fix-Audio.ps1— it bouncesAudiosrv,AudioEndpointBuilder, and the Bluetooth user service, clearing theCM_PROB_PHANTOMstates that block enumeration.Recalibrate VAD if the mic is selected but silent
In Settings → Audio → VAD calibration, recalibrate in a quiet room. If the noise floor sits above your speaking volume, voice-activity detection never fires and nothing is captured.
Reconnecting forever
A renderer stuck on "Reconnecting…" means the backend engine failed — usually during warmup or ONNX session create, not from a network fault. Open the diagnostic logs.
| Log signature | Cause | Fix |
|---|---|---|
| Hangs right after “loading Silero VAD” | VAD loaded on a GPU EP and deadlocked session create | Update to the latest build — VAD is pinned to CPU |
| Reshape “node_view” RuntimeException | Canary + DirectML + int8 kernel crash | Switch quantization or device in Settings → Model |
| “Recorder does not have method …” | Warmup failed before the recorder was installed | Update; the recorder now constructs before warmup |
No audio on playback
Saved recordings play back from the Transcription History dashboard. Silence on playback is almost always an output-routing issue, not a corrupt file.
- Check the OS mixer. Make sure WinSTT isn't muted for output — app-level mutes can survive restarts.
- Pick the right playback device. If your default output changed (a headset disconnected, a monitor's speakers took over), the OS may be routing playback somewhere you can't hear.
- Confirm the recording was actually saved. Recordings only have audio when
recordingRetentionisn't set so the file was never written — check that the row has a play button rather than a transcript-only entry.
Retention “Never” means keep forever
In Settings → History, recordingRetention: never means keep recordings forever, not "don't save." Recordings are always saved; retention only governs cleanup of old ones.
Model downloads fail
Models live on the Hugging Face hub. Behind a corporate proxy or a country block, the download can silently hang.
| Symptom | Cause | Fix |
|---|---|---|
| Stalls at 0% / times out | huggingface.co unreachable | Set HTTPS_PROXY, or install manually |
| Finishes but shows “Unavailable” | Killed mid-download left a .incomplete marker | Re-trigger the download — it resumes from partial bytes |
| 404 / 403 on the TTS pack | Asset renamed in a release rotation | Open an issue with the URL the server tried |
| Custom folder not in picker | Incomplete ONNX export | Add the missing files — see Custom Models |
For blocked networks, set a proxy before launching — WinSTT inherits your user environment, so setx HTTPS_PROXY http://your.proxy:8080 works:
setx HTTPS_PROXY "http://your.proxy:8080"Or skip the network entirely with Manual Model Install — the URLs are public and resumable.
Don't set a token for the TTS pack
The TTS pack is on the public winstt-assets repo. Setting a GITHUB_TOKEN that lacks read access to that repo causes a 403. Tokenless urllib works fine — let WinSTT use its built-in unauthenticated client.
A custom model folder must contain a complete onnx-community / Optimum export: encoder.onnx (or encoder_model.onnx), decoder_model.onnx (or decoder_model_merged.onnx), a HuggingFace tokenizer.json, and a config.json with a non-empty model_type. Partial folders show greyed-out in the picker with a tooltip naming the missing file — see Custom Models.
Hotkeys blocked
Every WinSTT hotkey except re-paste uses the passive keyboard listener path. Re-paste (general.repasteHotkey, default LCtrlLShiftV) is the only one registered as an exclusive global shortcut.
| Symptom | Cause | Fix |
|---|---|---|
| PTT never fires on a corporate box | Group policy blocks low-level keyboard hooks | Switch to Toggle mode (single key event, no hook) or run as Admin |
| Hotkey works for some apps, not others | Antivirus behavior-blocker flagging the global hook | Whitelist WinSTT's process in your AV |
| Re-paste does nothing | Another app already registered the chord | Change it in Settings → Hotkey → Re-paste hotkey |
| Paste lands in the wrong window | Focus drifted between hotkey release and paste | Enable Smart Endpoint so the turn ends faster; confirm focus first |
Locked-down boxes can disable PTT entirely
On machines where group policy blocks low-level keyboard hooks, Push-to-Talk won't work at all. Toggle uses a single key event instead of a held hook and is the reliable fallback. Running WinSTT as Administrator also restores the hook on some configurations.
For terminals, VMs, or RDP where the host clipboard isn't reachable, switch Settings → Advanced → Paste via SendInput instead of the default clipboard paste.
Bluetooth mono in Listen
Listen mode transcribes a loopback of your system audio — your microphone capture won't help. The common failure is a Bluetooth headset that drops into the mono 16 kHz headset profile when it has an active mic, which makes Listen-mode audio sound thin and transcribe poorly.
Force A2DP (high-quality stereo) on the headset
In Windows Sound settings, ensure the headset is using its stereo (A2DP) profile, not the hands-free headset profile. Disconnecting the headset's microphone often flips it back to A2DP.
Or route through a virtual loopback cable
Install VB-Audio Virtual Cable, set CABLE Output (VB-Audio) as the loopback device in Settings → Audio → Loopback, and route the source app (Teams, Zoom, OBS) into CABLE Input.
Prefer a wired headset for meetings
Wired headsets and VB-Cable avoid the Bluetooth profile-switch entirely and are the most reliable for sustained Listen-mode capture.
Windows “Listen to this device” is flaky on Bluetooth
The OS-level loopback works on wired devices but is unreliable over Bluetooth. VB-Cable is the dependable path for Listen mode.
Still stuck?
Capture a diagnostic bundle
Settings → About → Diagnostics → Save Diagnostic Bundle
Reproduce with --debug
So the app logs carry the verbose trace — see Debug Mode.
File a bug with the bundle attached
At github.com/dahshury/WinSTT/issues. Feature ideas and questions live in Discussions.
Related
Debug Mode
Gather the app logs and a redacted diagnostic bundle for bug reports.
Manual Model Install
Offline, proxy, and firewalled installs of the built-in models.
Recording modes
Push-to-talk, toggle, listen, and wake-word — and when each one applies.
FAQ
Short answers to the questions that come up before a bug report.