# Whisper API

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Eine lokale Whisper-API mit GPU-Beschleunigung und Web-Admin-Interface für die Transkription von Audio-Dateien. OpenAI-kompatible API mit Multi-Model-Support.

**🇩🇪 Deutsche Version** | [🇺🇸 English Version](README_EN.md)

## Features

- **OpenAI-kompatible API** - Drop-in Ersatz für OpenAI Whisper API
- **GPU-beschleunigt** - Nutzt NVIDIA GPUs (CUDA) für schnelle Transkription
- **CPU Fallback** - Automatischer Wechsel zu CPU wenn keine GPU verfügbar
- **Multi-Model Support** - Unterstützung für alle Whisper Modelle (tiny bis large-v3)
- **Model Management** - Modelle herunterladen, wechseln und löschen via Admin Panel
- **Default: large-v3** - Beste Qualität mit deiner RTX 3090
- **Web-Admin-Interface** - API-Key Management, Model Management und Statistiken unter `/admin`
- **API-Key Authentifizierung** - Sichere Zugriffskontrolle (Environment + Datenbank)
- **Cross-Platform** - Docker-basiert, läuft auf Windows und Linux
- **Automatische Cleanup** - Logs nach 30 Tagen automatisch gelöscht
- **Persistente Speicherung** - Modelle und Daten in Docker Volumes

## Architektur

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Client/App    │────▶│   FastAPI App    │────▶│  Whisper GPU    │
│  (Clawdbot etc) │     │   (Port 8000)    │     │  (large-v3)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  /admin Panel    │
                        │  - Key Mgmt      │
                        │  - Dashboard     │
                        │  - Logs          │
                        └──────────────────┘
```

## Schnellstart

### Voraussetzungen

- Docker Desktop (Windows) oder Docker + docker-compose (Linux)
- NVIDIA GPU mit CUDA-Unterstützung (RTX 3090)
- NVIDIA Container Toolkit installiert

### Installation

1. **Repository klonen:**
```bash
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api
```

2. **Umgebungsvariablen konfigurieren:**
```bash
cp .env.example .env
# Bearbeite .env nach deinen Wünschen
```

3. **Docker-Container starten:**
```bash
docker-compose up -d
```

4. **Erster Start:**
   - Das `large-v3` Modell (~3GB) wird automatisch heruntergeladen
   - Dies kann 5-10 Minuten dauern
   - Status überprüfen: `docker-compose logs -f`

### Verifizierung

```bash
# Health-Check
curl http://localhost:8000/health

# API-Info
curl http://localhost:8000/v1/models
```

## API-Dokumentation

### Authentifizierung

Alle API-Endpunkte (außer `/health` und `/admin`) benötigen einen API-Key:

```bash
Authorization: Bearer sk-dein-api-key-hier
```

### Endpunkte

#### POST /v1/audio/transcriptions

Transkribiert eine Audio-Datei.

**Request:**
```bash
curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-dein-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/pfad/zur/audio.mp3" \
  -F "model=large-v3" \
  -F "language=de" \
  -F "response_format=json"
```

**Response:**
```json
{
  "text": "Hallo Welt, das ist ein Test."
}
```

#### POST /v1/audio/transcriptions (mit Timestamps)

**Request:**
```bash
curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "file=@audio.mp3" \
  -F "timestamp_granularities[]=word" \
  -F "response_format=verbose_json"
```

**Response:**
```json
{
  "text": "Hallo Welt",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 1.5,
      "text": "Hallo Welt",
      "words": [
        {"word": "Hallo", "start": 0.0, "end": 0.5},
        {"word": "Welt", "start": 0.6, "end": 1.2}
      ]
    }
  ]
}
```

#### GET /v1/models

Liste verfügbarer Modelle.

#### GET /v1/available-models

Liste aller verfügbaren Whisper Modelle mit Download-Status.

**Response:**
```json
{
  "models": [
    {
      "name": "large-v3",
      "size": "2.88 GB",
      "description": "Best accuracy",
      "is_downloaded": true,
      "is_active": true
    }
  ]
}
```

#### GET /v1/model-status

Aktueller Download-Status des Modells.

**Response:**
```json
{
  "name": "large-v3",
  "loaded": true,
  "is_downloading": false,
  "download_percentage": 100,
  "status_message": "Model loaded successfully"
}
```

#### POST /v1/switch-model

Zu einem anderen Modell wechseln.

**Request:**
```bash
curl -X POST http://localhost:8000/v1/switch-model \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "model=base"
```

#### POST /v1/reload-model

Aktuelles Modell neu herunterladen.

#### DELETE /v1/delete-model/{model_name}

Ein heruntergeladenes Modell löschen.

#### GET /health

Health-Check mit GPU- und Model-Status.

**Response:**
```json
{
  "status": "healthy",
  "gpu": {
    "available": true,
    "name": "NVIDIA GeForce RTX 3090",
    "vram_used": "2.1 GB",
    "vram_total": "24.0 GB"
  },
  "model": "large-v3",
  "version": "1.0.0"
}
```

## Admin-Interface

Das Web-Interface ist erreichbar unter: `http://localhost:8000/admin`

### Login

- **Benutzername:** `admin` (konfigurierbar in `.env`)
- **Passwort:** `-whisper12510-` (konfigurierbar in `.env`)

### Features

- **Dashboard:** Übersicht über Nutzung, Performance-Statistiken, **Model Download Status**
- **API-Keys:** Verwalten (erstellen, deaktivieren, löschen)
- **Models:** 
  - Alle Whisper Modelle verwalten (tiny, base, small, medium, large-v1, large-v2, large-v3)
  - Modelle herunterladen, aktivieren und löschen
  - **CPU/GPU Mode Toggle**
  - Model neu herunterladen
- **Logs:** Detaillierte Transkriptions-Logs mit Filter

## Konfiguration

### .env.example

```bash
# Server
PORT=8000
HOST=0.0.0.0

# Whisper
WHISPER_MODEL=large-v3
WHISPER_DEVICE=cuda
WHISPER_COMPUTE_TYPE=float16

# Authentifizierung
# Mehrere API-Keys mit Komma trennen
API_KEYS=sk-dein-erster-key,sk-dein-zweiter-key
ADMIN_USER=admin
ADMIN_PASSWORD=-whisper12510-

# Daten-Retention (Tage)
LOG_RETENTION_DAYS=30

# Optional: Sentry für Error-Tracking
# SENTRY_DSN=https://...
```

### Docker-Compose Anpassungen

```yaml
services:
  whisper-api:
    # ...
    environment:
      - PORT=8000  # Änderbar
      - WHISPER_MODEL=large-v3
      - WHISPER_DEVICE=cuda  # oder 'cpu' für CPU-Modus
    volumes:
      - whisper_models:/app/models    # Persistiert Modelle (Named Volume)
      - whisper_data:/app/data        # SQLite Datenbank
      - whisper_uploads:/app/uploads  # Temporäre Uploads
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  whisper_models:
  whisper_data:
  whisper_uploads:
```

## Migration zu Linux

Die Docker-Konfiguration ist plattformunabhängig. Für Linux:

1. **NVIDIA Docker installieren:**
```bash
# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker
```

2. **Projekt klonen und starten:**
```bash
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api
docker-compose up -d
```

3. **GPU-Passthrough verifizieren:**
```bash
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
```

## Integration mit Clawdbot

Für die Integration in einen Clawdbot Skill:

```python
import requests

API_URL = "http://localhost:8000/v1/audio/transcriptions"
API_KEY = "sk-dein-api-key"

def transcribe_audio(audio_path):
    with open(audio_path, "rb") as f:
        response = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f},
            data={"language": "de"}
        )
    return response.json()["text"]
```

## Verfügbare Modelle

| Modell | Größe | Beschreibung | Geschwindigkeit | Genauigkeit |
|--------|-------|--------------|-----------------|-------------|
| **tiny** | 39 MB | Schnellste, niedrigste Qualität | Sehr schnell | Niedrig |
| **base** | 74 MB | Gut für Tests | Schnell | Mittel |
| **small** | 244 MB | Balance Speed/Qualität | Mittel | Gut |
| **medium** | 769 MB | Gute Genauigkeit | Langsam | Sehr gut |
| **large-v2** | 2.87 GB | Höhere Genauigkeit | Sehr langsam | Exzellent |
| **large-v3** | 2.88 GB | Beste Genauigkeit (Default) | Sehr langsam | Exzellent |

**Empfehlungen:**
- **Entwicklung/Tests:** `base` oder `small`
- **Produktion:** `large-v3` (mit RTX 3090)
- **CPU-Modus:** `small` oder `medium`

## Performance

Mit RTX 3090 und large-v3:
- **1 Minute Audio:** ~3-5 Sekunden Verarbeitungszeit
- **VRAM-Nutzung:** ~10 GB
- **Batch-Verarbeitung:** Möglich für parallele Requests

Mit CPU und small:
- **1 Minute Audio:** ~30-60 Sekunden Verarbeitungszeit
- **RAM-Nutzung:** ~1 GB

## Troubleshooting

### GPU nicht erkannt / Automatischer CPU Fallback

Falls keine GPU erkannt wird, schaltet die API automatisch auf CPU-Modus um:

```bash
# NVIDIA Container Toolkit prüfen
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

# Logs prüfen - sollte "GPU not available, falling back to CPU mode" zeigen
docker-compose logs whisper-api
```

**Manueller Wechsel:** Über Admin Panel (`/admin/models`) oder API:
```bash
curl -X POST http://localhost:8000/v1/switch-device \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "device=cpu"
```

### Modell-Download Status anzeigen

- **Dashboard:** Zeigt Download-Fortschritt in Echtzeit
- **API:** `GET /v1/model-status` für aktuellen Status
- **Logs:** `docker-compose logs -f` zeigt Download-Progress

### Modell-Download langsam

```bash
# Im Admin Panel unter Models ein kleineres Modell wählen (z.B. base, small)
# Oder via API:
curl -X POST http://localhost:8000/v1/switch-model \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "model=base"
```

### Port belegt

```bash
# Port in .env ändern
PORT=8001
```

## Backup

Wichtige Daten (Docker Named Volumes):
- `whisper_data` - SQLite Datenbank (API-Keys, Logs)
- `whisper_models` - Heruntergeladene Whisper-Modelle
- `./.env` - Konfiguration

```bash
# Backup erstellen
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "tar czf /backup/whisper-api-backup.tar.gz -C / data models"

# Oder komplettes Backup inkl. .env
cp .env .env.backup
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine tar czf /backup/whisper-api-full-backup.tar.gz -C / data models
```

### Backup wiederherstellen

```bash
# Backup extrahieren
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "cd / && tar xzf /backup/whisper-api-backup.tar.gz"
```

## Lizenz

MIT License - Siehe LICENSE Datei

## Support

Bei Problemen:
1. Logs prüfen: `docker-compose logs -f`
2. Health-Check: `curl http://localhost:8000/health`
3. Issue auf Gitea erstellen

---

**Erstellt für:** b0rborad @ ragtag.rocks  
**Hardware:** Dual RTX 3090 Setup  
**Zweck:** Clawdbot Skill Integration