xavierk
f9792219e3
Quick start with upgrade, first run, dictation, niri and debug steps. New GPU and CUDA section stating that the published package uses Vulkan and CPU and that CUDA is a local-build option. The old name now appears only in the Origin credit line.
Voculinux turns speech into typed text in whatever app has focus. It is a free, AGPL-3.0-licensed desktop app for X11 and Wayland. After you download a model, local engines (whisper.cpp by default, plus OpenAI Whisper, Faster Whisper, VOSK, and Parakeet) run speech-to-text on your machine. An optional remote HTTP API is off unless you configure it.
No account is required. Models download once. After that, speech-to-text stays on your machine. It is built for Void Linux, with niri and the Dank Material Shell in mind, and is inspired by an earlier project credited under Origin.
Current release: v0.19.1, a patch on v0.19.0 that warns when a leftover launcher from the upstream project shadows Voculinux. v0.19.0 was the first Voculinux release: a Void Linux package from the signed xbps repository, niri and Dank Material Shell support, a model default chosen by free GPU memory, and a fix that keeps system-audio capture from ever opening the microphone. Details: docs/UPDATE.md.
Features
- On-device after model download: Local engines; speech-to-text stays on your machine
- X11 and Wayland: Text injection via xdotool, IBus, wtype, ydotool, or clipboard fallback
- Several engines: whisper.cpp (default), OpenAI Whisper, Faster Whisper, VOSK, Parakeet, plus optional remote HTTP API or local gateway from Settings (not on-device)
- GPU acceleration: Vulkan for AMD, Intel, and NVIDIA with whisper.cpp, with a CPU fallback. CUDA is a local-build option, not part of the package; see GPU and CUDA
- Toggle or push-to-talk: New installs default to hold Right Alt; existing configs keep their shortcut
- System tray + settings: Searchable sidebar, Speech Model simple setup with Advanced as an island, status icons, audio feedback
- Start on login: XDG autostart (desktop session, not a systemd service)
- Packaging: signed Void Linux xbps repository (glibc, x86_64). No other channel is published for Voculinux
Screenshots
Voculinux in action. Full gallery on the website screenshots page.
Product
 Real-time voice-to-text transcription |
 System tray with listening indicator |
 About & Updates in Settings |
 Log viewer for debugging |
Settings
 Speech Engine |
 Recognition |
 Audio |
 Performance |
 General |
 Advanced |
 Floating overlay while listening (green) |
 Floating overlay while processing (amber) |
Install
Voculinux is published only as a signed Void Linux xbps repository. Other
channels (AUR, AppImage, .deb / .rpm, Flatpak, Snap, Nix, PyPI and the
upstream install script) are not published for Voculinux.
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
After that, Voculinux upgrades with the rest of the system:
sudo xbps-install -Su # upgrades Voculinux together with everything else
xbps-query -R voculinux # shows the version the repository serves
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, CPU otherwise |
| Whisper (OpenAI) | PyTorch path; NVIDIA/CUDA with a CUDA PyTorch you install yourself |
| 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 # start the tray app; it also appears in your application menu
voculinux --toggle # start or stop dictation from a keybind or script
- First run: the tray icon appears first, then the speech model loads in the
background. If no model is present, it downloads once (a few hundred MB to
about 1 GB, checksum-verified). The default is chosen from your free memory:
large-v3-turbo-q8_0, thenq5_0, thensmallas memory gets tighter. - Dictate: focus any text field, hold Right Alt, speak, release. The text is typed at the cursor.
- Hands-free: switch to toggle mode in Settings, or bind
voculinux --toggle. - On niri: copy the example keybind pack and read docs/NIRI.md.
Typing goes straight to the cursor (
wtype), with no permission prompt. The tray needs a StatusNotifier host, which Dank Material Shell provides. - Something wrong? Run
voculinux --debug, then see Troubleshooting.
Quit and relaunch Voculinux after an upgrade so the running tray uses the new version.
Leftover launchers from an earlier install
Launchers left by an earlier install of the upstream project can point at a Python environment that no longer exists. They start nothing, yet they appear next to Voculinux in the application menu. Voculinux logs and shows one notice that names those files. It never deletes or changes them, so remove the ones it names yourself. Keep any launcher that still starts a working install.
From a source checkout (developers)
git clone https://git.bongbetic.com/xavierk/voculinux.git
cd voculinux
./install.sh --dev
See CONTRIBUTING.md for the two-venv layout and the dev workflow.
Requirements
| OS | Linux. The published package targets Void Linux (glibc, x86_64) |
| Python | 3.11 or newer |
| Display | X11 or Wayland |
| Hardware | Microphone; GPU optional (Vulkan, any vendor) |
Python 3.11+ is required, with PyGObject from the system (python3-gi or the Void python3-gobject package). Ubuntu 22.04 (Python 3.10) and Debian 11 (3.9) are below that floor. Source-checkout distribution notes: docs/DISTRO_COMPATIBILITY.md.
GPU and CUDA
Voculinux is not a CUDA build. The published Void package accelerates whisper.cpp with Vulkan, plus CPU code paths, and it does not ship CUDA. Void has no CUDA toolkit package, so the package cannot be built against one.
| Where | What runs | Notes |
|---|---|---|
| Published Void package, NVIDIA GPU | Vulkan | Needs the NVIDIA driver, which provides the Vulkan device. This is the supported NVIDIA path, tested on an RTX 2050 (4 GB) |
| Published Void package, AMD or Intel GPU | Vulkan | Needs the Mesa Vulkan driver. Software Vulkan devices are skipped |
| Published Void package, no usable GPU | CPU | The best instruction-set variant (AVX2 and others) is loaded at run time |
Local rebuild of pywhispercpp with GGML_CUDA=1 and a toolkit you installed by hand |
CUDA | Works, but unsupported: you maintain it, and the package will not replace it on upgrade without a fresh rebuild |
| OpenAI Whisper engine (PyTorch) in your own Python environment | CUDA | Not included in the package; you install a CUDA PyTorch yourself |
| Faster Whisper engine in your own Python environment | CPU (INT8), CUDA optional | Not included in the package |
How the whisper.cpp engine decides: it uses the backends the installed
pywhispercpp was actually built with, not what the machine could run. When a
CUDA-built pywhispercpp is installed and a complete toolkit is found (nvcc,
the runtime header and libcudart, with GPU compute capability 7.0 or newer),
CUDA ranks first; otherwise the order is Vulkan, then CPU. The model size then
follows the free memory of the chosen backend, with its own thresholds (CUDA needs
somewhat more than Vulkan for the same model, per the measurements in
docs/PERF_BASELINE_PROTOCOL.md). To see which
backend loaded, run voculinux --debug and read the startup log.
Usage
Dictation
- Push-to-talk (default on new installs): hold Right Alt (Option on Mac-layout keyboards) and speak
- Speak into the microphone
- Release to stop, or switch to Toggle mode in Settings (double-tap a key to start/stop)
Existing configs keep their saved shortcut.
Voice commands
English phrases always work. With a non-English recognition language, matching punctuation / line-break phrases in that language are also recognized (Italian virgola / punto, French virgule / point, etc.).
| Command | Action |
|---|---|
| "new line" | Line break |
| "period" / "full stop" / "dot" | . |
| "comma" | , |
| "question mark" | ? |
| "exclamation mark" | ! |
| "delete that" | Delete last sentence |
| "capitalize" | Capitalize next word |
CLI
voculinux --help
voculinux --version
voculinux --debug
voculinux --engine whisper_cpp # default
voculinux --engine whisper
voculinux --engine faster_whisper
voculinux --engine vosk
voculinux --engine parakeet
voculinux --engine remote_api
voculinux --model medium
voculinux --model medium.en-q5_0 # exact whisper.cpp variant
voculinux --model large-v3-turbo
voculinux --wayland
voculinux --start-minimized
Autostart
Start on Login creates an XDG autostart desktop entry (~/.config/autostart/). It does not install a systemd unit. Enable from the first-run dialog, tray menu, or Settings.
Configuration
Stored at ~/.config/voculinux/config.json. Prefer the Settings dialog for day-to-day changes. Settings → Speech Model starts with a simple setup; expand Advanced for engine, size, and specialization. Set post_processing.script_path to an executable to transform each transcription result (stdin → stdout) before it is injected; leave empty to disable.
Neural VAD (Silero) is used when onnxruntime is available. The xbps package does not pull it in; add onnxruntime from your own Python environment.
Documentation
| Document | Description |
|---|---|
| Installation | Void xbps repository and running |
| Troubleshooting | Common failures |
| User guide | Dictation, engines, models, tips |
| Update guide | Upgrade steps and release notes |
| Changelog | Release history pointers |
| Support | Where to get help |
| Distribution compatibility | Distro matrix and session notes |
| Remote HTTP API | Offload transcription to a server |
| Contributing | Dev setup, style, PR process |
| Security | Supported versions and vulnerability reporting |
| Docs index | Full documentation map |
Privacy and security
- Local engines process audio on-device after you download a model; no account required
- Optional remote API is off by default and only used when you configure a server
- Model downloads are checked against pinned checksums
Report vulnerabilities privately per SECURITY.md.
Development
git clone https://git.bongbetic.com/xavierk/voculinux.git
cd voculinux
./install.sh --dev
source venv/bin/activate
pytest
voculinux --debug
See CONTRIBUTING.md for the two-venv layout, just recipes, and PR guidelines.
Roadmap
Shipped: graphical settings, multi-language support, whisper.cpp default, Vulkan GPU, Wayland/IBus, in-app update checker, Parakeet and Faster Whisper engines, Void Linux xbps packaging.
Planned:
- Application-specific voice commands
- User-customizable voice command map
Origin
Voculinux is inspired by Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux
It is an independent project for Void Linux. Its source, issues and releases live on the fork's own host.
Contributing
Bug reports, docs, and code are welcome. Start with CONTRIBUTING.md and open issues.
Repository
The source, issues, pull requests, and releases live at https://git.bongbetic.com/xavierk/voculinux. Open issues and pull requests there.
License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
You may use, study, modify, and redistribute the software under AGPL-3.0. If you run a modified version as a network service, AGPL also requires that you make the corresponding source available.
Optional Orukeet model
With the Parakeet engine installed, Settings → Speech Model → Parakeet also
offers orukeet-v0.1.0. It uses the existing local sherpa-onnx recognizer for
25 European languages; the recommended Parakeet model and default whisper.cpp
engine stay unchanged.
The download comes from a pinned revision of oruk/orukeet on Hugging Face. Voculinux checks every file against its bundled SHA-256 pins and checks the publisher's release manifest against those same pins. The manifest download participates in Hugging Face's normal model-download accounting. Cached recognition works offline and does not send audio or usage events. The model occupies about 641 MiB; its CC BY-SA 4.0 weights license and NVIDIA attribution are included.
Optional Underdog Bark 3.0 models
Settings → Speech Model → Parakeet also offers two builds of
Underdog Bark 3.0, an
English fine-tune of Parakeet TDT 0.6B v3 (CC BY 4.0): bark-3.0 (int8, 653 MiB)
and bark-3.0-int4 (4-bit, 379 MiB, about half the memory, slower). Both come
from a pinned revision of
velddev/Underdog-Bark-3.0-sherpa-onnx,
an unofficial sherpa-onnx conversion not made or endorsed by Conway Research.
They run on the existing sherpa-onnx recognizer, every file is checked against
its bundled SHA-256 pin, and the downloads include the license and attribution
notice.
Choose one for English dictation of conversational speech, bark-3.0-int4 when
memory is tight; for read or multilingual speech keep v3-european.