VoiceUse / Docs / Troubleshooting

Troubleshooting

Common issues and their solutions.

Installation Issues

pyaudio install fails

Cause: Missing PortAudio system library.

Fix:

Windows

pip install pipwin
pipwin install pyaudio

Debian / Ubuntu

sudo apt-get install portaudio19-dev python3-pyaudio

macOS

brew install portaudio

mss or pyautogui import error

Fix:

pip install mss pyautogui

Runtime Issues

No audio playback

Cause: Missing playback backend.

Fix: Install ffplay (via ffmpeg) or mpv:

Windows

  1. Download ffmpeg from ffmpeg.org
  2. Add bin folder to PATH
  3. Verify: ffplay -version

macOS

brew install ffmpeg

Linux

sudo apt-get install ffmpeg
# or
sudo pacman -S ffmpeg

Hotkey not working

CauseFix
pynput not installedpip install pynput
No OS permissionsRun as administrator (Windows) or check input permissions (macOS)
Conflicting hotkeyChange audio.hotkey in config.yaml

Wake word not detected

Cause: Missing PORCUPINE_ACCESS_KEY for custom models.

Fix:

STT / LLM calls hang

CauseFix
Missing API keySet GROQ_API_KEY
Network issuesCheck internet connection
Rate limitingWait and retry; check provider status

Run with --verbose for detailed error output:

voiceuse --verbose

Window focus fails on Linux

Cause: xdotool not installed or Wayland incompatibility.

Fix:

sudo apt-get install xdotool wmctrl
Wayland

xdotool does not work on Wayland. Switch to X11 or use XWayland.

Low confidence on vision clicks

CauseFix
Poor lightingIncrease room lighting
High monitor scalingReduce DPI scaling to 100%
Ambiguous descriptionBe more specific: "the blue Submit button"
Wrong providerTry switching between Codex and Anthropic

Grok Voice plugin won't start

CauseFix
Missing XAI_API_KEYSet environment variable
websockets not installedpip install websockets
Microphone in useClose other apps using the microphone

Getting Help

If your issue isn't listed here:

  1. Run with --verbose and check the output
  2. Check GitHub Issues
  3. Open a new issue with:
    • Your OS and Python version
    • Your config.yaml (with API keys redacted)
    • The exact error message
    • Steps to reproduce