From 3461f4520779d07b05fd5355507485ab2a58e2fb Mon Sep 17 00:00:00 2001
From: duffyduck <info@hacker-net.de>
Date: Fri, 10 Apr 2026 01:49:08 +0200
Subject: [PATCH] docs: update README with XTTS v2 setup details, voice cloning
 guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Architecture diagram for XTTS flow (Gaming-PC ↔ RVS ↔ ARIA-VM)
- Port 8020 (not 8000), token must match, model caching
- Voice cloning step-by-step guide
- TTS engine switching (Piper/XTTS) with fallback
- Known limitation: RVS zombie connections

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 40 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 63f409e..61de3a1 100644
--- a/README.md
+++ b/README.md
@@ -530,38 +530,68 @@ cp ARIA-v0.0.3.0.apk ~/ARIA-AGENT/rvs/updates/
 ## XTTS v2 — GPU TTS Server (optional)
 
 Laeuft auf einem separaten Rechner mit NVIDIA GPU (z.B. Gaming-PC mit RTX 3060).
-Verbindet sich ueber RVS mit der ARIA-Infrastruktur — kein VPN noetig.
+Verbindet sich ueber RVS mit der ARIA-Infrastruktur — kein VPN noetig, funktioniert
+ueber verschiedene Netze hinweg.
+
+### Architektur
+
+```
+Gaming-PC (Windows, RTX 3060, Docker Desktop + WSL2)
+├── aria-xtts        XTTS v2 GPU Server (Port 8020 intern)
+└── aria-xtts-bridge RVS-Relay (empfaengt Requests, sendet Audio)
+    └── Beide teilen ./voices/ Volume fuer Voice Cloning
+
+         ↕ RVS (Rechenzentrum, WebSocket Relay)
+
+ARIA-VM
+└── aria-bridge: tts_engine="xtts" → xtts_request via RVS → wartet auf xtts_response
+```
 
 ### Voraussetzungen
 
 - Docker Desktop mit WSL2 (Windows) oder Docker mit NVIDIA Runtime (Linux)
 - NVIDIA Container Toolkit
 - GPU mit mindestens 4GB VRAM (6GB+ empfohlen)
+- **Gleicher RVS_TOKEN wie auf der ARIA-VM!**
 
 ### Setup
 
 ```bash
 cd xtts
 cp .env.example .env
-# .env mit RVS-Verbindungsdaten fuellen (gleiche wie auf der ARIA-VM)
+# .env mit RVS-Verbindungsdaten fuellen (gleicher Token wie ARIA-VM!)
 docker compose up -d
-# Erster Start laedt ~2GB Model herunter
+# Erster Start laedt ~2GB Model herunter (danach gecacht)
 ```
 
+**Wichtig:** Der XTTS-Server laeuft intern auf Port **8020** (nicht 8000).
+Das Model wird im Volume `xtts-models` gecacht und muss nur einmal geladen werden.
+
 ### Features
 
 - **Natuerliche Stimmen**: Deutlich bessere Qualitaet als Piper
-- **Voice Cloning**: Eigene Stimme mit 6-10s Audio-Sample
+- **Voice Cloning**: Eigene Stimme mit 6-10s Audio-Sample (~2s Latenz auf RTX 3060)
 - **16 Sprachen**: Deutsch, Englisch, Franzoesisch, etc.
-- **RVS-Integration**: Bridge waehlt automatisch XTTS wenn verfuegbar
+- **Fallback**: Wenn XTTS nicht erreichbar, nutzt die Bridge automatisch Piper
+
+### TTS-Engine umschalten
+
+In der Diagnostic unter Einstellungen → Sprachausgabe:
+- **TTS aktiv**: Global An/Aus
+- **TTS Engine**: Piper (lokal, CPU, schnell) oder XTTS v2 (remote, GPU, natuerlich)
+- **Piper**: Standard-Stimme, Highlight-Stimme, Speed pro Stimme
+- **XTTS**: Stimmen-Auswahl, Voice Cloning
 
 ### Stimme klonen
 
-In der Diagnostic unter Einstellungen → Sprachausgabe → XTTS:
 1. TTS Engine auf "XTTS v2" stellen
-2. "Stimme klonen" → Audio-Dateien hochladen (WAV/MP3, min. 6-10s)
+2. "Stimme klonen" → Audio-Dateien hochladen (WAV/MP3, 1-10 Dateien, min. 6-10s gesamt)
 3. Name vergeben → "Stimme erstellen"
-4. Neue Stimme in der Auswahl verfuegbar
+4. "Laden" klicken → neue Stimme in der Auswahl
+5. Stimme auswaehlen → Config wird automatisch gespeichert
+
+> **Tipp:** Fuer beste Ergebnisse: saubere Aufnahme, eine Stimme, kein Hintergrund,
+> 10-30 Sekunden Gesamtlaenge. Mehrere kurze Dateien werden zusammengefuegt.
 
 ---
 
@@ -633,6 +663,8 @@ docker exec aria-core ssh aria-wohnung hostname
 - **Wake Word nur auf VM**: Die Bridge hoert auf "ARIA" ueber das lokale Mikrofon der VM.
   In der App gibt es Energy-basierte Erkennung (Phase 1). On-device "ARIA"-Keyword (Porcupine) ist Phase 2.
 - **Audio-Format**: App nimmt AAC/MP4 auf, Bridge konvertiert via FFmpeg zu 16kHz PCM.
+- **RVS Zombie-Connections**: WebSocket-Verbindungen sterben gelegentlich ohne Fehlermeldung.
+  Bridge hat Ping-Check (5s), Diagnostic nutzt frische Verbindungen pro Request.
 - **Bildanalyse eingeschraenkt**: Bilder werden in `/shared/uploads/` gespeichert. ARIA kann
   sie per Bash/Read-Tool oeffnen, aber Claude Vision (direkte Bildanalyse) ist ueber den
   Proxy-Pfad (`claude --print`) noch nicht moeglich. ARIA sieht den Dateipfad, nicht das Bild.