xtts-server/README.md

# XTTS2 OpenAI-Compatible TTS Server

High-Performance Text-to-Speech Platform with FastAPI, Redis Queueing, GPU Workers & OpenAI Speech API Compatibility.

---

## 🔥 Übersicht

Dieses Projekt stellt eine vollständig modulare, skalierbare und produktionsreife lokale Text-to-Speech-Plattform bereit. Die API ist vollständig kompatibel zur **OpenAI Speech API**, unterstützt **XTTS2 Zero-Shot Voice Cloning**, mehrere Audioformate und verteilte GPU-Worker.

Zielsetzung:

* Hochqualitative TTS-Synthese für Spiele, Voice-Overs und AI-Produktion
* Zero-Shot Voice Cloning mit XTTS2
* OpenAI-kompatible Endpoints als Drop-in Replacement
* Skalierbare Worker-Architektur für hohe Lasten

---

## 🧱 Architektur

```
┌────────────────────┐       ┌───────────────────────────────┐
│ FastAPI Gateway    │◀──────┤ Redis Queue + Cache            │
│ - OpenAI API       │       └───────────────────────────────┘
│ - Rate Limits      │
│ - Port Auto-Select │       ┌───────────────────────────────┐
│ - Voice Registry   │──────▶│ Worker (XTTS2)                 │
└────────────────────┘       │ - GPU/CPU Auto Detect          │
                             │ - Zero-Shot Voice Cloning      │
                             └───────────────────────────────┘
```

---

## 🚀 Features

### Core Features

* OpenAI-kompatible Speech API
* Zero-Shot Voice Cloning mit XTTS2
* Unterstützung für `wav`, `mp3`, `ogg`
* Dynamische Portwahl (8000–8100) mit Fallback
* Registry für permanente Stimmen
* Queue-basierte Worker-Architektur (Redis)
* GPU Auto-Detection für Worker

### Deployment Features

* Multi-Stage Docker Images (Gateway & Worker)
* Makefile PRO für Build, Deploy, Scaling & Testing
* Logs + Portfile + Healthchecks
* Lazy Load der XTTS2-Modelle

---

## 📦 Installation

### Voraussetzungen

* Docker & Docker Compose
* NVIDIA Container Runtime (für GPU-Worker)
* Linux oder macOS (Windows WSL2 möglich)

### Start in 3 Schritten

```bash
make build
make up
make status
```

Die dynamische Portwahl speichert den genutzten Port in:

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

---

## 📡 OpenAI-kompatible Endpunkte

### POST /v1/audio/speech

Request Beispiel:

```json
{
  "model": "xtts-v2",
  "input": "Hello, hero",
  "voice": "auto",
  "format": "wav"
}
```

Antwort:

* binares Audio
* Content-Type abhängig vom Format

### POST /v1/voices/register

* Registriert permanente Stimmen
* Unterstützt Samples per URL oder Base64

### GET /health

* Healthcheck für Monitoring & CI

---

## 🧪 Selftest

```bash
make selftest
```

Prüft:

* Redis erreichbar
* Gateway erreichbar
* Worker zieht Jobs
* Mini-Synthese erfolgreich

---

## 📁 Projektstruktur

```
project/
├── gateway/
│   ├── main.py
│   ├── api/
│   ├── core/
│   ├── voices/
│   ├── logs/
│   └── Dockerfile
│
├── worker/
│   ├── main.py
│   ├── engine/
│   ├── core/
│   └── Dockerfile
│
├── scripts/
│   └── find_port.py
│
├── Makefile
├── docker-compose.yml
└── README.md
```

---

## 🔐 Sicherheit & Best Practices

* Optional: API Keys für öffentliche Deployments
* Rate Limits im Gateway aktivierbar
* HTTPS über Reverse Proxy
* Keine sensiblen Voice-Daten einchecken
* Worker nur intern erreichbar halten

---

## 🛠 Roadmap

* Prometheus & Grafana Monitoring
* Business-Level Logging (JSON Logs)
* Support für weitere Modelle (F5, Kokoro, Piper)
* WebSocket Realtime TTS Output

---

## 🧑‍💻 Maintainer

**Stephan W.** – Architektur & Betrieb

```}
```