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.6.1-beta

This patch release brings significant improvements to the installation experience and GPU support!

✨ New Features

• Interactive Backend Selection - When installing whisper.cpp, choose between GPU (Vulkan/CUDA) or CPU backend

  • Intelligent hardware detection recommends the best option
  • Shows helpful tips when GPU libraries are missing
  • Respects your choice during installation

• Enhanced Welcome Message - Completely redesigned end-of-installation experience

  • Shows exactly what was installed (engine, backend, locations)
  • Clear step-by-step testing instructions
  • Voice command examples ("period", "comma", "new line", "delete that")
  • All management commands in one place

🔧 Improvements

• Simplified Install Commands - No more --tag parameter needed

  • Before: curl .../main/install.sh | bash -s -- --tag=v0.6.1-beta
  • After: curl .../v0.6.1-beta/install.sh | bash

• Version Consistency - Install script is now downloaded directly from the release tag

  • Ensures perfect version matching between script and code
  • No risk of main branch changes affecting releases

• Better GPU Support - Fixed Vulkan development library detection

  • Properly installs libvulkan-dev, glslc, and other required packages
  • Falls back gracefully when GPU libraries are missing
  • Clear error messages with installation instructions

🐛 Bug Fixes

• Fixed Bash Compatibility - Resolved ((var++)) arithmetic issues with set -e
• Fixed TTY Detection - Interactive mode now works correctly with --interactive flag
• Auto-install Git - Installer now automatically installs git if not present
• Fixed GPU Installation - Properly executes pip commands for GPU backend installation

---

Previous Release: v0.6.0-beta

Major milestone: whisper.cpp is now the default engine!

• ⚡ 10x faster installation (~1-2 min vs ~5-10 min)
• 🎮 Universal GPU support - AMD, Intel, NVIDIA via Vulkan
• 🤖 whisper.cpp integration - C++ optimized speech recognition
• 📦 Interactive installer - Choose between 3 engines
• 🔧 Hardware auto-detection - GPU, RAM, Vulkan support detection
• 🐛 Critical bug fixes - Text escaping, audio feedback, punctuation

---

🎉 Beta Release with whisper.cpp!

We're excited to share Vocalinux Beta with the community! whisper.cpp brings 10x faster installation and universal GPU support. See "What's New" above for details.

---

✨ Features

• 🎤 Double-tap Ctrl to start/stop voice dictation
• ⚡ 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
• 🔊 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/v0.6.1-beta/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

: Installs v0.6.1-beta. For other versions, check GitHub Releases.

Installation Options

Default (whisper.cpp - recommended):

curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/v0.6.1-beta/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/v0.6.1-beta/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/v0.6.1-beta/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.

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

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

⚙️ 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
• 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)
• 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