Voculinux # Voculinux **Voice dictation for Linux** [![Void Linux](https://img.shields.io/badge/Void%20Linux-glibc%20x86__64-478061)](#void-linux-signed-xbps-repo) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Privacy: on-device](https://img.shields.io/badge/privacy-on--device-success)](#privacy-and-security) [![X11 & Wayland](https://img.shields.io/badge/display-X11%20%7C%20Wayland-lightgrey)](#features) [![Release](https://img.shields.io/badge/release-v0.19.1-478061)](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.19.1) [Website](https://voculinux.com) · [Install](#install) · [Docs](#documentation) · [Releases](https://git.bongbetic.com/xavierk/voculinux/releases) · [Issues](https://git.bongbetic.com/xavierk/voculinux/issues)
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](#origin). **Current release:** [v0.19.1](https://git.bongbetic.com/xavierk/voculinux/releases/tag/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](#void-linux-signed-xbps-repo), 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](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](#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](https://voculinux.com/screenshots/). ### Product
Transcription in Action
Real-time voice-to-text transcription 		System Tray
System tray with listening indicator
About View
About & Updates in Settings 		Log Viewer
Log viewer for debugging
### Settings
Speech Engine settings
Speech Engine 		Recognition settings
Recognition 		Audio settings
Audio
Performance settings
Performance 		General settings
General 		Advanced tuning and settings
Advanced
Dictation overlay listening
Floating overlay while listening (green) 		Dictation overlay processing
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](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 ``` After that, Voculinux upgrades with the rest of the system: ```bash 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 ```bash voculinux # start the tray app; it also appears in your application menu voculinux --toggle # start or stop dictation from a keybind or script ``` 1. **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`, then `q5_0`, then `small` as memory gets tighter. 2. **Dictate:** focus any text field, hold **Right Alt**, speak, release. The text is typed at the cursor. 3. **Hands-free:** switch to toggle mode in Settings, or bind `voculinux --toggle`. 4. **On niri:** copy the example keybind pack and read [docs/NIRI.md](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. 5. **Something wrong?** Run `voculinux --debug`, then see [Troubleshooting](docs/TROUBLESHOOTING.md). 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) ```bash git clone https://git.bongbetic.com/xavierk/voculinux.git cd voculinux ./install.sh --dev ``` See [CONTRIBUTING.md](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](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](docs/PERF_BASELINE_PROTOCOL.md)). To see which backend loaded, run `voculinux --debug` and read the startup log. ## Usage ### Dictation 1. **Push-to-talk (default on new installs):** hold Right Alt (Option on Mac-layout keyboards) and speak 2. Speak into the microphone 3. **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 ```bash 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](docs/INSTALL.md) | Void xbps repository and running | | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common failures | | [User guide](docs/USER_GUIDE.md) | Dictation, engines, models, tips | | [Update guide](docs/UPDATE.md) | Upgrade steps and release notes | | [Changelog](CHANGELOG.md) | Release history pointers | | [Support](SUPPORT.md) | Where to get help | | [Distribution compatibility](docs/DISTRO_COMPATIBILITY.md) | Distro matrix and session notes | | [Remote HTTP API](docs/HTTP_REMOTE.md) | Offload transcription to a server | | [Contributing](CONTRIBUTING.md) | Dev setup, style, PR process | | [Security](SECURITY.md) | Supported versions and vulnerability reporting | | [Docs index](docs/README.md) | 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](SECURITY.md). ## Development ```bash git clone https://git.bongbetic.com/xavierk/voculinux.git cd voculinux ./install.sh --dev source venv/bin/activate pytest voculinux --debug ``` See [CONTRIBUTING.md](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](CONTRIBUTING.md) and [open issues](https://git.bongbetic.com/xavierk/voculinux/issues). - [Report a bug](https://git.bongbetic.com/xavierk/voculinux/issues/new) - [Request a feature](https://git.bongbetic.com/xavierk/voculinux/issues/new) ## 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](LICENSE)). 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](https://huggingface.co/oruk/orukeet). 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](https://huggingface.co/ConwayResearch/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](https://huggingface.co/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`.