Jatin K MalikandGitHub
fa4da40e7b
* test(coverage): improve test coverage from 57% to 80%+ Add 30 new test files with 861 additional test cases to improve overall test coverage from 57% to 80%+ (statement coverage). Key modules covered: - recognition_manager.py: 43% → 69% (audio device detection, transcription, model download, engine initialization, buffer management) - text_injector.py: improved coverage for X11/Wayland text injection, environment detection, clipboard fallback, shortcut injection - ibus_engine.py: 22% → 73% (engine lifecycle, text injection, socket server) - evdev_backend.py: 11% → 78% (device detection, key event handling) - pynput_backend.py: 43% → 76% (start/stop, key handling, callbacks) - keyboard_backends/__init__.py: 54% → improved (backend creation, env detection) - whispercpp_model_info.py: 32% → improved (GPU detection, model recommendations) - about_dialog.py, first_run_dialog.py, main.py, single_instance.py, common_types.py, config_manager.py, autostart_manager.py: various improvements All 1433 tests pass with proper test isolation to prevent mock pollution between test modules. * test(quality): audit and fix test quality issues Code review audit identified and fixed the following issues: - Remove bare try/except blocks that swallow all errors (7 tests fixed in recognition_manager_deep, replaced with proper assertions or deleted) - Delete source code inspection tests that read .py files as strings instead of testing behavior (deleted test_about_dialog_coverage.py and test_first_run_dialog_coverage.py entirely - ~35 useless tests removed) - Add meaningful assertions replacing weak assertIsNotNone/assertIsInstance checks (common_types_coverage, ibus_engine_coverage, keyboard_backends_extra) - Fix tests that mock the system under test instead of its dependencies (text_injector_extra now mocks subprocess.run instead of injection methods) - Add missing assertions to tests with no verification (ibus_engine focus_out, log window info, copy to clipboard) - Verify download tests check requests.get was called with correct URLs (coverage_boost download tests) - Fix pytest warning by renaming test_audio_input import to avoid pytest collecting it as a test function All 1356 tests pass with 0 failures and 0 warnings. Statement coverage: 80.3% (3257/4054 lines covered). * style(tests): fix black formatting and isort import ordering Auto-format all new test files with black and isort to pass CI lint checks. * fix(tests): resolve CI hangs and rename test files for clarity - Fix CI hangs by properly mocking gi/GTK/IBus in all test files - Fix sys.modules pollution in recognition manager tests by using tmp_path - Add pytest-timeout to prevent future hangs - Rename 28 test files to use descriptive, consistent names mapping to source modules * fix(tests): resolve Python 3.13 CI failures - Fix _load_stdlib_module() in test_recognition_manager_downloads.py to handle stdlib modules that are packages (directories with __init__.py) rather than single .py files. In Python 3.13, zipfile became a package, causing FileNotFoundError during test collection (exit code 2). - Fix invalid escape sequence '$' in test_cross_distro_compatibility.py by using a raw string. Python 3.13 reports this as SyntaxWarning and Python 3.14 will make it a SyntaxError. * fix(tests): use direct import for zipfile instead of _load_stdlib_module The _load_stdlib_module approach fails on Python 3.13 where zipfile is a package (zipfile/__init__.py). Loading it via spec_from_file_location with a custom name breaks relative imports inside the package (e.g. 'from ._path import ...' resolves to '_stdlib_zipfile._path' which doesn't exist). Simply import zipfile at module level before any test mocks can pollute sys.modules — this is safe because the module-level code runs during test collection, before any test fixtures or patches are applied. * fix(tests): mock gi/GTK in conftest to prevent CI hangs On CI, real PyGObject is installed and module-level imports in vocalinux source files (ibus_engine, tray_indicator, settings_dialog, etc.) trigger GTK initialization or IBus daemon connections that hang indefinitely in headless environments. pytest-timeout's signal-based timeout cannot interrupt these C-level blocking calls. Fix by mocking gi and gi.repository in conftest.py (which runs before any test module is collected), ensuring all test files are protected regardless of whether they remember to mock individually. Also add timeout-minutes: 10 to the CI test job as a safety net so that any remaining hangs fail fast instead of running indefinitely. * fix(tests): unconditionally mock gi in conftest for CI The previous 'if gi not in sys.modules' guard was ineffective on CI because PyGObject is installed via pip, so the real gi module is already loaded. This caused GTK initialization and IBus daemon connections that hang indefinitely in headless CI environments. Now unconditionally replace gi and gi.repository with mocks during test collection, regardless of whether the real package is installed. * fix(tests): reduce timeout to 10s and use thread-based timeout Use timeout_method=thread instead of signal (default) so that pytest-timeout can interrupt C-level blocking calls (GTK operations, socket accepts, subprocess waits) that the signal-based method cannot handle. Also reduce per-test timeout from 30s to 10s since no legitimate unit test should take longer, and hanging tests were consuming the entire CI job timeout budget. * fix(tests): set global socket timeout to prevent blocking on CI Tests in test_ibus_engine.py create real Unix sockets with daemon threads that block on socket.accept(). When tests fail or timeout, these threads remain blocked indefinitely, preventing pytest from completing. The thread-based timeout catches the hang but cannot terminate the blocking accept() call. Set socket.setdefaulttimeout(5) in conftest.py so all socket operations (accept, connect, recv) will raise socket.timeout after 5 seconds instead of blocking forever. * fix(tests): add cleanup fixture for IBus socket server threads Add autouse fixture that stops any leftover VocalinuxEngine socket server threads after each test. Tests that trigger _start_socket_server() spawn daemon threads blocking on socket.accept() that persist after the test completes, eventually causing pytest-timeout to kill the process. The cleanup fixture sets _server_running=False and closes the server socket, which unblocks the accept() call and allows the daemon thread to terminate. * fix(tests): reduce socket timeout to 0.1s to avoid slowing tests The 5-second socket timeout caused socket operations in daemon threads to block for 5 seconds per iteration before timing out, significantly slowing the test suite on CI. Reduce to 0.1s so blocking socket calls fail fast without noticeably impacting test execution time. * fix(tests): use 2s socket timeout and increase CI timeout to 15min The 0.1s socket timeout was too aggressive and caused legitimate test socket operations to fail. Use 2s which is long enough for test sockets to work but short enough to unblock daemon threads. Increase CI job timeout to 15 minutes to accommodate the socket timeout overhead from daemon threads that retry every 2 seconds. * fix(tests): block known-blocking daemon threads to prevent CI hangs Instead of using socket timeouts (which either break tests or are too slow), prevent specific known-blocking daemon threads from starting: - ibus_engine.server_thread: blocks on socket.accept() - evdev_backend._monitor_devices: blocks on select.select() These threads are identified by their target function name and skipped during Thread.start(). The thread is marked as started/stopped so join() calls in cleanup code don't raise RuntimeError. Test-created daemon threads (e.g. mock socket servers) are unaffected since they use different target function names. * fix(tests): patch Thread.join for Python 3.13 compatibility Python 3.13 changed threading internals — join() now uses _handle.join() which raises 'thread not started' for threads that were never actually started. Instead of trying to fake internal state, patch join() to be a no-op for threads that were skipped by our _safe_thread_start guard. This fixes the 2 remaining test_evdev_backend_ext failures on Python 3.13.
Vocalinux
Voice-to-text for Linux, finally done right!
Linux has always punched above its weight, except when it comes to voice typing. Vocalinux fixes that.
It's a free, GPLv3-licensed desktop app that lets you dictate text into any application, on X11 or Wayland, using fully offline speech recognition. 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.
No internet required. No data leaves your machine. Just speak and type.
📚 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/xclipwhen 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
KeyboardShortcutManageron 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.mdsection 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:
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh
Choose your engine:
- whisper.cpp ⭐ (Recommended) - Fast, works with any GPU via Vulkan
- Whisper (OpenAI) - PyTorch-based, NVIDIA GPU only
- 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.
Installation Options
Default (whisper.cpp - recommended):
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:
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:
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
# 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 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
# 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 for distribution-specific information and experimental support for Gentoo, Alpine, Void, Solus, and more.
🎙️ Usage
Voice Dictation
- Toggle mode: Double-tap the shortcut key (default Ctrl) to start recording
- Speak clearly into your microphone
- 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
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
systemdunit/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:
{
"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
# 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 - Detailed installation instructions
- Update Guide - How to update Vocalinux
- User Guide - Complete user documentation
- Distribution Compatibility - Distro/session behavior and caveats
- Contributing - 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:
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
Custom icon design✅Graphical settings dialog✅Whisper AI support✅Multi-language support (FR, DE, RU)✅whisper.cpp integration (default engine)✅Vulkan GPU support✅- In-app update mechanism
- Application-specific commands
- Debian/Ubuntu package (.deb)
Wayland support via IBus✅- Voice command customization
🌐 The Voca Ecosystem
Vocalinux is part of a family of privacy-first, offline voice dictation tools. Same mission, every operating system.
| Platform | Project | Website | GitHub | Status |
|---|---|---|---|---|
| 🐧 Linux | VocaLinux | vocalinux.com | jatinkrmalik/vocalinux | ✅ Beta v0.9.0 |
| 🍎 macOS | VocaMac | vocamac.com | jatinkrmalik/vocamac | 🚀 Beta |
| 🪟 Windows | VocaWin | vocawin.com | jatinkrmalik/vocawin | 📋 Planned |
Each platform uses native technologies for the best possible integration, while sharing the same privacy-first philosophy and offline-only architecture.
🤝 Contributing
We welcome contributions! Whether it's bug reports, feature requests, or code contributions, please check out our Contributing Guide.
Contributors
Thanks to everyone who has contributed to Vocalinux! 🙌
Quick Links
⭐ 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 file for details.
Star Chart
Made with ❤️ for the Linux community