HMS MediaEngine Agent
362e089be0
Der Nutzer hat recht: Der Ordner war voller Entwicklungs-Muell. Jetzt ist sauber getrennt: ROOT (was der Nutzer sieht und braucht): - run.py = das Programm - hms_app/ = der Anwendungscode - HMS MediaEngine.app = macOS Doppelklick-Starter - HMS-Start.vbs = Windows Doppelklick-Starter - HMS-Install.vbs = Windows Erst-Installation - HMS-Mac-Install.command = macOS Homebrew-Installation - HMS-Portable-Install.command = macOS Portable-Installation (16GB-Fix) - installer_gui.py = grafischer Installer - launcher.pyw + launcher_core.py = interne Start-Logik - LIESMICH.txt = 10-Zeilen-Kurzanleitung - .gitignore _entwicklung/ (alles andere, NICHT benoetigt): - packages/ apps/ native/ plugins/ tools/ schemas/ tests/ docs/ build/ fixture_profiles/ - PLAN.md STATUS.md ERRORS.md TEST_REPORT.md CHANGELOG.md README.md - pyproject.toml uv.lock setup_*.sh/ps1 make_mac_app.py Diese Trennung gilt ab sofort fuer alle Commits. Der Nutzer kann _entwicklung/ loeschen wenn er Platz braucht - die App laeuft ohne. Verifiziert: App startet nach Aufraeumen unveraendert (Health 200).
3.8 KiB
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:
- Manifest anlegen –
plugin.jsonmit Pflichtfeldern (schema_version,id,name,version,api_version,kind,vendor,entrypoints,capabilities,failure_mode). Siehe manifest-reference.md. - 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.
- 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.