sirmrakandQwen-Coder
adac79e765
- Перемещена документация в docs/ с четкой структурой: - tutorials/ — пошаговые руководства (2mic-hat, installer) - integration/ — техническая интеграция (vad-wakeword, mqtt-led) - deployment/ — развёртывание (systemd-services) - architecture/ — архитектура проекта (overview) - Обновлён README.md с навигацией по документации - DEPLOY.md сокращён до quick start с ссылками на docs/ - Добавлен docs/README.md — индекс документации - Создан QWEN.md — контекст для ИИ-ассистента - Удалён мусор: - wyoming_satellite.zip (build artifact) - wyoming-led.service, wyoming-satellite.service (дубликаты) - .qwen/settings.json.orig (бэкап) - .lgd-nfy0 (пустой файл) - docker/run (заглушка) - Обновлён .gitignore: - examples/led_brightness_config.json (автогенерируемый конфиг) - *.old, *.bak, *~ (бэкапы) - *.zip (архивы) - .qwen/settings.json.orig - *.lgd-* (пустые файлы) - led_brightness_config.json исключён из отслеживания (assume-unchanged) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
191 lines
5.7 KiB
Markdown
191 lines
5.7 KiB
Markdown
# 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
|