hms-mediaengine/docs/plugin-sdk

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:

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.
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.
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.

Dokumente

Dokument	Inhalt
README.md	Übersicht, Pluginarten, Verzeichnisstruktur, Quick Start
manifest-reference.md	Vollständige plugin.json-Feldreferenz
shader-contract.md	Standard-Uniform-Satz, cbuffer-Layout, Backend-Syntax
parameters-and-dmx.md	Parameter, DMX-Slots, Kurven, gemeinsamer Effektvertrag
lifecycle.md	Lebenszyklus, Quarantäne, Show-Lock
adaptive-quality.md	Adaptive-Quality-Varianten und Wechselregeln
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.