xtts-server/ONBOARDING.md

Onboarding Guide

Willkommen im Projekt! Dieses Dokument führt neue Entwickler vollständig ein – ohne Rückfragen, ohne offene Punkte.

Ziel: Du sollst in der Lage sein, das gesamte System zu verstehen, zu betreiben und weiterzuentwickeln.

---

1. Projektüberblick

Das XTTS2 TTS-System ist eine modulare, verteilte Plattform für hochwertige Text-to-Speech-Synthese mit Zero-Shot Voice Cloning. Der Aufbau orientiert sich an professionellen Backend-Architekturen mit Queueing, GPU-Workern und einer OpenAI-kompatiblen API.

Hauptkomponenten:

• Gateway (FastAPI): HTTP-API, Validierung, Routing, Port-Autodetection.
• Redis: Queue, Cache, interne Metadaten.
• Worker (XTTS2): führt TTS aus, nutzt GPU automatisch, arbeitet skalierbar.

Dieses System eignet sich für:

• Spielevertonung
• Automatisiertes Voice-Over
• Lokale AI-Pipelines
• Multimodale Agenten

---

2. Architektur

Client → Gateway → Redis Queue → Worker (XTTS2) → Gateway → Client

• Das Gateway nimmt Requests entgegen und legt Jobs in Redis ab.
• Worker verarbeiten Jobs parallel und liefern Audiodaten zurück.
• Die API ist OpenAI-kompatibel – Clients können ohne Anpassung migriert werden.

---

3. Voraussetzungen

Software

• Docker & Docker Compose
• Git
• Python 3.10 / 3.11 (für lokales Debugging)
• NVIDIA GPU + Container Toolkit (optional, aber empfohlen)

Hardware

• 8 GB RAM minimum
• GPU mit mindestens 4–6 GB VRAM für XTTS2

---

4. Repository klonen

git clone <repo-url>
cd tts-server

---

5. Projektstruktur verstehen

gateway/      → FastAPI-Gateway
worker/       → XTTS2-GPU-Worker
scripts/      → Hilfsskripte (Portfinder, Selftest)
voices/       → Voice Registry
Makefile      → Build-, Deploy- und Diagnosewerkzeuge
docker-compose.yml

Die wichtigsten Einstiegspunkte:

• gateway/main.py – Start des API-Gateways
• worker/main.py – Start des XTTS2-Workers
• scripts/find_port.py – Portscanner (8000–8100)

---

6. System starten

make build
make up

• Der Portscanner prüft Ports 8000–8100
• Der freie Port wird in gateway/port.txt gespeichert

Status prüfen:

make status

Stoppen:

make down

---

7. API testen

Healthcheck

curl http://localhost:<PORT>/health

TTS Request

curl -X POST http://localhost:<PORT>/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
        "model": "xtts-v2",
        "input": "Hello there!",
        "voice": "auto",
        "format": "wav"
      }' \
  --output output.wav

Stimme registrieren

curl -X POST http://localhost:<PORT>/v1/voices/register \
  -H "Content-Type: application/json" \
  -d '{
        "name": "narrator",
        "samples": ["https://example.com/voice.wav"]
      }'

---

8. Entwicklung

Lokales Setup ohne Docker

Virtualenv

python3 -m venv .venv
source .venv/bin/activate

Abhängigkeiten installieren

Gateway:

pip install -r gateway/requirements.gateway.txt

Worker:

pip install -r worker/requirements.worker.txt

Services starten

Redis (Lokal):

docker run -p 6379:6379 redis:7

Gateway:

python gateway/main.py

Worker:

python worker/main.py

---

9. Skalieren

Mehrere Worker starten:

make worker-scale N=3

Der Gateway verteilt automatisch die Jobs über Redis.

---

10. Selftest

make selftest

Prüft:

• Redis erreichbar
• Worker verarbeitet Jobs
• Audioausgabe funktioniert

---

11. Troubleshooting

Gateway startet nicht?

• Port belegt → gateway/port.txt prüfen
• Logs prüfen → gateway/logs/
• Redis erreichbar?

Worker reagiert nicht?

• GPU verfügbar? → nvidia-smi
• Torch kompatibel?
• XTTS2 Modell lädt?

Audio klingt falsch?

• Voice-Sample ungeeignet
• Format falsch gesetzt
• Sprache nicht angegeben

---

12. Best Practices

• Keine persönlichen Sprachsamples committen
• Docker Images regelmäßig erneuern
• Worker skalieren statt Gateway ändern
• API-Versionen strikt pflegen
• Code Style: PEP8

---

13. Weiterentwicklung

Empfohlene nächste Schritte:

• Monitoring (Prometheus)
• WebSocket TTS
• Multi-Model Routing
• GUI für Voice Management
• Auth Layer für öffentliche Deployments

---

14. Verantwortlichkeiten

• Projektleitung: Stephan W.
• Backend Architektur: Team evtl. weitere Rollen später definieren

---

15. Abschluss

Wenn du bis hier gelesen hast, bist du vollständig einsatzfähig. Viel Erfolg!“}