Troubleshooting Guide

Solutions

• Ensure you ran the installer from the homepage or install guide
• Check if the virtual environment is activated: source ~/.local/share/vocalinux/venv/bin/activate
• Verify Python version (3.9+ required): python3 --version
• Try reinstalling: ./uninstall.sh && ./install.sh

Solutions

• Check microphone permissions in your system settings
• Verify microphone is detected: arecord -l (Linux)
• Test microphone recording: arecord -d 3 test.wav && aplay test.wav
• Ensure no other application is using the microphone
• Check PulseAudio/PipeWire settings: pavucontrol

Solutions

• For Wayland: Ensure IBus is running and Vocalinux IBus is configured
• For X11: Verify xdotool is installed: sudo apt install xdotool
• Check if the target application has focus
• Try a different application (terminal, text editor) to isolate the issue
• Restart Vocalinux after changing display servers

Solutions

• Use a smaller model (tiny or base instead of medium/large)
• Enable GPU acceleration if available (Vulkan for AMD/Intel, CUDA for NVIDIA)
• Switch to VOSK engine for lower resource usage
• Reduce audio sample rate in settings

Solutions

• Use a larger model (small → medium → large) for better accuracy
• Ensure microphone is positioned correctly and not too far
• Reduce background noise
• Speak clearly and at a moderate pace
• Try a different speech engine (whisper.cpp vs VOSK)
• Set the correct language in settings

Solutions

• Confirm the server URL is reachable from the Vocalinux machine
• Check whether the server expects /inference or /v1/audio/transcriptions
• Set the API key if your server requires bearer token authentication
• Use HTTPS and a firewall when the server is outside a trusted LAN

Solutions

• Install neural VAD support: pip install "vocalinux[vad]"
• Restart Vocalinux after installing ONNX Runtime support
• Use the VAD sensitivity setting in Recognition to tune quiet speech detection
• If Silero cannot load, Vocalinux falls back safely to amplitude-based VAD

Solutions

• Ensure you have internet connectivity for downloading dependencies
• Run with sufficient permissions (don't use sudo unless specifically needed)
• Check your distribution is supported (Ubuntu 22.04+, Fedora 39+, Arch)
• Install system dependencies manually: sudo apt install python3-pip python3-gi python3-venv
• Check disk space: df -h

Solutions

• Check if another application is capturing the shortcut
• Verify Vocalinux is running (check system tray)
• Try changing the shortcut in Settings
• On Wayland, ensure keyboard shortcuts are not blocked by compositor settings

Solutions

• v0.10.1+ automatically recovers after suspend - ensure you're on latest version
• Check system tray icon status after resume
• If issues persist, restart Vocalinux from tray menu

Solutions

• v0.10.1+ bundles resources to prevent missing tray icons - ensure you're on latest version
• Ensure your desktop environment supports system trays (GNOME requires an AppIndicator extension)
• Install the GNOME AppIndicator extension (pick your distro): Debian/Ubuntu: sudo apt install gnome-shell-extension-appindicator — Fedora: sudo dnf install gnome-shell-extension-appindicator — Arch: sudo pacman -S gnome-shell-extension-appindicator
• Then enable the extension (Extensions app, or: gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com) and log out/in if needed
• Debian/Ubuntu: sudo apt install libayatana-appindicator3-1 — Fedora: sudo dnf install libayatana-appindicator-gtk3 — Arch: sudo pacman -S libayatana-appindicator (legacy libappindicator-gtk3 can leave the icon missing on KDE)
• Try launching from terminal to see any errors: vocalinux --debug

Solutions

• v0.10.1+ includes dedicated close button - update to latest version
• Settings dialog now forces window decorations