---
created: 2026-08-30
modified: 2026-08-30
type: note
tags:
  - voice
  - system
  - ai
aliases:
  - Jervis
  - Voice Assistant
---

# Home Voice Assistant System (Jervis)

> **Source of truth:** Gitea repo `sam/voice-assistant` → `https://gitea.lab.audasmedia.com.au/sam/voice-assistant`
> Docs: `docs/overview.md`, `docs/agent-api.md`, `docs/clients.md` (in that repo).

## TL;DR
Local, private voice assistant. "Hey Jervis" → natural language → one LLM brain (voice-agent on `.13:8501`)
decides intent → calls tools (time/weather/shopping/HA control/reminders/character voices) → speaks via piper → Snapcast.

**Command it from anywhere:** `POST http://192.168.20.13:8501/voice {"text":"add milk to the shopping list"}` (reply is spoken).

## Components (host:port)
| Component | Host | Port | Role |
|---|---|---|---|
| ESP32-S3 (wake word) | — | — | mic, LED |
| voice_bridge / voice_whisper | .13 | docker/:5000 | STT |
| **voice-agent (LLM brain)** | .13 | **:8501** | tool-calling |
| OmniRoute | .13 | :20129 | LLM gateway |
| piper_tts | .13 | :10200 | TTS |
| Snapcast | .13 | :1780 | audio |
| Home Assistant | .30 | :8123 | control |
| KitchenOwl | .35 | owl.lab | shopping |
| mosquitto | .13/.30 | :1883 | MQTT |

See the repo `docs/overview.md` for the full diagram + `docs/agent-api.md` for the API contract + `docs/clients.md` for type/web/Android.

## Status (2026-08-30)
- Voice-over-Snapcast restored (piper docker + HA→.13 SSH auth fixed); full-length speech (pure-python resampler).
- Agent persistent as NixOS systemd service; tools verified: time, weather, shopping (KitchenOwl), HA control, reminders, feed-fish, character voices (Trump etc.).
- **Music working**: `play_music` → Mopidy → Spotify → Snapcast (gst-plugin-spotify + device-auth credentials.json; Radiohead/Pink Floyd verified). Fast LLM route `voice-fast` (OpenRouter→opencode-go→deepseek flash) cuts response latency to ~2-3s.
- Next: pause/stop music tools, Apprise messaging (sam/jo/harry/finn), calendar (N8N), extended TTS voices. See [[secrets_fixes]] for credential issues.

See also: [[Docker Containers]], [[Home Network Map Overview]].