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).
132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
# Parameter und DMX
|
||
|
||
Dieses Dokument beschreibt Parameter-Definitionen, DMX-Slots, Kurven und den gemeinsamen Effektvertrag. Grundlage sind PLAN.md §14.7 (DMX-Parameter-Slots), §14.8 (Gemeinsamer Effektvertrag), das JSON-Schema und der Validator `packages/plugin_sdk/hms_plugin_sdk/manifest.py`.
|
||
|
||
## Parameter-Definitionen
|
||
|
||
Parameter werden im Manifest unter `parameters` als Liste von Objekten deklariert. Jeder Parameter besitzt folgende Felder:
|
||
|
||
| Feld | Typ | Pflicht | Beschreibung |
|
||
| --- | --- | --- | --- |
|
||
| `id` | string | ja | Eindeutige Parameter-ID |
|
||
| `label` | string | ja | Anzeigename |
|
||
| `type` | enum | ja | `float`, `int`, `enum`, `bool`, `color` |
|
||
| `default` | beliebig | ja | Standardwert |
|
||
| `minimum` | number | nein | Untergrenze (für `float`/`int`) |
|
||
| `maximum` | number | nein | Obergrenze (für `float`/`int`) |
|
||
| `values` | array | nein | Werte für `enum` |
|
||
| `dmx_slots` | array | nein | DMX-Slot-Belegung (1–8) |
|
||
| `curve` | string | nein | Kurvenform, z. B. `quadratic` |
|
||
|
||
### Parametertypen
|
||
|
||
Der Validator (`manifest.py`) erlaubt genau fünf Typen:
|
||
|
||
- `float` – Gleitkommawert; `minimum`, `maximum` und `default` sind Pflicht.
|
||
- `int` – Ganzzahl.
|
||
- `enum` – Aufzählung; `values` listet die erlaubten Werte.
|
||
- `bool` – Wahrheitswert (`0`/`1`).
|
||
- `color` – Farbe, als RGB-Array (z. B. `[0, 0, 0]`).
|
||
|
||
### Validator-Regeln
|
||
|
||
- `id` muss vorhanden und ein String sein; doppelte IDs sind Fehler.
|
||
- `type` muss einer der fünf erlaubten Typen sein.
|
||
- Für `float` müssen `minimum`, `maximum` und `default` vorhanden sein.
|
||
- `dmx_slots` muss eine Liste von Ganzzahlen sein.
|
||
- Die Summe aller `dmx_slots` über alle Parameter darf **8 nicht überschreiten** (PLAN.md §14.7).
|
||
|
||
## DMX-Slots (§14.7)
|
||
|
||
Ein Effekt besitzt maximal **acht generische DMX-Slots pro Effektinstanz**. Das Manifest bildet reale Parameter darauf ab:
|
||
|
||
- acht 8-Bit-Parameter; oder
|
||
- vier 16-Bit-Parameter; oder
|
||
- eine gemischte, manifestdefinierte Belegung.
|
||
|
||
Der DMX-Footprint des Layer-Fixtures bleibt dadurch stabil, auch wenn neue Plugins installiert werden.
|
||
|
||
### Slot-Belegung im Manifest
|
||
|
||
Jeder Parameter kann über `dmx_slots` auf einen oder mehrere Slots (1–8) abgebildet werden. Das Vignette-Beispiel belegt die Slots 1–8:
|
||
|
||
```json
|
||
"parameters": [
|
||
{"id": "amount", "label": "Amount", "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [1]},
|
||
{"id": "radius", "label": "Radius", "type": "float", "minimum": 0, "maximum": 2, "default": 0.5, "dmx_slots": [2]},
|
||
{"id": "softness", "label": "Softness", "type": "float", "minimum": 0, "maximum": 1, "default": 0.4, "dmx_slots": [3]},
|
||
{"id": "roundness","label": "Roundness","type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [4]},
|
||
{"id": "center_x", "label": "Center X", "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [5]},
|
||
{"id": "center_y", "label": "Center Y", "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [6]},
|
||
{"id": "color", "label": "Color", "type": "color", "default": [0, 0, 0], "dmx_slots": [7]},
|
||
{"id": "invert", "label": "Invert", "type": "bool", "default": 0, "dmx_slots": [8]},
|
||
{"id": "mix", "label": "Mix", "type": "float", "minimum": 0, "maximum": 1, "default": 1, "dmx_slots": []}
|
||
]
|
||
```
|
||
|
||
Der `mix`-Parameter belegt keinen DMX-Slot (`dmx_slots: []`), da er Teil des gemeinsamen Effektvertrags ist.
|
||
|
||
### 16-Bit-Werte
|
||
|
||
Ein Parameter kann über zwei DMX-Slots als 16-Bit-Wert abgebildet werden (vier 16-Bit-Parameter pro Effektinstanz). Die genaue Belegung ist manifestdefiniert. Der Validator zählt jeden Slot in `dmx_slots` einzeln; die Gesamtsumme darf 8 nicht überschreiten.
|
||
|
||
## Kurven
|
||
|
||
Parameter können eine Kurvenform über `curve` deklarieren. Das Schema erlaubt einen beliebigen String; das Beispiel aus PLAN.md §14.3 verwendet `quadratic`:
|
||
|
||
```json
|
||
{
|
||
"id": "radius",
|
||
"label": "Radius",
|
||
"type": "float",
|
||
"minimum": 0.0,
|
||
"maximum": 40.0,
|
||
"default": 0.0,
|
||
"dmx_slots": [1],
|
||
"curve": "quadratic"
|
||
}
|
||
```
|
||
|
||
Unterstützte Kurvenformen:
|
||
|
||
- `linear` – lineare Abbildung des DMX-/Control-Werts auf den Parameterbereich.
|
||
- `quadratic` – quadratische Abbildung, die feine Abstufungen in einem Teilbereich begünstigt.
|
||
|
||
## Gemeinsamer Effektvertrag (§14.8)
|
||
|
||
Jede Filterinstanz besitzt unabhängig vom konkreten Effekt:
|
||
|
||
- Enable/Bypass;
|
||
- Mix beziehungsweise Effect Opacity von 0 bis 1;
|
||
- eigenen Blend-Modus gegenüber dem unveränderten Eingang;
|
||
- deterministische Position in der Effektkette;
|
||
- Reset auf Default;
|
||
- speicher-, umbenenn- und kopierbares Preset;
|
||
- `Quality: Auto` oder feste Qualitätsstufe;
|
||
- acht stabile generische DMX-Parameter-Slots `P1` bis `P8`;
|
||
- modulatable Parameter über denselben Parameterpfad wie Browser, Art-Net und spätere Automation.
|
||
|
||
### `mix`
|
||
|
||
Der `mix`-Parameter (Effect Opacity) liegt zwischen 0 und 1. `Mix 0` muss den Effekt kostengünstig bypassen (PLAN.md §15.3). Das Vignette-Beispiel implementiert das im Shader:
|
||
|
||
```hlsl
|
||
float m = saturate(param_mix);
|
||
if (m < 0.01)
|
||
{
|
||
return src; // Mix 0 = kostenloser Bypass (§15.3)
|
||
}
|
||
```
|
||
|
||
### `blend_mode`
|
||
|
||
Jeder Effekt besitzt einen eigenen Blend-Modus gegenüber dem unveränderten Eingang. Der Blend-Modus ist Teil des Effektvertrags und wird pro Instanz gesetzt.
|
||
|
||
### `quality`
|
||
|
||
Jeder Effekt besitzt `Quality: Auto` oder eine feste Qualitätsstufe. Die Qualitätsstufe wählt eine Adaptive-Quality-Variante (siehe [adaptive-quality.md](adaptive-quality.md)).
|
||
|
||
### Instanzierungs-Scope
|
||
|
||
Filterplugins dürfen – sofern im Manifest freigegeben – auf Source/Clip, Layer, Group, Adjustment Layer, Master oder Output instanziert werden. V1 muss mindestens Layer, Group/Adjustment und Master unterstützen. Die Kettenreihenfolge ist fachlich relevant und wird strikt von oben nach unten ausgewertet. Verschieben, Bypass, Kopieren und Presetwechsel müssen atomar an einer Framegrenze erfolgen (PLAN.md §14.8).
|