xavierk
8b842e5712
After the tray is up, Voculinux looks for a user-level vocalinux.desktop or ~/.local/bin/vocalinux(-gui) whose target is gone. It logs them and shows one notification naming the files to remove. It never changes the user's files, and a working upstream install is left alone. The README gains a migration note. Fixes #52
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.
Current release: v0.19.0. 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
- 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
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.
Migrating from a previous Vocalinux install
A previous Vocalinux install can leave launcher files behind. Those that point at a Python environment which no longer exists start nothing, yet they appear next to Voculinux as an old Vocalinux entry, and choosing one does nothing. Voculinux logs and shows one notice that names those files. It never deletes or changes them, so remove them yourself:
rm -f ~/.local/share/applications/vocalinux.desktop # old Vocalinux menu entry
rm -f ~/.local/bin/vocalinux ~/.local/bin/vocalinux-gui # old Vocalinux wrapper scripts
Keep any launcher that still starts a working install. Voculinux only reports launchers that cannot start.
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) |
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.
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 Voca 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
python -m vocalinux.main --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 a hard fork of Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux
Voculinux is that project's fork 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.