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