Files

T

Sergey SilaevandGitHub 582d494633 chore(build): uv tooling, a Python 3.11 floor, and verified model downloads (epic #701 , phases 2.5 & 5) (#713 )

* chore(build): migrate justfile tooling to uv

All recipes now run through 'uv run' against .venv, with a shared
DEV_EXTRAS variable (dev + vad) because uv syncs the environment
exactly and would otherwise uninstall the dev tools between
recipes. 'deps' installs dev+vad; new 'deps-all' covers every
extra. 'build' switches to 'uv build'; 'version' uses --no-sync.

Bump [tool.uv] required-version to >=0.12,<0.13 for uv 0.12.x, and
raise the mypy python_version target to 3.12: mypy 1.19 in the lock
cannot target 3.9 and numpy 2.x stubs need a 3.12 target to parse
(mypy is not run in CI or pre-commit; this only affects 'just
typecheck').

* fix(tests): isolate test runs from real XDG state; fix Arch model-path crash

Local test runs failed en masse (185 failures) while CI stayed
green: tests picked up the developer's real ~/.local/share/vocalinux
models via the default XDG paths and switched IBus/keyboard code
paths through the desktop session env (XDG_CURRENT_DESKTOP/
XDG_SESSION_TYPE on GNOME/Wayland, issue #478 branches). conftest
now points XDG base dirs at a throwaway session-wide directory and
clears session variables at import time, mirroring a fresh CI
runner (paths like MODELS_DIR freeze at first import during
collection, so fixture-time isolation is too late).

Also guard the Arch branch of _get_system_model_paths(): it removed
/usr/local/share/vocalinux/models unconditionally and crashed with
ValueError on Arch hosts when a custom XDG_DATA_DIRS never added
that path. Add regression tests, and make the lock-file test assert
the actual $XDG_DATA_HOME/vocalinux contract instead of the
hardcoded ~/.local/share default.

* fix(tests): keep the IBus engine double a plain class

Python 3.14's unittest.mock re-instantiates a user subclass when it builds
child mocks (klass(name=...)). VocalinuxEngine inherits from whatever
IBus.Engine resolves to, and the test module bound that to the MagicMock
class itself, so every engine instantiation raised

    TypeError: VocalinuxEngine.__init__() got an unexpected keyword argument 'name'

on 3.14 while passing on 3.13. Replace it with a plain stand-in class that
still hands out per-instance MagicMocks for the IBus API surface the engine
touches.

The same pattern remains in test_ibus_engine.py, test_ibus_engine_utils.py,
test_ibus_active_engine_guard.py and test_ibus_xkb_wayland.py; those never
instantiate the engine, so they are unaffected for now.

* fix(install): build the venv from the system Python

install.sh looked up a bare `python3` from PATH. Started from an activated
virtualenv — a shell left in uv's .venv after `just deps` — it built venv/
from that interpreter, where distro PyGObject is invisible even with
--system-site-packages, and the run aborted with

    Distro PyGObject (python3-gi / python3-gobject) is not importable in the venv.

A mismatched venv/ then survived every retry, because the installer reuses
whatever venv it finds.

- drop an inherited VIRTUAL_ENV (and its bin from PATH) before any
  interpreter lookup
- select the interpreter explicitly: $SYSTEM_PYTHON (default
  /usr/bin/python3) or PATH python3, preferring one that can import gi,
  and create the venv with it instead of `python3`
- recreate venv/ when it was built by a different interpreter
- name the interpreter in the PyGObject guard's error

Documents the two environments (uv's .venv for tooling, venv/ for the
installed app) in CONTRIBUTING, the justfile header and AGENTS.md, and adds
the mismatch symptom to the INSTALL troubleshooting section.

* chore(python): raise the supported floor to 3.11

requires-python promised 3.9 while the CI matrix ran 3.9/3.10/3.11/3.13,
the classifiers advertised up to 3.14, mypy targeted 3.12 and install.sh
enforced 3.9 — five different answers to "which Python does this support".

Settle on 3.11 everywhere: pyproject (requires-python, classifiers, black
targets), install.sh's MIN_VERSION, check-system-deps.sh, the distro package
map, the CI matrix (now 3.11-3.14, matching the classifiers), the release and
nightly workflows, and the docs.

mypy now targets the floor instead of 3.12, so type checking covers what we
promise; numpy 2.x ships stubs in 3.12 syntax that a 3.11 target cannot
parse, so its imports are skipped. (mypy has 71 pre-existing errors either
way; no CI job gates on it.)

uv.lock and the requirements/* exports are regenerated — dropping 3.9/3.10
removes most of the version-conditional resolution branches.

tests/test_python_version_policy.py pins the invariant: install.sh's floor,
requires-python, the classifiers and the CI matrix must agree.

* ci: run lint and tests from uv.lock

The lock file and the hash-pinned exports were not enforced anywhere: CI
still built a venv by hand and installed unpinned `PyGObject` plus
`-e ".[dev,vad]"`, so the tool versions it checked against had nothing to do
with the ones `just lint` uses locally.

Both Python jobs now use astral-sh/setup-uv and run through `uv sync
--locked` / `uv run --locked`, which also fails the build when uv.lock drifts
from pyproject.toml.

Partially covers phase 5 of #701 (tests install from the lock, lock freshness
gate); trusted publishing, artifact checksums and action SHA pinning are
still open there.

* ci: lint from a dedicated dependency group

The lint job failed on this branch: `uv run --extra dev` syncs the whole
project, so it tried to build pyaudio from source on a runner that installs
no system dependencies.

    src/pyaudio/device_api.c:9:10: fatal error: portaudio.h: No such file or directory

Move black/isort/flake8 out of the `dev` extra into a `lint` dependency
group. CI runs `uv run --locked --only-group lint`, which installs the three
pure-Python tools and skips the project entirely — no portaudio or
girepository headers needed. `just deps` and DEV_EXTRAS request the group
alongside the dev extras, so the local environment still carries test and
lint tooling at once and `just lint` matches CI version for version.

pre-commit is unaffected: its hooks pin their own tool versions upstream.

* fix(install): never configure an engine the venv cannot import

vosk became an optional extra in #705, but the installer still writes
`"engine": "vosk"` into config.json on the whisper.cpp fallback path even
when installing the extra only produced a warning. config.json also survives
reinstalls — every writer guards on "file does not exist" — so an engine
picked by an earlier attempt outlives the venv that supported it. Either way
Vocalinux dies at startup:

    ModuleNotFoundError: No module named 'vosk'

- the fallback now writes the vosk config only when `import vosk` actually
  succeeds, and otherwise leaves the engine configuration alone
- a new verify_configured_engine() runs near the end of the install: if
  config.json selects vosk and the venv cannot import it, it says so and
  prints both fixes instead of leaving a broken install behind

* feat(models): verify every model download against a pinned digest

Pins a sha256/md5 per downloadable speech model in
src/vocalinux/utils/model_checksums.txt and verifies against it in both
install.sh and the runtime downloaders, before the file is moved into place.
Verification fails closed. Covers phase 2.5 of #701; see the PR for details.

* docs(agents): rebase AGENTS.md onto the #727 rewrite

* fix(install): hash models that are already on disk instead of trusting them

* refactor(models): one download path per engine, and fix Whisper's

* docs(install): drop distros that cannot meet the 3.11 floor

* docs: retire the distros and Python versions the 3.11 floor rules out

* fix(install): abort instead of warning when Python is below the floor

* fix(install): fall back to the system Python, not the one on PATH

* fix(install): match an existing venv by installation, not by X.Y

* fix(install): repair a config naming an engine the venv cannot import

* fix(models): pin VOSK by the sha256 of bytes we fetched, not upstream's md5

* fix(justfile): request the dev set in every recipe that syncs

* test(version): scan the docs and website trees for a stale Python floor

* docs: correct the stale model-checksum and distro claims

* fix(models): stamp the VOSK tree the app extracts, as the installer does

* fix(install): replace an unverified VOSK model only once its successor is ready

* docs(install): align the Fedora floor with the rest of the tree

* test(install): drop an f-string with no placeholders

* test(models): stub the downloader probe the VOSK installer test relies on

* docs: drop the long dashes from two model-checksum comments

* fix(install): gate on the interpreter, not on the distro release label

* fix(justfile): export the lint group into requirements/dev.txt

* fix(models): unpack the VOSK tree into staging and stamp it before the swap

* fix(whisper): adopt a checkpoint an earlier release stored under the catalog name

* docs(settings): state what a stray Whisper copy really means for deletion

* fix(models): hash a whisper.cpp model found on disk before it reaches ctypes

* docs(contributing): stop telling readers to uninstall their linters

* fix(install): stop warning off distros the project documents as supported

* docs(distros): file the supported derivatives under supported

2026-08-24 00:25:06 -07:00

20 KiB

Raw Blame History

Linux Distribution Compatibility

Implementation Status

The cross-distribution compatibility improvements have been implemented in phases:

Phase	Status	Description
Phase 1	✅ Complete	Dynamic GI_TYPELIB_PATH detection using pkg-config, multi-arch support, ALSA library fallbacks
Phase 2	✅ Complete	Enhanced distro detection (Gentoo, Alpine, Void, Solus, Mageia)
Phase 3	✅ Complete	System dependency checker, improved error messages
Phase 4	✅ Complete	CI test matrix, pkg-config as core dependency
Phase 5	✅ Complete	Fixed remaining hardcoded GI_TYPELIB_PATH values in install.sh and CI workflow
Phase 6	✅ Complete	Added wrapper script verification tests, updated documentation
Phase 7	✅ Complete	Flatpak packaging (whisper.cpp engine) for universal distribution support — see `packaging/flatpak/`. Flathub submission in progress.
Phase 8	📋 Planned	Snap packaging for Ubuntu Software Store

Technical Implementation

Dynamic GI_TYPELIB_PATH Detection

The installer now uses a robust multi-step approach to detect the correct GI_TYPELIB_PATH across different distributions:

Primary Method: Uses pkg-config --variable=typelibdir gobject-introspection-1.0 (most reliable)
Fallback Paths: Checks common distribution-specific paths in priority order:
- Ubuntu/Debian multi-arch: /usr/lib/x86_64-linux-gnu/girepository-1.0
- ARM64: /usr/lib/aarch64-linux-gnu/girepository-1.0
- Fedora/RHEL: /usr/lib64/girepository-1.0
- Arch/Generic: /usr/lib/girepository-1.0
- Local installs: /usr/local/lib/girepository-1.0
Architecture Support: Detected paths for x86_64, ARM64, ARMHF, RISC-V, POWER, and s390x

Wrapper Scripts

The installer creates wrapper scripts (~/.local/bin/vocalinux and ~/.local/bin/vocalinux-gui) that:

Set the correct GI_TYPELIB_PATH environment variable
Handle input group permissions for Wayland keyboard shortcuts
Provide seamless cross-distro compatibility

Desktop Entry

The .desktop entry is automatically configured with the detected GI_TYPELIB_PATH, ensuring the application launches correctly from the application menu regardless of distribution.

Officially Supported Distributions

These distributions are tested and known to work well with Vocalinux. A derivative is judged by the Python it ships rather than by its own version number, which rarely tracks the base release, and install.sh checks the interpreter rather than the release label.

Distribution	Version	Status	Notes
Ubuntu	24.04+	✅ Full Support	22.04 ships Python 3.10, below the 3.11 floor
Debian	12+, Testing	✅ Full Support	Primary target; use Ayatana AppIndicator
Fedora	39+	✅ Good Support	Uses lib64 paths, fully supported
Arch Linux	Rolling	✅ Good Support	Community tested, rolling release compatible
openSUSE	Tumbleweed	✅ Good Support	Good support with zypper package manager
Linux Mint	On Ubuntu 24.04+	✅ Good Support	Mint 22 qualifies; Mint 21 is on Ubuntu 22.04, below the floor
Pop!_OS	24.04+	✅ Good Support	Uses Ubuntu's own numbering
elementary OS	On Ubuntu 24.04+	✅ Good Support	elementary 8 qualifies; 7 is on Ubuntu 22.04
Zorin OS	On Ubuntu 24.04+	✅ Good Support	Zorin 17 is on Ubuntu 22.04, below the floor
Manjaro	Rolling	✅ Good Support	Arch base, inherits Arch compatibility
EndeavourOS	Rolling	✅ Good Support	Arch base, inherits Arch compatibility

Experimental Support

These distributions may work but have known limitations or are less tested:

Distribution	Status	Known Issues
Gentoo	⚠️ Experimental	No package manager support, manual install required. Packages are compiled from source which takes longer.
Alpine Linux	⚠️ Experimental	Uses musl libc (not glibc). Some Python packages may not have pre-built wheels and may need to be compiled.
Void Linux	⚠️ Experimental	Untested, manual install required. Uses xbps package manager.
Solus	⚠️ Experimental	Untested, manual install required. Uses eopkg package manager.
Mageia	⚠️ Experimental	Untested, uses dnf/urpmi package managers.

Not Supported

These distributions are known to be incompatible:

Distribution	Status	Reason
NixOS	❌ Not Supported	Completely different filesystem layout (/nix/store), incompatible with standard installer

Requirements by Distribution

Ubuntu/Debian-based

sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 \
  portaudio19-dev python3-dev python3-venv pkg-config

Note for Debian 12+: Use gir1.2-ayatanaappindicator3-0.1 instead of gir1.2-appindicator3-0.1

Debian-specific notes

Debian's standard repositories differ from Ubuntu in a few ways that matter for Vocalinux:

pywhispercpp build prerequisites — On a clean Debian install the following packages are not pulled in transitively (unlike Ubuntu) but are required when pywhispercpp must be compiled from source (e.g. for GPU support):

sudo apt install -y libssl-dev autoconf automake libtool patchelf

The installer now installs these automatically, but if you hit a CMake error like Could not find OpenSSL during a manual reinstall, add the above first.

ydotool — ydotool is not packaged in Debian's standard repos. The installer falls back gracefully to IBus or wtype for most Wayland compositors. KDE Plasma Wayland users should first select IBus Wayland in System Settings -> Keyboard -> Virtual Keyboard. If you specifically need ydotool as a fallback, compile it from source:

sudo apt install -y git cmake libevdev-dev
git clone https://github.com/ReimuNotMoe/ydotool.git /tmp/ydotool
cmake -S /tmp/ydotool -B /tmp/ydotool/build
sudo cmake --build /tmp/ydotool/build --target install
sudo systemctl enable --now ydotoold

Scoped source builds — If you need to force pywhispercpp to rebuild from source, use the package-scoped flag to avoid compiling unrelated deps like NumPy from source (which takes a very long time and can fail):

source ~/.local/share/vocalinux/venv/bin/activate
PYWHISPERCPP_CLEAN=1 pip install --force-reinstall --no-binary=pywhispercpp pywhispercpp
deactivate

Verifying libwhisper.so resolution — If Vocalinux starts with libwhisper.so.1: cannot open shared object file, check for unresolved symbols:

ldd $(find ~/.local/share/vocalinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'

If any libraries are listed, re-run the installer with --rebuild-whispercpp or switch to the VOSK engine (--engine=vosk) as a fully-packaged alternative.

Fedora/RHEL-based

sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

Arch Linux-based

sudo pacman -S --needed python-gobject gtk3 gobject-introspection \
  portaudio python pkg-config

openSUSE

PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install -y \
  "${PYVER}-pip" "${PYVER}-gobject" "${PYVER}-gobject-cairo" \
  "${PYVER}-devel" "${PYVER}-virtualenv" \
  gtk3 typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
  typelib-1_0-Notify-0_7 libnotify4 \
  gobject-introspection-devel portaudio-devel pkg-config cmake wget curl unzip \
  xdotool wtype

# Optional: only needed for whisper.cpp Vulkan GPU builds
sudo zypper install -y vulkan-tools vulkan-devel shaderc

Note: openSUSE Tumbleweed often uses versioned Python package names such as python313-devel. The -devel suffix means development headers for compiling native dependencies; it does not mean beta or unstable packages. If ${PYVER}-virtualenv is unavailable on your snapshot, try ${PYVER}-venv.

Gentoo

sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libayatana-appindicator \
  media-libs/portaudio dev-lang/python:3.11

Note: Gentoo compiles packages from source, which will take longer.

Alpine Linux

sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev \
  py3-virtualenv pkgconf

Note: Alpine uses musl libc. Some Python packages may need to be compiled from source.

Void Linux

sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libappindicator \
  gobject-introspection portaudio-devel python3-devel pkg-config

Solus

sudo eopkg install python3-pip python3-gobject gtk3 libappindicator \
  gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config

Mageia

sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config
# or
sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

PyPI, pip, and pipx Installation

The PyPI package is useful when you want a standard Python package install, or when you want to manage Vocalinux with pipx. However, Vocalinux requires system desktop packages that cannot be installed by pip or pipx.

Use the official installer when possible. It installs the required system packages, creates the virtual environment, installs Vocalinux, sets up desktop integration, and downloads the default speech model:

curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh | bash

Important: Install System Packages First

Before running pip install vocalinux, pip install "vocalinux[vosk]", or pipx install vocalinux, you must install the required system packages:

Ubuntu/Debian

sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 \
  libgirepository1.0-dev libcairo2-dev portaudio19-dev python3-dev \
  python3-venv pkg-config xdotool wtype wl-clipboard xclip xsel

On Ubuntu 24.04+ or Pop!_OS, install libgirepository-2.0-dev if libgirepository1.0-dev is not available.

Fedora

sudo dnf install python3-gobject gtk3 gtk3-devel libayatana-appindicator-gtk3 \
  gobject-introspection-devel portaudio-devel python3-devel \
  python3-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel

Arch Linux

sudo pacman -S python-gobject gtk3 libayatana-appindicator gobject-introspection \
  python-cairo portaudio python-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel

openSUSE

PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 \
  typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
  typelib-1_0-Notify-0_7 libnotify4 \
  portaudio-devel "${PYVER}-devel" "${PYVER}-virtualenv" pkg-config xdotool wtype wl-clipboard xclip xsel

pip Installation Steps

Install system packages (see above for your distribution)
Create a virtual environment with system site-packages enabled:
```
python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
```
--system-site-packages lets the venv use distro-provided GTK bindings such as python3-gi, which are often more reliable than building PyGObject from source in a venv.

Install Vocalinux from PyPI:

pip install vocalinux
# vosk engine: pip install "vocalinux[vosk]"

Run Vocalinux:
```
vocalinux
```

pipx Installation Steps

Install system packages (see above for your distribution)

Install pipx (if not already installed):

# Ubuntu/Debian
sudo apt install pipx
pipx ensurepath

# Fedora
sudo dnf install pipx
pipx ensurepath

# Arch Linux
sudo pacman -S pipx
pipx ensurepath

Install Vocalinux:

pipx install vocalinux
# vosk engine: pipx install "vocalinux[vosk]"

Run Vocalinux:
```
vocalinux
```

Why System Packages Are Required

Vocalinux uses GTK3 for its GUI, AppIndicator/Ayatana for the system tray icon, PortAudio for microphone capture, and tools such as xdotool, wtype, and clipboard utilities (wl-clipboard, xclip, xsel) for text injection and layout-independent Wayland paste fallback. These are system libraries and desktop tools that must be installed with your distribution's package manager. Python packages from PyPI can provide Python bindings, but they do not provide the underlying GTK typelibs, tray support, audio development libraries, or text injection binaries.

Troubleshooting pip/pipx Installation

If vocalinux fails to start:

Check for missing system packages - The error message will indicate which packages are missing
Verify GI_TYPELIB_PATH - In rare cases, you may need to set this environment variable:
```
export GI_TYPELIB_PATH=/usr/lib/x86_64-linux-gnu/girepository-1.0
vocalinux
```
Check package metadata - Run pip show vocalinux or pipx runpip vocalinux show vocalinux to confirm which version was installed.
Check Python dependencies - Run pip check inside the venv, or pipx runpip vocalinux check for pipx.

If Vocalinux reports that a speech recognition model is missing, open Settings and download a model, or use the official installer to download the default model during setup.

Recommended Alternative

For the best experience with automatic dependency handling, use the official installer:

curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh | bash

This installer automatically detects your distribution and installs all required system packages.

Text Injection Tools

Vocalinux requires text injection tools to work with X11 or Wayland:

For X11

xdotool: Required for X11 sessions

For Wayland

IBus: Recommended for KDE Plasma Wayland and generally the most reliable direct text input path
wtype: Recommended for wlroots-style Wayland compositors such as sway
ydotool: Universal alternative that works with both X11 and Wayland. Current distro packages use the per-user ydotool.service; source builds can install the system-level ydotoold.service. Vocalinux uses clipboard paste with wl-clipboard, xclip, or xsel to avoid non-US layout scrambling.
xdotool: May work via XWayland fallback

Installation by Distribution

# Ubuntu/Debian/Fedora/Arch/openSUSE
sudo apt install xdotool wtype wl-clipboard xclip xsel     # Ubuntu/Debian
sudo dnf install xdotool wtype wl-clipboard xclip xsel     # Fedora
sudo pacman -S xdotool wtype wl-clipboard xclip xsel       # Arch
sudo zypper install xdotool wtype wl-clipboard xclip xsel  # openSUSE

Ubuntu releases which package ydotool install a user unit named ydotool.service. Enable it only for the account running Vocalinux:

sudo apt install ydotool
sudo usermod -aG input $USER  # then log out and back in
systemctl --user enable --now ydotool.service

Do not use sudo systemctl --global enable ydotool.service. Global user-unit enablement also starts the input-injection daemon for the display-manager greeter and other accounts. If it was previously enabled globally, repair the setup with:

sudo systemctl --global disable ydotool.service
systemctl --user enable --now ydotool.service

The command is different for the Debian source-build path documented above: the upstream install supplies the system unit ydotoold.service, so sudo systemctl enable --now ydotoold.service is correct only for that route.

Manual Installation

For unsupported or experimental distributions:

Run the dependency checker:
```
bash scripts/check-system-deps.sh
```
Install missing dependencies using your package manager based on the checker output
Run the installer with --skip-system-deps:
```
./install.sh --skip-system-deps
```

Or install from source in a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -e .[whisper]

Desktop Environment Compatibility

Desktop Environment	Status	Notes
GNOME	✅ Full Support	Primary target, uses AppIndicator
KDE Plasma	✅ Full Support	On Wayland, select IBus Wayland in System Settings -> Keyboard -> Virtual Keyboard
Xfce	✅ Full Support	Works with AppIndicator
Cinnamon	✅ Full Support	Works with AppIndicator
MATE	✅ Full Support	Works with AppIndicator
LXQt	✅ Full Support	Works with AppIndicator
sway	✅ Good Support	Wayland native, uses wtype
i3	✅ Good Support	X11, uses xdotool
Hyprland	⚠️ Experimental	Wayland, may need wtype configuration

Autostart Compatibility

Vocalinux uses XDG autostart desktop entries for "Start on Login".

Desktop-session autostart file location:
- $XDG_CONFIG_HOME/autostart/vocalinux.desktop, or
- ~/.config/autostart/vocalinux.desktop (fallback)
This launches Vocalinux as a user GUI app after login.
Vocalinux does not create a systemd service/unit for this feature.

Practical caveat:

Mainstream desktop environments generally honor XDG autostart.
Minimal/custom WM sessions may need an explicit autostart manager or WM startup hook.

Display Server

Display Server	Status	Notes
X11	✅ Full Support	Uses xdotool for text injection
Wayland	✅ Full Support	Uses IBus, wtype, ydotool, or xdotool fallback depending on compositor
XWayland	✅ Full Support	Automatically detected, falls back to xdotool if needed

Architecture Support

Architecture	Status	Notes
x86_64 (AMD64)	✅ Full Support	Primary target
arm64 (AArch64)	✅ Good Support	Tested on Raspberry Pi, ARM64 servers
armhf	⚠️ Experimental	Limited testing
riscv64	⚠️ Experimental	Limited testing, may need to compile dependencies

Reporting Issues

When reporting issues, please include:

Distribution information:
```
cat /etc/os-release
```

Desktop environment:

echo $XDG_CURRENT_DESKTOP
echo $SESSION_TYPE

Dependency checker output:
```
bash scripts/check-system-deps.sh
```
Python version:
```
python3 --version
```
Error messages or logs:
- Any error messages from the installer
- Output from running vocalinux-gui from terminal
- Relevant journal logs if applicable
Steps to reproduce:
- What you were trying to do
- What happened instead
- Expected behavior

Testing Checklist

Use this checklist when testing on a new distribution:

Pre-Install

Run dependency checker: bash scripts/check-system-deps.sh
Note missing packages
Check desktop environment
Check display server (X11/Wayland)

Installation

Run installer: ./install.sh
Check for errors during installation
Verify virtual environment was created
Check wrapper scripts exist

Post-Install

Launch from terminal: ~/.local/bin/vocalinux-gui
Launch from application menu
Verify tray icon appears
Test keyboard shortcuts (Hold Right Alt by default)
Test audio recording
Test text injection in different applications
Test Settings dialog opens correctly
Test model download if using Whisper

Known Issues to Watch For

AppIndicator not showing in tray
Audio device not detected
Text injection not working
Model download failures
Permission errors with udev/input

Contributing Compatibility Fixes

If you successfully get Vocalinux working on an unsupported or experimental distribution:

Test thoroughly using the checklist above
Document any distribution-specific requirements
Submit a PR with:
- Distribution detection logic (if needed)
- Package installation commands
- Any patches or workarounds required
- Update to this compatibility document

20 KiB Raw Blame History

Linux Distribution Compatibility

Implementation Status

Technical Implementation

Dynamic GI_TYPELIB_PATH Detection

Wrapper Scripts

Desktop Entry

Officially Supported Distributions

Experimental Support

Not Supported

Requirements by Distribution

Ubuntu/Debian-based

Debian-specific notes

Fedora/RHEL-based

Arch Linux-based

openSUSE

Gentoo

Alpine Linux

Void Linux

Solus

Mageia

PyPI, pip, and pipx Installation

Important: Install System Packages First

Ubuntu/Debian

Fedora

Arch Linux

openSUSE

pip Installation Steps

pipx Installation Steps

Why System Packages Are Required

Troubleshooting pip/pipx Installation

Recommended Alternative

Text Injection Tools

For X11

For Wayland

Installation by Distribution

Manual Installation

Desktop Environment Compatibility

Autostart Compatibility

Display Server

Architecture Support

Reporting Issues

Testing Checklist

Pre-Install

Installation

Post-Install

Known Issues to Watch For

Contributing Compatibility Fixes

See Also

20 KiB

Raw Blame History