xavierk
4171567fd7
User-facing docs, About page and website now point at the fork and the Void xbps repository, with one credit line to upstream Vocalinux. Channels this fork does not publish are removed from navigation.
5.6 KiB
Troubleshooting
Common install and runtime problems. Install overview: INSTALL.md. Support channels: SUPPORT.md.
Always try once with debug logs:
voculinux --debug
Command not found: voculinux
Void package: the package puts voculinux on your PATH. Check the install:
command -v voculinux # should print a path under /usr/bin
xbps-query voculinux # shows the installed package and its version
If the package is missing, install it with sudo xbps-install -S voculinux (see
INSTALL.md).
Source checkout:
source venv/bin/activate
voculinux
No audio / microphone not working
- Check system sound settings and mute state
- Confirm PipeWire is running in your session. The package captures through PipeWire
(
pw-record,pw-dump), andpactl list short sourcesshould list your microphone - List ALSA capture devices:
arecord -l - Run
voculinux --debugand confirm the selected device - Reset a bad device index: set
audio.device_indextonullin~/.config/voculinux/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. Voculinux 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.
Tray icon missing / No module named gi
Void package: the package depends on python3-gobject, gtk+3 and
libayatana-appindicator. Update the package, which also pulls in any missing dependency:
sudo xbps-install -Su voculinux
Source checkout: the venv must see the system PyGObject. Rebuild it with the installer:
deactivate 2>/dev/null || true
rm -rf venv
./install.sh --dev
On GNOME, the tray icon needs an AppIndicator (StatusNotifier) extension. If the icon never appears, install an AppIndicator extension from your distribution, then enable it:
gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
# log out/in if needed
Refresh icons. The package installs them under /usr/share/icons/hicolor; a source install
uses ~/.local/share/icons/hicolor:
sudo gtk-update-icon-cache -f -t /usr/share/icons/hicolor
voculinux --debug
Text not injected into apps
X11:
xdotool type "hello"
Wayland:
wtype "hello"
printf "bonjour" | wl-copy
Clipboard paste uses wl-clipboard, xclip or xsel, whichever matches your session.
Wayland hotkeys do nothing: your user is not in the input group. See
Wayland hotkeys need the input group.
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 Voculinux (or log out/in). The package does not depend on IBus, so install it
first:
sudo xbps-install -S ibus
Compositor-specific notes: DISTRO_COMPATIBILITY.md.
Model download fails
Models download on first use. whisper.cpp models are managed from Settings or the first-run download.
VOSK is optional and is not in the package. If you install it in your own Python environment, you can also place a model by hand. Example:
mkdir -p ~/.local/share/voculinux/models
cd ~/.local/share/voculinux/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
libwhisper.so / pywhispercpp load errors
Void package: the package provides pywhispercpp. Import it directly to see the real error:
python3 -c "import pywhispercpp.model"
If that fails, update the package (sudo xbps-install -Su voculinux) and run
voculinux --debug again.
Source checkout: look for unresolved libraries in the venv's bindings, then rebuild them:
ldd $(find venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'
./install.sh --auto --rebuild-whispercpp
Old process still running after update
Stop via the tray, or use the lock-file PID (do not use pkill -f voculinux; it can kill editors and shells):
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/voculinux/instance.lock")"
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/voculinux-ibus/engine.pid")"
voculinux
Clean reinstall
Void package. Your configuration and models in your home directory are kept:
sudo xbps-remove voculinux
sudo xbps-install -S voculinux
Source checkout:
./uninstall.sh --keep-config --keep-data
./install.sh --dev
Source checkout: PyGObject not importable in the venv
The distribution's PyGObject 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 --dev
On systems with several system interpreters: SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh --dev.