76 lines
3.8 KiB
Markdown
76 lines
3.8 KiB
Markdown
|
# 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.
|