271 lines
4.5 KiB
Markdown
271 lines
4.5 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
make build
|
||
make up
|
||
```
|
||
|
||
* Der Portscanner prüft Ports 8000–8100
|
||
* Der freie Port wird in `gateway/port.txt` gespeichert
|
||
|
||
Status prüfen:
|
||
|
||
```bash
|
||
make status
|
||
```
|
||
|
||
Stoppen:
|
||
|
||
```bash
|
||
make down
|
||
```
|
||
|
||
---
|
||
|
||
# 7. API testen
|
||
|
||
## Healthcheck
|
||
|
||
```bash
|
||
curl http://localhost:<PORT>/health
|
||
```
|
||
|
||
## TTS Request
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
### Abhängigkeiten installieren
|
||
|
||
Gateway:
|
||
|
||
```bash
|
||
pip install -r gateway/requirements.gateway.txt
|
||
```
|
||
|
||
Worker:
|
||
|
||
```bash
|
||
pip install -r worker/requirements.worker.txt
|
||
```
|
||
|
||
### Services starten
|
||
|
||
Redis (Lokal):
|
||
|
||
```bash
|
||
docker run -p 6379:6379 redis:7
|
||
```
|
||
|
||
Gateway:
|
||
|
||
```bash
|
||
python gateway/main.py
|
||
```
|
||
|
||
Worker:
|
||
|
||
```bash
|
||
python worker/main.py
|
||
```
|
||
|
||
---
|
||
|
||
# 9. Skalieren
|
||
|
||
Mehrere Worker starten:
|
||
|
||
```bash
|
||
make worker-scale N=3
|
||
```
|
||
|
||
Der Gateway verteilt automatisch die Jobs über Redis.
|
||
|
||
---
|
||
|
||
# 10. Selftest
|
||
|
||
```bash
|
||
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!“}
|