diff --git a/README.md b/README.md index a06b4f4..b8695fd 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,286 @@ -# JUST-SAY-IT -A simple, lightweight voice-to-text converter for Linux. +# 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