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

6.7 KiB

Raw Blame History

Manual installation and PyPI

Use this when the recommended installer is not a fit, or you want an explicit package list. Prefer ./install.sh for a normal desktop install.

The commands below are human-readable baselines for manual installs. The installer's authoritative package inventory, including build helpers and fallbacks, is scripts/distro-package-map.yaml. Its generated shell module is committed so installations do not need a YAML parser.

System packages by distribution

Install desktop/system dependencies before creating a venv or running pip install voculinux. Pip cannot install GTK typelibs, AppIndicator, PortAudio, or text-injection tools.

Debian 11 and earlier are unsupported; the Debian instructions start at Debian 12, which is the oldest release with the required Python 3.11.

Ubuntu

sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
    libgirepository1.0-dev libcairo2-dev portaudio19-dev \
    build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
    wget curl unzip

# Tray: older Ubuntu → gir1.2-appindicator3-0.1
#        newer Ubuntu → gir1.2-ayatanaappindicator3-0.1
sudo apt install -y gir1.2-ayatanaappindicator3-0.1

sudo apt install -y xdotool                       # X11
sudo apt install -y wtype wl-clipboard xclip xsel # Wayland helpers

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

Debian 12

sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
    libgirepository1.0-dev libcairo2-dev portaudio19-dev \
    build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
    wget curl unzip \
    gir1.2-ayatanaappindicator3-0.1 \
    xdotool wtype wl-clipboard xclip xsel

Debian 13+

sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
    libgirepository-2.0-dev libcairo2-dev portaudio19-dev \
    build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
    wget curl unzip \
    gir1.2-ayatanaappindicator3-0.1 \
    xdotool wtype wl-clipboard xclip xsel

Debian notes (OpenSSL build deps, ydotool, etc.): DISTRO_COMPATIBILITY.md.

Fedora

sudo dnf install -y \
    python3-pip python3-devel python3-virtualenv \
    python3-gobject gtk3 ibus-devel libayatana-appindicator-gtk3 \
    gobject-introspection-devel portaudio-devel cairo-devel \
    gcc gcc-c++ make pkg-config cmake patchelf \
    wget curl unzip xdotool wtype wl-clipboard xclip xsel

Arch Linux

Prefer the AUR package (yay -S voculinux). Manual packages:

sudo pacman -S --needed \
    python-pip python-gobject gtk3 ibus \
    libayatana-appindicator gobject-introspection \
    python-cairo portaudio python-virtualenv \
    base-devel pkg-config cmake patchelf \
    wget curl unzip xdotool wtype wl-clipboard xclip xsel

openSUSE Tumbleweed

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 ibus typelib-1_0-IBus-1_0 \
    typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
    typelib-1_0-Notify-0_7 libnotify4 \
    gobject-introspection-devel portaudio-devel pkg-config cmake \
    gcc gcc-c++ make patchelf \
    wget curl unzip xdotool wtype wl-clipboard xclip xsel

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

-devel packages are headers for compiling native Python deps, not "beta" packages. If ${PYVER}-virtualenv is missing, try ${PYVER}-venv.

Other distributions

Gentoo, Alpine, Void, Solus, Mageia: DISTRO_COMPATIBILITY.md.

Install from a git checkout

Use the system Python (/usr/bin/python3). Distro PyGObject (gi) is compiled for that interpreter only, so a venv from pyenv/conda/uv cannot import it even with --system-site-packages.

cd voculinux
/usr/bin/python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install --upgrade pip setuptools wheel

pip install .                 # standard
pip install ".[whisper]"      # OpenAI Whisper extra
pip install ".[faster_whisper]"  # Faster Whisper (CTranslate2)
pip install ".[parakeet]"     # Parakeet (sherpa-onnx)
pip install ".[vad]"          # neural VAD
pip install -e ".[dev,vad]"   # development

Desktop integration

mkdir -p ~/.config/voculinux \
         ~/.local/share/voculinux/models \
         ~/.local/share/applications \
         ~/.local/share/icons/hicolor/scalable/apps

cp voculinux.desktop ~/.local/share/applications/
VENV_PATH=$(realpath venv/bin/voculinux)
sed -i "s|^Exec=voculinux|Exec=$VENV_PATH|" ~/.local/share/applications/voculinux.desktop

cp resources/icons/scalable/*.svg ~/.local/share/icons/hicolor/scalable/apps/
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor

Install from PyPI

Same system packages as above, then:

python3 -m venv ~/.local/share/voculinux-pypi/venv --system-site-packages
source ~/.local/share/voculinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install voculinux
# vosk engine: pip install "voculinux[vosk]"
# faster-whisper: pip install "voculinux[faster_whisper]"
# parakeet engine: pip install "voculinux[parakeet]"
voculinux

--system-site-packages lets the venv use distro GTK bindings (python3-gi). Building PyGObject from pip is often painful on Ubuntu/Debian.

If the app starts but no speech model is present, open Settings and download a model, or use the official installer which downloads the default model during setup.

pipx

# After system packages are installed:
pipx install voculinux
voculinux

pipx still cannot install system desktop libraries. Install those first with your package manager.

Why system packages are required

Voculinux uses GTK3, AppIndicator/Ayatana, PortAudio, and tools such as xdotool, wtype, and clipboard utilities. Those come from the distro. PyPI only supplies Python packages and wheels.

After install

Run: INSTALL.md
Engines and models: USER_GUIDE.md
Failures: TROUBLESHOOTING.md

6.7 KiB Raw Blame History