satellite/docs/architecture/overview.md

Архитектура 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):

# Микрофон
--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)
• Руководство по развёртыванию
• Интеграция VAD/Wake