┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Browser     │────▶│  nginx (SSL)     │────▶│  FastAPI         │
│  (microfoon) │     │  ha.el-kadi.nl   │     │  :8765           │
└──────────────┘     └──────────────────┘     │                   │
                                              │  ┌─────────────┐ │
┌──────────────┐                              │  │ Whisper      │ │
│  Claude /    │──▶ MCP stdio ───────────────▶│  │ (spraak→tekst)│ │
│  DeepSeek    │                              │  └─────────────┘ │
└──────────────┘                              │  ┌─────────────┐ │
                                              │  │ HA REST API │ │
                                              │  │ 192.168...  │ │
                                              │  └─────────────┘ │
                                              └──────────────────┘

Twee interfaces:

Web UI op www.ha.el-kadi.nl — push-to-talk knop in de browser
MCP Server — via Claude Desktop / DeepSeek TUI (stdio)

Beide gebruiken dezelfde Whisper-transcriptie en Home Assistant client.

Vereisten

Python 3.10+
Home Assistant met een long-lived access token
nginx (voor SSL en domein)
Een domein (hier: ha.el-kadi.nl) met DNS die naar jouw server wijst
Optioneel: CUDA-compatibele GPU voor snellere lokale Whisper

Installatie

1. Clone en installeer dependencies

cd /opt  # of een andere gewenste locatie
git clone <jouw-repo> ha-voice-control
cd ha-voice-control
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configuratie

Kopieer het voorbeeld en vul je gegevens in:

cp .env.example .env

Bewerk .env:

# Home Assistant
HA_URL=http://192.168.1.235:8123
HA_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Whisper: "local" (faster-whisper, offline) of "openai" (API)
WHISPER_MODE=local
WHISPER_MODEL=base

# Web server
WEB_HOST=127.0.0.1
WEB_PORT=8765

De Home Assistant token maak je aan via: Home Assistant → Profiel (linksonder) → Beveiliging → Lange-levensduur toegangstokens

3. Eerste keer Whisper model downloaden

Bij de eerste start met WHISPER_MODE=local downloadt faster-whisper automatisch het model. Beschikbare modellen (oplopend in grootte/nauwkeurigheid):

tiny / tiny.en — ~75 MB, snelste
base / base.en — ~145 MB, aanbevolen voor NL
small / small.en — ~488 MB
medium / medium.en — ~1.5 GB
large-v3 — ~3 GB, meest accuraat

.en varianten zijn alleen voor Engels. Voor Nederlands gebruik je de meertalige versies.

4. Start de web server

source venv/bin/activate
python -m src.web_server
# Of direct met uvicorn:
uvicorn src.web_server:app --host 127.0.0.1 --port 8765

Test of het werkt: curl http://127.0.0.1:8765/api/health

5. nginx + SSL configureren

# Kopieer de nginx config
sudo cp nginx/ha.el-kadi.nl.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/ha.el-kadi.nl.conf /etc/nginx/sites-enabled/

# SSL certificaten met Let's Encrypt (certbot)
sudo certbot --nginx -d ha.el-kadi.nl -d www.ha.el-kadi.nl

# Pas de ssl_certificate paden aan in de config indien nodig
# Herlaad nginx
sudo nginx -t && sudo systemctl reload nginx

6. Systemd service (zodat de server automatisch start)

Maak /etc/systemd/system/ha-voice-control.service:

[Unit]
Description=HA Voice Control Web Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/ha-voice-control
EnvironmentFile=/opt/ha-voice-control/.env
ExecStart=/opt/ha-voice-control/venv/bin/python -m src.web_server
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ha-voice-control

MCP Server gebruiken

Claude Desktop

Voeg toe aan je claude_desktop_config.json:

{
  "mcpServers": {
    "ha-voice": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/opt/ha-voice-control",
      "env": {
        "HA_TOKEN": "jouw-token-hier",
        "WHISPER_MODE": "local"
      }
    }
  }
}

DeepSeek TUI

In je config.toml:

[[mcp_servers]]
name = "ha-voice"
command = "python"
args = ["-m", "src.mcp_server"]
cwd = "/opt/ha-voice-control"
env = { HA_TOKEN = "jouw-token-hier", WHISPER_MODE = "local" }

Beschikbare MCP tools

Tool	Beschrijving
`speak_command`	Base64 audio → transcribeer → voer uit via HA
`transcribe_audio`	Alleen transcriberen, geen actie
`send_text_command`	Stuur tekst naar HA conversation agent
`list_lights`	Toon alle lampen en hun status
`control_light`	Zet een lamp aan/uit/toggle met helderheid
`list_all_entities`	Toon alle HA entities
`get_entity_state`	State van één entity opvragen
`call_ha_service`	Roep een willekeurige HA service aan

API endpoints (web server)

Methode	Pad	Beschrijving
`GET`	`/api/health`	Health check
`POST`	`/api/transcribe`	Upload audio (multipart), krijg transcriptie + HA resultaat
`POST`	`/api/command`	`{"text": "doe de lampen uit"}` → HA
`GET`	`/api/lights`	Alle lampen met status
`POST`	`/api/light/control`	`{"entity_id": "...", "action": "turn_on"}`
`GET`	`/api/entities?domain=light`	Entities (optioneel gefilterd)
`GET`	`/api/entity/{entity_id}`	Volledige state van één entity
`POST`	`/api/service`	`{"domain": "light", "service": "turn_on", "entity_id": "..."}`

Gebruik

Open https://www.ha.el-kadi.nl in je browser (Chrome/Edge/Safari op desktop of mobiel)
Geef de browser toestemming voor de microfoon
Houd de microfoonknop ingedrukt en spreek je commando:
- "Doe de lampen in de woonkamer aan"
- "Zet alle lichten uit"
- "Dim de slaapkamer naar 50 procent"
Laat de knop los — je commando wordt getranscribeerd en uitgevoerd
Je ziet het resultaat verschijnen

De lampen onderaan de pagina kun je ook direct met de toggle-schakelaars bedienen.

Troubleshooting

"Microfoon niet beschikbaar"

De site moet via HTTPS geladen worden (browsers vereisen dit voor getUserMedia)
Controleer of nginx SSL correct is ingesteld
Lokaal testen op localhost werkt ook zonder HTTPS

Transcriptie werkt niet / foutmelding

Check of faster-whisper correct is geïnstalleerd: pip list | grep faster
Controleer de logs: journalctl -u ha-voice-control -f
Bij Open AI-modus: check of OPENAI_API_KEY is ingesteld
Het model wordt de eerste keer gedownload; dit kan even duren

"Fout bij uitvoeren" / Home Assistant niet bereikbaar

Controleer of HA_URL klopt en bereikbaar is vanaf de server
Verifieer de token: curl -H "Authorization: Bearer $HA_TOKEN" $HA_URL/api/
Check of de conversation agent in HA is ingeschakeld (Standaard is conversation integratie actief)

Audio wordt niet goed herkend

Gebruik een groter Whisper-model (small of medium) voor betere NL herkenning
Spreek duidelijk en dicht bij de microfoon
Verminder achtergrondgeluid