# Voice-to-Text System A real-time voice-to-text system using OpenAI Whisper that captures audio via global hotkeys and automatically types the transcribed text into any application. ## Features - **Real-time Speech Recognition**: Uses OpenAI Whisper for high-quality offline transcription - **Global Hotkeys**: Start/stop recording with customizable keyboard shortcuts (default: Ctrl+Alt+V) - **Cross-Application**: Works in any text field across all applications - **Daemon Support**: Can run as a background service - **Audio Feedback**: Optional sound notifications for recording start/stop - **Configurable**: JSON-based configuration with hot-reload support - **Privacy-First**: Completely offline operation, no data sent to external services ## Requirements ### System Requirements - Linux (Ubuntu/Debian, CentOS/RHEL, or similar) - Python 3.8 or higher - Audio input device (microphone) - X11 display server (for GUI automation) ### Dependencies - OpenAI Whisper for speech recognition - SoundDevice for audio capture - PyAutoGUI for text insertion - Pynput for global hotkey detection ## Installation ### Automated Installation (Recommended) 1. Clone or download this repository 2. Run the installation script with root privileges: ```bash sudo ./install/install.sh ``` The installer will: - Install system dependencies - Set up Python virtual environment - Install Python packages - Configure systemd service - Create configuration files - Set up command-line launcher ### Manual Installation 1. Install system dependencies: ```bash # Ubuntu/Debian sudo apt-get install python3-dev python3-pip python3-venv portaudio19-dev libsndfile1 ffmpeg alsa-utils pulseaudio xdotool # CentOS/RHEL sudo dnf install python3-devel python3-pip portaudio-devel libsndfile ffmpeg alsa-utils pulseaudio xdotool ``` 2. Create Python virtual environment: ```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` 3. Configure settings in `config/default_settings.json` ## Usage ### Command Line After installation, use the `voice-to-text` command: ```bash # Run in foreground voice-to-text # Run as daemon voice-to-text --daemon # Check status voice-to-text --status # Stop daemon voice-to-text --stop # Verbose logging voice-to-text --verbose ``` ### Systemd Service ```bash # Start service sudo systemctl start voice-to-text # Stop service sudo systemctl stop voice-to-text # Check status sudo systemctl status voice-to-text # Enable auto-start sudo systemctl enable voice-to-text ``` ### Basic Workflow 1. Start the application (foreground or daemon mode) 2. Press the hotkey (default: Ctrl+Alt+V) to start recording 3. Speak your message 4. Press the hotkey again to stop recording 5. The transcribed text will be automatically typed at your cursor position ## Configuration Configuration files are located in `/etc/voice-to-text-system/` (or `config/` for development). ### Main Settings (`default_settings.json`) ```json { \"hotkey\": \"++v\", \"audio\": { \"sample_rate\": 16000, \"channels\": 1, \"device_index\": null, \"noise_reduction_level\": 1, \"silence_threshold\": -40 }, \"whisper\": { \"model\": \"small\", \"language\": null }, \"typing\": { \"speed\": 0.05 }, \"logging\": { \"level\": \"INFO\", \"file\": \"/var/log/voice-to-text-system/voice-to-text.log\" } } ``` ### User Overrides (`user_settings.json`) You can override any default settings by creating a `user_settings.json` file: ```json { \"hotkey\": \"++r\", \"whisper\": { \"model\": \"base\" } } ``` ### Configuration Options #### Hotkeys - Format: `++` - Modifiers: `ctrl`, `alt`, `shift`, `cmd`/`super` - Examples: `++v`, `++space` #### Whisper Models - `tiny`: Fastest, lowest accuracy (~39M parameters) - `base`: Fast, good for simple speech (~74M parameters) - `small`: **Recommended** balance of speed/accuracy (~244M parameters) - `medium`: Slower but more accurate (~769M parameters) - `large`: Slowest, highest accuracy (~1550M parameters) #### Audio Settings - `sample_rate`: Audio sampling rate (16000 recommended) - `channels`: 1 for mono, 2 for stereo - `device_index`: Specific audio device (null for default) - `noise_reduction_level`: 0-3, higher = more noise reduction - `silence_threshold`: dB level to detect silence (-40 recommended) ## Troubleshooting ### Common Issues **1. \"Permission denied\" errors** - Make sure you're running with appropriate permissions - Check that audio device is accessible - Verify hotkey permissions for global capture **2. No audio captured** - Test microphone with: `voice-to-text --test-audio` - Check audio device settings - Verify PulseAudio/ALSA configuration **3. Hotkey not working** - Ensure no other application is using the same hotkey - Try running with `--verbose` to see hotkey detection logs - Check X11 permissions for input capture **4. Text not being inserted** - Verify the target application has focus - Check that PyAutoGUI has necessary permissions - Try the clipboard insertion method as fallback **5. Whisper model download fails** - Check internet connection for initial model download - Ensure sufficient disk space (~1-10GB depending on model) - Models are cached in `~/.cache/whisper/` ### Audio Device Testing ```bash # List available audio devices python3 -c \"import sounddevice; print(sounddevice.query_devices())\" # Test specific device voice-to-text --test-audio --device 0 ``` ### Log Files - Application logs: `/var/log/voice-to-text-system/voice-to-text.log` - Service logs: `journalctl -u voice-to-text -f` ## Development ### Project Structure ``` voice-to-text-system/ ├── src/ # Source code │ ├── main.py # Main application entry point │ ├── config_manager.py # Configuration management │ ├── speech_recognizer.py # Whisper integration │ ├── audio_manager.py # Audio capture │ ├── text_inserter.py # Text insertion │ ├── hotkey_detector.py # Global hotkey detection │ └── service_manager.py # Daemon functionality ├── config/ # Configuration files ├── sounds/ # Audio feedback files ├── install/ # Installation scripts ├── tests/ # Test files └── logs/ # Log files ``` ### Running for Development ```bash cd src python3 main.py --config ../config --verbose ``` ### Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License This project is open source. Please check the LICENSE file for details. ## Privacy and Security - **Offline Operation**: All processing happens locally, no data sent to external servers - **Temporary Files**: Audio recordings are stored temporarily and deleted after processing - **No Data Collection**: No usage analytics or telemetry - **Configurable Logging**: Control what information is logged ## Performance Tips - Use the `small` Whisper model for best speed/accuracy balance - Ensure adequate CPU resources (Whisper is CPU-intensive) - Use a good quality microphone for better transcription accuracy - Speak clearly and avoid background noise - Consider noise reduction settings for noisy environments ## Support For issues, questions, or contributions: - Check the troubleshooting section above - Review log files for error details - Test individual components with verbose logging - Ensure all dependencies are properly installed