57 lines
1.8 KiB
Markdown
57 lines
1.8 KiB
Markdown
# Voice Assistant Bridge (Docker Backend)
|
|
|
|
This repository contains the backend infrastructure for the local Voice Assistant system. It acts as the middleware between the ESP32 audio stream and Home Assistant.
|
|
|
|
## 🏗️ Architecture
|
|
|
|
```mermaid
|
|
graph LR
|
|
ESP32[ESP32 Hardware] -->|MQTT Audio Stream| Bridge
|
|
Bridge[Python Bridge] -->|HTTP Request| Whisper[Faster-Whisper Container]
|
|
Whisper -->|Text| Bridge
|
|
Bridge -->|MQTT Text Command| HA[Home Assistant]
|
|
Bridge -->|MQTT Status| ESP32
|
|
```
|
|
|
|
## 🧩 Components
|
|
|
|
### 1. `docker-compose.yml`
|
|
Orchestrates two containers:
|
|
* **`voice-bridge`**: The logic handler. Listens to MQTT audio, buffers it, detects Wake Words via `OpenWakeWord`, and handles routing.
|
|
* **`whisper-api`**: A lightweight Flask API wrapping `faster-whisper` for Speech-to-Text conversion.
|
|
|
|
### 2. `mqtt_audio_bridge.py`
|
|
The main Python script running inside the `voice-bridge` container.
|
|
* **Input:** Listens to raw PCM audio on `voice/audio_stream` (Broker .13).
|
|
* **Processing:**
|
|
* Uses **OpenWakeWord** to detect "Hey Jarvis".
|
|
* Buffers audio and sends to Whisper API.
|
|
* Safety mechanisms (Memory limits, Log rotation).
|
|
* **Output:** Publishes transcribed text to `homeassistant/voice/text` (Broker .30).
|
|
|
|
### 3. `app.py`
|
|
The Whisper API endpoint.
|
|
* **Model:** `small.en` (Optimized for CPU usage with `int8` quantization).
|
|
* **Language:** Locked to English to prevent hallucinations on static/silence.
|
|
|
|
## 🚀 Deployment
|
|
|
|
1. **Requirements:** Docker & Docker Compose.
|
|
2. **Configuration:** Update IP addresses in `mqtt_audio_bridge.py` for your MQTT brokers.
|
|
3. **Run:**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## 🔧 Debugging
|
|
|
|
**View Logs:**
|
|
```bash
|
|
docker compose logs -f voice_bridge
|
|
```
|
|
|
|
**Restart Stack:**
|
|
```bash
|
|
docker compose restart
|
|
```
|