Update README.md
This commit is contained in:
@@ -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\": \"<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:
|
||||
|
||||
```json
|
||||
{
|
||||
\"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 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
|
||||
|
||||
Reference in New Issue
Block a user