soubarnak
ea7be5f111
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
176 lines
4.7 KiB
Markdown
176 lines
4.7 KiB
Markdown
# Troubleshooting
|
|
|
|
Common install and runtime problems. Install overview: [INSTALL.md](INSTALL.md). Support channels: [SUPPORT.md](../SUPPORT.md).
|
|
|
|
Always try once with debug logs:
|
|
|
|
```bash
|
|
voculinux --debug
|
|
```
|
|
|
|
## Command not found: `voculinux`
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Check system sound settings and mute state
|
|
2. List capture devices: `arecord -l`
|
|
3. Run `voculinux --debug` and confirm the selected device
|
|
4. Reset a bad device index: set `audio.device_index` to `null` in `~/.config/voculinux/config.json`
|
|
5. 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](USER_GUIDE.md#audio-input) for explicit microphone selection and
|
|
**System Default** behavior.
|
|
|
|
## GTK / AppIndicator / `No module named gi`
|
|
|
|
Recreate the venv with system site packages:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
|
|
voculinux --debug
|
|
```
|
|
|
|
## Text not injected into apps
|
|
|
|
**X11:**
|
|
|
|
```bash
|
|
sudo apt install xdotool # or distro equivalent
|
|
xdotool type "hello"
|
|
```
|
|
|
|
**Wayland:**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install ibus
|
|
# Fedora
|
|
sudo dnf install ibus
|
|
# Arch
|
|
sudo pacman -S ibus
|
|
```
|
|
|
|
Compositor-specific notes: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md).
|
|
|
|
## Model download fails
|
|
|
|
Models download on first use. Manual VOSK example:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
deactivate 2>/dev/null || true
|
|
rm -rf venv
|
|
./install.sh
|
|
```
|
|
|
|
On systems with several system interpreters: `SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh`.
|
|
|
|
## Still stuck
|
|
|
|
- [SUPPORT.md](../SUPPORT.md)
|
|
- [GitHub Issues](https://github.com/VocaHQ/vocalinux/issues)
|
|
- [Discussions](https://github.com/VocaHQ/vocalinux/discussions)
|
|
- [Discord](https://discord.gg/t6muquAJbm)
|