e66bd218d9
* fix(audio): bound capture reads and support cancellation * fix(recognition): bound and serialize capture shutdown * fix(recognition): cancel retries and report stalled microphones * fix(audio): prefer pulse when the ALSA default is unavailable * fix(recognition): guard late callbacks and finalize capture tests * docs(audio): explain input selection and stall recovery * fix(speech): enforce auto-pause across buffered reload timeouts * fix(speech): recover auto-resume after reload timeout * test(speech): fix auto-pause follow-up test regressions * fix(speech): retain auto-resume after reconfigure timeout * fix(tray): preserve auto-pause recovery across suspend * test(capture-shutdown): give the bare tray the suspend path's shortcut managers _on_system_suspend now releases the main and per-language hotkey listeners before sleep (#1025); the fixture builds TrayIndicator without __init__, so it needs the two attributes present. * fix(tray): release hotkey listeners on suspend even while auto-paused Merging #1025's suspend cleanup with this branch's auto-pause handoff left an early return that skipped shortcut_manager.stop() whenever a configured game was active, keeping EVIOCGRABs held through sleep. The paused branch now only owns the model-lifecycle work; listener release and stopping active recognition run for every suspend. * fix(tray): hold the apply lock only around the download's verify and save Wrapping the whole recommended-model download in _apply_settings_lock blocked every GTK-thread settings apply (e.g. Test Dictation) for the length of the transfer. The engine already serializes reconfigures, so the lock only needs to cover verifying the download still owns the receipt and saving it; an apply that lands mid-download now proceeds instead of freezing the app. --------- Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
4.7 KiB
Troubleshooting
Common install and runtime problems. Install overview: INSTALL.md. Support channels: SUPPORT.md.
Always try once with debug logs:
vocalinux --debug
Command not found: vocalinux
# Official install wrappers
export PATH="$HOME/.local/bin:$PATH"
vocalinux
# Or run the venv binary
~/.local/share/vocalinux/venv/bin/vocalinux
# Source checkout
source venv/bin/activate
vocalinux
No audio / microphone not working
- Check system sound settings and mute state
- List capture devices:
arecord -l - Run
vocalinux --debugand confirm the selected device - Reset a bad device index: set
audio.device_indextonullin~/.config/vocalinux/config.json - Bluetooth mics: try a wired device to isolate SCO capture issues
Microphone Stalled
A Microphone Stalled notification means the selected input stopped delivering audio. Vocalinux stops the failed dictation attempt.
Open Settings → Audio. Use Microphone Test → Test to record two seconds and check the audio level, or select a different Input Device, then retry dictation. Test Dictation is a separate speech-recognition test. See Audio input for explicit microphone selection and System Default behavior.
GTK / AppIndicator / No module named gi
Recreate the venv with system site packages:
sudo apt install python3-gi python3-gi-cairo # Debian/Ubuntu example
# tray: gir1.2-ayatanaappindicator3-0.1 or gir1.2-appindicator3-0.1
deactivate 2>/dev/null || true
rm -rf venv
/usr/bin/python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -e .
On GNOME, enable the AppIndicator extension if the tray icon never appears:
# 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
gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
# log out/in if needed
Refresh icons:
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
vocalinux --debug
Text not injected into apps
X11:
sudo apt install xdotool # or distro equivalent
xdotool type "hello"
Wayland:
sudo apt install wtype wl-clipboard xclip xsel
wtype "hello"
printf "bonjour" | xsel --clipboard --input
KDE Plasma Wayland: wtype may fail if the compositor does not expose a virtual keyboard to normal clients. Prefer System Settings → Keyboard → Virtual Keyboard → IBus Wayland, then restart Vocalinux (or log out/in).
Install IBus if needed:
# Ubuntu/Debian
sudo apt install ibus
# Fedora
sudo dnf install ibus
# Arch
sudo pacman -S ibus
Compositor-specific notes: DISTRO_COMPATIBILITY.md.
Model download fails
Models download on first use. Manual VOSK example:
mkdir -p ~/.local/share/vocalinux/models
cd ~/.local/share/vocalinux/models
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip
More VOSK models: https://alphacephei.com/vosk/models whisper.cpp models are managed from Settings or first-run download.
libwhisper.so / pywhispercpp load errors
# Unresolved libs
ldd $(find ~/.local/share/vocalinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'
# Rebuild whisper.cpp bindings via installer
./install.sh --auto --rebuild-whispercpp
# Or switch to VOSK temporarily
vocalinux --engine vosk
Old process still running after update
Stop via the tray, or use the lock-file PID (do not use pkill -f vocalinux; it can kill editors and shells):
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/vocalinux/instance.lock")"
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/vocalinux-ibus/engine.pid")"
vocalinux
Clean reinstall
./uninstall.sh --keep-config --keep-data
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
bash /tmp/vl.sh
Distro PyGObject not importable in the venv
The distro python3-gi / python3-gobject package is installed, but venv/ was built by a different Python than the one it targets. Current install.sh ignores an activated virtualenv and rebuilds a mismatched venv/. Otherwise:
deactivate 2>/dev/null || true
rm -rf venv
./install.sh
On systems with several system interpreters: SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh.