dca937fc21
* feat(dictionary): combined custom dictionary with corrections Rebased onto latest main (conflict-resolution squash for PR #818). * fix(dictionary): stabilize the terms and corrections file contracts - corrections_path() stays at the fixed config_dir() location promised by the file contract instead of following a custom or --dictionary-file terms path, which could strand or duplicate corrections; a leftover file beside the terms file is still read once and copied over. - _atomic_write() preserves the replaced file's permission mode instead of resetting it to the process umask. - build_initial_prompt() streams terms and stops at the configured cap instead of reading and processing the whole file for every segment. * fix(settings): restore the selected dictionary pane after a search Searching can auto-switch the Custom Dictionary management pane to reveal a match, but clearing the query only restored widget visibility. Record the pane selection in the search baseline snapshot and restore it alongside the previous page so users return to the pane they chose. * fix(dictionary): close the remaining custom dictionary file-contract gaps - A --dictionary-file session override no longer imports a corrections file found beside the override into the standard config directory; the override scopes to terms only. - Terms reads validate the whole file before yielding: corrupt UTF-8 mid-file now yields no terms at all, matching the invalid status Settings reports instead of leaking a partial dictionary to recognition. - The terms read is bounded by MAX_TERMS_FILE_BYTES (1 MiB); a larger file is invalid everywhere with a dedicated status instead of being read on every segment. * fix(dictionary): keep usable terms prefix on oversized files and legacy corrections under overrides * fix(dictionary): cap yielded terms and keep added terms visible on oversized files * fix(dictionary): keep added terms visible without dropping scanner-owned lines * fix(dictionary): keep oversized terms manageable and honor mid-search pane switches - terms list gains a Show all / Show first 500 toggle; adding a term beyond the cap auto-expands so the new row renders with a Remove button instead of being invisible until the file is hand-edited - a manual dictionary pane switch during an active search drops the saved pre-search pane so clearing the query no longer rolls back the user's newer selection - annotate the new settings tests and type model_info so the parakeet branch stops adding fresh mypy errors * fix(settings): do not auto-expand terms on add past display cap Rebuilding up to thousands of term rows on the UI thread stalls the dialog; the overflow button already shows the true count, so the added term stays one click away. * test(dictionary): stub segment_callbacks on bare manager for history dispatch * fix(dictionary): stream oversized terms files when building the prompt build_initial_prompt decoded the whole 1 MiB read window before every transcription segment even though it only needs the first max_words terms. _iter_terms_for_prompt now reads oversized files line by line and stops at the prompt limit, keeping the same contract: complete leading lines only, invalid UTF-8 inside the usable window yields nothing. * fix(history): only the ended session's worker may extend its snippet A late segment could extend the newest history entry regardless of which session produced it, so a worker finishing after the next dictation session leaked its text into that session's entry. Track the worker that owned the ended session and require late segments to arrive on the same thread before merging; anything else forms its own snippet. * fix(speech): transcribe queued segments the reload worker never drained The recognition worker can exit during stop_recognition's bounded audio-thread join, so the released key's final buffer lands in the queue after the worker is gone and was silently dropped when the reload teardown replaced the queue. Drain whatever remains before swapping it — except on capture failure or an explicit cancel, which still discard the session's leftovers. * fix(settings): build term rows in idle slices and pin hidden additions Two problems shared one cause. Rebuilding up to 4096 rows synchronously stalled the dialog, and a term appended past the 500-row cap reported success while staying invisible. Rows now build in bounded GLib idle slices guarded by a refresh token, and a saved term outside the visible window is pinned to the top of the capped list until it disappears or becomes visible on its own. Adding under "show all" scrolls to the new term instead. * test(engine): annotate new test method return types * fix(ci): match a candidate row that leads the latest track block snapcraft status normally prints candidate as a continuation line under the latest track (channel in column 1). If candidate ever leads the track block it rides the track line instead (channel in column 3), and the resolver missed it and refused to promote. Match both layouts in the resolve and the pre-release re-verify. * fix(dictionary): bound prompt reads and scroll to landed terms - _iter_terms_for_prompt now reads each line via readline() capped by the remaining byte window, so an overlong line can never pull more than MAX_TERMS_FILE_BYTES into memory - the prompt path keeps decoding every complete line inside the usable window after the term limit is collected, so invalid UTF-8 anywhere in the window still yields no terms and matches the reader's invalid status - under "show all" Settings scrolls to the index where an added term landed (prepended or appended), verified against the row's label, instead of always scrolling to the end * fix(history,reload): keep late-segment ownership and drain stamped tuples - Track session_workers_seen so a worker from an earlier session can never merge into a newer snippet while a session is open - Unpack (segment, language) queue tuples in _transcribe_queued_segments; passing the tuple as audio raised TypeError and lost final speech - Refuse 'delete that' when a manual pad edit blurred segment boundaries - Translate term-row coordinates into the scrolled card's space so the scroll actually reaches rows below the fold - Type _on_dictionary_pane_changed's varargs * style: drop unneeded nonlocal for mutated worker set --------- Co-authored-by: Graham <graham@thegeeky.ninja>
Vocalinux 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 Voca account is required. Models download once. After that, speech-to-text stays on your machine.
Current release: v0.17.0. Minor: Faster Whisper and Parakeet engines, Speech Model simple setup, first-run system language, Snap with native Wayland typing, Flatpak bundles on the GitHub Release. 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 VocaGateway 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: install script, AppImage, AUR, PyPI, Snap (
--edge), Flatpak (release bundles and local build; not on Flathub)
Screenshots
Vocalinux 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
Recommended (interactive installer)
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
bash /tmp/vl.sh
Prefer to review the script first: open /tmp/vl.sh before running it, or clone the repo and run ./install.sh locally.
The installer detects hardware, recommends an engine, downloads a default model (~74MB for whisper.cpp tiny), installs neural VAD when ONNX Runtime is available, and sets up desktop integration. Typical install time with whisper.cpp is about 1-2 minutes.
| 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 |
Non-interactive options:
bash /tmp/vl.sh --auto # whisper.cpp defaults
bash /tmp/vl.sh --auto --engine=whisper # OpenAI Whisper
bash /tmp/vl.sh --auto --engine=faster_whisper # Faster Whisper (CPU)
bash /tmp/vl.sh --auto --engine=vosk # VOSK only
bash /tmp/vl.sh --auto --engine=parakeet # Parakeet (CPU)
For a specific release tag, see GitHub Releases or ./install.sh --tag=v0.17.0.
Arch Linux (AUR)
yay -S vocalinux
See docs/AUR.md.
AppImage
Download the x86_64 or aarch64 AppImage from Releases, mark it executable, and run it. Built against glibc 2.35 (Debian 12+, Ubuntu 22.04+, Fedora 36+, Arch, Tumbleweed). Host text-injection tools (xdotool on X11; wtype / ydotool / clipboard tools on Wayland) are still required. Current AppImages rebuild whisper.cpp with Vulkan and use the host GPU driver. Prefer the installer when you want system deps, a CUDA build, and models set up automatically.
Flatpak (any distro)
Install and auto-update via the self-hosted VocaHQ remote (flatpak update picks up each release):
flatpak install https://vocahq.github.io/vocalinux-flatpak/com.vocalinux.Vocalinux.flatpakref
The .flatpakref adds the vocahq remote and resolves the GNOME runtime through Flathub. Manually instead:
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --if-not-exists vocahq https://vocahq.github.io/vocalinux-flatpak/vocahq.flatpakrepo
flatpak install vocahq com.vocalinux.Vocalinux
Or sideload a GitHub Release bundle (Vocalinux-<version>-x86_64.flatpak or -aarch64.flatpak) after the Flathub GNOME runtime is present — bundles do not auto-update:
flatpak install --user ./Vocalinux-<version>-x86_64.flatpak
Local build:
flatpak install flathub org.gnome.Platform//50 org.gnome.Sdk//50
flatpak-builder --user --install --force-clean build-dir \
packaging/flatpak/com.vocalinux.Vocalinux.yml
flatpak run com.vocalinux.Vocalinux
Ships whisper.cpp with Vulkan. It is not on Flathub (submission flathub#9368 closed 2026-07-23 on policy grounds). Details: packaging/flatpak/README.md.
Snap (Ubuntu Snap Store)
Listing: snapcraft.io/vocalinux. stable is promoted from candidate after QA. Tagged releases also attach vocalinux_<version>_amd64.snap on GitHub.
sudo snap install vocalinux --edge
sudo snap connect vocalinux:audio-record # if mic is not auto-connected
sudo snap connect vocalinux:raw-input # global keyboard shortcuts (evdev)
sudo snap connect vocalinux:hardware-observe # list keyboards (/proc/bus/input/devices)
sudo snap connect vocalinux:uinput # native Wayland typing (ydotool)
v0.17.0 includes ydotool and the uinput plug. The Store still has to finish review of that plug, so snap info vocalinux may still show v0.16.2 (rev 7) on edge. That revision has no uinput plug; snap connect vocalinux:uinput fails until a 0.17.0+ revision is listed.
Until then, sideload the GitHub file:
sudo snap install --dangerous ./vocalinux_0.17.0_amd64.snap
sudo snap connect vocalinux:uinput
From source
git clone https://github.com/VocaHQ/vocalinux.git
cd vocalinux
./install.sh
# or pick the engine up front
./install.sh --engine=whisper_cpp
./install.sh --engine=vosk
./install.sh --engine=parakeet --auto
After installation
vocalinux # if ~/.local/bin is on PATH
# or
~/.local/share/vocalinux/venv/bin/vocalinux
You can also launch Vocalinux from your application menu.
Nightly builds
Daily builds from main appear on Releases. Use the latest stable or beta release for production; nightlies are untested.
Requirements
| OS | Linux (Ubuntu 24.04+, Debian 12+, Fedora 42+, Arch, openSUSE Tumbleweed) |
| Python | 3.11 or newer |
| Display | X11 or Wayland |
| Hardware | Microphone; GPU optional (Vulkan) |
The distro must ship Python 3.11+ because Vocalinux uses distro PyGObject (python3-gi). Ubuntu 22.04 (Python 3.10) and Debian 11 (3.9) are below that floor. 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
vocalinux --help
vocalinux --version
vocalinux --debug
vocalinux --engine whisper_cpp # default
vocalinux --engine whisper
vocalinux --engine faster_whisper
vocalinux --engine vosk
vocalinux --engine parakeet
vocalinux --engine remote_api
vocalinux --model medium
vocalinux --model medium.en-q5_0 # exact whisper.cpp variant
vocalinux --model large-v3-turbo
vocalinux --wayland
vocalinux --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/vocalinux/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.
Neural VAD (Silero) is used when onnxruntime is available; install via pip install "vocalinux[vad]" for manual/PyPI installs. The installer attempts this automatically.
Documentation
| Document | Description |
|---|---|
| Installation | Installer, AppImage, AUR, Flatpak, Snap, running |
| Manual / PyPI install | Package lists and pip workflows |
| 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 |
| Local VocaGateway (optional) | Start a local gateway from Settings; not on-device |
| 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://github.com/VocaHQ/vocalinux.git
cd vocalinux
./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, Flatpak packaging, AppImage, in-app update checker, Parakeet and Faster Whisper engines, Snap recipe.
Planned:
- Application-specific voice commands
- Debian/Ubuntu package (
.deb) - User-customizable voice command map
- Flathub publication (not currently listed; see #167)
Voca ecosystem
Vocalinux is part of VocaHQ. On-device speech-to-text first, one app per platform. Optional VocaGateway is self-hosted and not on-device.
| Platform | Project | Website | GitHub |
|---|---|---|---|
| Linux | VocaLinux | vocalinux.com | VocaHQ/vocalinux |
| macOS | VocaMac | vocamac.com | VocaHQ/vocamac |
| Windows | VocaWin | vocawin.com | VocaHQ/vocawin |
| Phone | VocaPhone | vocaphone.vocahq.com | VocaHQ/vocaphone |
| Gateway | VocaGateway | vocagateway.vocahq.com | VocaHQ/vocagateway |
Talk to us: Discord · X @vocahq · hello@vocahq.com
Contributing
Bug reports, docs, and code are welcome. Start with CONTRIBUTING.md and good first issues.
Contributors
Thanks to everyone who has contributed code, docs, or fixes:
Repository mirrors
GitHub is the primary forge for issues, PRs, CI, and releases.
| Role | URL |
|---|---|
| Primary | https://github.com/VocaHQ/vocalinux |
| Read-only mirror (Codeberg) | https://codeberg.org/jatinkrmalik/vocalinux |
Open issues and pull requests on GitHub only.
License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), aligning with the other VocaHQ distribution projects.
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.
Star Chart
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. Vocalinux 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.