Troubleshooting

Most VoiceWiz problems fall into four buckets: microphone access, model setup, transcription quality, and clipboard pasting. Here are the fixes that solve the majority of cases.

No audio detected

• Check microphone permissions in your operating system settings — the OS may be blocking access.
• Verify the correct input device is selected.
• Check audio levels in the debug logs (see enabling debug mode below).

Transcription fails or errors

• Ensure a speech model is downloaded — check the Models screen in the Control Panel.
• If using a local backend, verify the whisper.cpp or sherpa-onnx binaries are present (they're bundled with the installer).
• For cloud backends, verify your API key and that the provider is reachable.

Empty or wrong transcriptions

• Speak a little longer — very short clips can be dropped by voice-activity detection.
• Add specialized names and terms to the Dictionary.
• Try a larger model (Base → Small → Turbo) if accuracy is consistently low.

Pasting doesn't work

• macOS — grant Accessibility permission so VoiceWiz can simulate a paste.
• Windows — pasting uses built-in fallbacks; some elevated (admin) windows block simulated input.
• Linux (X11) — the fast paste path uses XTest, with xdotool as a fallback.
• Linux (Wayland) — pasting depends on your compositor; ydotool or wtype support is needed. GNOME and Hyprland hotkeys are supported through their respective integrations.

Model downloads stall

Model files are large (up to ~3 GB). If a download stalls, retry from the Models screen — downloads resume where possible.

Enabling debug mode

# in the .env file next to the app, or as an environment variable
OPENWHISPR_LOG_LEVEL=debug

Debug logs include audio levels, backend selection, and pipeline decisions — useful for pinpointing where a dictation went wrong.

Still stuck?

Open an issue on the issue tracker with your platform, VoiceWiz version, and relevant debug output — or write to rafa@rafa9-labs.com.