Files

T

soubarnak ea7be5f111 feat(identity): rename user-visible identity to voculinux with one-time legacy import

The fork takes its own name everywhere a user can see it: binaries
(voculinux, voculinux-gui), desktop entry, autostart, tray, D-Bus
namespace (com.voculinux.Voculinux, no alias for the old name),
config/data/cache dirs, single-instance lock, IBus engine identity,
tray icons, resource prefixes, VOCULINUX_* environment names, and the
update-checker user agent. The internal Python module stays vocalinux
and the distribution metadata keeps the upstream URLs as provenance.

On first run a previous Vocalinux install's config.json, custom
dictionary, and portal restore token are copied once into the new
locations (new config always wins, no merge, no write-back); models
re-resolve through the pinned-checksum download path. An offline
naming-sweep test proves no old-name strings remain on user-visible
surfaces outside the allowlist.

Refs #18

2026-11-06 01:29:39 +05:30

4.7 KiB

Raw Blame History

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`

# Official install wrappers
export PATH="$HOME/.local/bin:$PATH"
voculinux

# Or run the venv binary
~/.local/share/voculinux/venv/bin/voculinux

# Source checkout
source venv/bin/activate
voculinux

No audio / microphone not working

Check system sound settings and mute state
List capture devices: arecord -l
Run voculinux --debug and confirm the selected device
Reset a bad device index: set audio.device_index to null in ~/.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.

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
voculinux --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 Voculinux (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/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 whisper.cpp models are managed from Settings or first-run download.

`libwhisper.so` / pywhispercpp load errors

# Unresolved libs
ldd $(find ~/.local/share/voculinux/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
voculinux --engine vosk

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

./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.

4.7 KiB Raw Blame History