Back to guide
🔧 Advanced

Common issues

2026-02-05 · 4 min

Microphone not detected

Make sure your microphone is plugged in and selected as the default device in your system settings.

  1. 1Check the physical connection of the microphone
  2. 2Open your OS audio settings and select the correct device
  3. 3Restart VoxWave
  4. 4Go to Settings > Audio and select your microphone

Transcription is slow

In local mode, the first transcription loads the Whisper model into memory (~5s). Subsequent ones are much faster.

💡

Switch to cloud mode (Pro) for transcription in < 500ms. Hybrid mode switches automatically.

Local mode: wrong language or poor accuracy

In local mode, VoxWave uses the Whisper 'small' model running on your CPU. Auto-detect works well in cloud mode (Groq), but the local model is less accurate at detecting language — especially on short sentences or in noisy environments.

  1. 1Open Settings > General
  2. 2Set your dictation language manually instead of 'Auto-detect'
  3. 3This tells Whisper exactly which language to expect, dramatically improving accuracy
💡

This is the single most impactful tip for local mode. Setting the language manually can improve transcription accuracy by 30-50% compared to auto-detect.

If you build from source, you can also switch to a larger Whisper model for better results (at the cost of speed):

# In config.yaml, change:
# whisper:
#   model: small    → try 'medium' for better accuracy
#   language: fr    → set your language explicitly

Text is not being injected

VoxWave uses Ctrl+V to inject text. Make sure the target application accepts pasting.

  • Some security apps block simulated keyboard shortcuts
  • Protected fields (passwords) do not accept pasting
  • Try pasting manually (Ctrl+V) to verify

Linux-specific issues

If VoxWave doesn't start or behaves unexpectedly on Linux, check the following:

  • Missing libxcb-cursor0: VoxWave crashes on startup with a Qt error. Fix: sudo apt install libxcb-cursor0
  • Text not injecting: VoxWave needs xclip and xdotool for clipboard operations on X11. Fix: sudo apt install xclip xdotool
  • Transparent widget looks broken: make sure your desktop environment has compositing enabled (most modern desktops do by default)
  • AppImage won't run: make sure it's executable (chmod +x VoxWave-x86_64.AppImage) and you have FUSE installed (sudo apt install fuse)
💡

VoxWave works best on X11. Wayland support is experimental — if you experience issues, try switching to an X11 session.

Whisper generates phantom text

If you press the shortcut without speaking, Whisper may generate phantom text. VoxWave detects and rejects known hallucinations automatically.

⚠️

If you experience frequent hallucinations, check that your microphone is not picking up excessive ambient noise. A headset microphone is recommended.