# Architecture Overview

High-level architecture of Wyoming Satellite.

## Core Components

```
┌─────────────────────────────────────────────────────────────┐
│                    Home Assistant                           │
│                  (Wyoming Integration)                      │
└──────────────────────┬──────────────────────────────────────┘
                       │ Wyoming Protocol (TCP)
                       │ Port 10700
┌──────────────────────▼──────────────────────────────────────┐
│              Wyoming Satellite                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  SatelliteBase                                      │   │
│  │  ├─ AlwaysStreamingSatellite                        │   │
│  │  ├─ VadStreamingSatellite                           │   │
│  │  └─ WakeStreamingSatellite                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ MicSettings  │  │ SndSettings  │  │ WakeSettings │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              EventHandler                           │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────┬─────────────────────┬───────────────────────────┘
           │                     │
           │ Audio In            │ Audio Out
           │ (arecord)           │ (aplay)
┌──────────▼──────┐     ┌────────▼──────────┐
│   Microphone    │     │     Speaker       │
│   USB/HAT       │     │     USB/HAT       │
└─────────────────┘     └───────────────────┘

┌─────────────────────────────────────────────────────────────┐
│              Local Services (Optional)                      │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐         │
│  │  Wake Word Service  │  │   Event Service     │         │
│  │  (Vosk, port 10400) │  │  (MQTT, port 10500) │         │
│  └─────────────────────┘  └─────────────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

## Satellite Modes

### AlwaysStreamingSatellite

Continuously streams audio to Home Assistant.

- **Pros:** Lowest latency, simplest
- **Cons:** Highest bandwidth, no local processing
- **Use case:** Fast LAN, no privacy concerns

### VadStreamingSatellite

Uses Voice Activity Detection to start streaming only when speech is detected.

- **VAD Systems:**
  - **Silero:** Neural network-based, more accurate
  - **WebRTC:** Lightweight, faster
- **Features:**
  - Pre-roll buffer (sends audio before VAD trigger)
  - Wake word timeout (wait for wake word after VAD)
- **Use case:** Privacy-focused, bandwidth-constrained

### WakeStreamingSatellite

Uses local wake word detection before streaming.

- **Wake Word Systems:**
  - **Vosk:** Grammar-based (Russian phrases)
  - **openWakeWord:** Neural network
  - **Porcupine:** Commercial KWS
- **Flow:**
  1. Continuously listen for wake word
  2. On detection → start streaming to HA
  3. Process command → stop streaming
- **Use case:** Full local wake word, "Hey Google" style

## Audio Pipeline

```
Microphone
    │
    ▼
┌─────────────────┐
│ Audio Capture   │ arecord -r 16000 -c 1 -f S16_LE
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Pre-processing  │ Volume, AGC, Noise Suppression
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ VAD / Wake      │ Decision: stream or not?
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Wyoming Protocol│ Encode to Wyoming messages
└────────┬────────┘
         │
         ▼
    Home Assistant
```

## Key Files

| File | Purpose |
|------|---------|
| `wyoming_satellite/__main__.py` | CLI entry point, argument parsing |
| `wyoming_satellite/satellite.py` | Satellite implementations |
| `wyoming_satellite/settings.py` | Settings dataclasses |
| `wyoming_satellite/event_handler.py` | Wyoming event handling |
| `wyoming_satellite/vad.py` | VAD implementations (Silero, WebRTC) |
| `wyoming_satellite/webrtc.py` | WebRTC audio processing |

## Configuration

Main configuration via CLI arguments (see `__main__.py`):

```bash
# Microphone
--mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw'
--mic-noise-suppression 2
--mic-auto-gain 5

# Wake word
--wake-uri tcp://127.0.0.1:10400
--wake-word-name "привет дроид"

# VAD
--vad
--vad-system webrtc
--vad-threshold 0.5

# Events (LED, MQTT)
--event-uri tcp://127.0.0.1:10500
```

## State Machine

```
                    ┌──────────────┐
                    │   Stopped    │
                    └──────┬───────┘
                           │ Start
                           ▼
                    ┌──────────────┐
          ┌────────│  Listening   │────────┐
          │        └──────┬───────┘        │
          │               │                │
    VAD trigger     Wake detection    Streaming
          │               │                │
          ▼               ▼                ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │  VAD     │    │   Wake   │    │Streaming │
    │ Active   │    │  Active  │    │  Audio   │
    └────┬─────┘    └────┬─────┘    └────┬─────┘
         │               │               │
         └───────────────┴───────────────┘
                         │
                    AudioStop
                         ▼
                  ┌──────────────┐
                  │  Listening   │
                  └──────────────┘
```