Files

stephan 8cd91b6f22 updated skeleton with true data

2025-12-09 08:40:18 +01:00

4.4 KiB

Raw Permalink Blame History

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! 🚀

4.4 KiB Raw Permalink Blame History Unescape Escape