# 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.18.5-478061)](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.18.5) [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. **Current release:** [v0.18.5](https://git.bongbetic.com/xavierk/voculinux/releases/tag/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](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](https://voculinux.com/screenshots/). ### 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](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 ``` 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 ```bash voculinux # from the xbps package, on your PATH ``` You can also launch Voculinux from your application menu. ### 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) | 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). ## 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 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](SECURITY.md). ## Development ```bash 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](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](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`.