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
195 lines
6.7 KiB
Markdown
195 lines
6.7 KiB
Markdown
# Manual installation and PyPI
|
|
|
|
Use this when the [recommended installer](INSTALL.md) 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`](../scripts/distro-package-map.yaml).
|
|
Its generated shell module is committed so installations do not need a YAML
|
|
parser.
|
|
|
|
Related: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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+
|
|
|
|
```bash
|
|
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](DISTRO_COMPATIBILITY.md).
|
|
|
|
### Fedora
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](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`.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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](INSTALL.md#running-voculinux)
|
|
- Engines and models: [USER_GUIDE.md](USER_GUIDE.md)
|
|
- Failures: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|