# 
Vocalinux
#### Voice-to-text for Linux, finally done right!
[](https://github.com/jatinkrmalik/vocalinux)
[](https://github.com/jatinkrmalik/vocalinux/releases)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/jatinkrmalik/vocalinux/actions)
[](https://github.com/jatinkrmalik/vocalinux)
[](https://www.python.org/downloads/)
[](https://www.gtk.org/)
[](https://codecov.io/gh/jatinkrmalik/vocalinux)
[](https://github.com/jatinkrmalik/vocalinux/stargazers)
[](https://github.com/jatinkrmalik/vocalinux/network)
[](https://github.com/jatinkrmalik/vocalinux/watchers)
[](https://github.com/jatinkrmalik/vocalinux/commits)
[](https://github.com/jatinkrmalik/vocalinux/commits)
[](CONTRIBUTING.md)
[](https://github.com/jatinkrmalik/vocalinux/issues)
**A seamless free open-source private voice dictation system for Linux**, comparable to built-in solutions on macOS and Windows.
## 📚 What's New in v0.9.0-beta
> 🎉 **Release: Left/Right modifier keys, sound effects toggle, Wayland clipboard fallback, and more.**
### 🚀 Highlights (v0.8.0 → v0.9.0)
| Feature | Description |
|---------|-------------|
| **⌨️ Left/Right Modifier Keys** | Choose Left Ctrl vs Right Ctrl (etc.) as your shortcut trigger |
| **🔔 Sound Effects Toggle** | Enable or disable audio feedback from the Settings dialog |
| **📋 Wayland Clipboard Fallback** | Automatic clipboard copy when virtual keyboard injection isn't available |
| **🛠️ Installation Polish** | Better pipx/Debian guidance and headless display detection |
### ✨ New Features (v0.9.0)
- **Left/Right Modifier Key Distinction** — Shortcuts now support `Left Ctrl`, `Right Alt`, etc., with grouped UI in Settings
- **Sound Effects Toggle** — New Audio Settings toggle to silence start/stop/error sounds
- **Clipboard Fallback for Wayland** — Auto-copies text via `wl-copy`/`xclip` when injection unavailable (KDE Plasma etc.)
- **Display Availability Check** — Graceful error message when running in headless environments
### 🐛 Bug Fixes (v0.9.0)
- **#308**: Distinguish left vs right modifier keys (evdev + pynput backends)
- **#307**: Remove unwanted leading space when starting a new transcription session
- **#305**: Pass configured shortcut mode to `KeyboardShortcutManager` on startup
- **#299**: Add clipboard fallback for Wayland compositors without virtual keyboard support
- **#289**: Improve Debian/pipx installation error messages and cross-distro dependency guidance
### 🔧 Improvements
- **Grouped shortcut selector** — Settings dropdown now organises shortcuts by Either/Left/Right side
- **pipx documentation** — New `DISTRO_COMPATIBILITY.md` section for pipx users
---
## ✨ Features
- 🎤 **Toggle or Push-to-Talk** activation modes
- ⚡ **Real-time transcription** with minimal latency
- 🌎 **Universal compatibility** across all Linux applications
- 🔒 **100% Offline operation** for privacy and reliability
- 🤖 **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
Here are some screenshots showcasing Vocalinux in action:
Real-time voice-to-text transcription
|
System tray with listening indicator
|
About view with version info
|
Log viewer for debugging
|
Overview of key features and configuration options with annotations
|
## 🚀 Quick Install
### Interactive Install (Recommended)
Our new interactive installer guides you through setup with intelligent hardware detection:
```bash
curl -fsSL raw.githubusercontent.com/jatinkrmalik/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** (~39MB for whisper.cpp tiny)
- **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/jatinkrmalik/vocalinux/releases).
### Installation Options
**Default (whisper.cpp - recommended):**
```bash
curl -fsSL raw.githubusercontent.com/jatinkrmalik/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/jatinkrmalik/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/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=vosk
```
Lightweight option (~40MB), works on systems with 4GB RAM.
### Alternative: Install from Source
```bash
# Clone the repository
git clone https://github.com/jatinkrmalik/vocalinux.git
cd vocalinux
# Run the installer (will prompt for Whisper)
./install.sh
# Or with Whisper support
./install.sh --with-whisper
```
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/jatinkrmalik/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 22.04+, Debian 11+, Fedora 39+, Arch Linux, openSUSE Tumbleweed)
- **Python**: 3.8 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. **Toggle mode**: Double-tap the shortcut key (default Ctrl) to start recording
2. Speak clearly into your microphone
3. **Toggle mode**: Double-tap again (or pause speaking) to stop, or **Push-to-Talk mode**: release the key to 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 --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
}
}
```
You can also configure settings through the graphical Settings dialog (right-click the tray icon).
## 🔧 Development Setup
```bash
# Clone and install in dev mode
git clone https://github.com/jatinkrmalik/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
## 🔊 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~~ ✅
- [ ] In-app update mechanism
- [ ] Application-specific commands
- [ ] Debian/Ubuntu package (.deb)
- [x] ~~Wayland support via IBus~~ ✅
- [ ] Voice command customization
## 🤝 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/jatinkrmalik/vocalinux/issues/new?template=bug_report.md)
- 💡 [Request a Feature](https://github.com/jatinkrmalik/vocalinux/issues/new?template=feature_request.md)
- 💬 [Discussions](https://github.com/jatinkrmalik/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 General Public License v3.0** - see the [LICENSE](LICENSE) file for details.
---
Made with ❤️ for the Linux community