121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# Show-Control Primitives
|
|
|
|
## Ziel
|
|
|
|
Diese Primitive-Menge ist die kleine, dauerhafte interne Steuersemantik fuer software-only Show-Control. Sie bleibt bewusst generisch:
|
|
|
|
- keine UI-spezifischen Sonderfaelle
|
|
- keine grandMA-spezifische Kopplung
|
|
- keine zweite Architektur neben Host-Core und API
|
|
|
|
Der aktuelle Stand gilt faktisch als eingefrorene Show-Control-v1-Semantik. Erweiterungen muessen kuenftig kompatibel zur bestehenden direct-/staged-Trennung, Fehlercode-Menge und Event-Sicht bleiben.
|
|
|
|
Der Implementierungspfad liegt in `crates/infinity_host/src/external_control.rs`.
|
|
|
|
## Primitive
|
|
|
|
### `blackout`
|
|
|
|
- Typ: direkt, mutierend
|
|
- Semantik: setzt globalen Blackout an oder aus
|
|
- Idempotenz: ja, bezogen auf den Zielzustand
|
|
- Fehlercodes: unterliegende Host-Fehler nur bei Persistenzproblemen, typischerweise `persist_failed`
|
|
- Event-Auswirkung: Info-Event auf Erfolg
|
|
|
|
### `recall_preset`
|
|
|
|
- Typ: direkt, mutierend
|
|
- Semantik: recalled ein Preset inklusive seiner Zielgruppe und Transition-Metadaten
|
|
- Idempotenz: praktisch ja, wenn dasselbe Preset erneut recalled wird
|
|
- Fehlercodes: `unknown_preset`, `persist_failed`
|
|
- Event-Auswirkung: Info-Event auf Erfolg, Warning-Event bei unbekanntem Preset
|
|
|
|
### `recall_creative_snapshot`
|
|
|
|
- Typ: direkt, mutierend
|
|
- Semantik: recalled einen gespeicherten Creative Snapshot inklusive Scene- und Transition-State
|
|
- Idempotenz: praktisch ja, wenn derselbe Snapshot erneut recalled wird
|
|
- Fehlercodes: `unknown_creative_snapshot`, `persist_failed`
|
|
- Event-Auswirkung: Info-Event auf Erfolg, Warning-Event bei unbekanntem Snapshot
|
|
|
|
### `set_master_brightness`
|
|
|
|
- Typ: direkt, mutierend
|
|
- Semantik: setzt globale Helligkeit, intern auf `0.0..1.0` geklemmt
|
|
- Idempotenz: ja, bezogen auf den geklemmten Zielwert
|
|
- Fehlercodes: typischerweise nur `persist_failed`
|
|
- Event-Auswirkung: Info-Event auf Erfolg
|
|
|
|
### `set_pattern`
|
|
|
|
- Typ: staged
|
|
- Semantik: staged das Pattern fuer die naechste explizite Transition
|
|
- Idempotenz: ja, letzter Wert gewinnt
|
|
- Fehlercodes: `invalid_pattern_id`
|
|
- Event-Auswirkung: kein Host-Event bis `trigger_transition`
|
|
|
|
### `set_group_parameter`
|
|
|
|
- Typ: staged
|
|
- Semantik: staged einen Scene-Parameter fuer die naechste Transition und kann optional gleichzeitig die Zielgruppe fuer diese Transition setzen
|
|
- Idempotenz: ja, letzter Wert pro Parameter-Key gewinnt
|
|
- Fehlercodes: `invalid_group_parameter_key`
|
|
- Event-Auswirkung: kein Host-Event bis `trigger_transition`
|
|
|
|
### `upsert_group`
|
|
|
|
- Typ: direkt, mutierend
|
|
- Semantik: legt eine Runtime-Gruppe an oder ueberschreibt sie bewusst mit `overwrite: true`
|
|
- Idempotenz: ja mit `overwrite: true`, nein mit `overwrite: false`
|
|
- Fehlercodes: `invalid_group_id`, `invalid_group_members`, `group_exists`, `persist_failed`
|
|
- Event-Auswirkung: Info-Event auf Erfolg
|
|
|
|
### `set_transition_style`
|
|
|
|
- Typ: staged
|
|
- Semantik: staged Transition-Style und optional Duration fuer die naechste explizite Transition
|
|
- Idempotenz: ja, letzter Wert gewinnt
|
|
- Fehlercodes: keine zusaetzlichen Primitive-Fehler
|
|
- Event-Auswirkung: kein Host-Event bis `trigger_transition`
|
|
|
|
### `trigger_transition`
|
|
|
|
- Typ: ausfuehrend, mutierend
|
|
- Semantik: materialisiert den aktuell gestagten Transition-Intent in den Host
|
|
- Ausfuehrungsreihenfolge:
|
|
1. `select_group` nur wenn ueber staged Parameter ein Gruppenkontext gesetzt wurde
|
|
2. `set_transition_duration_ms` nur wenn staged
|
|
3. `set_transition_style` nur wenn staged
|
|
4. `select_pattern`
|
|
5. `set_scene_parameter` fuer alle staged Parameter
|
|
- Idempotenz: nein, erfolgreicher Trigger konsumiert den gestagten Intent
|
|
- Fehlercodes: `transition_pattern_required` plus unterliegende Host-Fehler wie `unknown_group` oder `persist_failed`
|
|
- Event-Auswirkung: die unterliegenden Host-Kommandos erzeugen die sichtbaren Info-/Warning-Events
|
|
|
|
### `request_snapshot`
|
|
|
|
- Typ: read-only
|
|
- Semantik: liefert den aktuellen Host-Snapshot ohne Host-Mutation
|
|
- Idempotenz: ja
|
|
- Fehlercodes: keine Primitive-eigenen
|
|
- Event-Auswirkung: keine
|
|
|
|
## Hinweis zur Adapter-Nutzung
|
|
|
|
Die staged Primitive sind fuer externe Show-Control-Adapter gedacht, die absichtlich mehrere kleine Eingaben sammeln und erst mit `trigger_transition` in einen Host-seitigen Uebergang umsetzen. Direkte UI- oder API-Kommandos koennen weiterhin eager bleiben; die stabile interne Adapter-Semantik wird davon nicht aufgeblasen.
|
|
|
|
Ein stateless Port darf staged Primitive nicht stillschweigend akzeptieren. Wenn `set_pattern`, `set_group_parameter`, `set_transition_style` oder `trigger_transition` ohne Session-/Adapter-Kontext direkt an einem Port landen, ist der erwartete Fehlercode `show_control_session_required`.
|
|
|
|
## Referenz-Client
|
|
|
|
Der sehr duenne generische Referenzpfad liegt in `crates/infinity_host/src/external_control.rs`:
|
|
|
|
- `ReferenceShowControlClient::stateful(...)` fuer direkte plus staged Flows
|
|
- `ReferenceShowControlClient::stateless(...)` zum bewussten Nachweis, dass staged Primitive am nackten Port mit `show_control_session_required` abgewiesen werden
|
|
- `BufferedShowControlAdapter` und `ShowControlSession` als kleine Buffer-/Commit-Implementierung ohne neue Grundarchitektur
|
|
|
|
Ergaenzende Randbedingungen:
|
|
|
|
- `docs/external_control_bridge.md` beschreibt die generische Prozess-Aussenkante auf Basis derselben Primitive
|
|
- `docs/control_ownership.md` beschreibt die konfliktfreie Koexistenz mehrerer Control-Quellen
|