HMS MediaEngine Agent
985f156525
- README: Pluginarten, Verzeichnisstruktur, Quick Start (§14.1/§14.2) - manifest-reference: komplette plugin.json-Feldreferenz mit Validator-Regeln und ZIP-Sicherheit (§27.2) - shader-contract: Standard-Uniformsatz je Backend, cbuffer-Layout, 16-Byte-Alignment, Multipass, AQ-Bindung, GLES-Einschraenkungen (§14.4) - parameters-and-dmx: dmx_slots max 8 (§14.7), Kurven, 16-Bit-Werte, gemeinsamer Effektvertrag mix/blend/quality (§14.8) - lifecycle: Zustandsmaschine, Quarantaene, Show-Lock (§14.5/§26.3) - adaptive-quality: Varianten, Semantik-Erhalt, Kompilierung vor Aktivierung, Framegrenzen-Wechsel (§5.2) - example-walkthrough: komplettes Filter-Plugin anhand vignette - 1199 Zeilen, Deutsch, alle Beispiele aus echten Repo-Dateien
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.
|