# Vocalinux #### Voice-to-text for Linux, finally done right! [![Status: Beta](https://img.shields.io/badge/Status-Beta-blue)](https://github.com/jatinkrmalik/vocalinux) [![GitHub release](https://img.shields.io/github/v/release/jatinkrmalik/vocalinux?include_prereleases)](https://github.com/jatinkrmalik/vocalinux/releases) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Vocalinux CI](https://github.com/jatinkrmalik/vocalinux/workflows/Vocalinux%20CI/badge.svg)](https://github.com/jatinkrmalik/vocalinux/actions) [![Platform: Linux](https://img.shields.io/badge/platform-Linux-lightgrey)](https://github.com/jatinkrmalik/vocalinux) [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) [![Made with GTK](https://img.shields.io/badge/Made%20with-GTK-green)](https://www.gtk.org/) [![codecov](https://codecov.io/gh/jatinkrmalik/vocalinux/branch/main/graph/badge.svg)](https://codecov.io/gh/jatinkrmalik/vocalinux) [![GitHub stars](https://img.shields.io/github/stars/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/stargazers) [![GitHub forks](https://img.shields.io/github/forks/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/network) [![GitHub watchers](https://img.shields.io/github/watchers/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/watchers) [![Last commit](https://img.shields.io/github/last-commit/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/commits) [![Commit activity](https://img.shields.io/github/commit-activity/m/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/commits) [![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md) [![GitHub issues](https://img.shields.io/github/issues/jatinkrmalik/vocalinux)](https://github.com/jatinkrmalik/vocalinux/issues) ![Vocalinux Users](https://github.com/user-attachments/assets/e3d8dd16-3d4f-408c-b899-93d85e98b107) **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.5.0-beta We're excited to announce our first **Beta release**! Vocalinux has evolved significantly since the last alpha, with numerous bug fixes and feature improvements. ### πŸ› Critical Bug Fixes - Fixed text escaping issues (apostrophes and quotes no longer have backslash escapes) - Fixed stop sound being transcribed as "thank you" - Fixed missing spaces after punctuation when transcribing again ### ✨ Key New Features - **Customizable keyboard shortcuts** - Configure your own activation shortcuts via GUI - **Modern GNOME HIG settings dialog** - Complete UI overhaul following GNOME design guidelines - **Pleasant audio feedback** - Gliding tones replace harsh beeps - **Interactive installer with GPU detection** - Smart hardware auto-detection - **Better Wayland support** - Native keyboard shortcuts without XWayland ### πŸ”§ Quality Improvements - **80%+ test coverage** - Comprehensive test suite across all modules - **Microphone reconnection** - Automatic recovery when microphone disconnects - **Audio buffer management** - Prevents memory issues during long recordings --- > πŸŽ‰ **Beta Release!** > > We're excited to share Vocalinux Beta with the community! > See "What's New" above for details on this release. --- ## ✨ Features - 🎀 **Double-tap Ctrl** to start/stop voice dictation - ⚑ **Real-time transcription** with minimal latency - 🌎 **Universal compatibility** across all Linux applications - πŸ”’ **Offline operation** for privacy and reliability (with VOSK) - πŸ€– **Optional Whisper AI** support for enhanced accuracy - 🎨 **System tray integration** with visual status indicators - πŸ”Š **Pleasant audio feedback** - smooth gliding tones, headphone-friendly - βš™οΈ **Graphical settings** dialog for easy configuration ## πŸ“Έ Screenshots Here are some screenshots showcasing Vocalinux in action:
Transcription in Action
Real-time voice-to-text transcription 		System Tray
System tray with listening indicator
About View
About view with version info 		Log Viewer
Log viewer for debugging
Features Overview
Overview of key features and configuration options with annotations
## πŸš€ Quick Install ### Interactive Install (Recommended for New Users) Let the installer guide you through the setup with smart hardware detection: ```bash curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --tag=v0.5.0-beta --interactive ``` The interactive installer will: - **Auto-detect your hardware** (GPU, RAM) - **Recommend the best configuration** for your system - **Guide you through each step** with clear explanations - **Show you how to launch and use** Vocalinux after installation ### One-liner Installation (Quick Install) ```bash curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --tag=v0.5.0-beta ``` > **Note**: Installs v0.5.0-beta. For the most recent version, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases). > > **GPU Detection**: The installer now automatically detects NVIDIA GPUs and uses CPU-only PyTorch when no GPU is present, saving you ~2GB of download! This will: - Clone the repository to `~/.local/share/vocalinux-install` - Install all system dependencies - Set up a virtual environment in `~/.local/share/vocalinux/venv` - Install **both VOSK and Whisper AI** speech engines: - **VOSK**: installs the `vosk` Python package from PyPI - **Whisper**: installs the `openai-whisper` package from PyPI, which also pulls in PyTorch (the ML framework Whisper requires) - Create a symlink at `~/.local/bin/vocalinux` - Download the default **Whisper tiny** speech model (~75MB) > ⏱️ **Note**: Installation takes ~5-10 minutes due to Whisper AI dependencies (PyTorch with CUDA support, ~2.3GB). **Whisper with CPU-only PyTorch (no NVIDIA GPU needed):** ```bash curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --tag=v0.5.0-beta --whisper-cpu ``` This installs Whisper with CPU-only PyTorch (~200MB instead of ~2.3GB). Works great for systems without NVIDIA GPU. **For low-RAM systems (8GB or less) - VOSK only:** ```bash curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --tag=v0.5.0-beta --no-whisper ``` This skips Whisper installation entirely and configures VOSK as the default engine. ### 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. ### 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! ## πŸ“š What's New in v0.5.0-beta We're excited to announce our first **Beta release**! Vocalinux has evolved significantly since the last alpha, with numerous bug fixes and feature improvements. ### πŸ› Critical Bug Fixes - Fixed text escaping issues (apostrophes and quotes no longer have backslash escapes) - Fixed stop sound being transcribed as "thank you" - Fixed missing spaces after punctuation when transcribing again ### ✨ Key New Features - **Customizable keyboard shortcuts** - Configure your own activation shortcuts via GUI - **Modern GNOME HIG settings dialog** - Complete UI overhaul following GNOME design guidelines - **Pleasant audio feedback** - Gliding tones replace harsh beeps - **Interactive installer with GPU detection** - Smart hardware auto-detection - **Better Wayland support** - Native keyboard shortcuts without XWayland ### πŸ”§ Quality Improvements - **80%+ test coverage** - Comprehensive test suite across all modules - **Microphone reconnection** - Automatic recovery when microphone disconnects - **Audio buffer management** - Prevents memory issues during long recordings For a complete list of changes, see the release notes. ## πŸ“‹ 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. **Double-tap Ctrl** to start recording 2. Speak clearly into your microphone 3. **Double-tap Ctrl** again (or pause speaking) 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 # Use Whisper AI engine vocalinux --model medium # Use medium-sized model vocalinux --wayland # Force Wayland mode ``` ## βš™οΈ Configuration Configuration is stored in `~/.config/vocalinux/config.json`: ```json { "speech_recognition": { "engine": "vosk", "model_size": "small", "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 β”‚ β”œβ”€β”€ text_injection/ # Text injection (X11/Wayland) β”‚ β”œβ”€β”€ ui/ # GTK UI components β”‚ └── utils/ # Utility functions β”œβ”€β”€ 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 - [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)~~ βœ… - [ ] In-app update mechanism - [ ] Application-specific commands - [ ] Debian/Ubuntu package (.deb) - [x] ~~Improved Wayland support~~ βœ… - [ ] 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). ### 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