# 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:

```bash
nvidia-smi
```

NVIDIA Docker prüfen:

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

---

# 3. Repository klonen

```bash
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

```bash
make build
```

## 5.2 Server starten

```bash
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

```bash
make logs
```

## 5.4 Services stoppen

```bash
make down
```

## 5.5 Status anzeigen

```bash
make status
```

---

# 6. Ohne Docker entwickeln (lokales Debugging)

## 6.1 Virtuelle Umgebung

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

## 6.2 Abhängigkeiten installieren

Gateway:

```bash
pip install -r gateway/requirements.gateway.txt
```

Worker:

```bash
pip install -r worker/requirements.worker.txt
```

Redis lokal starten:

```bash
docker run -p 6379:6379 redis:7
```

Gateway starten:

```bash
python gateway/main.py
```

Worker starten:

```bash
python worker/main.py
```

---

# 7. TTS API testen

## 7.1 Healthcheck

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

## 7.2 TTS Anfrage

```bash
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

```bash
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:

```bash
make worker-scale N=4
```

Redis verteilt Jobs automatisch FIFO.

---

# 9. Selftest

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