9b48cfa703eb8b2af2779edd2bfcc32f2b53ac51
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)
- Clone or download this repository
- Run the installation script with root privileges:
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
- Install system dependencies:
# 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
- Create Python virtual environment:
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
- Configure settings in
config/default_settings.json
Usage
Command Line
After installation, use the voice-to-text command:
# 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
# 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
- Start the application (foreground or daemon mode)
- Press the hotkey (default: Ctrl+Alt+V) to start recording
- Speak your message
- Press the hotkey again to stop recording
- 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)
{
\"hotkey\": \"<ctrl>+<alt>+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:
{
\"hotkey\": \"<ctrl>+<shift>+r\",
\"whisper\": {
\"model\": \"base\"
}
}
Configuration Options
Hotkeys
- Format:
<modifier>+<modifier>+<key> - Modifiers:
ctrl,alt,shift,cmd/super - Examples:
<ctrl>+<alt>+v,<ctrl>+<shift>+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 stereodevice_index: Specific audio device (null for default)noise_reduction_level: 0-3, higher = more noise reductionsilence_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
--verboseto 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
# 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
cd src
python3 main.py --config ../config --verbose
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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
smallWhisper 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
Languages
Python
84.7%
Shell
15.3%