Jatin K MalikandGitHub
f48bdda525
* docs: polish project documentation for a clearer public surface Rewrite the README and supporting docs for a more professional first impression: less emoji and badge noise, install-first structure, and a real documentation index. Add a Contributor Covenant, tighten SECURITY and GitHub templates, and make distro/update guides read as product docs instead of internal status notes. * docs: split install guide and add changelog plus support pages Break INSTALL.md into a short primary guide, manual/PyPI package lists, and troubleshooting. Add root CHANGELOG.md and SUPPORT.md, wire them into the docs index and README, and drop the outdated screenshot lag note now that v0.15 assets are on main. * docs: humanize PR copy and remove em dashes Strip em/en dashes from the documentation rewritten in this PR, fix mid-sentence colon fallout from that pass, and smooth a few stiff phrases so the public docs read more natural. * docs: list Faster Whisper after rebase onto main Installer and CLI already accept faster_whisper. Document it next to the other engines, drop the outdated screenshot lag note, and keep the on-device wording honest for local vs remote.
4.2 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
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.