How royalcities/rc-home-assistant-low-vram works
Project type and purpose
• This is a full-stack, self-hosted AI voice assistant “stack” built on Docker Compose.
• Purpose: provide local, GPU-accelerated voice interaction using open-source AI services (wake-word detection, speech-to-text, text-to-speech) plus Home Assistant for device control and automation.
File structure
Top-level files:
• docker-compose.yml – orchestrates all containers
• README.md – project overview, architecture hints
• AI-Persistent-Memory.md, Vocal-Command-Daisy-Chaining.md, Ollama-Model-Recommendations.md – advanced feature guides
Indirectly referenced folders (auto-created volumes):
• homeassistant_config/ – HA config volume
• whisper-data/ – Whisper model files
• piper-data/ – Piper voice data
• wakeword-data/ – custom wake-word models
Key insights from README
• Four main services: homeassistant (no GPU), whisper (CUDA STT), piper (CUDA TTS), openwakeword (CUDA wake-word).
• External dependency: Ollama AI daemon running on host at port 11434.
• GPU acceleration via nvidia-container-toolkit in each AI service.
• Host networking for mDNS/SSDP device discovery.
• Optional Bluetooth device passthrough to Home Assistant.
• Volumes auto-provisioned for persistence.
Main components
A. Input layer
• Microphone (host OS device)
• Wake-word detection container (openwakeword)
B. Processing layer
• Speech-to-Text container (Whisper)
• Conversation agent (Ollama, external)
C. Orchestration & control
• Home Assistant container
• Automations & device integrations (Zigbee, Matter, BLE, LAN)
D. Output layer
• Text-to-Speech container (Piper)
• Speaker (host OS audio output)
E. Persistent storage & config
• Volumes: homeassistant_config, whisper-data, piper-data, wakeword-data
F. External services & devices
• Ollama daemon (host)
• Smart home devices (lights, plugs, sensors)
• User’s browser/UI (http://localhost:8123)
Relationships & data flows
1. Microphone captures audio → forwarded to openwakeword
2. openwakeword detects wake-word → streams raw audio to Whisper
3. Whisper decodes → text transcript → sent to Home Assistant
4. Home Assistant routes text to Ollama agent (HTTP API)
5. Ollama generates response → returned to HA
6. HA forwards response text to Piper
7. Piper synthesizes audio → plays via speaker
8. HA triggers automations or device API calls (Zigbee, BLE, local LAN)
Architectural patterns & design principles
• Microservices: each AI function is a separate container
• Containerization with Docker Compose for easy orchestration
• Layered architecture (input → processing → orchestration → output)
• GPU offload for compute-heavy tasks
• Host network mode for zero-config device discovery
• Persistent volumes for upgrade-safe data/config
Technologies & frameworks to call out
• Docker & Docker Compose
• NVIDIA Container Toolkit (nvidia-docker)
• Home Assistant (Python, YAML-based config)
• Whisper (PyTorch/CUDA)
• Piper (Rust or Python + CUDA)
• OpenWakeWord (TensorFlow Lite + CUDA)
• Ollama API (HTTP REST)
• mDNS/SSDP, Bluetooth (Linux host)