# HMS MediaEngine – Plugin-SDK-Dokumentation

Diese Dokumentation beschreibt das Plugin-System der HMS MediaEngine (PLAN.md §14) und das eingebaute Starterpaket (§15). Sie richtet sich an Entwickler, die eigene Plugins schreiben oder die eingebauten Plugins als Vorlage nutzen.

## Was ist ein Plugin?

Ein Plugin ist ein selbstbeschreibendes Paket, das der MediaEngine eine neue Fähigkeit hinzufügt – typischerweise einen GPU-Effekt (Filter/Generator) oder eine Quelle. Jedes Plugin besteht aus einem Manifest (`plugin.json`) und den dazugehörigen Shader-Dateien. Die Engine validiert das Paket, kompiliert die Shader und bindet sie an die Render-Pipeline (PLAN.md §14.1, §14.5).

## Pluginarten (§14.1)

| Typ | Aufgabe |
| --- | --- |
| `source` | Video, Bild, Capture, Stream oder andere Texturquelle |
| `generator` | generiert GPU-Inhalt ohne Eingangsbild |
| `filter` | verarbeitet eine Eingangs-Textur |
| `transition` | mischt zwei Quellen zeitabhängig |
| `mixer` | spezielles Layer-Compositing |
| `output` | HDMI, Art-Net-Pixel, später NDI/Spout/Recording |
| `control` | Art-Net, später MIDI, OSC, HTTP/Webhook |
| `automation` | LFO, Audio-Mapping oder spätere KI-Regeln |

## Verzeichnisstruktur (§14.2)

Ein Plugin wird als Verzeichnis oder validiertes ZIP installiert:

```text
com.hms.fx.gaussian_blur/
├─ plugin.json
├─ shaders/
│  ├─ d3d11/
│  │  ├─ horizontal.hlsl
│  │  └─ vertical.hlsl
│  ├─ gl/
│  │  ├─ horizontal.frag
│  │  └─ vertical.frag
│  └─ gles/
│     ├─ horizontal.frag
│     └─ vertical.frag
├─ presets/
├─ thumbnail.png
├─ LICENSE
└─ README.md
```

Die Shader liegen je Backend in einem eigenen Unterordner (`d3d11/`, `gl/`, `gles/`). Weitere Dateien wie `presets/`, `thumbnail.png`, `LICENSE` und `README.md` sind optional.

## Quick Start

Ein minimales Filter-Plugin besteht aus drei Schritten:

1. **Manifest anlegen** – `plugin.json` mit Pflichtfeldern (`schema_version`, `id`, `name`, `version`, `api_version`, `kind`, `vendor`, `entrypoints`, `capabilities`, `failure_mode`). Siehe [manifest-reference.md](manifest-reference.md).
2. **Shader schreiben** – je deklariertem Backend eine Shader-Datei, die den Standard-Uniform-Satz (§14.4) und die Backend-Syntaxregeln einhält. Siehe [shader-contract.md](shader-contract.md).
3. **Validieren** – das Manifest wird gegen das Schema und den Validator geprüft (`packages/plugin_sdk/hms_plugin_sdk/manifest.py`). Shader müssen für jedes deklarierte Backend existieren.

Ein vollständiges, schrittweises Beispiel von null anhand des eingebauten Vignette-Plugins findest du in [example-walkthrough.md](example-walkthrough.md).

## Dokumente

| Dokument | Inhalt |
| --- | --- |
| [README.md](README.md) | Übersicht, Pluginarten, Verzeichnisstruktur, Quick Start |
| [manifest-reference.md](manifest-reference.md) | Vollständige `plugin.json`-Feldreferenz |
| [shader-contract.md](shader-contract.md) | Standard-Uniform-Satz, cbuffer-Layout, Backend-Syntax |
| [parameters-and-dmx.md](parameters-and-dmx.md) | Parameter, DMX-Slots, Kurven, gemeinsamer Effektvertrag |
| [lifecycle.md](lifecycle.md) | Lebenszyklus, Quarantäne, Show-Lock |
| [adaptive-quality.md](adaptive-quality.md) | Adaptive-Quality-Varianten und Wechselregeln |
| [example-walkthrough.md](example-walkthrough.md) | Schritt-für-Schritt-Beispiel (Vignette) |

## Sicherheitsgrenzen (§14.6)

- Shaderplugins erhalten keinen Dateisystem- oder Netzwerkzugriff.
- Native DLL-Plugins sind vor Version 2 nicht vorgesehen.
- Python-Control-/Automation-Plugins laufen später in einem separaten Prozess mit freigegebener Command-API.
- Kein Plugin greift direkt auf SQLite oder interne Python-Objekte zu.
- Pluginfehler werden einem konkreten Plugin zugeordnet und in der UI angezeigt.