voculinux/README.md

Ubuntu Voice Typing

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

Overview

Ubuntu Voice Typing provides a user-friendly speech-to-text solution for Linux users with:

• Activation via customizable keyboard shortcuts (default: Alt+Shift+V)
• Real-time transcription with minimal latency
• Universal compatibility across applications
• Offline operation for privacy and reliability
• Visual indicators for microphone 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

Project Structure

ubuntu-voice-typing/
├── docs/                      # Documentation
│   ├── INSTALL.md            # Installation guide
│   └── USER_GUIDE.md         # User guide with command reference
├── 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
│       ├── config_manager.py  # Configuration management
│       ├── keyboard_shortcuts.py  # Keyboard shortcut handling
│       └── tray_indicator.py  # System tray UI
├── tests/                     # Test suite
│   └── test_basic.py         # Basic unit tests
├── install.sh                 # Installation script
├── LICENSE                    # GPLv3 license
├── README.md                  # This file
├── setup.py                   # Python package configuration
└── ubuntu-voice-typing.desktop  # Desktop entry file

Installation

Prerequisites

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

Quick Install

# Clone the repository
git clone https://github.com/ubuntu-voice-typing/ubuntu-voice-typing.git
cd ubuntu-voice-typing

# 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 Ubuntu Voice Typing in several ways:

# From the terminal
ubuntu-voice-typing

# With debugging enabled
ubuntu-voice-typing --debug

# With a specific speech recognition engine
ubuntu-voice-typing --engine whisper

# With a specific model size
ubuntu-voice-typing --model medium

Using Voice Commands

Ubuntu Voice Typing 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/ubuntu-voice-typing/config.json and includes:

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

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/ubuntu-voice-typing/ubuntu-voice-typing.git
cd ubuntu-voice-typing

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

# Run tests
pytest tests/

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

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

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

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

   • Manages global keyboard shortcuts
   • Enables activation from any application

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

Contributing

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

License

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