xavierk
2a5710334b
Mod+Shift+D is Move Column Right in Dank Material Shell's niri binds (dms/binds.kdl), so the shipped example competed with it silently. The toggle moves to Mod+Shift+M, which is free in niri's stock binds and in DMS's binds. The start and stop examples move off Mod+Shift+E, which is stock niri's quit, to Mod+Shift+S and Mod+Shift+X. niri validate rejects a key bound twice in one binds block but not across blocks, so validation cannot show a conflict. The docs now give a grep over the config tree and niri's embedded stock binds for checking a key before binding it. The overlay pointer is corrected to Mod+Shift+Slash. A test pins the doc and the include to one toggle key that is not Mod+Shift+D. Fixes #45
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.18.5. Patch: a stop that races a recording start can no longer leave the mic recording forever, keyboards stay alive through suspend and the GNOME lock screen, Ctrl+mouse-wheel zoom works again, Dictation Pad and Settings stop travelling workspaces together, and paste-injection copies are marked sensitive for clipboard history on wl-clipboard 2.2+. 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.
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.