# Installation guide

How to install Voculinux. Short overview: [project README](../README.md).

Voculinux is published only as a signed Void Linux xbps repository (glibc, x86_64).
Other install channels are not published for it. Source checkouts are a developer path.

| Path | When to use |
|------|-------------|
| [Void package](#install) | Void Linux, glibc, x86_64: the published install |
| [Source checkout](#from-a-source-checkout-developers) | Contributors and developers |
| [Update](#update) | Upgrading an existing install |
| [Troubleshooting](TROUBLESHOOTING.md) | Tray, audio, injection, models |

## Install

### Void Linux (signed xbps repo)

Void Linux **glibc `x86_64` only**. Each version tag publishes a signed
personal xbps repository to the project's rolling `latest` release:
binary packages (`*.x86_64.xbps`) with their signatures, the signed
repository metadata (`x86_64-repodata`), and the client key
(`FINGERPRINT` plus the fingerprint-named `.plist`). The registration URL
below always serves the newest release.

This is a **third-party repository** — it is published by this project,
not by upstream Void Linux, and its packages are built from the
templates in `packaging/void/srcpkgs/`. Details: [packaging/void/README.md](../packaging/void/README.md).

Repository key, RSA 4096. Pin this fingerprint:

```text
fa:d1:00:32:ce:b1:b9:fd:73:05:05:76:75:54:37:25
```

```bash
# as root on the Void system: trust the key, register the repository, install
curl -fsSL -o '/var/db/xbps/keys/fa:d1:00:32:ce:b1:b9:fd:73:05:05:76:75:54:37:25.plist' \
  https://git.bongbetic.com/xavierk/voculinux/raw/branch/main/packaging/void/repository-key.plist
echo 'repository=https://git.bongbetic.com/xavierk/voculinux/releases/download/latest' > /etc/xbps.d/voculinux.conf
xbps-install -S voculinux
```

The key file is named by its fingerprint, so xbps finds it on the first
sync and asks nothing. If xbps still shows a fingerprint prompt, answer
`N` unless it reads exactly the fingerprint above (it must also match the
`FINGERPRINT` file attached to the release). Do not add `-y` to the first
sync: it would accept an unknown key without asking.

### Speech engines

| Engine | When to use |
|--------|-------------|
| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA |
| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA |
| **Faster Whisper** | CPU-friendly Whisper via CTranslate2 / INT8 |
| **VOSK** | Low RAM / minimal footprint |
| **Parakeet** | CPU; NVIDIA NeMo ASR via sherpa-onnx; 25 European languages |
| **Remote API** | Offload to a server you configure |

The xbps package does not include the optional engines (Faster Whisper, Whisper,
VOSK, Parakeet) or the Silero VAD runtime (`onnxruntime`). Add them from your own
Python environment, as the package's install message describes. Models download
on first run.

### After installation

```bash
voculinux                 # from the xbps package, on your PATH
```

You can also launch Voculinux from your application menu.

### Wayland hotkeys need the input group

On Wayland, the default Right Alt shortcut reads keyboard devices through evdev. Your user
needs `input` group membership, or the evdev hotkey backend cannot open `/dev/input` devices:

```bash
sudo usermod -aG input $USER   # then log out and back in
```

Joining `input` gives read access to every keyboard and pointer device. X11 does not need
this step. The package does not add the group for you; its install message says the same.

### Audio capture

The package captures audio through PipeWire (`pw-record`, `pw-dump`) and PortAudio.
PipeWire must be running in your session.

### CLI

```bash
voculinux --help
voculinux --version
voculinux --debug
voculinux --engine whisper_cpp
voculinux --engine whisper
voculinux --engine vosk
voculinux --engine parakeet
voculinux --engine remote_api
voculinux --model tiny
voculinux --model medium.en-q5_0
voculinux --model large-v3-turbo
voculinux --wayland
voculinux --start-minimized
```

The optional engines (`whisper`, `vosk`, `parakeet`) need their Python packages in your own
environment first; see [Speech engines](#speech-engines).

### Autostart

**Start on Login** writes an XDG autostart desktop entry (`~/.config/autostart/`). It does
not install a systemd unit. Enable from the first-run dialog, tray menu, or Settings.

## From a source checkout (developers)

Source checkouts are for development. For the two-venv layout and the dev workflow, see
[CONTRIBUTING.md](../CONTRIBUTING.md).

```bash
git clone https://git.bongbetic.com/xavierk/voculinux.git
cd voculinux
./install.sh --dev
source venv/bin/activate
voculinux
```

`./install.sh --help` lists the installer flags. The installer needs Python 3.11+ and the
distribution's PyGObject. Distribution notes: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md).

## Requirements

| | |
|--|--|
| **OS** | Void Linux (glibc, x86_64) for the published package. Source checkouts: see [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md) |
| **Python** | 3.11 or newer |
| **Display** | X11 or Wayland |
| **Hardware** | Microphone; GPU optional (Vulkan) |
| **Disk** | ~200MB with default whisper.cpp model |
| **RAM** | 4GB minimum; 8GB comfortable |

The Void package depends on Void's own Python, PyGObject and GTK 3 packages. A source
checkout needs Python 3.11+ with PyGObject from the system (`python3-gobject` on Void).
Ubuntu 22.04 (Python 3.10) and Debian 11 (Python 3.9) are below that floor.

### GPU (optional)

whisper.cpp uses Vulkan when available (AMD, Intel, NVIDIA). The Void build enables Vulkan
by default. Check the driver with `vulkaninfo --summary`.

## Data locations (XDG)

| Path | Purpose |
|------|---------|
| `~/.config/voculinux/` | Configuration |
| `~/.local/share/voculinux/` | Data and speech models (downloaded on first use) |
| `~/.config/autostart/` | Start on Login entry |
| `/usr/share/applications/voculinux.desktop` | Desktop entry, installed by the package |
| `/usr/share/icons/hicolor/scalable/apps/` | Icons, installed by the package |

Source installs put the desktop entry and icons under `~/.local/share/applications/` and
`~/.local/share/icons/hicolor/scalable/apps/` instead.

## whisper.cpp (default engine)

Default engine: C++ Whisper port with Vulkan GPU support and lower install cost than the
PyTorch Whisper stack.

| Size | Approx. | Use |
|------|---------|-----|
| tiny | ~74MB | Fast dictation (default) |
| base | ~141MB | Balance |
| small | ~465MB | Better accuracy |
| medium | ~1.5GB | High accuracy |
| large | ~3.0GB | Best accuracy |

In Settings → Speech Model, simple setup steers language and speed/accuracy. Expand
**Advanced** for engine, **Model Size**, and **Specialization** (multilingual, English-only,
quantized, Turbo, legacy large). More detail: [USER_GUIDE.md](USER_GUIDE.md).

Switch engines in Settings → Speech Model (Advanced), or edit `~/.config/voculinux/config.json`
(`engine`: `whisper_cpp` | `whisper` | `vosk` | `parakeet` | `remote_api`).

## Uninstall

Remove the Void package:

```bash
sudo xbps-remove voculinux
```

This removes the package files only. Your configuration, downloaded models and autostart
entry live in your home directory and stay until you delete them:

```bash
rm -rf ~/.config/voculinux ~/.local/share/voculinux
rm -f ~/.config/autostart/voculinux.desktop
```

From a source checkout, `./uninstall.sh` removes the install and that checkout's `venv/`,
`build/`, `dist/`, and Python bytecode. `--keep-config` and `--keep-data` leave
`~/.config/voculinux` and `~/.local/share/voculinux` in place.

```bash
./uninstall.sh
./uninstall.sh --keep-config
./uninstall.sh --keep-data
```

## Update

Packaged installs update through xbps. See [UPDATE.md](UPDATE.md).

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

## More documentation

| Doc | Contents |
|-----|----------|
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common failures and fixes |
| [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md) | Support matrix and source-checkout notes |
| [USER_GUIDE.md](USER_GUIDE.md) | Day-to-day use |
| [SUPPORT.md](../SUPPORT.md) | Where to get help |
| [Documentation index](README.md) | Full list |