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

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

{
  "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`

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

`video.ready`

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

`video.error`

{
  "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:

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

Shortcode

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

Entwicklung

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

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

Deployment auf Hetzner

Storage Box einrichten (BX11)
CX22 Server mit Docker
DNS: videos.islandpferde-melanieworbs.de -> Server-IP
SSL-Zertifikat via Coolify/Traefik
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