VocalinuxVocalinux

Support Guide

Troubleshooting Guide

Having issues with Vocalinux? Find solutions to common problems below. Can't find your issue? Open a GitHub issue for help.

Quick Debug Command

Run Vocalinux with debug output to see detailed logs:

vocalinux --debug

Vocalinux won't start

Symptoms

  • Command not found
  • Module import errors
  • Application crashes on launch

Solutions

  • Ensure you ran the installer: curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash
  • Check if the virtual environment is activated: source ~/.local/share/vocalinux/venv/bin/activate
  • Verify Python version (3.8+ required): python3 --version
  • Try reinstalling: ./uninstall.sh && ./install.sh

No audio detected / microphone not working

Symptoms

  • Dictation shows no text
  • Audio level indicator stays at zero

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

Text not appearing in applications

Symptoms

  • Dictation works but text doesn't appear
  • Text injection fails

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

High CPU/GPU usage

Symptoms

  • System slowdown during dictation
  • Fan noise
  • Laggy response

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

Poor transcription accuracy

Symptoms

  • Many transcription errors
  • Wrong words
  • Garbled text

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

Installation fails

Symptoms

  • Dependency errors
  • Package not found
  • Permission denied

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

Keyboard shortcut not working

Symptoms

  • Double-tap Ctrl doesn't start dictation
  • Custom shortcuts ignored

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

Tray icon not appearing

Symptoms

  • No system tray icon
  • Cannot access settings

Solutions

  • Ensure your desktop environment supports system trays (GNOME requires extension)
  • Install AppIndicator extension for GNOME: sudo apt install gnome-shell-extension-appindicator
  • Check if ayatana-appindicator is installed: sudo apt install libayatana-appindicator3-1
  • Try launching from terminal to see any errors: vocalinux --debug

Still having issues?