xtts-server/DEV_SETUP.md

Developer Setup Guide

Dieses Dokument befähigt jeden Entwickler dazu, das komplette XTTS2-TTS-System lokal aufzusetzen, zu verstehen, zu debuggen und zu erweitern – ohne Rückfragen.

---

1. Ziel des Dokuments

• Lokale Entwicklungsumgebung vollständig einrichten
• Services starten & stoppen
• Worker skalieren
• API testen
• Debugging-Strategien
• Best Practices für Code, Deployment & GPU-Nutzung

---

2. Voraussetzungen

Software

• Docker ≥ 24.x
• Docker Compose ≥ v2.x
• Git
• Python 3.10–3.11
• Optional: Editor wie VS Code mit Python- & Docker-Extensions

Hardware

• Linux (empfohlen), macOS oder Windows WSL2
• Für GPU-Betrieb: NVIDIA GPU + Container Toolkit

GPU prüfen:

nvidia-smi

NVIDIA Docker prüfen:

docker run --rm --gpus all nvidia/cuda:12.1.0-base nvidia-smi

---

3. Repository klonen

git clone <repo-url>
cd tts-server

---

4. Projektstruktur

tts-server/
├── gateway/                → FastAPI-Gateway
│   ├── main.py
│   ├── api/
│   ├── core/
│   ├── voices/
│   ├── logs/
│   └── Dockerfile
│
├── worker/                 → XTTS2 Worker
│   ├── main.py
│   ├── engine/
│   ├── core/
│   └── Dockerfile
│
├── scripts/
│   └── find_port.py        → Portscanner (8000–8100)
│
├── docker-compose.yml      → Multi-Service Orchestration
├── Makefile                → PRO Workflow
├── README.md
└── ONBOARDING.md

---

5. Docker-basiertes Development (empfohlen)

5.1 Images bauen

make build

5.2 Server starten

make up

Der Portscanner wählt automatisch den ersten freien Port (8000–8100) und legt ihn ab in:

gateway/port.txt
gateway/logs/gateway.log

5.3 Logs ansehen

make logs

5.4 Services stoppen

make down

5.5 Status anzeigen

make status

---

6. Ohne Docker entwickeln (lokales Debugging)

6.1 Virtuelle Umgebung

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

6.2 Abhängigkeiten installieren

Gateway:

pip install -r gateway/requirements.gateway.txt

Worker:

pip install -r worker/requirements.worker.txt

Redis lokal starten:

docker run -p 6379:6379 redis:7

Gateway starten:

python gateway/main.py

Worker starten:

python worker/main.py

---

7. TTS API testen

7.1 Healthcheck

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

7.2 TTS Anfrage

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

7.3 Stimme registrieren

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

---

8. Worker skalieren

Höhere Last? Mehrere Worker starten:

make worker-scale N=4

Redis verteilt Jobs automatisch FIFO.

---

9. Selftest

make selftest

Testet:

• Redis erreichbar
• Gateway online
• Worker zieht Jobs
• Synthese funktioniert

---

10. Debugging

Gateway startet nicht

• Prüfen: gateway/logs/
• Port frei? gateway/port.txt
• Redis erreichbar?

Worker lädt nicht

• XTTS2 Modell verfügbar?
• GPU verfügbar? nvidia-smi
• Torch CUDA Version kompatibel?

Audio-Probleme

• Voice Sample ungeeignet
• Sprache nicht angegeben
• Format falsch

---

11. Code Guidelines

• PEP8 Stil
• Logging strukturiert (JSON empfohlen)
• Kein Hardcoding von Pfaden
• Hohe Modularität
• Unit Tests für Kernkomponenten
• Feature Branches: feature/<name>
• Commits: Conventional Commits

---

12. Best Practices

• Worker lieber horizontal skalieren statt optimieren
• Keine sensiblen Voice Samples committen
• Docker Images regelmäßig aktualisieren
• Für Public Deployments: Auth Layer aktivieren

---

13. Nächste Schritte für Entwickler

• Monitoring & Dashboards
• WebSocket Realtime TTS
• Mehrsprachige Voice Registry
• Model Hot-Swapping (XTTS2, F5, Kokoro)
• CI/CD Pipeline hinzufügen

---

14. Fertig!

Wenn du dieses Dokument verstanden hast, kannst du das Projekt vollständig entwickeln, erweitern und deployen.

Viel Erfolg! 🚀