Wake Word Service (Codewort-Training)

Lokales Wake-Word-Training und -Erkennung auf Basis von openWakeWord. Ermöglicht das Trainieren eines eigenen "hey xynap"-Codeworts mit TTS-generierten und manuell hochgeladenen Aufnahmen. Die Erkennung erfolgt per WebSocket direkt im Browser — ohne Google oder externe Dienste.

Architektur

Browser (AudioWorklet 48kHz → 16kHz PCM)
  └─► WebSocket wss://platform.xynap.tech/wakeword/ws
        └─► openWakeWord ONNX Inference
              └─► {event: "wake"} → Frontend-Callback

Wenn kein trainiertes Modell aktiv ist, fällt das System auf die Web Speech API (Chrome/Edge, sendet an Google) zurück.

Dienst-Infos

Container	wakeword-service
Interner Port	5600
Netzwerk	ai-network
API-Prefix	/api/v1/wakeword/
WebSocket	wss://platform.xynap.tech/wakeword/ws
Daten-Volume	/data/(Modelle, Samples)
Aktives Modell	/data/active_model.txt

Training Pipeline

Das Training läuft vollautomatisch in 7 Phasen:

Phase	Name	Beschreibung
1	samples_tts	TTS-Samples generieren (alle Stimmen × 5 Geschwindigkeiten)
2	samples_upload	Hochgeladene eigene Aufnahmen prüfen
3	augment	Noise-Augmentierung (–25 dB White Noise)
4	features	openWakeWord Feature-Extraktion (Mel-Spektrogramm, 96-dim Embeddings)
5	train	PyTorch DNN trainieren (FC-Layer + ReLU + LayerNorm + Sigmoid, Adam lr=0.001)
6	validate	False-Positive-Rate messen
7	save	ONNX-Modell speichern + Index aktualisieren

API-Endpoints

Alle Endpunkte sind über/api/v1/wakeword/(Platform-API-Proxy) erreichbar.

Methode	Pfad	Beschreibung	Permission
GET	/status	Aktives Modell + WebSocket-URL	—
WS	/ws	Binary PCM Stream → Wake-Event	—
GET	/models	Liste trainierter Modelle	wakeword.read
POST	/train	Training starten	wakeword.manage
GET	/training/{job_id}	Trainingsstatus + Phasen-Progress	wakeword.read
POST	/samples/upload	WAV-Dateien hochladen	wakeword.manage
GET	/samples	Alle Samples (gruppiert nach Wort)	wakeword.read
DELETE	/samples/{word}	Samples eines Wortes löschen	wakeword.manage
POST	/models/{name}/activate	Modell aktivieren	wakeword.manage
DELETE	/models/{name}	Modell löschen	wakeword.manage

WebSocket-Protokoll

Client → Server: Binary (Int16 PCM, 16kHz Mono, 256 samples = 16ms)
Server → Client: JSON {"event": "wake", "score": 0.87, "word": "hey xynap"}
                 JSON {"event": "ping"}

Admin-UI

Unter Einstellungen → Codewort-Training können Admins:

1. Neues Modell trainieren— Wort eingeben, TTS-Samples aktivieren, Training starten
2. Eigene Aufnahmen hochladen— WAV-Dateien (werden automatisch auf 16kHz mono resampled)
3. Browser-Recording— Hold-to-Record (max. 3 Sekunden) direkt im Browser
4. Modell aktivieren— Trainiertes Modell für alle User scharf schalten
5. Trainingsfortschritt— Live-Anzeige der 7 Phasen per Polling

Browser-Integration

Das ComposableuseWakeWord.tsimplementiert die clientseitige Erkennung:

1. GET /api/v1/wakeword/status— prüft ob Modell aktiv, holt WebSocket-URL
2. AudioContext+AudioWorklet(pcm-processor.js) — erfasst Mikrofon-Audio
3. Dezimierung 48 kHz → 16 kHz + Float32 → Int16 im Worklet-Thread
4. Binary PCM-Frames (256 Samples = 16 ms) per WebSocket an Service
5. Bei{event:"wake"}→ Intent-Callback auslösen

Reconnect-Logik: max. 5 Versuche mit exponentiellem Backoff.

Abhängigkeiten

Service	Zweck
TTS-Gateway (Port 5200)	Sample-Generierung beim Training
STT-Gateway (Port 5400)	Validierung (optional)
openWakeWord 0.6.0	ONNX-Inferenz + Preprocessing
PyTorch ≥ 2.0	DNN-Training
onnxruntime 1.20.1	ONNX-Export + Inferenz

Konfiguration

Env-Variable	Datei	Wert
WAKEWORD_SERVICE_URL	/etc/xynap/platform/backend.env	http://wakeword-service:5600
DETECT_THRESHOLD	Microserviceserver.py	0.5

Test-Tool

# Wake-Word-Erkennung über alle TTS-Stimmen testen
xynap-test-wakeword

# Anderes Codewort testen
xynap-test-wakeword --word "ok xynap"

# Nur bestimmte Stimmen
xynap-test-wakeword --voices qwen3|piper|all --out /tmp/

Dateipfade

Typ	Pfad
Microservice	/usr/local/xynap/wakeword-service/server.py
Dockerfile	/usr/local/xynap/wakeword-service/Dockerfile
Platform-API Router	/usr/local/xynap/platform/backend/app/core/wakeword/router.py
Admin-UI	/usr/local/xynap/platform/frontend/src/shell/admin/WakeWordView.vue
Composable	/usr/local/xynap/platform/frontend/src/shell/composables/useWakeWord.ts
AudioWorklet	/usr/local/xynap/platform/frontend/src/shell/composables/pcm-processor.js
Service-Register	/home/admin/docs/services/wakeword.md