Files

T

HMS MediaEngine Agent 985f156525 Phase 3: Plugin-SDK-Dokumentation (docs/plugin-sdk/, 7 Dateien)

- 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

2026-09-11 01:57:30 +02:00

3.6 KiB

Raw Blame History

Plugin-Lebenszyklus

Dieses Dokument beschreibt den Lebenszyklus eines Plugins. Grundlage sind PLAN.md §14.5 (Plugin-Lebenszyklus), §14.6 (Sicherheitsgrenze), §26.3 (Show-Lock) und die Implementierung packages/plugin_sdk/hms_plugin_sdk/lifecycle.py.

Zustände

Der Lebenszyklus kennt folgende Zustände:

discovered → validated → installed → enabled → compiled → active
                                      ↘ quarantined / incompatible

Zusätzlich existiert der Zustand disabled (deaktiviert, aber installiert). Die vollständige Zustandsmenge (lifecycle.py):

discovered
validated
installed
enabled
compiled
active
quarantined
incompatible
disabled

Übergänge

Übergänge sind nur entlang definierter Kanten erlaubt; Sprünge sind Fehler (InvalidTransitionError). Die erlaubten Übergänge (lifecycle.py):

Von	Nach
`discovered`	`validated`, `incompatible`, `quarantined`
`validated`	`installed`, `incompatible`, `quarantined`
`installed`	`enabled`, `disabled`, `quarantined`
`enabled`	`compiled`, `disabled`, `quarantined`
`compiled`	`active`, `quarantined`, `disabled`
`active`	`disabled`, `quarantined`
`disabled`	`enabled`, `quarantined`
`quarantined`	– (manuelle Entfernung/Neuinstallation)
`incompatible`	–

Discovery und Validierung

discover() scannt ein Verzeichnis mit Plugin-Ordnern, lädt plugin.json und validiert es (inkl. Shader-Existenz). Jedes Plugin wird in validated oder incompatible/quarantined überführt (lifecycle.py).

Die Validierung umfasst (PLAN.md §14.5):

Manifest-Schema;
eindeutige Plugin-ID und semantische Version;
API-Kompatibilität;
Pfad- und ZIP-Sicherheit;
erlaubte Dateitypen und Größenlimits;
Shader-Kompilierung;
Capability-Prüfung;
vollständige, vorab kompilierbare Adaptive-Quality-Varianten und unveränderte Parametersemantik;
Lizenzmetadaten;
Hash des Pakets.

Quarantäne (§3.5, §14.5)

Ein fehlerhaftes Plugin wird quarantiniert, ohne ein Projekt unbrauchbar zu machen. Der Effekt wird überbrückt (bypass_on_error). Die Quarantäne speichert die Ursache (last_error). Aus quarantined gibt es keinen automatischen Übergang; das Plugin muss manuell entfernt oder neu installiert werden.

Show-Lock (§26.3)

Der Show-Lock sperrt strukturelle Änderungen während einer laufenden Show:

Installieren/Updaten ist gesperrt. Übergänge, die Installation/Update bedeuten (installed von discovered/validated), sind im Show-Lock blockiert.
Enable/Disable und Parameter bleiben erlaubt. Aktivieren bereits installierter Plugins (enabled/compiled/active) bleibt möglich (PLAN.md §17.7 Live-Modus).
Versionswechsel sind gesperrt. Ein Update startet einen neuen Zyklus; im Show-Lock wird ein Versionswechsel abgelehnt.

Der Show-Lock wird über set_show_lock(enabled) gesetzt (lifecycle.py).

Doppelte Plugin-IDs

Doppelte Plugin-IDs sind Fehler, keine stillen Überschreibungen. Ein Versionskonflikt wird erkannt; ohne Show-Lock gewinnt der neue Stand, mit Show-Lock wird der Versionswechsel abgelehnt (lifecycle.py).

Sicherheitsgrenze (§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.

3.6 KiB Raw Blame History Unescape Escape