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.
8.0 KiB
Installation guide
How to install Voculinux. Short overview: project README.
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 | Void Linux, glibc, x86_64: the published install |
| Source checkout | Contributors and developers |
| Update | Upgrading an existing install |
| Troubleshooting | 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.
Repository key, RSA 4096. Pin this fingerprint:
fa:d1:00:32:ce:b1:b9:fd:73:05:05:76:75:54:37:25
# 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
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:
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
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.
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.
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.
Requirements
| OS | Void Linux (glibc, x86_64) for the published package. Source checkouts: see 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.
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:
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:
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.
./uninstall.sh
./uninstall.sh --keep-config
./uninstall.sh --keep-data
Update
Packaged installs update through xbps. See UPDATE.md.
sudo xbps-install -Su voculinux
More documentation
| Doc | Contents |
|---|---|
| TROUBLESHOOTING.md | Common failures and fixes |
| DISTRO_COMPATIBILITY.md | Support matrix and source-checkout notes |
| USER_GUIDE.md | Day-to-day use |
| SUPPORT.md | Where to get help |
| Documentation index | Full list |