Vocalinux # Vocalinux **Voice-to-text for Linux, finally done right!** [![Privacy: on-device](https://img.shields.io/badge/privacy-on--device%20after%20model%20download-success)](https://github.com/VocaHQ/vocalinux#features) [![X11 & Wayland](https://img.shields.io/badge/display-X11%20%7C%20Wayland-lightgrey)](https://github.com/VocaHQ/vocalinux#features) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![Discord](https://img.shields.io/discord/1538633755877580810?logo=discord&logoColor=white&label=Discord)](https://discord.gg/t6muquAJbm) [![Email](https://img.shields.io/badge/hello%40vocahq.com-1a7f4e)](mailto:hello@vocahq.com) [![VocaHQ](https://img.shields.io/badge/VocaHQ-vocahq.com-1a7f4e)](https://vocahq.com) [![GitHub release](https://img.shields.io/github/v/release/VocaHQ/vocalinux)](https://github.com/VocaHQ/vocalinux/releases) [![PyPI](https://img.shields.io/pypi/v/vocalinux)](https://pypi.org/project/vocalinux/) [![AUR](https://img.shields.io/aur/version/vocalinux)](https://aur.archlinux.org/packages/vocalinux) [![Vocalinux CI](https://github.com/VocaHQ/vocalinux/actions/workflows/unified-pipeline.yml/badge.svg?branch=main)](https://github.com/VocaHQ/vocalinux/actions/workflows/unified-pipeline.yml?query=branch%3Amain) [![codecov](https://codecov.io/gh/VocaHQ/vocalinux/branch/main/graph/badge.svg)](https://codecov.io/gh/VocaHQ/vocalinux) [![Follow on X](https://img.shields.io/badge/Follow%20%40vocahq-000000?style=flat&logo=x&logoColor=white)](https://x.com/vocahq) [![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04+-E95420?logo=ubuntu&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) [![Debian](https://img.shields.io/badge/Debian-12+-A81D33?logo=debian&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) [![Fedora](https://img.shields.io/badge/Fedora-39+-51A2DA?logo=fedora&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) [![Arch](https://img.shields.io/badge/Arch-rolling-1793D1?logo=archlinux&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) [![openSUSE](https://img.shields.io/badge/openSUSE-Tumbleweed-73BA25?logo=opensuse&logoColor=white)](docs/DISTRO_COMPATIBILITY.md)
Linux has always punched above its weight, except when it comes to voice typing. Vocalinux fixes that. It's a free, AGPL-3.0-licensed desktop app that lets you dictate text into *any* application, on X11 or Wayland, using on-device speech recognition after you download a model. Pick from three engines (whisper.cpp, OpenAI Whisper, or VOSK), get automatic GPU acceleration via Vulkan, and control it all with customizable keyboard shortcuts: toggle or push-to-talk. Models are downloaded once. After that, speech-to-text stays on your machine. No Voca account is required. Just speak and type. ## ๐Ÿ“š What's New in v0.16.0 > **0.16.0** adds an in-app update checker with tray notifications, defaults new installs to hold Right Alt push-to-talk, makes the language list searchable, lets you delete unused downloaded models, and adds a family dictation tone picker. The project license is AGPL-3.0. The installer is hardened (Justfile, uv lockfiles, distro python3-gi). The app icon, tray states, and site favicons use the shared Voca family mic. ### Highlights | Feature | Description | |---------|-------------| | **Update checker** | Settings โ†’ About checks stable/nightly channels; tray shows Update Available when GitHub has a newer release (#631, #645) | | **Right Alt PTT default** | New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648) | | **Searchable languages** | Type to filter the Speech Model language list (#672) | | **Delete unused models** | Remove leftover downloaded speech models from Settings (#671) | | **AGPL-3.0** | License aligned with other VocaHQ projects (#660) | | **Family mic icons** | App icon, tray states, and site favicons use the shared Voca family mic (#704) | | **Tone picker** | Settings โ†’ Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708) | | **Installer** | Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706) | ### Also in this release - IBus: safer scoped injection, engine restore after teardown, XKB layout restore on X11 (#623, #643, #665) - Audio: filter unsafe virtual capture devices; open stereo mics at native channel count; catalog tones are the family preview WAVs, not the synthesized #707 files (#629, #673, #708) - Clipboard: restore after ydotool paste; text-only reads and safer overlapping restore (#588, #646) - GPU / AppImage: honor bundled GPU libs and skip software Vulkan; ship transitive GI typelibs (AppImage fix already hotfixed onto the v0.15.0 AppImages) (#674, #637) - Settings / tray: separate Close from Test Dictation; reuse Settings/Logs windows; prefer Ayatana AppIndicator on KDE; optional missing-tray warning toggle (#670, #669, #621, #628) - Test Dictation: no longer reports no speech when recognition never started (#702) - Settings: About page groups this app, the VocaHQ family, and talk-to-us links (#718) - Installer / downloads / tests: gate `util-linux-extra` to Ubuntu 24.04+; report failed model downloads; stop tests from overwriting real `config.json` (#635, #690, #694) - Website: vocalinux.com restyled to the Voca family workbench; Discord and X links point at VocaHQ (#728, #729, #722, #717) See [docs/UPDATE.md](docs/UPDATE.md) and the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.0). --- ## Features - ๐ŸŽค **Toggle or Push-to-Talk** activation modes - โšก **Real-time transcription** with minimal latency - ๐ŸŒŽ **Universal compatibility** across all Linux applications - ๐Ÿ”’ **On-device after model download** โ€” speech-to-text stays on your machine - ๐Ÿค– **whisper.cpp by default** - High-performance C++ speech recognition - ๐ŸŽฎ **Universal GPU support** - Vulkan acceleration for AMD, Intel, and NVIDIA - ๐ŸŽจ **System tray integration** with visual status indicators - ๐Ÿš€ **Start on login support** via XDG autostart (desktop-session startup) - ๐Ÿ”Š **Pleasant audio feedback** - smooth gliding tones, headphone-friendly - โš™๏ธ **Graphical settings** dialog for easy configuration - ๐Ÿ“ฆ **3 engine choices** - whisper.cpp (default), OpenAI Whisper, or VOSK ## ๐Ÿ“ธ Screenshots Vocalinux in action. Settings gallery shots may lag the newest UI. Full gallery on the [website screenshots page](https://vocalinux.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
## ๐Ÿš€ Quick Install ### Interactive Install (Recommended) Our new interactive installer guides you through setup with intelligent hardware detection: ```bash curl -fsSL raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh ``` **Choose your engine:** 1. **whisper.cpp** โญ (Recommended) - Fast, works with any GPU via Vulkan 2. **Whisper** (OpenAI) - PyTorch-based, NVIDIA GPU only 3. **VOSK** - Lightweight, works on older systems The installer will: - **Auto-detect your hardware** (GPU, RAM, Vulkan support) - **Recommend the best engine** for your system - **Download the appropriate model** (~74MB for the default whisper.cpp tiny model) - **Install neural VAD support** when ONNX Runtime is available - **Install in ~1-2 minutes** (vs 5-10 min with old Whisper) > **Note**: Always installs the latest release. For a specific version, check [GitHub Releases](https://github.com/VocaHQ/vocalinux/releases). ### Installation Options **Default (whisper.cpp - recommended):** ```bash curl -fsSL raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh ``` Fastest installation (~1-2 min), universal GPU support via Vulkan. **Whisper (OpenAI) - if you prefer PyTorch:** ```bash curl -fsSL raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=whisper ``` NVIDIA GPU only (~5-10 min, downloads PyTorch + CUDA). **VOSK only - for low-RAM systems:** ```bash curl -fsSL raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=vosk ``` Lightweight option (~40MB), works on systems with 4GB RAM. ### Arch Linux (AUR) ```bash yay -S vocalinux ``` See [docs/AUR.md](docs/AUR.md). ### Flatpak (any distro) For a sandboxed, distro-independent install (great for NixOS, Fedora Silverblue, Steam Deck, and anywhere else), build the Flatpak from the bundled manifest: ```bash 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 ``` The Flatpak ships the whisper.cpp engine with Vulkan GPU support and runs through XWayland on Wayland sessions. See [`packaging/flatpak/README.md`](packaging/flatpak/README.md) for build details, permissions, and Flathub submission notes. Flathub publishing is in progress. ### Alternative: Install from Source ```bash # Clone the repository git clone https://github.com/VocaHQ/vocalinux.git cd vocalinux # Run the interactive installer (engine picker + GPU detection) ./install.sh # Or pick the engine up front ./install.sh --engine=whisper_cpp # whisper.cpp (default, GPU-accelerated) ./install.sh --engine=vosk # lightweight VOSK ``` The installer handles everything: system dependencies, Python environment, speech models, and desktop integration. ### ๐ŸŒ™ Nightly Releases (Bleeding Edge) For developers and early adopters who want to test the latest features, check out our [GitHub Releases page](https://github.com/VocaHQ/vocalinux/releases) which includes both beta and nightly builds. > **โš ๏ธ Warning**: Nightly releases contain the absolute latest code and may be unstable. For production use, we recommend using the latest beta release. Nightly builds are automatically generated from the `main` branch every day. They include all merged changes but haven't undergone the same testing as beta releases. **Release Channels:** - **Beta** (Recommended) - Tested pre-releases with known features - **Nightly** - Untested bleeding edge with latest commits ### After Installation ```bash # If ~/.local/bin is in your PATH (recommended): vocalinux # Or activate the virtual environment first: source ~/.local/bin/activate-vocalinux.sh vocalinux # Or run directly: ~/.local/share/vocalinux/venv/bin/vocalinux ``` Or launch it from your application menu! ## ๐Ÿ“‹ Requirements - **OS**: Linux (tested on Ubuntu 24.04+, Debian 12+, Fedora 39+, Arch Linux, openSUSE Tumbleweed) - **Python**: 3.11 or newer - **Display**: X11 or Wayland - **Hardware**: Microphone for voice input **Note:** See [Distribution Compatibility](docs/DISTRO_COMPATIBILITY.md) for distribution-specific information and experimental support for Gentoo, Alpine, Void, Solus, and more. ## ๐ŸŽ™๏ธ Usage ### Voice Dictation 1. **Push-to-talk (default)**: Hold Right Alt (Option on Mac-layout keyboards) and speak 2. Speak clearly into your microphone 3. **Release** the key to stop, or switch to **Toggle mode** in Settings (double-tap a key to start/stop) ### Voice Commands | Command | Action | |---------|--------| | "new line" | Inserts a line break | | "period" / "full stop" | Types a period (.) | | "comma" | Types a comma (,) | | "question mark" | Types a question mark (?) | | "exclamation mark" | Types an exclamation mark (!) | | "delete that" | Deletes the last sentence | | "capitalize" | Capitalizes the next word | ### Command Line Options ```bash vocalinux --help # Show all options vocalinux --debug # Enable debug logging vocalinux --engine whisper_cpp # Use whisper.cpp engine (default) vocalinux --engine whisper # Use OpenAI Whisper engine vocalinux --engine vosk # Use VOSK engine vocalinux --model medium # Use medium-sized model vocalinux --model medium.en-q5_0 # Use exact whisper.cpp model variant vocalinux --model large-v3-turbo # Use large-v3 Turbo with whisper.cpp vocalinux --wayland # Force Wayland mode vocalinux --start-minimized # Start without first-run modal prompts ``` ### Autostart on Login Vocalinux uses the Linux desktop standard for autostart: - **Mechanism**: XDG autostart desktop entry (`vocalinux.desktop`) - **Path**: `$XDG_CONFIG_HOME/autostart/` or `~/.config/autostart/` (fallback) - **Launch mode**: Starts as a regular **user desktop app** in your graphical session - **Not used**: No `systemd` unit/service is created by Vocalinux for autostart How to enable/disable: - First-run welcome dialog - Tray menu: **Start on Login** - Settings dialog: **Start on Login** Compatibility notes: - Works on mainstream desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt) - On minimal/custom window-manager sessions, an autostart handler may be required (for example DE-specific startup hooks or tools like `dex`) ## โš™๏ธ Configuration Configuration is stored in `~/.config/vocalinux/config.json`: ```json { "speech_recognition": { "engine": "whisper_cpp", "model_size": "tiny", "vad_sensitivity": 3, "silence_timeout": 2.0 } } ``` For whisper.cpp, `model_size` may be a size such as `tiny` or an exact ggml model ID such as `medium.en-q5_0` or `large-v3-turbo`. You can also configure this through the graphical Settings dialog, where whisper.cpp models are split into **Model Size** and **Specialization** controls. Unused leftover downloads can be deleted from **Unused downloads** on the Speech Model page (expand the section, then delete one model at a time). ### Neural Voice Activity Detection Vocalinux ships with a Silero VAD model and uses it automatically when `onnxruntime` is available. The official installer attempts to install this support automatically. Without it, recording falls back to the simpler amplitude-threshold VAD. For manual or PyPI installs, enable neural VAD with: ```bash pip install "vocalinux[vad]" ``` Restart Vocalinux after install. The Recognition tab in Settings shows which backend is active. The same `vad_sensitivity` (1-5) works for both -- it's mapped to a Silero probability threshold internally (1 = 0.8, 5 = 0.3). ## ๐Ÿ”ง Development Setup ```bash # Clone and install in dev mode git clone https://github.com/VocaHQ/vocalinux.git cd vocalinux ./install.sh --dev # Activate environment source venv/bin/activate # Run tests pytest # Run from source with debug python -m vocalinux.main --debug ``` ## ๐Ÿ“ Project Structure ``` vocalinux/ โ”œโ”€โ”€ src/vocalinux/ # Main application code โ”‚ โ”œโ”€โ”€ speech_recognition/ # Speech recognition engines (VOSK, Whisper, whisper.cpp) โ”‚ โ”‚ โ””โ”€โ”€ recognition_manager.py # Unified engine interface โ”‚ โ”œโ”€โ”€ text_injection/ # Text injection (X11/Wayland) โ”‚ โ”œโ”€โ”€ ui/ # GTK UI components โ”‚ โ””โ”€โ”€ utils/ # Utility functions โ”‚ โ”œโ”€โ”€ whispercpp_model_info.py # whisper.cpp model metadata & hardware detection โ”‚ โ””โ”€โ”€ vosk_model_info.py # VOSK model metadata โ”œโ”€โ”€ tests/ # Test suite โ”œโ”€โ”€ scripts/ # Development utilities โ”‚ โ””โ”€โ”€ generate_sounds.py # Sound generation script โ”œโ”€โ”€ resources/ # Icons and sounds โ”œโ”€โ”€ docs/ # Documentation โ””โ”€โ”€ web/ # Website source ``` ## ๐Ÿ“– Documentation - [Installation Guide](docs/INSTALL.md) - Detailed installation instructions - [Update Guide](docs/UPDATE.md) - How to update Vocalinux - [User Guide](docs/USER_GUIDE.md) - Complete user documentation - [Distribution Compatibility](docs/DISTRO_COMPATIBILITY.md) - Distro/session behavior and caveats - [Contributing](CONTRIBUTING.md) - Development setup and contribution guidelines ## Repository mirrors GitHub is the **primary** forge for issues, pull requests, CI, and releases. | Role | URL | |------|-----| | Primary | https://github.com/VocaHQ/vocalinux | | Read-only mirror (Codeberg) | https://codeberg.org/jatinkrmalik/vocalinux | The Codeberg copy is a read-only source backup. Open issues and PRs on GitHub only. ## ๐Ÿ”Š Sound Customization Vocalinux uses smooth, pleasant gliding tones for audio feedback: - **Start**: Ascending F4โ†’A4 (0.6s) - positive, uplifting - **Stop**: Descending A4โ†’F4 (0.6s) - resolves completion - **Error**: Lower descending E4โ†’C4 (0.7s) - gentle but noticeable All sounds use pure sine waves with smoothstep interpolation for buttery smooth pitch transitions - perfect for headphone use! ### Regenerate Sounds To modify or regenerate the notification sounds: ```bash python scripts/generate_sounds.py ``` This script generates all three sounds using the same smooth glide algorithm. You can edit the frequencies, durations, and amplitudes in the script to customize the sounds to your preference. ## ๐Ÿ—บ๏ธ Roadmap - [x] ~~Custom icon design~~ โœ… - [x] ~~Graphical settings dialog~~ โœ… - [x] ~~Whisper AI support~~ โœ… - [x] ~~Multi-language support (FR, DE, RU)~~ โœ… - [x] ~~whisper.cpp integration (default engine)~~ โœ… - [x] ~~Vulkan GPU support~~ โœ… - [x] In-app update mechanism โœ… - [x] ~~Wayland support via IBus~~ โœ… - [x] ~~Flatpak packaging~~ โœ… (Flathub submission in progress) - [ ] Application-specific commands - [ ] Debian/Ubuntu package (.deb) - [ ] Voice command customization ## ๐ŸŒ The Voca Ecosystem Vocalinux is part of [VocaHQ](https://vocahq.com). On-device speech-to-text first, one app per platform. Optional [VocaGateway](https://vocagateway.vocahq.com) is self-hosted and not on-device. | Platform | Project | Website | GitHub | Status | |----------|---------|---------|--------|--------| | ๐Ÿง Linux | **VocaLinux** | [vocalinux.com](https://vocalinux.com) | [VocaHQ/vocalinux](https://github.com/VocaHQ/vocalinux) | โœ… Available now (`v0.16.0`) | | ๐ŸŽ macOS | **VocaMac** | [vocamac.com](https://vocamac.com) | [VocaHQ/vocamac](https://github.com/VocaHQ/vocamac) | ๐Ÿš€ Beta (`v0.9.0`) | | ๐ŸชŸ Windows | **VocaWin** | [vocawin.com](https://vocawin.com) | [VocaHQ/vocawin](https://github.com/VocaHQ/vocawin) | ๐Ÿš€ Unsigned beta (`v0.1.0-beta.1`) | | ๐Ÿ“ฑ Phone | **VocaPhone** | [vocaphone.vocahq.com](https://vocaphone.vocahq.com) | [VocaHQ/vocaphone](https://github.com/VocaHQ/vocaphone) | ๐Ÿš€ Android beta / iOS [TestFlight](https://testflight.apple.com/join/wd85wQ3W) | | ๐Ÿ–ง Gateway | **VocaGateway** | [vocagateway.vocahq.com](https://vocagateway.vocahq.com) | [VocaHQ/vocagateway](https://github.com/VocaHQ/vocagateway) | ๐Ÿงช Early ยท optional ยท not on-device | > VocaWin is unsigned. SmartScreen may warn about an unknown publisher. It is not a Microsoft Store ship. > > Each platform uses native technologies. The shared bar is on-device first; [VocaGateway](https://vocagateway.vocahq.com) is optional self-hosted compute and is not on-device. > > Talk to us: [Discord](https://discord.gg/t6muquAJbm) ยท [X @vocahq](https://x.com/vocahq) ยท [hello@vocahq.com](mailto:hello@vocahq.com) ## ๐Ÿค Contributing We welcome contributions! Whether it's bug reports, feature requests, or code contributions, please check out our [Contributing Guide](CONTRIBUTING.md). ### Contributors Thanks to everyone who has contributed to Vocalinux! ๐Ÿ™Œ ### Quick Links - ๐Ÿ› [Report a Bug](https://github.com/VocaHQ/vocalinux/issues/new?template=bug_report.md) - ๐Ÿ’ก [Request a Feature](https://github.com/VocaHQ/vocalinux/issues/new?template=feature_request.md) - ๐Ÿ’ฌ [Discussions](https://github.com/VocaHQ/vocalinux/discussions) ## โญ Support If you find Vocalinux useful, please consider: - โญ Starring this repository - ๐Ÿ› Reporting bugs you encounter - ๐Ÿ“– Improving documentation - ๐Ÿ”€ Contributing code ## ๐Ÿ“œ License This project is licensed under the **GNU Affero General Public License v3.0** ([AGPL-3.0](LICENSE)), aligning with the other [VocaHQ](https://github.com/VocaHQ) distribution projects ([VocaMac](https://github.com/VocaHQ/vocamac), [VocaPhone](https://github.com/VocaHQ/vocaphone), [VocaGateway](https://github.com/VocaHQ/vocagateway)). 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 [![Star History Chart](https://api.star-history.com/chart?repos=VocaHQ/vocalinux&type=date&legend=top-left&sealed_token=ZWyQQLhSORoR4mKf6UXMGFSCBXRxM_yEZgc8MFCH_ysBjaFUm_OCH-bI3TD7OivczEzm-ADRIpF9xCWFOMHvBPW95eQBxzfRMpNksChz7rN_eiqL7AIMDw)](https://www.star-history.com/?type=date&repos=VocaHQ%2Fvocalinux) ---

Made with โค๏ธ for the Linux community