# Архитектура Wyoming Satellite

Обзор архитектуры Wyoming Satellite.

## Основные компоненты

```
┌─────────────────────────────────────────────────────────────┐
│                    Home Assistant                           │
│                  (Wyoming интеграция)                       │
└──────────────────────┬──────────────────────────────────────┘
                       │ Wyoming Protocol (TCP)
                       │ Порт 10700
┌──────────────────────▼──────────────────────────────────────┐
│              Wyoming Satellite                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  SatelliteBase                                      │   │
│  │  ├─ AlwaysStreamingSatellite                        │   │
│  │  ├─ VadStreamingSatellite                           │   │
│  │  └─ WakeStreamingSatellite                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ MicSettings  │  │ SndSettings  │  │ WakeSettings │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              EventHandler                           │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────┬─────────────────────┬───────────────────────────┘
           │                     │
           │ Audio In            │ Audio Out
           │ (arecord)           │ (aplay)
┌──────────▼──────┐     ┌────────▼──────────┐
│   Микрофон      │     │   Динамик         │
│   USB/HAT       │     │   USB/HAT         │
└─────────────────┘     └───────────────────┘

┌─────────────────────────────────────────────────────────────┐
│              Локальные сервисы (опционально)                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐         │
│  │  Wake Word Service  │  │   Event Service     │         │
│  │  (Vosk, порт 10400) │  │  (MQTT, порт 10500) │         │
│  └─────────────────────┘  └─────────────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

## Режимы работы спутника

### AlwaysStreamingSatellite

Постоянно передаёт аудио в Home Assistant.

- **Преимущества:** Минимальная задержка, простота
- **Недостатки:** Высокий трафик, нет локальной обработки
- **Применение:** Быстрая LAN, нет требований к приватности

### VadStreamingSatellite

Использует Voice Activity Detection для начала стриминга только при обнаружении речи.

- **VAD системы:**
  - **Silero:** Нейросетевой, более точный
  - **WebRTC:** Лёгкий, быстрый
- **Возможности:**
  - Пре-буфер (отправляет аудио до триггера VAD)
  - Таймаут wake word (ожидание фразы после VAD)
- **Применение:** Приватность, ограничение трафика

### WakeStreamingSatellite

Использует локальную детекцию wake word перед стримингом.

- **Системы wake word:**
  - **Vosk:** Грамматика (русские фразы)
  - **openWakeWord:** Нейросеть
  - **Porcupine:** Коммерческий KWS
- **Поток:**
  1. Постоянное прослушивание wake word
  2. При обнаружении → стриминг в HA
  3. Обработка команды → остановка стриминга
- **Применение:** Полная локальная активация, стиль "Hey Google"

## Аудио пайплайн

```
Микрофон
    │
    ▼
┌─────────────────┐
│ Захват аудио    │ arecord -r 16000 -c 1 -f S16_LE
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Предобработка   │ Громкость, AGC, шумоподавление
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ VAD / Wake      │ Решение: стримить или нет?
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Wyoming Protocol│ Кодирование в Wyoming сообщения
└────────┬────────┘
         │
         ▼
    Home Assistant
```

## Основные файлы

| Файл | Назначение |
|------|------------|
| `wyoming_satellite/__main__.py` | CLI entry point, парсинг аргументов |
| `wyoming_satellite/satellite.py` | Реализации спутников |
| `wyoming_satellite/settings.py` | Dataclass настроек |
| `wyoming_satellite/event_handler.py` | Обработка Wyoming событий |
| `wyoming_satellite/vad.py` | VAD реализации (Silero, WebRTC) |
| `wyoming_satellite/webrtc.py` | WebRTC обработка аудио |

## Конфигурация

Основная конфигурация через CLI аргументы (см. `__main__.py`):

```bash
# Микрофон
--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

# События (LED, MQTT)
--event-uri tcp://127.0.0.1:10500
```

## Машина состояний

```
                    ┌──────────────┐
                    │   Остановка  │
                    └──────┬───────┘
                           │ Старт
                           ▼
                    ┌──────────────┐
          ┌────────│  Прослушивание│────────┐
          │        └──────┬───────┘        │
          │               │                │
    VAD триггер    Wake детекция    Стриминг
          │               │                │
          ▼               ▼                ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │  VAD     │    │   Wake   │    │Стриминг  │
    │ Активен  │    │  Активен │    │  Аудио   │
    └────┬─────┘    └────┬─────┘    └────┬─────┘
         │               │               │
         └───────────────┴───────────────┘
                         │
                    AudioStop
                         ▼
                  ┌──────────────┐
                  │  Прослушивание│
                  └──────────────┘
```

---

## 🔗 Связанное

- [Настройки (cheat sheet)](settings-cheatsheet.md)
- [Руководство по развёртыванию](../../DEPLOY.md)
- [Интеграция VAD/Wake](integration/vad-wakeword.md)