# README — VoskWyoming Satellite

Удалённый голосовой спутник, использующий [Wyoming protocol](https://github.com/rhasspy/wyoming) для Home Assistant.

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

## Возможности

- 🏠 **Интеграция с Home Assistant** — Нативная поддержка Wyoming протокола
- 🎤 **Локальная детекция wake word** — Vosk, русские фразы ("привет дроид" и др.)
- 🔇 **Аудио улучшения** — Шумоподавление WebRTC и автоматическое усиление
- 💡 **MQTT LED управление** — ReSpeaker XVF3800 4-MIC с авто-обнаружением HA
- 🎯 **Voice Activity Detection** — Silero или WebRTC VAD для приватной работы

## Быстрый старт

### 1. Установка

```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. Установка systemd сервисов

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

### 3. Запуск

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

В Home Assistant: **Настройки → Устройства и сервисы → Найдено → Wyoming Satellite → Настроить**

---

## Документация

| Руководство | Описание |
|-------------|----------|
| [**Развёртывание**](DEPLOY.md) | Полное руководство по развёртыванию |
| [**Tutorials**](docs/tutorials/) | Пошаговые руководства для разного оборудования |
| [**Архитектура**](docs/architecture/overview.md) | Как работает Wyoming Satellite |
| [**MQTT LED**](docs/integration/mqtt-led.md) | LED управление с Home Assistant |
| [**VAD/Wake интеграция**](docs/integration/vad-wakeword.md) | Техническое руководство |
| [**Настройки**](docs/settings-cheatsheet.md) | Шпаргалка по CLI флагам |

### Tutorials

- [**2-MIC HAT**](docs/tutorials/2mic-hat.md) — Raspberry Pi + ReSpeaker 2-MIC HAT
- [**Установщик**](docs/tutorials/installer.md) — Интерактивный установщик

---

## Требования

- **Python 3.9+**
- **Linux** (протестировано на Raspberry Pi OS)
- **Микрофон** (USB или HAT)
- **Опционально:** ReSpeaker XVF3800 USB 4-MIC Array (для LED управления)

---

## Структура проекта

```
Satellite/
├── wyoming_satellite/       # Основной Python пакет
├── examples/                # Примеры скриптов (LED, MQTT, конфиги)
├── services/                # systemd сервис файлы
├── docs/                    # Документация
│   ├── tutorials/          # Руководства по оборудованию
│   ├── integration/        # Технические руководства
│   ├── deployment/         # Руководства по развёртыванию
│   └── architecture/       # Документация по архитектуре
├── sounds/                  # Аудио файлы (awake.wav и др.)
├── scripts/                 # Вспомогательные скрипты
└── tests/                   # Юнит тесты
```

---

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

### Wake words (русские)

Отредактируйте `start_satellite.sh`:

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

### Аудио настройки

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

### VAD настройки

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

---

## Разработка

```bash
# Линтинг
pylint wyoming_satellite/
mypy wyoming_satellite/

# Тесты
pytest tests/

# Форматирование
black wyoming_satellite/
isort wyoming_satellite/
```

---

## Видео уроки

- [Wyoming Voice Satellite с ChatGPT](https://www.youtube.com/watch?v=eTKgc0YDCwE)
- [Локальный голосовой ассистент с ChatGPT](https://www.youtube.com/watch?v=pAKqKTkx5X4)

---

## Внешние ресурсы

- [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

Этот проект является частью экосистемы Open Home Foundation.

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