voculinux/docs/TROUBLESHOOTING.md

# 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`

Void package: the package puts `voculinux` on your PATH. Check the install:

```bash
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](INSTALL.md#install)).

Source checkout:

```bash
source venv/bin/activate
voculinux
```

## No audio / microphone not working

1. Check system sound settings and mute state
2. Confirm PipeWire is running in your session. The package captures through PipeWire
   (`pw-record`, `pw-dump`), and `pactl list short sources` should list your microphone
3. List ALSA capture devices: `arecord -l`
4. Run `voculinux --debug` and confirm the selected device
5. Reset a bad device index: set `audio.device_index` to `null` in `~/.config/voculinux/config.json`
6. 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.

## 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:

```bash
sudo xbps-install -Su voculinux
```

Source checkout: the venv must see the system PyGObject. Rebuild it with the installer:

```bash
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:

```bash
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`:

```bash
sudo gtk-update-icon-cache -f -t /usr/share/icons/hicolor
voculinux --debug
```

## Text not injected into apps

**X11:**

```bash
xdotool type "hello"
```

**Wayland:**

```bash
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](INSTALL.md#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:

```bash
sudo xbps-install -S ibus
```

Compositor-specific notes: [DISTRO_COMPATIBILITY.md](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:

```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

## `libwhisper.so` / pywhispercpp load errors

Void package: the package provides pywhispercpp. Import it directly to see the real error:

```bash
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:

```bash
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):

```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

Void package. Your configuration and models in your home directory are kept:

```bash
sudo xbps-remove voculinux
sudo xbps-install -S voculinux
```

Source checkout:

```bash
./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:

```bash
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`.

## Still stuck

- [SUPPORT.md](../SUPPORT.md)
- [Open issues](https://git.bongbetic.com/xavierk/voculinux/issues)
- [Report a bug](https://git.bongbetic.com/xavierk/voculinux/issues/new)