# README — VoskWyoming Satellite

Remote voice satellite using the [Wyoming protocol](https://github.com/rhasspy/wyoming) for Home Assistant.

[![An open standard from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-open-standard.png)](https://www.openhomefoundation.org/)

## Features

- 🏠 **Home Assistant integration** — Native Wyoming protocol support
- 🎤 **Local wake word detection** — Vosk-based Russian wake words ("привет дроид", etc.)
- 🔇 **Audio enhancements** — WebRTC noise suppression and automatic gain control
- 💡 **MQTT LED control** — ReSpeaker XVF3800 4-MIC array support with HA discovery
- 🎯 **Voice Activity Detection** — Silero or WebRTC VAD for privacy-focused operation

## Quick Start

### 1. Install

```bash
git clone <repository-url> ~/projects/Satellite
cd ~/projects/Satellite

python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate
pip install -r requirements.txt
```

### 2. Install systemd Services

```bash
sudo ./install_systemd_services.sh
```

### 3. Start

```bash
sudo systemctl enable --now wyoming-satelite-vosk.service
sudo systemctl status wyoming-satelite-vosk.service
```

In Home Assistant: **Settings → Devices & Services → Discovered → Wyoming Satellite → Configure**

---

## Documentation

| Guide | Description |
|-------|-------------|
| [**Deployment**](DEPLOY.md) | Full deployment guide with systemd services |
| [**Tutorials**](docs/tutorials/) | Step-by-step setup for different hardware |
| [**Architecture**](docs/architecture/overview.md) | How Wyoming Satellite works |
| [**MQTT LED**](docs/integration/mqtt-led.md) | LED control with Home Assistant |
| [**VAD Integration**](docs/integration/vad-wakeword.md) | Technical integration guide |

### Tutorials

- [**2-MIC HAT**](docs/tutorials/2mic-hat.md) — Raspberry Pi + ReSpeaker 2-MIC HAT
- [**Installer**](docs/tutorials/installer.md) — Interactive installer guide

---

## Requirements

- **Python 3.9+**
- **Linux** (tested on Raspberry Pi OS)
- **Microphone** (USB or HAT)
- **Optional:** ReSpeaker XVF3800 USB 4-MIC Array (for LED control)

---

## Project Structure

```
Satellite/
├── wyoming_satellite/       # Main Python package
├── examples/                # Example scripts (LED, MQTT, configs)
├── services/                # systemd service files
├── docs/                    # Documentation
│   ├── tutorials/          # Hardware-specific guides
│   ├── integration/        # Technical integration guides
│   ├── deployment/         # Deployment guides
│   └── architecture/       # Architecture documentation
├── sounds/                  # Audio files (awake.wav, etc.)
├── scripts/                 # Helper scripts
└── tests/                   # Unit tests
```

---

## Configuration

### Wake Words (Russian)

Edit `start_satellite.sh`:

```bash
--wake-word-name "привет дроид"
--wake-word-name "привет придурок"
--wake-word-name "привет жопа с ушами"
```

### Audio Settings

```bash
--mic-noise-suppression 2
--mic-auto-gain 5
```

### VAD Settings

```bash
--vad
--vad-system webrtc
--vad-threshold 0.5
```

---

## Development

```bash
# Linting
pylint wyoming_satellite/
mypy wyoming_satellite/

# Tests
pytest tests/

# Format
black wyoming_satellite/
isort wyoming_satellite/
```

---

## 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)

---

## External Resources

- [Wyoming Protocol](https://github.com/rhasspy/wyoming)
- [Home Assistant Integration](https://www.home-assistant.io/integrations/wyoming)
- [Vosk](https://alphacephei.com/vosk/)
- [ReSpeaker 4-MIC Array](https://github.com/respeaker/usb_4mic_array)

---

## License

This project is part of the Open Home Foundation ecosystem.

[![An open standard from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-open-standard.png)](https://www.openhomefoundation.org/)