314 lines
7.2 KiB
Markdown
Executable File
314 lines
7.2 KiB
Markdown
Executable File
# VoskWyoming Satellite
|
|
|
|
Remote voice satellite using the [Wyoming protocol](https://github.com/rhasspy/wyoming).
|
|
|
|
* Works with [Home Assistant](https://www.home-assistant.io/integrations/wyoming)
|
|
* Local wake word detection using [Vosk](https://alphacephei.com/vosk/)
|
|
* Audio enhancements using [webrtc](https://github.com/rhasspy/webrtc-noise-gain/)
|
|
* MQTT integration for LED control and Home Assistant discovery
|
|
|
|
[](https://www.openhomefoundation.org/)
|
|
|
|
---
|
|
|
|
## 📋 Requirements
|
|
|
|
* Python 3.9+
|
|
* Linux (tested on Raspberry Pi OS)
|
|
* Microphone (USB or HAT)
|
|
* Optional: ReSpeaker XVF3800 USB 4-MIC Array (for LED control)
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Clone and Install
|
|
|
|
```bash
|
|
git clone <repository-url> ~/projects/Satellite
|
|
cd ~/projects/Satellite
|
|
|
|
# Create virtual environment
|
|
python3 -m venv ~/.venv_satellite
|
|
source ~/.venv_satellite/bin/activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Install systemd Services
|
|
|
|
```bash
|
|
sudo ./install_systemd_services.sh
|
|
```
|
|
|
|
This script automatically:
|
|
- Detects your virtual environment location
|
|
- Substitutes correct paths in service files
|
|
- Installs the `satellite-python` wrapper
|
|
|
|
### 3. Start Services
|
|
|
|
```bash
|
|
# LED control (optional, requires ReSpeaker)
|
|
sudo systemctl enable wyoming-event.service
|
|
sudo systemctl start wyoming-event.service
|
|
|
|
# Wyoming Satellite
|
|
sudo systemctl enable wyoming-satelite-vosk.service
|
|
sudo systemctl start wyoming-satelite-vosk.service
|
|
|
|
# Wake word detection (Vosk)
|
|
sudo systemctl enable wyoming-wakeword-vosk.service
|
|
sudo systemctl start wyoming-wakeword-vosk.service
|
|
```
|
|
|
|
### 4. Verify
|
|
|
|
```bash
|
|
sudo systemctl status wyoming-satelite-vosk.service
|
|
journalctl -u wyoming-satelite-vosk.service -f
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Installation
|
|
|
|
### System Dependencies
|
|
|
|
```bash
|
|
sudo apt-get install python3-venv python3-pip alsa-utils
|
|
```
|
|
|
|
### Python Dependencies
|
|
|
|
```bash
|
|
# Create and activate venv
|
|
python3 -m venv ~/.venv_satellite
|
|
source ~/.venv_satellite/bin/activate
|
|
|
|
# Install requirements
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Service Files
|
|
|
|
All service files are in `service/` directory and use placeholders that are automatically replaced during installation:
|
|
|
|
| Placeholder | Description |
|
|
|-------------|-------------|
|
|
| `__SAT_BASE_DIR__` | Path to Satellite repository |
|
|
| `__SAT_VENV__` | Path to virtual environment |
|
|
| `__CURRENT_USER__` | Current username |
|
|
| `__HOME_DIR__` | User home directory |
|
|
|
|
### Available Services
|
|
|
|
| Service | Description | Port |
|
|
|---------|-------------|------|
|
|
| `wyoming-satelite-vosk.service` | Main Wyoming satellite | 10700 |
|
|
| `wyoming-wakeword-vosk.service` | Vosk wake word detection | 10400 |
|
|
| `wyoming-event.service` | LED control + MQTT | 10500 |
|
|
|
|
### Configuration Files
|
|
|
|
| File | Location | Description |
|
|
|------|----------|-------------|
|
|
| `config.yaml` | `local/vosk-wake-dev/wyoming_vosk_wake/` | VAD and wake word settings |
|
|
| `led_brightness_config.json` | `examples/` | LED brightness levels (auto-created) |
|
|
|
|
---
|
|
|
|
## 🎤 Usage
|
|
|
|
### Manual Start (without systemd)
|
|
|
|
```bash
|
|
# Activate venv
|
|
source ~/.venv_satellite/bin/activate
|
|
|
|
# Start satellite
|
|
./start_satellite.sh
|
|
|
|
# Or directly
|
|
python3 -m wyoming_satellite \
|
|
--name 'my-satellite' \
|
|
--uri 'tcp://0.0.0.0:10700' \
|
|
--mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \
|
|
--snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw'
|
|
```
|
|
|
|
### Wake Word Configuration
|
|
|
|
Edit `local/vosk-wake-dev/wyoming_vosk_wake/config.yaml`:
|
|
|
|
```yaml
|
|
vad:
|
|
vad_enabled: true
|
|
energy_threshold: 800
|
|
speech_threshold: 0.5
|
|
min_speech_duration_ms: 200
|
|
|
|
logging_level: debug # debug, info, warning, error
|
|
```
|
|
|
|
### LED Control (ReSpeaker)
|
|
|
|
The LED service requires the [ReSpeaker XVF3800 control scripts](https://github.com/respeaker/usb_4mic_array):
|
|
|
|
```bash
|
|
# Clone ReSpeaker repo
|
|
git clone https://github.com/respeaker/usb_4mic_array.git ~/projects/reSpeaker_XVF3800_USB_4MIC_ARRAY
|
|
|
|
# The LED service will automatically find xvf_host.py
|
|
```
|
|
|
|
MQTT Topics:
|
|
- `wyoming/led/command` - Send commands
|
|
- `wyoming/led/brightness/set` - Set brightness (0-255)
|
|
- `wyoming/led/brightness/state` - Brightness state
|
|
- `wyoming/led/state` - Current LED state
|
|
- `wyoming/led/availability` - Online/offline status
|
|
|
|
---
|
|
|
|
## 🔍 Examples
|
|
|
|
See `examples/` directory for additional scripts:
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `wyoming-led.py` | LED control with MQTT and Home Assistant discovery |
|
|
| `2mic_service.py` | Configuration for 2-mic HAT |
|
|
| `4mic_service.py` | Configuration for 4-mic array |
|
|
| `usbmic_service.py` | Configuration for USB microphone |
|
|
|
|
---
|
|
|
|
## 🛠️ Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
Satellite/
|
|
├── service/ # systemd service files
|
|
├── examples/ # Example scripts
|
|
├── local/ # Local wake word services
|
|
│ └── vosk-wake-dev/ # Vosk wake word detection
|
|
├── scripts/ # Helper scripts
|
|
├── install_systemd_services.sh # Auto-install services
|
|
├── requirements.txt # Python dependencies
|
|
├── start_satellite.sh # Main startup script
|
|
└── DEPLOY.md # Deployment guide
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run linters
|
|
pylint wyoming_satellite/
|
|
mypy wyoming_satellite/
|
|
|
|
# Run tests (if available)
|
|
pytest tests/
|
|
```
|
|
|
|
### Updating Dependencies
|
|
|
|
```bash
|
|
# Update requirements.txt from current venv
|
|
pip freeze > requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
* [Deployment Guide](DEPLOY.md) - Full deployment instructions
|
|
* [Wyoming Protocol](https://github.com/rhasspy/wyoming) - Protocol documentation
|
|
* [Home Assistant Integration](https://www.home-assistant.io/integrations/wyoming) - HA setup
|
|
* [Vosk](https://alphacephei.com/vosk/) - Wake word recognition
|
|
|
|
---
|
|
|
|
## 🎥 Video Tutorials
|
|
|
|
* [Wyoming Voice Satellite with ChatGPT](https://www.youtube.com/watch?v=eTKgc0YDCwE)
|
|
* [Local ChatGPT Voice Assistant](https://www.youtube.com/watch?v=pAKqKTkx5X4)
|
|
|
|
---
|
|
|
|
## ⚙️ Audio Enhancements
|
|
|
|
### WebRTC Noise Suppression
|
|
|
|
Enabled by default via `requirements.txt` (webrtc-noise-gain==1.2.3)
|
|
|
|
Configure in satellite startup:
|
|
```bash
|
|
--mic-auto-gain 5 \
|
|
--mic-noise-suppression 2
|
|
```
|
|
|
|
### VAD (Voice Activity Detection)
|
|
|
|
Configured in `config.yaml`:
|
|
```yaml
|
|
vad:
|
|
vad_enabled: true
|
|
mode: 3 # 0-3, higher = more aggressive
|
|
sample_rate: 16000
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Service won't start
|
|
|
|
```bash
|
|
# Check status
|
|
sudo systemctl status wyoming-satelite-vosk.service
|
|
|
|
# View logs
|
|
journalctl -u wyoming-satelite-vosk.service -f
|
|
|
|
# Check Python path
|
|
which satellite-python
|
|
satellite-python --version
|
|
```
|
|
|
|
### Microphone not detected
|
|
|
|
```bash
|
|
# List audio devices
|
|
arecord -L
|
|
aplay -L
|
|
|
|
# Test recording
|
|
arecord -r 16000 -c 1 -f S16_LE -t raw -d 5 test.wav
|
|
aplay test.wav
|
|
```
|
|
|
|
### MQTT Connection Issues
|
|
|
|
Check broker settings in `examples/wyoming-led.py`:
|
|
```python
|
|
MQTT_BROKER = "192.168.200.100"
|
|
MQTT_PORT = 1883
|
|
MQTT_USER = "mqtt"
|
|
MQTT_PASS = "mqtt"
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
This project is part of the Open Home Foundation ecosystem.
|
|
|
|
[](https://www.openhomefoundation.org/)
|