voculinux/README.md

Vocalinux

A seamless voice dictation system for Linux, comparable to the built-in solutions on macOS and Windows.

Overview

Vocalinux provides a user-friendly speech-to-text solution for Linux users with:

• Activation via double-tap Ctrl keyboard shortcut
• Real-time transcription with minimal latency
• Universal compatibility across applications
• Offline operation for privacy and reliability
• Visual indicators for microphone status
• Audio feedback for recognition status

Technical Foundation

This project leverages existing open-source technologies:

• Speech recognition: VOSK API / Whisper
• Text injection: xdotool (X11) / ydotool/wtype (Wayland)
• User interface: GTK for system tray and settings
• Audio feedback: PulseAudio for sound notifications

Project Structure

vocalinux/
├── docs/                      # Documentation
│   ├── INSTALL.md            # Installation guide
│   └── USER_GUIDE.md         # User guide with command reference
├── resources/                 # Resource files
│   └── sounds/               # Audio notification sounds
│       ├── start_recording.wav  # Sound when recording starts
│       ├── stop_recording.wav   # Sound when recording stops
│       └── error.wav            # Sound when an error occurs
├── src/                       # Source code
│   ├── __init__.py           # Package initialization
│   ├── main.py               # Main entry point
│   ├── speech_recognition/   # Speech recognition components
│   │   ├── __init__.py
│   │   ├── command_processor.py  # Voice commands processor
│   │   └── recognition_manager.py  # Speech recognition engine management
│   ├── text_injection/       # Text injection components
│   │   ├── __init__.py
│   │   └── text_injector.py  # X11/Wayland text injection
│   └── ui/                   # User interface components
│       ├── __init__.py
│       ├── audio_feedback.py  # Audio notification system
│       ├── config_manager.py  # Configuration management
│       ├── keyboard_shortcuts.py  # Keyboard shortcut handling
│       └── tray_indicator.py  # System tray UI
├── tests/                     # Test suite
│   ├── conftest.py           # Pytest configuration
│   ├── test_audio_feedback.py
│   ├── test_command_processor.py
│   ├── test_config_manager.py
│   ├── test_keyboard_shortcuts.py
│   ├── test_main.py
│   ├── test_recognition_manager.py
│   ├── test_speech_recognition.py
│   ├── test_text_injector.py
│   └── test_tray_indicator.py
├── activate-vocalinux.sh     # Script to activate the environment
├── install.sh                 # Installation script
├── LICENSE                    # GPLv3 license
├── README.md                  # This file
├── setup.py                   # Python package configuration
└── vocalinux.desktop          # Desktop entry file

Installation

Prerequisites

• Ubuntu 22.04 or newer (may work on other Linux distributions)
• Python 3.8 or newer
• X11 or Wayland desktop environment

Quick Install

# Clone the repository
git clone https://github.com/jatinkrmalik/vocalinux.git
cd vocalinux

# Run the installer script
./install.sh

The installer will:

1. Install system dependencies
2. Set up Python dependencies
3. Configure the application
4. Create a desktop entry

For detailed installation instructions, see docs/INSTALL.md.

Usage

Starting the Application

After installation, you can start Vocalinux in several ways:

# From the terminal
vocalinux

# With debugging enabled
vocalinux --debug

# With a specific speech recognition engine
vocalinux --engine whisper

# With a specific model size
vocalinux --model medium

# Force Wayland compatibility mode
vocalinux --wayland

Using Voice Dictation

1. Double-tap the Ctrl key to start recording
2. You'll hear a start sound when recording begins
3. Speak clearly into your microphone
4. Double-tap Ctrl again or pause speaking to stop recording
5. You'll hear a stop sound when recording ends

Using Voice Commands

Vocalinux supports various voice commands for text formatting:

Command	Action
"new line"	Inserts a line break
"period"	Types a period (.)
"comma"	Types a comma (,)
"question mark"	Types a question mark (?)
"delete that"	Deletes the last sentence
"capitalize"	Capitalizes the next word

For a complete list of commands, see docs/USER_GUIDE.md.

Configuration

Configuration is stored in ~/.config/vocalinux/config.json and includes:

{
    "recognition": {
        "engine": "vosk",
        "model_size": "small",
        "auto_punctuate": true,
        "vad_sensitivity": 3,
        "timeout": 2.0
    },
    "shortcuts": {
        "toggle_recognition": "ctrl+ctrl"
    },
    "ui": {
        "start_minimized": false,
        "show_notifications": true,
        "audio_feedback": true
    },
    "advanced": {
        "debug_logging": false,
        "wayland_mode": false
    }
}

Custom Sounds

You can customize the audio feedback by replacing the sound files in the resources/sounds/ directory:

• start_recording.wav - Played when recording starts
• stop_recording.wav - Played when recording stops
• error.wav - Played when an error occurs

WAV format is used for all audio notifications.

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/jatinkrmalik/vocalinux.git
cd vocalinux

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality and consistency. The hooks will automatically check your code for linting errors before each commit, which helps prevent CI pipeline failures.

To set up pre-commit hooks:

1. Install pre-commit: pip install pre-commit
2. Install the git hooks: pre-commit install

Now, when you try to commit changes, the pre-commit hooks will automatically run and check your code. If any issues are found, the commit will be blocked until you fix them.

To manually run all pre-commit hooks on all files:

pre-commit run --all-files

Pre-commit Checks

The following checks are performed by pre-commit:

• black: Code formatting
• isort: Import sorting
• flake8: Code style and error detection
• Various file checks (trailing whitespace, merge conflicts, etc.)

Key Components

1. Speech Recognition Manager (src/speech_recognition/recognition_manager.py)

   • Manages speech recognition engines (VOSK, Whisper)
   • Handles audio recording and voice activity detection
   • Processes recognition results

2. Command Processor (src/speech_recognition/command_processor.py)

   • Interprets voice commands in recognition results
   • Converts commands to text or actions

3. Text Injector (src/text_injection/text_injector.py)

   • Injects text into active applications
   • Supports both X11 and Wayland environments
   • Automatically falls back to XWayland when needed

4. Audio Feedback (src/ui/audio_feedback.py)

   • Provides audio cues for application states
   • Uses WAV format for sound files
   • Uses system audio players (PulseAudio/ALSA)

5. Tray Indicator (src/ui/tray_indicator.py)

   • Provides system tray interface
   • Shows recognition status
   • Offers menu for control

6. Keyboard Shortcut Manager (src/ui/keyboard_shortcuts.py)

   • Manages global keyboard shortcuts
   • Enables activation from any application
   • Handles modifier key normalization

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=src

Roadmap

Future development plans include:

1. Custom icon design
2. Graphical settings dialog
3. Advanced voice commands for specific applications
4. Multi-language support
5. Better integration with popular applications
6. Improved model management
7. Customizable keyboard shortcuts via GUI
8. More audio feedback options

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For contribution guidelines, please see CONTRIBUTING.md.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.