Документация: рефакторинг структуры docs/ и очистка мусора
- Перемещена документация в 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>
This commit is contained in:
Qwen-Coder
@@ -0,0 +1,190 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user