Vocalinux

Voice-to-text for Linux, finally done right!

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:

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 for New Users)

Let the installer guide you through the setup with smart hardware detection:

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)

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.

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):

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:

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

# 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

# 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 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

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:

{
  "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

# 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 - Detailed installation instructions
• Update Guide - How to update Vocalinux
• User Guide - Complete user documentation
• 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) ✅
• In-app update mechanism
• Application-specific commands
• Debian/Ubuntu package (.deb)
• 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.

Quick Links

• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 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 file for details.

---

Made with ❤️ for the Linux community