# VoskWyoming Satellite — Project Context

## Project Overview

**VoskWyoming Satellite** is a remote voice satellite implementation using the [Wyoming protocol](https://github.com/rhasspy/wyoming) for Home Assistant voice control. It provides:

- **Home Assistant integration** via Wyoming protocol
- **Local wake word detection** using Vosk (Russian wake words: "привет дроид", etc.)
- **Audio enhancements** via WebRTC noise suppression and gain control
- **MQTT integration** for LED control (ReSpeaker XVF3800 4-MIC array) and Home Assistant discovery
- **Voice Activity Detection (VAD)** using Silero or WebRTC

**Key technologies:** Python 3.9+, Wyoming protocol, Vosk, WebRTC, MQTT, systemd

---

## Building and Running

### Prerequisites

```bash
sudo apt-get install python3-venv python3-pip alsa-utils
```

### Setup

```bash
# Clone and setup
cd ~/projects/Satellite
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate
pip install -r requirements.txt
```

### Run (Development)

```bash
# From project root
./start_satellite.sh          # Uses systemd-style config
./start-dev.sh                # Development mode
python3 -m wyoming_satellite  # Direct module run
```

**Main script:** `wyoming_satellite/__main__.py` — argparse-based CLI with extensive options for mic, sound, wake word, VAD, and event handling.

### Run (Production — systemd)

```bash
sudo ./install_systemd_services.sh  # Auto-installs services

# Start services
sudo systemctl enable --now wyoming-event.service
sudo systemctl enable --now wyoming-satelite-vosk.service
sudo systemctl enable --now wyoming-wakeword-vosk.service

# Check status
journalctl -u wyoming-satelite-vosk.service -f
```

### Services

| Service | Port | Description |
|---------|------|-------------|
| `wyoming-satelite-vosk.service` | 10700 | Main Wyoming satellite |
| `wyoming-wakeword-vosk.service` | 10400 | Vosk wake word detection |
| `wyoming-event.service` | 10500 | LED control + MQTT events |

---

## Development

### Code Quality

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

# Formatting
black wyoming_satellite/
isort wyoming_satellite/

# Tests
pytest tests/
tox  # Multi-version testing
```

**Config files:**
- `pylintrc` — Pylint with many disabled checks (pragmatic approach)
- `mypy.ini` — Permissive, ignores missing imports
- `.isort.cfg` — Import sorting
- `tox.ini` — pytest-based test runner for Python 3.9–3.13

### Project Structure

```
Satellite/
├── wyoming_satellite/       # Main package
│   ├── __main__.py          # CLI entry point
│   ├── satellite.py         # Satellite implementations
│   ├── settings.py          # Dataclass-based settings
│   ├── event_handler.py     # Wyoming event handling
│   ├── vad.py               # Voice activity detection
│   └── webrtc.py            # WebRTC audio processing
├── services/                 # systemd service files
├── examples/                 # Example scripts (LED, MQTT)
├── scripts/                  # Helper scripts
├── tests/                    # pytest tests
├── sounds/                   # Audio files (awake.wav, etc.)
├── start_satellite.sh        # Main startup script
├── install_systemd_services.sh  # Service installer
└── requirements.txt          # Dependencies
```

### Key Files

| File | Purpose |
|------|---------|
| `wyoming_satellite/__main__.py` | Main entry point, CLI parsing |
| `wyoming_satellite/satellite.py` | `SatelliteBase`, `AlwaysStreamingSatellite`, `VadStreamingSatellite`, `WakeStreamingSatellite` |
| `wyoming_satellite/settings.py` | Settings dataclasses (`MicSettings`, `SndSettings`, `VadSettings`, `WakeSettings`, etc.) |
| `start_satellite.sh` | Production startup script (wake/vad modes) |
| `services/*.service` | systemd unit files with placeholders |

---

## Configuration

### Wake Words (Russian)

Configured in `start_satellite.sh`:
```bash
--wake-word-name "привет дроид"
--wake-word-name "привет придурок"
--wake-word-name "привет жопа с ушами"
```

### VAD Settings

```yaml
# local/vosk-wake-dev/wyoming_vosk_wake/config.yaml
vad:
  vad_enabled: true
  energy_threshold: 800
  speech_threshold: 0.5
  min_speech_duration_ms: 200
```

### MQTT (LED Control)

Topics in `examples/wyoming-led.py`:
- `wyoming/led/command`
- `wyoming/led/brightness/set`
- `wyoming/led/brightness/state`
- `wyoming/led/state`
- `wyoming/led/availability`

---

## Testing Practices

- **Framework:** pytest + pytest-asyncio
- **Test files:** `tests/test_satellite.py`, `tests/test_wake_streaming.py`
- **Shared fixtures:** `tests/shared.py`
- **Multi-version:** tox runs tests on Python 3.9–3.13

---

## Deployment Notes

- **Virtual env location:** `~/.venv_satellite` or `~/projects/.venv_satellite`
- **Service installer:** `install_systemd_services.sh` auto-detects venv path and substitutes placeholders (`__SAT_BASE_DIR__`, `__SAT_VENV__`, `__CURRENT_USER__`)
- **Wrapper script:** `satellite-python` installed to `/usr/local/bin/` for systemd services

---

## External Resources

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

---

## Known Issues / Workarounds

- **pylintrc:** Many checks disabled — pragmatic approach, focus on functionality over strict linting
- **mypy:** `ignore_missing_imports = true` — third-party stubs not always available
- **Audio:** Uses `arecord`/`aplay` with specific hardware (`plughw:CARD=Array,DEV=0`) — adjust for different microphones