video-service/README.md

# Video-Service fuer Kurs-Booking Plugin

Python-basierter Microservice fuer Video-Hosting und HLS-Streaming.

## Technologie-Stack

| Komponente | Version | Beschreibung |
|------------|---------|--------------|
| Python | 3.13 | Support bis Oktober 2029 |
| FastAPI | 0.115 | REST API Framework |
| Redis | 7.4 | Task Queue (BSD-Lizenz) |
| Celery | 5.4 | Async Task Processing |
| FFmpeg | 6.1 | Video-Konvertierung |

## Quick Start

```bash
# Container starten
cd video-service
docker compose up -d

# Logs anzeigen
docker compose logs -f video-api

# Health Check
curl http://localhost:8500/api/v1/health
```

## Architektur

```
video-service/
+-- app/
|   +-- main.py              # FastAPI App
|   +-- config.py            # Pydantic Settings
|   +-- celery_app.py        # Celery Config
|   +-- api/
|   |   +-- routes.py        # API Endpoints
|   |   +-- auth.py          # JWT + API-Key
|   +-- services/
|   |   +-- storage.py       # File Management
|   |   +-- converter.py     # FFmpeg Wrapper
|   +-- tasks/
|   |   +-- video_tasks.py   # Celery Tasks
|   +-- models/
|       +-- schemas.py       # Pydantic Models
+-- storage/
|   +-- uploads/             # Hochgeladene Videos
|   +-- converted/           # HLS Output
+-- tests/
    +-- test_api.py
```

## API Endpoints

| Endpoint | Methode | Auth | Beschreibung |
|----------|---------|------|--------------|
| `/health` | GET | - | Health Check |
| `/api/v1/health` | GET | - | Detaillierter Health Check |
| `/api/v1/videos/upload` | POST | API-Key | Video hochladen |
| `/api/v1/videos/{id}/status` | GET | API-Key | Status abfragen |
| `/api/v1/videos` | GET | API-Key | Alle Videos listen |
| `/api/v1/videos/{id}` | DELETE | API-Key | Video loeschen |
| `/api/v1/videos/{id}/token` | POST | API-Key | Stream-Token generieren |
| `/api/v1/stream/{id}/master.m3u8` | GET | JWT | HLS Master Playlist |
| `/api/v1/stream/{id}/{quality}/playlist.m3u8` | GET | JWT | Quality Playlist |
| `/api/v1/stream/{id}/{quality}/{segment}` | GET | JWT | Video Segment |

## Authentifizierung

### API-Key (WordPress -> Video-Service)

```
X-API-Key: your-api-key
```

### JWT Token (Client -> Streaming)

```
/api/v1/stream/{video_id}/master.m3u8?token=eyJ...
```

Token-Inhalt:
```json
{
  "video_id": "abc123",
  "buchung_id": 789,
  "ip": "192.168.1.100",
  "exp": 1701442800
}
```

## Konfiguration

### Environment Variables

| Variable | Default | Beschreibung |
|----------|---------|--------------|
| `API_KEY` | - | API-Key fuer WordPress |
| `JWT_SECRET` | - | Secret fuer Stream-Tokens |
| `JWT_EXPIRY_HOURS` | 1 | Token-Gueltigkeit |
| `REDIS_URL` | redis://redis:6379/0 | Redis-Verbindung |
| `STORAGE_PATH` | /app/storage | Speicherpfad |
| `WORDPRESS_WEBHOOK_URL` | - | Webhook-URL |
| `ALLOWED_ORIGINS` | - | CORS Origins |
| `VIDEO_DOMAIN` | - | Produktions-Domain |
| `MAX_UPLOAD_SIZE_MB` | 2048 | Max. Upload (2GB) |
| `VIDEO_QUALITIES` | 360p,720p,1080p | HLS Qualitaeten |
| `HLS_SEGMENT_DURATION` | 6 | Segment-Laenge |

## Video-Konvertierung

### HLS Output-Struktur

```
videos/{video_id}/
+-- metadata.json
+-- thumbnail.jpg
+-- hls/
    +-- master.m3u8
    +-- 360p/
    |   +-- playlist.m3u8
    |   +-- segment_000.ts
    |   +-- segment_001.ts
    +-- 720p/
    |   +-- playlist.m3u8
    |   +-- segment_000.ts
    +-- 1080p/
        +-- playlist.m3u8
        +-- segment_000.ts
```

### Quality Presets

| Quality | Resolution | Video Bitrate | Audio Bitrate |
|---------|------------|---------------|---------------|
| 360p | -2:360 | 800k | 96k |
| 720p | -2:720 | 2500k | 128k |
| 1080p | -2:1080 | 5000k | 192k |

## Webhook Events

Der Service sendet Webhooks an WordPress:

### `video.progress`
```json
{
  "event": "video.progress",
  "video_id": "abc123",
  "kurs_id": 42,
  "status": "processing",
  "progress": 45
}
```

### `video.ready`
```json
{
  "event": "video.ready",
  "video_id": "abc123",
  "kurs_id": 42,
  "status": "ready",
  "metadata": {
    "duration_seconds": 3600,
    "width": 1920,
    "height": 1080
  },
  "thumbnail_url": "https://..."
}
```

### `video.error`
```json
{
  "event": "video.error",
  "video_id": "abc123",
  "kurs_id": 42,
  "status": "error",
  "error_message": "FFmpeg conversion failed"
}
```

## WordPress Integration

### Einstellungen

In WordPress unter **Veranstaltungen > Einstellungen > Video-Service**:

1. Video-Service URL eintragen (z.B. `http://localhost:8500`)
2. API-Key eintragen (muss mit VIDEO_API_KEY uebereinstimmen)
3. Verbindung testen

### Shortcode

```
[kurs_video buchung_id="123"]
[kurs_video buchung_id="123" video_id="5"]
```

## Entwicklung

```bash
# Lokale Tests
cd video-service
python -m pytest tests/ -v

# API Dokumentation
# http://localhost:8500/docs (nur im Debug-Modus)
```

## Deployment auf Hetzner

1. Storage Box einrichten (BX11)
2. CX22 Server mit Docker
3. DNS: videos.islandpferde-melanieworbs.de -> Server-IP
4. SSL-Zertifikat via Coolify/Traefik
5. Environment Variables in Coolify setzen

## Sicherheit

- API-Key zwischen WordPress und Service
- JWT fuer Streaming mit IP-Binding
- Rate-Limiting (10 req/s)
- Kein direkter Zugriff auf Storage
- HTTPS in Produktion

---

**Version:** 1.0.0
**Stand:** 02. Dezember 2025