# 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!“}