xavierk
4171567fd7
User-facing docs, About page and website now point at the fork and the Void xbps repository, with one credit line to upstream Vocalinux. Channels this fork does not publish are removed from navigation.
229 lines
8.0 KiB
Markdown
229 lines
8.0 KiB
Markdown
# 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 |
|