hms-mediaengine/_entwicklung/PLAN.md

HMS MediaEngine – technischer Bauplan v1.2

Arbeitstitel. Der Produktname kann später ohne technische Auswirkung geändert werden.

Dokumentstatus: verbindliche Umsetzungsgrundlage
Zielgruppe: ausführende Entwicklungs-KI und technische Prüfer
Primärplattform: Windows 11 x64, portabel ohne Installation
Weitere Zielplattformen: Linux x64 und Raspberry Pi 5 / Linux ARM64
Produktklasse: modularer Medienserver, VJ-System und generativer Licht-/Pixeleffekt-Server
Revision 1.2: Windows-D3D11-Renderpfad, Mini-PC-Profil, Multi-Server-Discovery/Sync, QLab-inspirierte Weboberfläche und verbindliches Generator-/Effekt-Starterpaket
Lieferumfang dieses Dokuments: ausschließlich Bau- und Prüfvorgaben für eine spätere Umsetzung; kein Programmcode und keine fertige Benutzeroberfläche
Stand: 10. September 2026

---

1. Auftrag an die ausführende KI

Baue eine portable, modular erweiterbare Medienserver-Software, die Videos, Bilder, Live-Quellen und generative Effekte in mehreren Layern GPU-beschleunigt verarbeitet. Das System wird lokal über HDMI beziehungsweise DisplayPort ausgegeben, über einen Webbrowser im Netzwerk bedient und zusätzlich wie ein Medienserver-Fixture über Art-Net/DMX gesteuert.

Die Software muss von Beginn an Erweiterungspunkte für folgende spätere Funktionen besitzen:

• zusätzliche Quellen, Videoeffekte, Generatoren, Übergänge und Ausgaben als Plugins;
• mehrere physische Displays und Projektoren;
• Output-Mapping, Warping und Edge-Blending;
• Art-Net-Pixel-Ausgabe für LED-Fixtures;
• Cue- und Timeline-Betrieb;
• Audioanalyse und deterministische Sound-to-Light-Modulation;
• KI-gestützte Programmierung, Szenenauswahl und Automatik;
• im LAN auffindbare, gruppierbare und synchron steuerbare Render-Nodes.

Dieser Bauplan ist normativ. Abweichungen sind nur zulässig, wenn sie in einer Architecture Decision Record dokumentiert, technisch begründet, getestet und vom Auftraggeber freigegeben werden.

1.1 Verbindliche Arbeitsweise

Die ausführende KI muss:

1. zuerst Phase 0 als technischen Machbarkeitsnachweis abschließen;
2. danach strikt in der angegebenen Phasenreihenfolge arbeiten;
3. nach jeder Phase alle zugehörigen Tests und Abnahmekriterien ausführen;
4. STATUS.md, ERRORS.md, TEST_REPORT.md und die ADRs aktuell halten;
5. keine Mock-Funktion, Attrappe oder reine UI-Darstellung als fertig melden;
6. keine nicht getestete Softwaredecodierung als Hardwarebeschleunigung ausgeben;
7. keine Pixelverarbeitung in Python-Schleifen implementieren;
8. keine Plattformabhängigkeit ohne Abstraktionsschicht in den Domänenkern aufnehmen;
9. bei einem nicht bestandenen Gate stoppen, die Ursache dokumentieren und gezielt sanieren;
10. keine spätere Phase beginnen, solange das aktuelle Gate rot ist.

---

2. Produktvision

Das Ziel ist kein vollständiger Nachbau von Resolume oder MADRIX in Version 1.0. Ziel ist ein belastbarer, klar begrenzter Kern, der die wichtigsten Funktionen beider Produktklassen verbindet:

• Medienserver: Clips, Playback, Layer, Blend-Modi, Transformationen, Videoeffekte und DMX-Steuerung;
• VJ-System: schnelle Medienauswahl, Szenen, Übergänge, Live-Preview und Timeline;
• generativer Effektserver: Farbverläufe, Noise, Plasma, Chaser, Formen, Partikel und audioaktive Parameter;
• Mapping-System: virtuelle Canvas, mehrere Ausgänge, Warping und Edge-Blending;
• Automationsplattform: Parameterbindungen, Modulatoren, Audioanalyse und später KI.

2.1 Leitsatz

Python steuert. Native Bibliotheken decodieren. Die GPU rendert. Der Browser bedient.

Python darf das Showmodell, die API, Art-Net, Persistenz, Plugins, Timeline und Automation verwalten. Video-Decoding, Skalierung, Blending, Blur, Distortion, Farbbearbeitung und finale Ausgabe müssen über native Bibliotheken und GPU-Shader erfolgen.

---

3. Nicht verhandelbare Anforderungen

3.1 Portable Windows-Ausgabe

• Auslieferung als entpackbares ZIP-Verzeichnis.
• Start über HMS-MediaEngine.exe ohne Setup.
• Keine Administratorrechte.
• Keine Registry-Pflicht.
• Kein global installiertes Python, Node.js, GStreamer oder FFmpeg erforderlich.
• Alle Anwendungsabhängigkeiten werden mitgeliefert.
• GPU-Treiber und Betriebssystemkomponenten dürfen vorausgesetzt werden; sie können technisch nicht sinnvoll mitgeliefert werden.
• Anwendungsdaten und Projekte bleiben vollständig innerhalb des portablen Ordners, sofern kein anderer Datenpfad konfiguriert wurde.
• Keine automatische Aktualisierung während eines laufenden Showbetriebs.

3.2 Browseroberfläche

• Die vollständige Bedienoberfläche wird als lokale Webanwendung ausgeliefert.
• Bedienung lokal und von anderen Geräten im LAN.
• Echtzeitänderungen über WebSocket.
• Die Browseroberfläche ist niemals der primäre Videoausgang.
• Ein Abbruch oder Neuladen des Browsers darf den laufenden Videooutput nicht stoppen.
• Responsive Bedienung für Desktop und Tablet.
• Ein Control-PC beziehungsweise ein als Coordinator gewählter Server muss mehrere Media-Server in einer gemeinsamen Oberfläche finden, paaren, überwachen, gruppieren und bedienen können.
• Die Showausgabe läuft auf jedem Node unabhängig von der Browserverbindung weiter.

3.3 Videoausgabe

• Native randlose Vollbildausgabe auf wählbaren Displays.
• Mindestens 1920 × 1080 bei 60 Hz.
• Desktop-Zielprofil: virtuelle Canvas bis mindestens 3840 × 2160 bei 60 Hz.
• VSync und kontrolliertes Frame-Pacing.
• Anzeigezuordnung anhand stabiler Displaymerkmale, soweit das Betriebssystem diese liefert.
• Sicherer Fallback, falls ein Display fehlt oder getrennt wird.

3.4 Art-Net

• Art-Net 4 ArtDMX-Eingang.
• Das System meldet sich bei Discovery als Media Server beziehungsweise passender Node-Stil.
• Konfigurierbare Universe- und Startadressen.
• Master-Fixture und ein Layer-Fixture pro Layer.
• Ein Lichtpult kann mehrere Server gleichzeitig steuern; jeder Server erhält eine eindeutige Node-ID, einen eindeutigen Art-Net-Namen und konfliktfreie Universe-Bereiche.
• 8- und 16-Bit-Parameter.
• Konfigurierbares Verhalten bei Signalverlust.
• Später ArtTimeCode, ArtTrigger, ArtSync und Art-Net-Pixel-Ausgabe.

3.5 Modularität

• Plugins sind ab der ersten lauffähigen Version Bestandteil der Architektur.
• Plugin-API ist versioniert.
• Der Kern kennt keine fest codierte Liste aller zukünftigen Effekte.
• Plugins dürfen den Renderer nicht unkontrolliert blockieren oder direkten Zugriff auf interne Datenbanken erhalten.
• Ein fehlerhaftes Plugin muss deaktiviert oder überbrückt werden können, ohne ein Projekt unbrauchbar zu machen.

3.6 Zukunftssicherheit

• Alle wichtigen Objekte erhalten stabile UUIDs.
• Jeder Server erhält beim ersten Start eine dauerhafte node_id, die nicht von IP-Adresse oder Hostname abhängt.
• Projektdateien enthalten eine schema_version.
• Persistierte Strukturen erhalten Migrationen.
• Parameter werden über stabile Pfade beziehungsweise IDs adressiert.
• Audio, Timeline, DMX, Browser und KI greifen über denselben Parameter-/Command-Layer zu.
• Eine spätere KI darf ausschließlich freigegebene Commands und Tools verwenden, nicht direkt Renderer, Datenbank oder Dateisystem manipulieren.

---

4. Umfang und Abgrenzung

4.1 MVP-Funktionsumfang

Der erste produktiv nutzbare Stand umfasst:

• einen Master-Canvas;
• acht gleichzeitig patchbare Layer;
• Video-, Bild-, Solid-, Generator- und Adjustment-Layer;
• zwei frei belegbare Effekt-Slots pro Layer;
• Opacity, Blend-Modus und 2D-Transformation;
• das vollständige Generator- und Effekt-Starterpaket aus Abschnitt 15;
• speicherbare Szenen/Presets mit direktem Abruf, jedoch noch ohne QLab-artige Cue-Ablauflogik;
• Art-Net-Steuerung über Master- und Layer-Fixtures;
• LAN-Discovery, sichere Node-Paarung und eine Cluster-/Serverübersicht für mindestens zwei Server;
• direkte Mehrserver-Steuerung durch ein Lichtpult über getrennte Universe-Bereiche;
• Browser-Liveoberfläche mit reduziertem Preview;
• Projekt speichern, laden, duplizieren und exportieren;
• ein oder zwei physische Ausgänge;
• portables Windows-Paket;
• Diagnoseansicht für FPS, Framezeit, Decoder und Art-Net.

4.2 Nicht Bestandteil des ersten MVP

• vollständiger 3D-Renderer;
• hardware-framegelockte Multi-Rechner-Ausgabe;
• Genlock-/Framelock-Steuerung;
• vollständige NDI-, SDI- oder Capture-Card-Matrix;
• QLab-artige GO-/Standby-Logik, Cue-Sequenzen, Cue-Carts und vollständige Show-Cue-Listen;
• vollständige Timeline; Datenmodell und Parameter-Engine bleiben dafür vorbereitet;
• Plugin-Marktplatz;
• Multi-User-Rechteverwaltung auf Enterprise-Niveau;
• KI-gesteuerte Live-Show ohne Bedienerfreigabe;
• vollständiger MADRIX- oder Resolume-Funktionsumfang;
• framegenaue Rückwärtswiedergabe jedes beliebigen Long-GOP-Codecs.

Die Architektur darf diese Erweiterungen nicht verhindern, sie müssen aber nicht vorzeitig implementiert werden.

---

5. Zielprofile und Capability-Tiers

Das System erkennt beim Start Hardware und verfügbare Backends und ordnet sie einem Capability-Tier zu.

Tier	Zielsystem	Verbindliches Testprofil
DESKTOP_FULL	Windows/Linux mit dedizierter GPU und mindestens 8 GB VRAM	4K60 Master, 8 × 1080p60 Quellen, normale Shader-Effekte, bis zu 2 Ausgänge
DESKTOP_LITE	aktueller Windows-Mini-PC mit schneller iGPU	1080p60 Master, 4 Medien-/Generator-Layer, mehrere einfache Effekte, ein mittlerer Blur, ein Ausgang plus reduziertes Preview
PI_LITE	Raspberry Pi 5 mit aktiver Kühlung	1080p60 Master, 2 Video-/Generator-Layer, einfache Shader-Effekte
HEADLESS_CONTROL	Server ohne Display-GPU	Medienverwaltung, Timeline, Art-Net und Remote-Steuerung ohne lokalen Renderoutput

Ein Plugin deklariert Mindest-Tier, Kostenklasse und Qualitätsstufen. Die normale Betriebsart ist Auto: Anpassungen laufen ohne Dialog, Unterbrechung oder auffällige UI-Warnung und werden nur dezent als AUTO sowie ausführlich in Diagnostics protokolliert. Erst wenn selbst die definierte Mindestqualität das Framebudget nicht hält, erscheint eine Operatorwarnung. Ein stiller Wechsel von Hardware- auf Softwaredecodierung bleibt untersagt.

5.1 Realistische Mini-PC-Klassen

Hardwareklasse	Erwartetes Profil	Einordnung
moderner 6–8-Kern-Mini-PC mit Radeon-680M/780M-Klasse oder vergleichbarer schneller iGPU, 32 GB Dual-Channel-RAM, NVMe, 1-Gbit-Ethernet	DESKTOP_LITE, 1080p60 mit etwa vier typischen Layern	empfohlene portable Standardhardware; konkrete Layerzahl hängt von Codec, Auflösung und Effekten ab
aktuelle Intel-Core-U-/Core-Ultra- oder vergleichbare iGPU-Plattform mit funktionierendem D3D11-Hardwaredecode und zwei Speicherkanälen	DESKTOP_LITE nach Phase-0-Messung	geeignet, wenn der GPU-residente Pfad und die Treiberprüfung grün sind
Intel-N100-Klasse mit 16 GB RAM	unteres Lite-Profil, typischerweise ein bis zwei Videolayer und einfache Effekte	als kompakter Player/Node sinnvoll, nicht als 4K- oder Heavy-FX-Hauptserver einplanen
dedizierte GPU mit mindestens 8 GB VRAM	DESKTOP_FULL	für 4K60, mehrere Ausgänge, viele Layer, starken Blur/Feedback und komplexes Mapping

Bei integrierten GPUs ist Speicherbandbreite ein Teil des Grafikbudgets. Dual-Channel-RAM ist deshalb verbindlich empfohlen. Die Software zeigt kein pauschales Leistungsversprechen, sondern führt beim ersten Start einen kurzen Capability-/Decode-Test aus und aktiviert selbstständig ein passendes Qualitätsprofil.

5.2 Automatische Hardwareerkennung und Adaptive Quality

Beim ersten Start sowie nach Änderung von GPU, Treiber oder Displaykonfiguration führt die Engine vor Freigabe des Liveoutputs einen kurzen, reproduzierbaren Selbsttest aus. Das Ergebnis wird an einen Hardware-Fingerprint gebunden gespeichert.

Erfasst und getestet werden mindestens:

• GPU-Adapter, Feature-Level/API, Treiber und dedizierter beziehungsweise geteilter Speicher;
• D3D11-/GL-/GLES-Funktionen, maximale Textur-/Render-Target-Größen und Timing Queries;
• Hardware-Decodeprofile für H.264, H.265 und optional AV1 sowie gleichzeitige Decoderinstanzen;
• GPU-residenter Memory-Pfad und notwendige Farbkonvertierungen;
• Hardwareencoder für Preview;
• CPU-Kerne, RAM, Speicherbandbreiten-Indikatoren und NVMe-Durchsatz;
• angeschlossene Displays, Auflösungen, Bildraten und gemeinsame Ausgabeanforderung;
• Mikrobeispiele für Decode, zwei-/vierfaches Compositing, Blur, Farbkorrektur und Present.

Aus den Messwerten entstehen kein bloßer Marketing-Score, sondern konkrete Budgets: maximale sichere Decoderzahl je Format, Renderzeitbudget, Textur-/Speicherbudget, Preloadbudget und zulässige Qualitätsstufen je Effekt.

Laufzeitregler

Ein eigener AdaptiveQualityController überwacht GPU-Framezeit p50/p95/p99, Decodequeues, Dropped Frames, Speicherbudget, Encoderlast und thermische Drosselung. Er arbeitet mit Hysterese und ändert höchstens eine Stufe pro Regelintervall:

1. Preview-FPS/Auflösung und Thumbnail-Aktualisierung reduzieren;
2. nicht showkritische Analyse, Scope- und UI-Telemetrieraten reduzieren;
3. Samplezahl, Downsample-Faktor und Iterationen teurer Effekte innerhalb manifestierter Qualitätsvarianten anpassen;
4. Generator-/Partikeldichte und interne Feedbackauflösung reduzieren;
5. vorbereitete Medien-Proxies verwenden, sofern Bildformat, Timing und In-/Out-Punkte identisch bleiben;
6. erst wenn das nicht genügt: klarer Überlaststatus und definierte Fallback-Policy.

Nicht automatisch verändert werden:

• physische Ausgangsauflösung oder Refresh Rate;
• Layer-Reihenfolge, aktive Layer, Cue-/Szenenlogik oder DMX-Zuordnung;
• Farben/Geometrie außerhalb deklarierter tolerierbarer Qualitätsunterschiede;
• Hardwaredecode zu Softwaredecode;
• ein Effekt durch vollständigen Bypass, sofern der Betreiber dies nicht als letzte Fallback-Stufe freigegeben hat.

Alle Shadervarianten werden vorab kompiliert. Diskrete Wechsel erfolgen atomar an einer Framegrenze; kontinuierliche Qualitätsparameter werden kurz interpoliert. Abwertung reagiert schnell auf anhaltende Last, Aufwertung deutlich langsamer, damit kein sichtbares Pumpen entsteht. Der Operator sieht im Normalbetrieb nur Quality: Auto; Experten können Mindeststufe, Prioritäten und ein festes Profil setzen. Im Show-Lock darf niemals ein neuer Benchmark gestartet werden.

---

6. Gesamtarchitektur

flowchart TD
    WEB["Control Center im Browser"] --> COORD["Coordinator / Control Core"]
    DESK["Lichtpult via Art-Net"] --> NODEA["Media-Server A"]
    DESK --> NODEB["Media-Server B"]
    COORD --> NODEA
    COORD --> NODEB
    NODEA --> OUTA["HDMI / Mapping A"]
    NODEB --> OUTB["HDMI / Mapping B"]

Jeder Media-Server bleibt zugleich eigenständig: lokal besteht er weiterhin aus Supervisor, Control Core, Render Worker und Webserver. Der Coordinator ist eine Rolle des Control Core und kann auf einem Render-Server oder einem reinen HEADLESS_CONTROL-PC laufen.

6.1 Prozessaufteilung

A. Supervisor/Launcher

Aufgaben:

• Start und Überwachung der Teilprozesse;
• Wahl freier lokaler Ports;
• Setzen portabler Runtime-Pfade;
• Öffnen des Standardbrowsers;
• Heartbeat-Überwachung;
• kontrolliertes Beenden;
• Wiederanlauf nach einem Control-Core-Absturz;
• Crash- und Startdiagnose.

B. Control Core

Technologie: Python mit asyncio, FastAPI, Pydantic und WebSocket.

Aufgaben:

• autoritativer Projekt- und Showzustand;
• REST-/WebSocket-API;
• Art-Net-Empfang und Parameterauflösung;
• Node-Identität, Discovery, Paarung und Clusterprotokoll;
• optionaler Coordinator für Servergruppen, Preflight und zeitgestempelte Commands;
• Szenen, Cues, Timeline und Automation;
• Plugin-Verwaltung;
• Medienindex und Metadaten;
• Persistenz und Migrationen;
• Audioanalyse beziehungsweise Audio-Feature-Verteilung;
• KI-Command-Gateway;
• Telemetrieaggregation.

C. Render Worker

Technologie in V1: Python-Prozess als Orchestrator für native GStreamer- und GPU-Komponenten. Unter Windows ist D3D11 der Primärpfad; Linux nutzt OpenGL und Raspberry Pi OpenGL ES. Keine Pixelverarbeitung in Python.

Der eigentliche Rendergraph läuft in einem mitgelieferten nativen Render-Modul beziehungsweise GStreamer-Plugin. Phase 0 entscheidet per ADR zwischen Rust und C++ sowie zwischen eigenständiger Render-Bridge und GStreamer-Plugin. Python darf Pipelines konfigurieren und gebündelte Parameterblöcke übergeben, aber weder pro Pixel arbeiten noch pro Frame einzelne D3D11-Drawcalls steuern.

Aufgaben:

• Hardwaredecoder auswählen und verifizieren;
• Medienquellen laden und vorpuffern;
• GPU-Texturen verwalten;
• Rendergraph aufbauen;
• Shader kompilieren und ausführen;
• Layer mischen;
• finale Canvas rendern;
• physische Ausgänge ansteuern;
• Rendertelemetrie liefern;
• bei Verlust des Control Core den letzten gültigen Zustand halten oder den konfigurierten Fallback ausführen.

Der Render Worker muss austauschbar bleiben. Eine spätere Rust-/wgpu-Implementierung muss über dasselbe IPC- und Capability-Protokoll angebunden werden können.

D. Web-Frontend

Technologie: TypeScript mit React oder Svelte; eine Technologie auswählen und danach nicht ohne ADR wechseln. Empfehlung: React mit Vite oder SvelteKit im statischen SPA-Modus. Keine Server-Side-Rendering-Pflicht.

Aufgaben:

• Live-Mixer;
• Medienbrowser;
• Effekt- und Parametereditor;
• Presets/Szenen mit direktem Abruf;
• später optionaler Cue-/Timeline-Workspace als getrenntes Modul;
• Audio-/Automation-Mapping;
• DMX-Patch;
• Output-Mapping;
• Pluginverwaltung;
• Diagnose;
• QLab-inspirierte visuelle Designsprache für Mixer, Medien, Parameter und Cluster-/Node-Ansicht; keine QLab-artige GO-/Cue-Bedienlogik im MVP.

E. Optionale Worker

• Preview-Encoder;
• Art-Net-Pixel-Sender bei hoher Universe-Zahl;
• Offline-Medienanalyse/Transcoding;
• KI-Analysejobs.

Diese Worker werden nur extrahiert, wenn Messungen einen Nutzen zeigen.

6.2 IPC

Das IPC zwischen Control Core und Renderer verwendet in V1 lokales TCP auf 127.0.0.1 mit length-prefixed MessagePack. JSON darf ausschließlich im Debugmodus verwendet werden.

Jede Nachricht besitzt mindestens:

{
  "protocol_version": 1,
  "message_id": "uuid",
  "type": "command|event|snapshot|ack|error|telemetry",
  "revision": 123,
  "monotonic_timestamp_ns": 0,
  "payload": {}
}

Pflichtfunktionen:

• Handshake mit Versions- und Capability-Austausch;
• vollständiger State Snapshot nach Verbindungsaufbau;
• inkrementelle Deltas mit monotoner Revision;
• Ack/Fehler je zustandsänderndem Command;
• Idempotency-Key für wiederholbare Commands;
• Heartbeat mindestens alle 500 ms;
• Re-Sync nach Reconnect;
• maximale Payloadgröße;
• lokales IPC niemals an eine externe Netzwerkschnittstelle binden.

6.3 Multi-Server-Rollen und Discovery

Rollen

Rolle	Aufgabe	Darf ohne andere Rollen laufen?
RENDER_NODE	decodiert und rendert lokale Outputs; empfängt Art-Net und Cluster-Commands	ja
COORDINATOR	führt Node-Registry, Servergruppen, Preflight, Content-/State-Sync und zeitgestempelte Gruppen-Commands	ja, auch auf einem Render-Node
CONTROL_DESK	Browser-Arbeitsplatz ohne lokalen Renderer	ja, als HEADLESS_CONTROL mit Coordinator
ARTNET_CONSOLE	externes Lichtpult; steuert Nodes direkt oder optional über Gruppen-Fixtures am Coordinator	ja

Es gibt in V1 keine automatische Leader-Wahl. Der Betreiber bestimmt einen Coordinator und optional einen vorbereiteten Ersatz. Dadurch bleibt das Verhalten in einer Show nachvollziehbar. Fällt der Coordinator aus, spielen Render-Nodes ihren bereits aktivierten Zustand weiter und ihr direkter Art-Net-Eingang bleibt aktiv.

Auffinden

• Jeder Server erzeugt einmalig eine persistente node_id und einen editierbaren Anzeigenamen.
• Management-Discovery erfolgt per mDNS/DNS-SD als _hmsmedia._tcp.local..
• Der TXT-Datensatz enthält nur kleine, nicht vertrauliche Hinweise: Protokollversion, Node-ID, Rollen, API-Port und Capability-Digest.
• Die UI führt gefundene, bereits gepaarte, unbekannte, inkompatible und offline Nodes getrennt auf.
• mDNS ist keine Vertrauensentscheidung. Ein neuer Node wird erst nach PIN-/Fingerprint-Prüfung und Token-/Zertifikatsaustausch steuerbar.
• Für VLANs, geroutete Netze oder blockiertes Multicast gibt es eine persistente manuelle Node-Liste mit Host/IP und optionaler zentraler DNS-SD-Registrierung.
• Art-Net-Discovery bleibt davon unabhängig: Jeder Render-Node beantwortet ArtPoll mit einem eindeutigen Short-/Long-Name und seinen konfigurierten Ports/Universen.
• IP-Wechsel ändern die node_id nicht. Doppelte Node-IDs werden als Fehler blockiert.

Bedienmodelle

1. Direktes Lichtpult-Modell: Das Pult sendet ArtDMX an die IP oder Universe-Bereiche jedes Servers. Dies ist der robuste V1-Standard und benötigt keinen Coordinator im Echtzeitpfad.
2. Control-Center-Modell: Der Browser verbindet sich nur mit dem Coordinator. Dieser aggregiert Zustand und Telemetrie aller gepaarten Nodes und routet Commands an All, eine ServerGroup, einen einzelnen Node oder einen Output.
3. Koordiniertes Show-Modell: Der Coordinator prüft Medien/Plugins/Revision und verteilt in V1 zeitgestempelte Preset-/Parameterkommandos; spätere Cue-/Timeline-Kommandos verwenden denselben Pfad. Videoframes werden nicht über das Managementnetz gestreamt; jeder Node rendert lokal.

6.4 Getrennte Sync-Stufen

„Sync“ ist kein einzelnes Feature. Folgende Stufen müssen separat implementiert, angezeigt und getestet werden:

Stufe	Zweck	V1-Verfahren	Garantie
Discovery	Server finden	mDNS/DNS-SD plus manuelle Fallback-Liste	keine Autorisierung
Content Sync	identische Medien und Plugins	SHA-256-Manifest, resumierbare Chunks, Hashprüfung, Staging	byte-identische freigegebene Inhalte
Project Sync	identisches Showmodell	versionierter Snapshot plus Migration und atomare Aktivierung	gleiche Projekt-Revision
State Sync	Parameter-/Transportzustand	Full Snapshot, monotone Revisionen, Deltas und Reconnect	kein halber Zustand
Clock Sync	gemeinsame Showzeit	PTP, wenn verfügbar; sonst gemessene Offset-/Drift-Schätzung gegen Coordinator	messbare Softwarezeit, kein Genlock
Preset-/Command-Sync; später Cue/Timeline	gemeinsamer Start	Preload/Arm/Ack und execute_at typischerweise 100–300 ms im Voraus	Ziel p95 ≤ 10 ms Node-zu-Node im verkabelten Referenz-LAN
Frame/Scanout Sync	gleicher physischer Bildwechsel	nur mit geeigneter Genlock-/Framelock-Hardware	außerhalb V1; Software-Sync genügt dafür nicht

Der Wert von 10 ms ist ein Abnahmeziel für vorgepufferte Preset-/Command-Starts, keine Zusage für beliebige Rechner, WLAN, Codecs oder Displays. Für nahtloses Edge-Blending über mehrere Rechner ist Hardware-Synchronisation erforderlich.

6.5 Clusterprotokoll, Preflight und Fehlerfälle

• Node-Kommunikation: authentisiertes TLS-WebSocket mit MessagePack für Commands/State, HTTPS für Ressourcen und resumierbare Content-Chunks.
• Jede Cluster-Nachricht enthält mindestens cluster_id, node_id, command_id, Sequenz, Projekt-Revision, Absenderzeit, optionale execute_at-Showzeit und Trace-ID.
• Zustandsändernde Commands sind idempotent und werden mit accepted, armed, executed oder failed bestätigt.
• Ein Show-Preflight vergleicht Projekt-Revision, Asset-/Plugin-Hashes, Plugin-API, Render-Backend, Outputzuordnung, freien Speicher, Clock-Offset und erwartete Last.
• Aktivierung erfolgt zweiphasig: vollständig ins Staging übertragen und validieren, danach auf allen gewählten Nodes atomar auf dieselbe Revision schalten.
• Fehlende oder inkompatible Inhalte blockieren standardmäßig das Arm; eine bewusst gewählte Degradations-Policy muss sichtbar protokolliert werden.
• Heartbeat standardmäßig alle 500 ms; Zustände online, degraded, stale, offline, mit konfigurierbaren Schwellen.
• Bei Verbindungsverlust gilt je Node/Output eine Policy: letzten Zustand halten, Fallback-Szene oder Fade to Black.
• Nach Reconnect sendet der Node zunächst Status und vollständige Revision; Deltas werden erst nach erfolgreichem Re-Sync akzeptiert.
• Verkabeltes Gigabit-Ethernet und nach Möglichkeit ein getrenntes Show-VLAN sind der Referenzbetrieb. WLAN ist für Bedienung/Monitoring zulässig, nicht für garantierten Cue- oder Frame-Sync.

sequenceDiagram
    participant UI as Control Center
    participant C as Coordinator
    participant A as Node A
    participant B as Node B
    UI->>C: Preset auf Gruppe aktivieren
    C->>A: Preflight und Arm
    C->>B: Preflight und Arm
    A-->>C: Ready + lokale Showzeit
    B-->>C: Ready + lokale Showzeit
    C->>A: Execute at T
    C->>B: Execute at T
    A-->>C: Executed + Istzeit
    B-->>C: Executed + Istzeit

---

7. Verbindlicher Technologie-Stack

Bereich	Vorgabe
Sprache Control Core	Python, unterstützte Version exakt pinnen
API	FastAPI + Pydantic
Async Runtime	asyncio
Medienpipeline	GStreamer
nativer Renderkern	gebündelte Rust- oder C++-Render-Bridge/GStreamer-Plugin; Entscheidung in Phase 0
GPU-Pipeline V1	Backend-Abstraktion: Windows D3D11/D3D11Memory primär; Linux OpenGL; Raspberry Pi OpenGL ES
Shader V1	backendneutrales Parameterschema; mitgelieferte HLSL-Implementierung für D3D11 und GLSL/GLES-Implementierung für Linux/Pi
Datenbank	SQLite mit WAL-Modus
Web-Frontend	TypeScript, React oder Svelte, Vite-basierter Build
Frontend-Paketmanager	pnpm mit Lockfile
Python-Paketmanager	uv mit Lockfile
Python-Portable-Build	Nuitka Standalone/Onefolder oder nach Phase-0-Nachweis PyInstaller Onefolder
Tests Python	pytest, pytest-asyncio, Hypothesis wo sinnvoll
Frontend-Tests	Vitest + Playwright
Typprüfung	mypy oder pyright, Auswahl per ADR
Lint/Format	Ruff; Frontend ESLint/Prettier
Protokollkodierung	MessagePack, versionierte Pydantic-Schemata

7.1 Technischer Entscheidungszwang in Phase 0

Nuitka und PyInstaller müssen nicht beide dauerhaft unterstützt werden. Phase 0 testet mindestens eine vollständige portable Onefolder-Ausgabe inklusive GStreamer. Die Variante mit reproduzierbarerem Build und weniger Laufzeitfehlern wird per ADR festgelegt.

Ein Onefile-Paket ist ausdrücklich nicht das Ziel, weil Startzeit, temporäres Entpacken, Pluginverwaltung und gebündelte GStreamer-Komponenten dadurch unnötig erschwert werden.

Phase 0 vergleicht auf Windows einen vollständig D3D11-residenten Pfad mit einem möglichen GStreamer-GL-/Interop-Pfad. Freigegeben wird nur ein Pfad, bei dem Decoderoberfläche, Effekt-/Composite-Pässe und Ausgabe ohne regulären GPU→CPU→GPU-Rundweg arbeiten. Die Backend-Schnittstelle wird vor den Effekten festgelegt; ein späterer Backendwechsel darf Projekt-, Parameter-, DMX- oder Web-API nicht verändern.

---

8. Repository-Struktur

/
├─ README.md
├─ PLAN.md
├─ STATUS.md
├─ ERRORS.md
├─ TEST_REPORT.md
├─ CHANGELOG.md
├─ pyproject.toml
├─ uv.lock
├─ package.json
├─ pnpm-lock.yaml
├─ apps/
│  ├─ launcher/
│  ├─ control_server/
│  ├─ renderer/
│  └─ web/
├─ native/
│  └─ render_bridge/
├─ packages/
│  ├─ domain/
│  ├─ protocol/
│  ├─ parameter_engine/
│  ├─ render_backend/
│  │  ├─ d3d11/
│  │  └─ gl_gles/
│  ├─ capabilities/
│  ├─ adaptive_quality/
│  ├─ plugin_sdk/
│  ├─ artnet/
│  ├─ cluster/
│  ├─ content_sync/
│  ├─ timeline/
│  ├─ audio_analysis/
│  └─ persistence/
├─ plugins/
│  ├─ builtin/
│  │  ├─ generators/
│  │  ├─ filters/
│  │  ├─ transitions/
│  │  └─ outputs/
│  └─ examples/
├─ schemas/
│  ├─ project/
│  ├─ plugin/
│  ├─ ipc/
│  ├─ cluster/
│  └─ api/
├─ fixture_profiles/
│  ├─ master32/
│  └─ layer64/
├─ tests/
│  ├─ unit/
│  ├─ integration/
│  ├─ rendering/
│  ├─ cluster/
│  ├─ visual/
│  ├─ performance/
│  ├─ portability/
│  └─ e2e/
├─ tools/
│  ├─ media_probe/
│  ├─ shader_validate/
│  ├─ artnet_emulator/
│  ├─ capability_probe/
│  ├─ cluster_test_node/
│  └─ fixture_generator/
├─ build/
│  ├─ windows/
│  ├─ linux/
│  └─ raspberry_pi/
└─ docs/
   ├─ architecture/
   ├─ adr/
   ├─ plugin-sdk/
   ├─ api/
   ├─ fixture/
   ├─ performance/
   └─ operator/

Leere Zukunftsverzeichnisse müssen nicht erzeugt werden. Die Struktur beschreibt Eigentumsgrenzen. Code darf nicht beliebig zwischen Paketen quer importiert werden.

---

9. Portable Verzeichnisstruktur der Windows-Ausgabe

HMS-MediaEngine-Portable/
├─ HMS-MediaEngine.exe
├─ renderer.exe
├─ app/
├─ runtime/
│  ├─ python/
│  ├─ gstreamer/
│  └─ vc-runtime/
├─ web/
├─ plugins/
│  ├─ builtin/
│  └─ user/
├─ projects/
├─ media/
├─ userdata/
│  ├─ database/
│  ├─ cache/
│  ├─ sync-staging/
│  ├─ identity/
│  ├─ thumbnails/
│  └─ plugin-cache/
├─ config/
│  ├─ app.toml
│  ├─ artnet.toml
│  ├─ cluster.toml
│  └─ displays.toml
├─ logs/
├─ licenses/
└─ PORTABLE_MODE

9.1 Portable-Pfadregeln

• Alle internen Pfade werden relativ zum Anwendungsroot oder Projektroot gespeichert.
• Keine hart codierten Laufwerksbuchstaben.
• Keine Abhängigkeit vom aktuellen Working Directory.
• Medien dürfen intern kopiert oder als relative externe Referenz eingebunden werden.
• Beim Projekt-Export werden Medien optional gesammelt und Pfade neu geschrieben.
• Temporäre Dateien liegen in userdata/cache, nicht unkontrolliert im Betriebssystemprofil.
• Schreibbarkeit des Ordners wird beim Start geprüft.
• Bei schreibgeschütztem Medium startet die Anwendung sichtbar im Read-only-Modus.

9.2 Startablauf

1. Launcher bestimmt den eigenen absoluten Programmordner.
2. Runtime- und GStreamer-Suchpfade werden gesetzt.
3. Konfiguration und Datenbank werden migriert.
4. Renderer startet und meldet Capabilities.
5. Control Server startet auf konfiguriertem Port.
6. Node-Identity wird geladen, Discovery gestartet und – falls konfiguriert – die Verbindung zum Coordinator aufgebaut.
7. Healthcheck und lokaler Render-Preflight müssen grün sein.
8. Standardbrowser wird optional geöffnet.
9. Erst danach wird ein gespeichertes Autostart-Projekt aktiviert.

---

10. Domänenmodell

Alle Modelle werden in einem plattformneutralen Paket definiert und sowohl für Persistenz als auch API/IPC verwendet.

10.1 Hauptobjekte

Project

• id: UUID
• schema_version: int
• name: str
• created_at, updated_at
• settings
• media_assets[]
• compositions[]
• scenes[]
• timelines[]
• outputs[]
• control_bindings[]
• audio_profiles[]
• automation_policies[]
• plugin_requirements[]

Composition

• id
• name
• width, height, fps
• color_space
• background_color
• layers[] in eindeutiger Z-Reihenfolge
• duration optional

Layer

• id
• name
• enabled
• layer_type
• source
• opacity
• blend_mode
• transform
• crop
• color_controls
• effects[]
• mask optional
• target_group_id optional
• dmx_patch optional

Source

• plugin_id
• plugin_version
• source_type
• asset_id optional
• parameters
• playback_state
• in_point, out_point
• loop_mode
• speed

EffectInstance

• id
• plugin_id
• plugin_version
• scope: source|layer|group|master|output
• order_index
• enabled
• mix
• effect_blend_mode
• parameters
• preset_id optional
• quality_mode: auto|fixed
• requested_quality und nicht persistierter resolved_quality
• bypass_on_error

PresetScene

• referenzierter Composition-Zustand oder Parameter-Diff;
• Übergangstyp und -dauer;
• Preload-Hinweise;
• Trigger-Metadaten.

Cue – reserviertes Modell nach dem MVP

• referenziert später Preset, Parameteraktion, Medienaktion oder Kontrollbefehl;
• optional quantisierte Ausführung auf Beat/Timecode;
• Pre-/Post-Wait, Follow/Continue, Playhead-/Standby-Metadaten;
• wird in V1 weder in der Standard-UI angezeigt noch für direkten Presetabruf benötigt.

OutputSurface

• id, node_id, display_id
• physische Auflösung und Bildrate;
• Canvas-Ausschnitt;
• Zielrechteck;
• Warp-Mesh;
• Edge-Masks;
• Gamma/Farbkorrektur;
• Rotation/Flip;
• Testbildmodus;
• Fallbackverhalten.

Node

• id: UUID als persistente, netzwerkunabhängige Identität;
• Anzeigename, Hostname und zuletzt bekannte Endpunkte;
• Rollen und Capability-Digest;
• Software-/Protokollversion;
• Vertrauens-/Paarungsstatus;
• Renderbackend, Decoder, Outputs und Leistungs-Tier;
• Health, Clock-Offset/Drift, FPS und letzte Heartbeat-Zeit;
• aktive Projekt-/State-/Content-Revision.

ServerGroup

• id, name;
• node_ids[];
• Zielregel all, selected, tag_query oder feste Node-Liste;
• optionale Output-/Layer-Zuordnung;
• Sync- und Fehler-Policy;
• Art-Net-Gruppenpatch optional.

Cluster

• id, name;
• coordinator_node_id;
• gepaarte Nodes und Gruppen;
• gewünschte Projekt-/Content-Revision;
• Discovery- und Netzwerkprofil;
• Clock- und Sync-Policy;
• rollenbasierte Tokens/Zertifikats-Fingerprints.

ContentManifest

• Manifest-ID und Revision;
• Projekt-, Medien- und Plugin-Einträge;
• relativer portabler Pfad, Größe und SHA-256 je Datei;
• Plugin-API-/Backend-Anforderungen;
• optionale Chunk-Hashes für Resume;
• Signatur-/Herkunftsmetadaten;
• Freigabestatus je Node.

10.2 Parameterpfad

Jeder steuerbare Parameter besitzt einen stabilen Pfad, beispielsweise:

composition/{composition_id}/layer/{layer_id}/opacity
composition/{composition_id}/layer/{layer_id}/source/speed
composition/{composition_id}/layer/{layer_id}/effect/{effect_id}/parameter/radius
output/{output_id}/edge/left/gamma
cluster/group/{group_id}/scene/activate
cluster/node/{node_id}/output/{output_id}/intensity
master/intensity

Parameterpfade werden niemals aus sichtbaren Namen gebildet. Umbenennungen dürfen Automationen und DMX-Bindings nicht zerstören.

---

11. Parameter- und Control-Engine

Alle Steuerquellen arbeiten über eine gemeinsame Parameter-Engine. Direkte Seiteneffekte aus Art-Net-, Browser-, Timeline-, Audio- oder KI-Code auf den Renderer sind verboten.

11.1 Auswertungsreihenfolge

Defaultwert
→ Projekt-/Szenenbasis
→ Timeline-Automation
→ deterministische Modulatoren und Audio
→ Browser-/MIDI-/OSC-/Art-Net-Override
→ Sicherheitsregeln und Wertebegrenzung
→ Frame-Snapshot an Renderer

11.2 Prioritäten

1. Not-Aus/Blackout und Sicherheitslogik
2. expliziter manueller Operator-Override
3. freigegebener Lichtpult-Override
4. Browser-Livebedienung
5. Timeline/Cue
6. Audio-/LFO-Modulatoren
7. KI-Automation
8. Defaultwert

Die Priorität kann je Binding konfiguriert werden, aber KI darf niemals eine Sicherheitsregel überstimmen.

11.3 Übernahmeverfahren

• LTP für Auswahl-, Positions- und Effektparameter;
• HTP optional für Intensität/Opacity;
• Soft-Takeover für Browser/MIDI;
• Ownership mit Timeout;
• release-Command zur Rückgabe an die nächstniedrige Quelle;
• DMX-Ausfallmodus: hold, fade_to_scene, fade_to_black oder disable_source;
• geglättete Parameter mit Attack/Release oder definierter Interpolation;
• Trigger werden flankenbasiert und nicht als Dauerzustand ausgewertet.

11.4 Frame-Konsistenz

Alle für ein Bild geltenden Parameter werden vor dem Frame als unveränderlicher Snapshot gebildet. Es darf kein halber Zustand gerendert werden, bei dem beispielsweise X bereits geändert, Y aber noch alt ist.

---

12. Renderarchitektur

12.1 Rendergraph

Media Decode / Generator
→ Source Texture
→ Source Color Conversion
→ Effect Chain
→ Crop / Transform / Mask
→ Layer Composite
→ Adjustment Layers
→ Master Effects
→ Master Canvas
→ Output Slice / Warp / Edge / Color
→ Display Sink oder Pixel Mapper

12.2 Grundregeln

• Decodierte Frames bleiben möglichst vom Decoder bis zur Ausgabe im GPU-Speicher.
• CPU-Readback ist im normalen HDMI-Renderpfad verboten.
• Jeder unnötige Farbformatwechsel ist zu vermeiden und zu messen.
• Shader werden vor Aktivierung kompiliert.
• Medienwechsel werden vorgepuffert und atomar umgeschaltet.
• Bei Pluginfehler wird der Effekt überbrückt; der Layer bleibt aktiv.
• Der Renderer arbeitet mit einer festen Master-Bildrate.
• Quellen mit anderer Bildrate werden kontrolliert synchronisiert.
• Audio und Video verwenden eine gemeinsame monotone Zeitbasis.

12.3 Layer-Typen

Media Layer

• Video
• Standbild
• Bildsequenz später
• Kamera/Capture später
• Netzwerkstream später

Generator Layer

• Shader erzeugt ein Bild ohne Medienquelle.
• Standard-Inputs: Zeit, Phase, Auflösung, Farben, Seed, Audiofeatures.

Adjustment Layer

• verarbeitet die bereits zusammengesetzten Layer unterhalb beziehungsweise innerhalb einer Zielgruppe;
• Beispiele: Blur, Color Grade, Distortion, Feedback;
• Zielbereich muss explizit gespeichert werden.

Group Layer

• gruppiert mehrere Layer;
• eigene Opacity, Transform und Effektkette;
• verhindert spätere Sackgassen beim Mapping und bei komplexen Shows.

12.4 Blend-Modi V1

• Normal
• Add
• Multiply
• Screen
• Lighten
• Darken
• Difference
• Overlay
• Alpha Premultiplied

Blend-Modi müssen mit Golden-Image-Tests geprüft werden.

12.5 Playback

• Play, Pause, Stop, Retrigger;
• Loop, Once, Ping-Pong nur wenn technisch unterstützt;
• variable Geschwindigkeit;
• In-/Out-Punkte;
• normalisierte Position;
• Preload;
• Ende-Ereignis;
• optional Audio an/aus und Lautstärke.

Rückwärtswiedergabe und harte Random-Seeks werden nur für dafür geeignete Medien garantiert. Die Oberfläche muss sichtbar anzeigen, wenn ein Codec diese Funktionen nicht performant unterstützt.

12.6 Plattform-Backend-Vertrag

Der Rendergraph ist fachlich einheitlich, seine GPU-Implementierung jedoch plattformspezifisch. Projektdatei, Effektparameter, Layerlogik und DMX-Slots dürfen keinen D3D11-, HLSL-, OpenGL- oder GLSL-Typ enthalten.

Plattform	Primärer GPU-residenter Pfad	Verbotener Normalpfad
Windows 11	GStreamer-Hardwaredecoder mit D3D11Memory → D3D11-Texturen → D3D11-Compositor/eigene HLSL-Pässe → DXGI-Swapchain beziehungsweise d3d11videosink	Decoder → System-RAM/appsink → erneuter GPU-Upload
Linux x64	Hardwaredecode/DMABuf oder GLMemory → OpenGL-Texturen → GLSL → nativer Display-Sink	synchrones CPU-Readback je Frame
Raspberry Pi 5	verfügbarer V4L2-/GStreamer-Hardwarepfad → DMABuf/GL ES → GLES-Shader → Display-Sink	Softwaredecode als stiller Ersatz

Das interne RenderBackend-Interface stellt mindestens bereit:

• Geräte-/Adapterauswahl und Capability-Abfrage;
• Decoderoberflächen importieren;
• Render-Targets und Texturen anlegen;
• Shader-/Effektpässe ausführen;
• Layer compositen;
• Output-Slice präsentieren;
• GPU-Fences/Timing auslesen;
• ausschließlich expliziten asynchronen Readback für Preview/Pixel-Mapping anfordern.

Jeder Frame meldet seinen Memory-Typ. Ein unerwarteter Übergang in System-RAM setzt die Quelle auf degraded, erzeugt eine sichtbare Warnung und wird in Performance-Abnahmetests als Fehler gewertet.

---

13. Medienpipeline und Medienbibliothek

13.1 GStreamer

GStreamer übernimmt:

• Container-Demuxing;
• Decoderwahl;
• Hardwaredecoding;
• Zeitstempel und Synchronisation;
• Audio-Decoding;
• GPU-Upload beziehungsweise GPU-Memory-Weitergabe;
• Preview-Encoding;
• optional Transcoding-Hilfsfunktionen.

Der Renderer protokolliert pro Quelle:

• verwendeter Decoder;
• Hardware- oder Softwarepfad;
• Eingangsformat;
• GPU-Memory-Typ;
• Decodierzeit;
• Queuefüllstand;
• verworfene Frames;
• Farbkonvertierungen.

Unter Windows werden d3d11h264dec/passende D3D11-Decoder, d3d11convert, d3d11compositor und der D3D11-Ausgabepfad als erste Kandidaten geprüft. Die tatsächlich verfügbare Elementkette wird zur Laufzeit aus Capability-Tests gewählt und vollständig geloggt. Ein OpenGL-Pfad unter Windows ist nur zulässig, wenn Phase 0 dessen Interop ohne regelmäßige CPU-Kopie nachweist und er auf der Referenzhardware messbar besser oder stabiler ist.

13.2 Medienasset

Ein Asset speichert:

• stabile UUID;
• relativen Pfad;
• Dateigröße und Änderungszeit;
• Content-Hash optional beziehungsweise bei Projektpaketen verpflichtend;
• Container und Codecs;
• Breite, Höhe, FPS, Dauer;
• Alpha-Unterstützung;
• Audiostreams;
• Thumbnail-/Proxy-Pfade;
• Eignung für Seek/Reverse;
• Analyse- und Transcodingstatus.

13.3 Import

• Import blockiert niemals den Renderthread.
• Metadaten werden asynchron ermittelt.
• Thumbnails werden im Hintergrund erzeugt.
• Doppelte Assets werden erkannt.
• Fehlende Dateien werden sichtbar markiert und können neu verknüpft werden.
• Medienbank und Clipnummer sind explizite Show-Metadaten, nicht von Dateinamen abhängig.

13.4 Codecstrategie

V1 priorisiert verbreitete hardwaredecodierbare H.264-/H.265-Dateien. Zusätzlich ist ein für schnelles Triggern geeigneter Intra-Frame- beziehungsweise GPU-freundlicher Medienpfad vorzusehen. Der konkrete zusätzliche Codec wird erst nach Lizenz-, GStreamer- und Performancetest per ADR festgelegt.

---

14. Plugin-System

14.1 Pluginarten

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

14.2 Plugin-Paket

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

14.3 Beispielmanifest

{
  "schema_version": 1,
  "id": "com.hms.fx.gaussian_blur",
  "name": "Gaussian Blur",
  "version": "1.0.0",
  "api_version": 1,
  "kind": "filter",
  "vendor": "HMS",
  "entrypoints": {
    "d3d11": {
      "type": "hlsl_multipass",
      "passes": [
        {"pixel_shader": "shaders/d3d11/horizontal.hlsl"},
        {"pixel_shader": "shaders/d3d11/vertical.hlsl"}
      ]
    },
    "gl": {
      "type": "glsl_multipass",
      "passes": [
        {"fragment": "shaders/gl/horizontal.frag"},
        {"fragment": "shaders/gl/vertical.frag"}
      ]
    },
    "gles": {
      "type": "glsl_es_multipass",
      "passes": [
        {"fragment": "shaders/gles/horizontal.frag"},
        {"fragment": "shaders/gles/vertical.frag"}
      ]
    }
  },
  "capabilities": {
    "minimum_tier": "DESKTOP_LITE",
    "requires_input_texture": true,
    "supported_backends": ["d3d11", "gl", "gles"]
  },
  "adaptive_quality": {
    "default": "auto",
    "variants": [
      {"id": "low", "internal_scale": 0.25, "samples": 5},
      {"id": "medium", "internal_scale": 0.5, "samples": 9},
      {"id": "high", "internal_scale": 1.0, "samples": 17}
    ],
    "transition_ms": 180,
    "semantic_parameters_unchanged": ["radius", "mix"]
  },
  "parameters": [
    {
      "id": "radius",
      "label": "Radius",
      "type": "float",
      "minimum": 0.0,
      "maximum": 40.0,
      "default": 0.0,
      "dmx_slots": [1],
      "curve": "quadratic"
    },
    {
      "id": "quality",
      "label": "Quality",
      "type": "enum",
      "values": ["auto", "low", "medium", "high"],
      "default": "auto",
      "dmx_slots": [2]
    }
  ],
  "failure_mode": "bypass"
}

14.4 Standard-Shaderinputs

Jeder Shader erhält nach Bedarf:

• u_input_texture
• u_resolution
• u_time_seconds
• u_delta_seconds
• u_frame_index
• u_layer_opacity
• u_audio_rms
• u_audio_peak
• u_audio_bass
• u_audio_mid
• u_audio_treble
• u_audio_beat
• deklarierte Pluginparameter

Semantische Input-IDs, Typen, Wertebereiche, Farbräume und Texturkonventionen sind Teil der versionierten Plugin-API. Backendadapter binden sie an HLSL-Konstanten beziehungsweise GLSL-Uniforms; Projekte referenzieren niemals konkrete Variablennamen eines Backends.

14.5 Plugin-Lebenszyklus

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

Validierung umfasst:

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

14.6 Sicherheitsgrenze

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

14.7 DMX-Parameter-Slots

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.

14.8 Gemeinsamer Effektvertrag

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.

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.

---

15. Eingebautes Generator- und Effekt-Starterpaket

Die Auswahl orientiert sich funktional an den grundlegenden Echtzeitmustern von MADRIX und am Effekt-Workflow von Resolume, ohne deren Code, Presets, Namen oder Assets zu übernehmen. Ziel ist keine dreistellige Effektmenge, sondern ein kleiner, verlässlicher Grundstock, aus dem durch Layering, Parameter und Effektketten viele Looks entstehen.

15.1 Pflichtgeneratoren für V1

Interne Plugin-ID	Funktion	DMX-/Hauptparameter G1–G8	Adaptive Quality
hms.generator.solid	einfarbige Fläche	Farbe, Alpha	nicht erforderlich
hms.generator.gradient	linearer/radialer Mehrfarbenverlauf und Color Scroll	Palette, Typ, Winkel, Zentrum X/Y, Breite, Phase, Geschwindigkeit	Anzahl Farbstopps bleibt gleich; nur interne Abtastung darf variieren
hms.generator.checker_grid	Checkerboard, Raster und Kacheln	Farbe A/B, Zellgröße, Linienbreite, Offset X/Y, Winkel, Geschwindigkeit	nicht erforderlich
hms.generator.stripes_chaser	Streifen, Lauflicht und weiche Chaser	Palette, Breite, Abstand, Winkel, Richtung, Phase, Geschwindigkeit, Softness	nicht erforderlich
hms.generator.noise_clouds	Noise, Wolken und organische Texturen	Palette, Seed, Skala, Detail, Kontrast, Geschwindigkeit, Richtung, Morph	Octaves/Detail intern reduzieren
hms.generator.plasma	flüssiger, bewegter Farbverlauf	Palette, Skala, Stretch X/Y, Distanz, Phase, Geschwindigkeit, Seed	interne Frequenzzahl reduzieren
hms.generator.wave_bars	Sinus-/Dreieckwellen, Balken und Röhren	Palette, Wellenform, Anzahl, Amplitude, Frequenz, Winkel, Phase, Geschwindigkeit	Anzahl/Antialiasing intern reduzieren
hms.generator.shapes	Kreis, Rechteck, Dreieck, Linie und Polygon	Form, Anzahl, Größe, Rotation, Verteilung, Fill/Stroke, Palette, Seed	Formanzahl innerhalb deklarierter Grenze reduzieren
hms.generator.drops_ripples	fallende Punkte, Tropfen und konzentrische Wellen	Palette, Dichte, Größe, Lebensdauer, Geschwindigkeit, Ripplebreite, Richtung, Seed	maximale aktive Elemente reduzieren
hms.generator.starfield	Sternfeld beziehungsweise leichter Partikelraum	Palette, Anzahl, Größe, Geschwindigkeit, Richtung, Tiefe, Twinkle, Seed	Partikelzahl und interne Tiefe reduzieren

Generatoren verwenden eine lokale, speicherbare Phase. Sie unterstützen free_run, restart_on_load, manual_phase und später beat_sync. Gleicher Seed, gleiche Phase und gleiche Parameter müssen auf allen Backends innerhalb definierter Bildtoleranz dasselbe Muster liefern.

15.2 Pflichtfilter für V1

Interne Plugin-ID	Wirkung	P1–P8 beziehungsweise Hauptparameter	Last-/Sicherheitsregel
hms.fx.transform2d	zusätzlicher, wiederholbarer Transform in der Effektkette	Position X/Y, Scale X/Y, Rotation, Anchor, Wrap/Tile	keine Qualitätsreduktion; Geometrie bleibt exakt
hms.fx.color_adjust	Hue, Saturation, Brightness, Contrast, Gamma sowie Grayscale/Invert	Hue, Saturation, Brightness, Contrast, Gamma, Temperatur/Tint, Mode, Mix	ein GPU-Pass
hms.fx.gradient_map	Luminanz auf zwei Farben oder einen Verlauf abbilden	Palette, Low/High, Balance, Smoothness, Preserve Alpha, Invert, Mode, Mix	ein GPU-Pass
hms.fx.blur_sharpen	Gaussian Blur und Unsharp/Sharpen	Mode, Radius, Strength, Direction, Edge Mode, Quality, Threshold, Mix	separierbarer Blur; Downsample und Samplezahl über Auto Quality
hms.fx.pixelate_quantize	Mosaik/Pixelate und Posterize/Quantization	Pixel X/Y, Color Levels, Dither, Grid Offset, Aspect Lock, Mode, Mix	ein bis zwei GPU-Pässe
hms.fx.mirror_tile	horizontal/vertikal spiegeln, wiederholen und Teile tauschen	Mode, Tiles X/Y, Offset X/Y, Center, Rotation, Mix	ein GPU-Pass
hms.fx.kaleidoscope	radiale oder rechteckige Mehrfachspiegelung	Segments, Rotation, Center X/Y, Zoom, Mirror Mode, Phase, Mix	Segmentzahl semantisch unverändert; ein GPU-Pass
hms.fx.wave_displace	Wave-, Turbulence- und Noise-Displacement	Amount X/Y, Frequency, Angle, Phase, Speed, Noise Scale, Edge Mode	Noise-Detail adaptiv, Verformungsbetrag unverändert
hms.fx.rgb_split	RGB-Versatz/chromatische Aberration	Amount, Angle, Radial, Center X/Y, Red/Blue Balance, Edge Mode, Mix	ein GPU-Pass
hms.fx.glow_bloom	helle Bildteile weich aufleuchten lassen	Threshold, Knee, Radius, Intensity, Tint, Quality, Composite Mode, Mix	Downsample-Kaskade; höchste Stufe nur bei Budget
hms.fx.edge_emboss	Edge Detect, Outline und Emboss	Mode, Strength, Radius, Threshold, Direction, Color, Background, Mix	ein bis zwei GPU-Pässe
hms.fx.vignette	Randabdunklung/-färbung	Amount, Radius, Softness, Roundness, Center X/Y, Color, Invert, Mix	ein GPU-Pass
hms.fx.strobe_pulse	zeitgesteuertes Blinken/Pulsieren	Rate, Duty, Attack, Release, Phase, Sync Mode, Minimum Level, Mix	Projektweiter Safety-Lock; oberhalb der sicheren Voreinstellung nur nach expliziter Freigabe, nie durch DMX allein freischaltbar
hms.fx.feedback_trails	Feedback, Echo und Bewegungsspuren	Decay, Zoom, Rotation, Offset X/Y, Hue Shift, Blend, Clear	eigener Double Buffer; interne Auflösung adaptiv; Clear als flankenbasierter Trigger

Transform2D ergänzt den festen Layer-Transform: Der feste Transform bestimmt die grundlegende Platzierung; zusätzliche Transformeffekte können an jeder Stelle der Kette stehen. Dadurch sind beispielsweise „skalieren → spiegeln → verzerren → erneut platzieren“ möglich.

15.3 Bedien- und Presetpflichten

• Effektbrowser mit Suche, Kategorien Color, Blur, Distort, Stylize, Transform, Temporal und Favoriten;
• Effekt per Drag-and-drop oder Suchdialog in einen freien Slot beziehungsweise eine Adjustment-/Master-Kette einfügen;
• Live-Preview vor dem Commit, ohne den aktiven Output zu verändern;
• Reihenfolge per Drag-and-drop, Copy/Paste zwischen Layern und Reset je Instanz;
• benannte Benutzerpresets speichern, duplizieren, exportieren und fehlertolerant migrieren;
• jeder Effekt besitzt Mix und Blend-Modus; Mix 0 muss den Effekt kostengünstig bypassen;
• Parameterwerte bleiben beim Wechsel der Auto-Qualitätsstufe semantisch identisch;
• Feedback besitzt eine explizite Clear-Funktion und wird beim Projektwechsel kontrolliert geleert;
• Generator- und Effektparameter werden automatisch in Inspector, REST/WebSocket und DMX-Slot-Dokumentation veröffentlicht.

15.4 Abnahme jedes eingebauten Plugins

Für jeden Generator und Filter sind verpflichtend:

• HLSL-Implementierung für D3D11 sowie GLSL/GLES-Varianten gemäß Capability;
• Golden Images bei mindestens drei Parametersätzen;
• zeitabhängige Tests mit festem Seed und festem Frameindex;
• Alpha-/Premultiplication-Test und definierter Farbraum;
• Test für Extremwerte, NaN/Infinity und Auflösung 1 × 1;
• atomarer Bypass-, Preset- und Quality-Wechsel;
• dokumentierte GPU-Zeit bei 1080p und, sofern Tier erlaubt, 4K;
• Layer-, Adjustment-/Group- und Master-Scope-Test;
• P1–P8-/G1–G8-Kanalbelegung im generierten Fixture-Handbuch.

15.5 Nach dem V1-Starterpaket

• Chroma-/Luma-Key und Maskenwerkzeuge;
• LUT-/erweitertes Color Grading;
• Lens-/Fisheye-/Perspective-Distortion;
• Fire, Fluid, Metaballs und komplexe Partikelsysteme;
• Text, Clock und Ticker;
• Audio Spectrum, Waveform und beat-synchronisierte Varianten;
• Motion Detection/Optical Flow;
• Übergangspaket und node-basierter Effekt-Editor.

Jedes eingebaute Plugin dient zugleich als dokumentiertes SDK-Beispiel. Produktnamen anderer Hersteller werden nicht als Plugin-IDs oder Effektbezeichnungen verwendet.

---

16. Art-Net- und Fixture-Konzept

16.1 Netzwerk

• UDP-Port 6454 gemäß Art-Net.
• auswählbare Netzwerkschnittstelle;
• optional an konfigurierte Sender-IP binden;
• ArtPoll empfangen und ArtPollReply senden;
• ArtDMX-Sequenznummer auswerten, soweit vorhanden;
• Universe-Zählweise in UI eindeutig darstellen;
• Empfangstelemetrie pro Universe;
• Paketverlust, Jitter und letzter Empfang sichtbar;
• mehrere Sender nicht stillschweigend zusammenführen.

16.2 Fixture-Strategie

V1 verwendet:

• HMS MediaEngine Master 32ch
• HMS MediaEngine Layer 64ch

Der Patch ist frei konfigurierbar. Ein Layer-Fixture belegt exakt 64 Kanäle. Acht Layer entsprechen damit exakt einem DMX-Universe. Das Master-Fixture liegt separat oder auf einer anderen freien Adresse.

Mehrserver-Patch für ein Lichtpult

• Jeder Server verwendet dieselben Personality-Typen, aber einen eigenen, eindeutigen Universe-Bereich.
• Empfohlene Übertragung ist Art-Net-Unicast an die jeweilige Node-IP; Broadcast bleibt optional für einfache Netze.
• Der Coordinator führt einen zentralen Universe-Plan und markiert Überschneidungen zwischen gepaarten Nodes als Blocker vor dem Show-Lock.
• Ein Patch-Export enthält Node-ID, Art-Net Short Name, IP/Hostname, Net/Sub-Net/Universe, Startadresse, Layernummer und Fixture-Version.
• Jeder Node zeigt live, von welcher Sender-IP und auf welchem Universe Werte eintreffen. Mehrere Sender benötigen eine explizite Merge-/Prioritätsregel.
• Ändert sich eine IP, bleibt der Patch logisch an der Node-ID gebunden; das Pult muss je nach Pultmodell dennoch auf die neue Unicast-Adresse aktualisiert werden.
• Der Mindesttest umfasst ein Lichtpult, zwei Server, je ein Master-Fixture und zusammen mindestens acht Layer-Fixtures ohne Universe-Kollision.

16.3 Master-Fixture 32ch – Entwurf V1

Kanal	Parameter	Auflösung/Verhalten
1–2	Master Intensity	16 Bit
3	Blackout	Trigger/Schalter, höchste Priorität
4	Freeze Output	Schalter
5	Preset Bank	8 Bit
6–7	Preset Index	16 Bit
8	Preset Recall	steigende Flanke, direkter Abruf ohne Cue-GO-Logik
9	Transition Type	Enum
10–11	Transition Duration	16 Bit, konfigurierter Maximalwert
12–13	Global Speed	16 Bit
14–15	BPM	16 Bit
16	Tap Tempo	steigende Flanke
17–21	reserviert für spätere Cue-/Timeline-Erweiterung	im MVP neutral ignorieren
22	Audio Reactive Enable	Schalter
23	Audio Master Gain	8 Bit
24	Automation/AI Enable	nur Freigabe, keine Sicherheitsumgehung
25	Output Test Pattern	Enum
26	Preview Enable	Schalter
27	Global Hue	8 Bit
28	Global Saturation	8 Bit
29	Fallback Preset	8 Bit
30	Release Manual Overrides	Trigger mit Schutzlogik
31–32	reserviert	müssen neutral ignoriert werden

16.4 Layer-Fixture 64ch – Entwurf V1

Kanal	Parameter	Auflösung/Verhalten
1	Layer Enable	Schalter
2–3	Opacity	16 Bit
4	Source Type	Media/Generator/Live/Solid usw.
5	Media Bank	8 Bit
6	Media Folder	8 Bit
7–8	Media/Plugin Index	16 Bit
9	Load/Commit Selection	steigende Flanke
10	Transport	Stop/Play/Pause/Retrigger
11	Loop Mode	Enum
12	Playback Direction/Mode	Enum
13–14	Playback Speed	16 Bit, signed mapping
15–16	Playback Position	16 Bit normalisiert
17–18	In Point	16 Bit normalisiert
19–20	Out Point	16 Bit normalisiert
21	Blend Mode	Enum
22	Transform Mode/Anchor	Enum
23–24	Position X	16 Bit signed
25–26	Position Y	16 Bit signed
27–28	Scale X	16 Bit
29–30	Scale Y	16 Bit
31–32	Rotation	16 Bit
33	Crop Left	8 Bit
34	Crop Right	8 Bit
35	Crop Top	8 Bit
36	Crop Bottom	8 Bit
37	Hue	8 Bit
38	Saturation	8 Bit
39	Brightness	8 Bit
40	Contrast	8 Bit
41	FX1 Enable	Schalter
42	FX1 Plugin Select	8 Bit Show-Registry
43	FX1 Mix	8 Bit
44–51	FX1 Parameter P1–P8	je 8 Bit oder manifestgebundene Paare
52	FX2 Enable	Schalter
53	FX2 Plugin Select	8 Bit Show-Registry
54	FX2 Mix	8 Bit
55–62	FX2 Parameter P1–P8	je 8 Bit oder manifestgebundene Paare
63	Layer Retrigger/Reset	steigende Flanke
64	reserviert	neutral ignorieren

Modusabhängiger Source-Parameterblock 13–20

Die Kanäle 13–20 sind ein stabiler Source-Block mit pultseitigen Modes:

• bei Media: 13–14 Speed, 15–16 Position, 17–18 In Point, 19–20 Out Point wie in der Tabelle;
• bei Generator: acht generische Slots G1 bis G8 oder manifestdefinierte 16-Bit-Paare;
• bei Solid: Farbe/Alpha über definierte G-Slots;
• bei einem späteren Live-/Capture-Plugin: manifestdefinierte Source-Slots mit neutralen Defaults.

Der Fixture-Generator erzeugt für jeden eingebauten Generator einen Mode mit den sprechenden Parameternamen aus Abschnitt 15. Ein Wechsel von Source Type oder Plugin Index interpretiert vorhandene Faderwerte erst nach Load/Commit Selection neu. Pickup/Takeover verhindert Parametersprünge.

16.5 Auswahl- und Ladeverhalten

Änderungen an Bank/Folder/Index erzeugen zunächst nur eine pending selection. Erst eine steigende Flanke auf Load/Commit Selection löst Preload und Umschaltung aus. Optional darf ein konfigurierbarer Auto-Load-Modus mit Debounce angeboten werden. Dadurch lädt ein langsam bewegter Fader nicht dutzende Dateien hintereinander.

16.6 Speed-Mapping

Das genaue signed 16-Bit-Mapping wird dokumentiert und getestet. Vorgabe:

• untere Hälfte: negative Geschwindigkeit bis 0;
• Mittelpunkt: Pause;
• obere Hälfte: positive Geschwindigkeit bis konfiguriert maximal 4×;
• ein definierter, dokumentierter Wert entspricht exakt 1×;
• Totzone um Pause optional;
• fehlerhafte oder nicht unterstützte Reverse-Wiedergabe wird sichtbar gemeldet.

16.7 Fixtures und GDTF

Die Software erzeugt zunächst eine menschenlesbare CSV-/PDF-Kanalliste. Danach folgt ein Generator für GDTF beziehungsweise pultspezifische Personality-Dateien. Generierte Dateien müssen dieselbe Fixture-Schema-Version wie der Server ausweisen.

16.8 Art-Net-Pixel-Ausgabe

Spätere Output-Plugin-Pipeline:

Canvas oder Output Slice
→ Pixel-Mapping
→ GPU-Sampling
→ asynchroner Readback
→ Farb-/Gamma-Korrektur
→ RGB/RGBW-Kanalpackung
→ ArtDMX
→ ArtSync

Pflichtfunktionen:

• RGB, RGBW und wählbare Kanalreihenfolge;
• Start-Universe und Startadresse;
• mehrere Fixtures/Flächen;
• Gamma und Masterdimmer;
• Universe-Rate standardmäßig maximal DMX-kompatibel;
• ArtSync für zusammengehörige Universen;
• kein synchroner GPU-Readback im Renderthread;
• Bandbreitenanzeige und Universe-Zähler.

---

17. Browseroberfläche

17.1 Visuelle Richtung: QLab-inspiriert, funktional eigenständig

Als visuelle Referenz wurden die offiziellen QLab-5-Abbildungen des Workspace, der Cue-Liste, des Inspectors, der Seitenleiste mit aktiven Cues und des Cue-Carts geprüft. Übernommen werden ausschließlich allgemeine Gestaltungsprinzipien:

• dunkle, neutrale Desktop-Arbeitsoberfläche;
• hohe Informationsdichte statt großer Dashboard-Karten;
• klare horizontale Tabellenzeilen, dünne Trennlinien und kompakte Werkzeugleisten;
• ein großer zentraler Arbeitsbereich mit andockbaren, größenveränderbaren Randbereichen;
• ein kontextabhängiger Inspector im unteren Bereich;
• eine schmale rechte Status-/Aktiv-Seitenleiste;
• sparsame Statusfarben und eine deutliche Auswahlfarbe;
• zeitkritische Angaben in tabellarisch ausgerichteter Monospace-Schrift.

Nicht übernommen werden QLab-Logo, Icons, exakte Farben, Bildassets, Bezeichnungen, Layoutmaße oder Code. Der MVP besitzt ausdrücklich keinen GO-Button, keine Standby-Anzeige, keine Cue-Carts und keine QLab-Cue-Logik. Es wird auch kein funktionsloser GO-Platzhalter angezeigt.

17.2 MVP-Workspace

Bereich	Inhalt und Verhalten
obere Statusleiste	Produkt-/Projektname, lokaler Node beziehungsweise aktive Servergruppe, Outputstatus, Quality: Auto, FPS, Art-Net und Clock/Sync als kleine Zustandsanzeigen
linke Werkzeugleiste	einklappbare Symbole für Mixer, Media, Effekte, Presets, Outputs, Netzwerk, Plugins und Diagnostics; Textlabels optional
mittlerer Arbeitsbereich	standardmäßig dichte Layer-Tabelle oder der jeweilige Editor; keine card-basierte Startseite
unterer Inspector	kontextabhängige Tabs für ausgewählten Layer, Source, Transform, Color, FX, DMX und Advanced; vertikal skalier- und vollständig einklappbar
rechte Seitenleiste	umschaltbar zwischen Active Layers, Media Banks, Nodes und Alerts; aktive Einträge zeigen Fortschritt, Status und direkte sichere Aktionen
Fußleiste	Setup/Live-Lock, Anzahl/Selektion, Warnungszähler, Netzwerkstatus sowie Schalter für Inspector/Seitenleisten

Alle Paneele lassen sich per Divider vergrößern, verkleinern oder einklappen. Die Anordnung wird pro Browser/Bedienplatz gespeichert, die Showdaten bleiben davon getrennt.

17.3 Layer-Tabelle statt Kartenwand

Die primäre Mixeransicht verwendet eine kompakte Tabelle. Pflichtspalten:

Spalte	Inhalt
Status	aktiv, pausiert, vorgeladen, Warnung, Fehler oder offline
Layer	Z-Reihenfolge und editierbarer Name
Typ	Media, Generator, Adjustment oder Group
Source	Clip-/Generatorname und Bank/Index
Target	lokaler Node, Servergruppe, Output oder Composition-Gruppe
Time	Position/Dauer beziehungsweise Generatorphase
Opacity	Wert plus schmaler Fader
Blend	aktueller Blend-Modus
FX	zwei Slots mit Bypass-/Fehlerstatus
Control	Web, Art-Net, Timeline/Automation und aktueller Owner

Selektierte Zeilen erhalten eine klare, eigenständige Akzentfläche; laufende Zustände werden nicht durch großflächig blinkende Farben dargestellt. Zeilenhöhe im Desktop-Density-Modus: ungefähr 28–32 px. Mindestens acht Layer müssen bei 1440 × 900 zusammen mit einem nutzbaren Inspector sichtbar sein.

17.4 Inspector

• Tabs und Felder ändern sich nach Objekttyp, behalten aber feste Positionen für gemeinsame Parameter.
• Zahlenfelder erlauben Tippen, Ziehen und Feinsteuerung per Tastatur.
• Zeitwerte, 16-Bit-DMX-Werte und Positionen sind numerisch präzise editierbar.
• Jeder Parameter zeigt bei Bedarf Automation/Art-Net-Ownership und einen Release-Befehl.
• Pluginparameter werden aus dem manifestierten UI-Schema erzeugt, sehen aber wie native Controls aus.
• Änderungen mit Renderwirkung werden serverseitig bestätigt; Fehler erscheinen direkt am Feld und zusätzlich in Alerts.

17.5 Rechte Seitenleiste und Mehrserver-Ansicht

Active Layers zeigt nur tatsächlich laufende oder vorgeladene Layer mit Thumbnail, Position, Node, Pause/Stop und Fehlerstatus. Nodes zeigt je Server:

• Anzeigename, online/degraded/offline und Rolle;
• Output-Miniaturen beziehungsweise bewusst deaktiviertes Preview;
• Projekt-/Content-Revision und Übertragungsfortschritt;
• Clock-Offset/Drift und letzter synchroner Start;
• FPS, p95-Framezeit, Dropped Frames, GPU-/Speicherbudget;
• Art-Net-Sender, Paketrate und Universe-Bereich;
• Pairing-, Preflight- und Show-Lock-Status.

Ein Filter oben im Workspace bestimmt das aktuelle Ziel: Local, All, Servergruppe, einzelner Node oder Output. Gruppenänderungen zeigen vor dem Commit, welche Nodes sie erhalten.

17.6 Eigene Design-Tokens

Ausgangswerte, die im Designsystem zentral definiert und später thematisierbar sind:

• Flächen: fast schwarzes Anthrazit, zwei abgestufte Panelgraus und eine leicht hellere Hoverfläche;
• Text: helles Neutralgrau, gedämpftes Sekundärgrau, hoher Kontrast für wichtige Werte;
• Akzent: eigenes kühles Blau für Selektion/Fokus;
• Zustände: zurückhaltendes Grün, Gelb, Orange und Rot ausschließlich für betriebliche Bedeutung;
• Abstände: 4-/8-px-Raster;
• Radien: überwiegend 2–4 px, keine übermäßigen Pillen oder schwebenden Karten;
• Typografie: System-Sans beziehungsweise Inter-kompatibel; tabellarische Monospace-Ziffern für Zeit, DMX, FPS und Sync;
• Animationen: 100–180 ms für Paneele/Focus; keine dekorativen Animationen während Live.

Status darf nie allein durch Farbe vermittelt werden; Icon, Text oder Muster ergänzen die Bedeutung.

17.7 Betriebsmodi und Tastatur

• Setup: Struktur, Patch, Plugins, Outputs und Netzwerk dürfen geändert werden.
• Live: strukturelle Änderungen sind gesperrt; Layerparameter, Presetabruf und ausdrücklich freigegebene Livefunktionen bleiben nutzbar.
• Blackout/Freeze bleiben dauerhaft erreichbar, erhalten aber eine eigene Form und Schutzlogik statt QLab-Transportbuttons zu kopieren.
• Die Leertaste hat im MVP keine globale GO-Funktion. Tastenkürzel sind konfigurierbar und werden in Eingabefeldern nie abgefangen.
• Pfeiltasten navigieren Tabellen; Enter öffnet den Inspector; Escape beendet einen Editiervorgang, löst jedoch keinen Blackout aus.
• Destruktive Aktionen benötigen Bestätigung. Projektaktivierung zeigt Ziel-Nodes und Preflight-Ergebnis.

17.8 Preview

• Preview ist vom Operator-Output getrennt.
• Ziel: maximal 720p, standardmäßig 10–15 FPS.
• Hardwareencoding bevorzugt.
• Deaktivierbar und erste Stufe der automatischen Leistungsreduktion.
• Eine langsame Browserverbindung darf den Renderer nicht bremsen.
• Für Mapping darf ein höherwertiger lokaler Previewmodus existieren.

17.9 Netzwerk und Bedienerzugriff

• Der Einrichtungsdialog bietet Nur dieser Rechner und Show-LAN; keine unbemerkte Freigabe ins LAN.
• Im Show-LAN wird genau eine ausgewählte Schnittstelle gebunden und mDNS-Discovery aktiviert.
• Beim ersten Aktivieren wird ein Zugangstoken beziehungsweise Passwort eingerichtet; Node-Paarung ist davon getrennt.
• WebSocket und REST verwenden dieselbe Authentisierung; CORS ist restriktiv.
• Mehrere Browserclients erhalten denselben autoritativen Zustand.
• Zustandsänderungen werden serverseitig bestätigt; reine optimistic UI genügt nicht.

17.10 Visuelle Abnahme

Playwright erzeugt stabile Referenz-Screenshots für 1366 × 768, 1440 × 900, 1920 × 1080 und ein Tabletprofil. Abnahmekriterien:

• kein horizontaler Gesamtseiten-Scroll im Desktopprofil;
• Layer-Tabelle, Inspector und rechte Seitenleiste bleiben per Tastatur erreichbar;
• acht Layer sind bei 1440 × 900 ohne Überlagerung bedienbar;
• Zustände active, paused, preloaded, warning, error, offline und out_of_sync sind eindeutig unterscheidbar;
• lange Medien-/Node-Namen werden gekürzt, sind aber per Tooltip/Detailansicht vollständig lesbar;
• Layout bleibt bei 125 % und 150 % Browserzoom nutzbar;
• Preview-Ausfall verändert weder Layout noch Showoutput;
• helle, card-lastige oder marketingartige Dashboard-Varianten bestehen die Designabnahme nicht.

17.11 Spätere QLab-ähnliche Fähigkeiten

Erst in einer ausdrücklich später freigegebenen Produktphase darf ein optionaler Cue Workspace hinzukommen: Cue-Liste, Standby, GO, aktive Cues, Cue-Carts und Timeline. Diese Funktionen nutzen dann dieselbe Parameter-, Projekt-, Netzwerk- und Inspector-Infrastruktur, bleiben aber ein separates Modul und verändern den MVP-Workspace nicht.

---

18. Presets/Szenen und spätere Cue-Erweiterung

18.1 Preset/Szene im MVP

Eine Szene enthält entweder:

• vollständigen Composition-Snapshot; oder
• sparsamen Parameter-Diff gegenüber einem Basissnapshot.

Die Implementierung muss eindeutig festlegen, welche Variante gespeichert wird. Empfehlung: intern normalisierter Snapshot mit deduplizierten Asset-/Pluginreferenzen; für Übergänge wird zur Laufzeit ein Diff berechnet.

Im MVP wird ein Preset direkt aus Browser, Art-Net oder API geladen. Es gibt noch keinen Playhead, kein Standby und keinen GO-Ablauf.

18.2 Cue nach dem MVP

Das spätere optionale Cue-Modul referenziert:

• Zielszene;
• Übergangstyp;
• Dauer;
• Preloadzeit;
• Quantisierung optional;
• Follow-Zeit optional;
• Trigger-ID;
• Notizen.

18.3 Preset-Übergänge V1

• Cut
• Crossfade
• Dip to Black
• Wipe horizontal/vertical
• Luma Fade
• Plugin Transition

Ein Übergang darf beim Laden eines Mediums nicht auf einen schwarzen, noch nicht bereiten Decoder umschalten. Bei nicht bestandenem Preload gilt die konfigurierte Policy: warten, altes Bild halten oder definierter Fallback.

---

19. Timeline

Die Timeline ist ausdrücklich ein Modul nach dem MVP. Sie wird architektonisch vorbereitet und nutzt später dieselbe Parameter-Engine wie Livebetrieb und DMX; im ersten Workspace wird kein funktionsloser Timeline- oder GO-Bereich eingeblendet.

19.1 Tracktypen

• Media Track
• Generator Track
• Effect Track
• Parameter Automation Track
• Scene/Cue Track
• Master Track
• Audio Track
• Marker/Trigger Track
• später Timecode-/External-Control-Track

19.2 Timeline-Funktionen

• Play, Pause, Stop, Scrub;
• In/Out und Loop;
• Zoom und Snap;
• Clips verschieben, trimmen und duplizieren;
• Keyframes;
• Interpolation: Step, Linear, Smooth/Cubic, Bezier;
• Marker und benannte Abschnitte;
• Zeitbasis Sekunden und SMPTE;
• optionale musikalische Zeitbasis BPM/Takte/Beats;
• externe Synchronisation später über ArtTimeCode beziehungsweise weitere Timecode-Adapter;
• Undo/Redo;
• Autosave.

19.3 Echtzeitmodell

• Timelinezeit basiert auf monotonic clock beziehungsweise externer Zeitquelle.
• Der Renderer erhält pro Frame deterministisch ausgewertete Werte.
• Scrubbing verwendet einen separaten Preview-/Seekpfad und darf den Liveoutput nur im ausdrücklich aktivierten Edit-Live-Modus verändern.
• DMX oder Browser kann Parameter temporär übernehmen; nach Release übernimmt die Timeline anhand definierter Pickup-/Return-Regel.

19.4 Datenmodell

Timeline
 ├─ timebase
 ├─ duration
 ├─ loop_range
 └─ tracks[]
     ├─ target_parameter_path oder layer_id
     ├─ clips[]
     └─ keyframes[]

Keyframes referenzieren stabile Parameterpfade, nicht UI-Komponenten.

---

20. Audioanalyse und Sound-to-Light

Audio-Reaktivität muss ohne KI vollständig funktionieren. KI ist später eine zusätzliche Planungsebene, niemals Voraussetzung für Beat- oder Pegelsteuerung.

20.1 Audioeingänge

• Windows WASAPI beziehungsweise plattformneutral über GStreamer;
• physischer Eingang;
• Loopback/Systemaudio optional;
• Audiospur eines Videos;
• Netzwerkquelle später;
• Testsignalgenerator.

20.2 Analysefeatures

• Peak und RMS;
• geglättete Lautheit;
• FFT-Spektrum;
• konfigurierbare Frequenzbänder;
• Bass, Low-Mid, Mid, High-Mid, Treble;
• Spectral Flux/Onset;
• Beat-Trigger;
• BPM-Schätzung;
• Beat-Phase und Confidence;
• Stilleerkennung;
• später musikalische Abschnittserkennung offline.

20.3 Laufzeit

• Audioaufnahme in eigenem Echtzeitpfad;
• Analyse beispielsweise 50–100 Mal pro Sekunde;
• Feature-Snapshots timestamped;
• kein LLM und keine Cloudanfrage im Audiothread;
• Ringbuffer statt unkontrollierter Queues;
• Latenz und Dropouts sichtbar.

20.4 Mapping Engine

Jedes Audiofeature kann über ein Binding auf einen Parameter wirken:

Audiofeature
→ Gate/Threshold
→ Normalisierung
→ Gain
→ Kurve
→ Attack/Release
→ Min/Max
→ optional Quantisierung
→ Zielparameter

Beispiele:

• Bass steuert Blur Radius.
• Beat triggert einen Chaser-Step.
• Treble steuert Partikeldichte.
• RMS steuert Layer-Opacity.
• Beat-Phase steuert Gradient-Position.

Bindings sind speicherbar, aktivierbar, priorisierbar und in der UI live sichtbar.

20.5 Modulatoren ohne Audio

• LFO Sine/Triangle/Saw/Square;
• Random mit Seed;
• Envelope;
• Step Sequencer;
• BPM-synchroner Chaser;
• mathematische Kombination mehrerer Quellen.

---

21. KI- und Automationsfähigkeit

21.1 Grundsatz

Eine KI greift niemals direkt auf:

• GPU-/Rendererobjekte;
• GStreamer-Pipelines;
• SQLite;
• Projektdateien;
• Art-Net-Sockets;
• Plugin-Dateien

zu. Sie nutzt ausschließlich das versionierte Automation/Command Gateway.

21.2 KI-Tool-API

Spätere Tools:

• get_system_capabilities
• list_projects
• get_active_show_state
• list_layers
• list_media
• list_plugins
• get_parameter_schema
• preview_command_plan
• set_parameter
• apply_scene
• create_scene
• create_timeline_draft
• bind_audio_feature
• start_timeline
• stop_timeline
• release_override
• get_diagnostics

Jeder schreibende KI-Command besitzt:

• Request-ID;
• Actor/Provider/Model;
• erlaubten Scope;
• Dry-run-Möglichkeit;
• erwartete Zustandsrevision;
• Wertevalidierung;
• Rate-Limit;
• Audit-Eintrag;
• optional Bedienerfreigabe;
• Rollback- beziehungsweise Undo-Information.

21.3 KI-Priorität

KI arbeitet standardmäßig mit der niedrigsten aktiven Priorität. Manuelle Bedienung, Lichtpult, Timeline und Sicherheitsfunktionen können KI-Werte jederzeit überstimmen.

21.4 Sinnvolle KI-Funktionen

Offline/Programmierbetrieb

• Medien automatisch taggen;
• Musikdatei analysieren und Abschnitte markieren;
• Timeline-Entwurf aus Songstruktur erzeugen;
• passende Generatoren und Farbpaletten vorschlagen;
• Effektketten erstellen;
• DMX-/Audio-Bindings vorschlagen;
• Belastung anhand der Hardware abschätzen;
• Show auf fehlende Medien oder Plugins prüfen.

Livebetrieb

• zwischen vorher freigegebenen Szenen wählen;
• Effektintensität langsam an Stimmung/Energie anpassen;
• bei erkannten Musikabschnitten Automation-Presets wechseln;
• Diagnose erklären und einen sicheren Fallback vorschlagen.

Ein LLM darf nicht im Frame-, Audio- oder Art-Net-Echtzeitpfad liegen. Live-KI entscheidet höchstens auf einer langsamen Steuerungsebene; die deterministische Engine führt aus.

21.5 Provider-Abstraktion

• lokaler Provider;
• OpenAI-kompatible API;
• Ollama-kompatibler Provider;
• deaktivierter Offline-Modus;
• keine Providerlogik im Domänenmodell.

Secrets werden nicht in Projektdateien exportiert.

---

22. Multi-Display, Mapping und Edge-Blending

22.1 Architektur

Das System rendert zunächst eine virtuelle Master-Canvas. Physische Ausgänge erhalten Ausschnitte dieser Canvas.

Master Canvas
 ├─ Output Slice A → Warp → Edge Mask → Color → Display 1
 ├─ Output Slice B → Warp → Edge Mask → Color → Display 2
 └─ Pixel Map C    → Sampling → Art-Net

Diese Trennung muss bereits im Datenmodell von V1 existieren, auch wenn der vollständige Mapping-Editor später folgt.

22.2 Output-Slice

• frei wählbares Quellrechteck auf Master-Canvas;
• Zielauflösung und Refresh Rate;
• Position/Rotation/Flip;
• Overscan;
• Testbilder;
• Displayzuordnung;
• Aktiv/Standby;
• Fallback bei Displayverlust.

22.3 Warping

• initial 4-Corner-Keystone;
• danach Mesh-Warp mit konfigurierbarem Raster;
• Punkte verschieben und numerisch editieren;
• Preview-/Edit-Modus getrennt von Live;
• Mapping-Presets;
• Undo/Redo;
• GPU-Vertex- beziehungsweise Mesh-Verarbeitung.

22.4 Edge-Blending

• unabhängig für links/rechts/oben/unten;
• Blendbreite;
• Gamma/Exponent;
• Black-Level-Kompensation;
• Helligkeits- und Farbkorrektur je Output;
• Testpattern für Überlappung;
• Maskentextur optional;
• atomare Aktivierung vorbereiteter Änderungen.

22.5 Synchronisation

• Ausgänge derselben GPU verwenden denselben Renderclock und Frame-Snapshot.
• Mehrere GPUs sind in V1 nicht freigegeben.
• Exakte Synchronität über mehrere Rechner erfordert später externen Sync/Genlock/Framelock beziehungsweise klar spezifizierte Softwaregrenzen.
• ArtSync synchronisiert Art-Net-Daten, nicht physische HDMI-Refreshzyklen.

22.6 Verteilte Render-Nodes

Discovery, Paarung, gemeinsame Bedienung, Content-/Project-Sync und zeitgestempelte Starts gehören zur V1-Netzwerkbasis. Eine über mehrere Rechner aufgespannte gemeinsame Canvas ist dagegen eine spätere Mapping-Ausbaustufe.

Pflichtregeln für diese spätere Ausbaustufe:

• jedes OutputSurface bleibt fest einer node_id und einem physischen Display zugeordnet;
• Coordinator verteilt nur Showzustand, Medien und Zeitkommandos, keine fertigen Videoframes;
• alle Nodes bestätigen Preload und Renderfähigkeit vor Aktivierung;
• Software-Cue-Sync und physischer Scanout-/Genlock-Status werden getrennt angezeigt;
• ein Output darf nicht automatisch auf einen anderen Node springen, solange dessen Display-/Farb-/Warp-Profil nicht ausdrücklich kompatibel ist;
• für projektorübergreifendes Edge-Blending über mehrere Rechner ist geeignete Genlock-/Framelock-Hardware ein eigenes Capability- und Abnahmeprofil.

---

23. API-Konzept

23.1 REST

REST ist für Ressourcen und nicht hochfrequente Aktionen vorgesehen:

GET    /api/v1/system/capabilities
GET    /api/v1/system/health
GET    /api/v1/projects
POST   /api/v1/projects
GET    /api/v1/projects/{id}
PUT    /api/v1/projects/{id}
POST   /api/v1/projects/{id}/activate
POST   /api/v1/media/import
GET    /api/v1/media
GET    /api/v1/plugins
POST   /api/v1/plugins/install
POST   /api/v1/plugins/{id}/enable
GET    /api/v1/artnet/status
PUT    /api/v1/artnet/patch
GET    /api/v1/cluster/nodes
POST   /api/v1/cluster/nodes/{id}/pair
GET    /api/v1/cluster/groups
PUT    /api/v1/cluster/groups/{id}
POST   /api/v1/cluster/preflight
POST   /api/v1/cluster/sync/content
POST   /api/v1/cluster/revisions/{revision}/activate
GET    /api/v1/diagnostics

23.2 Commands

Zustandsänderungen mit Showwirkung laufen über versionierte Commands:

{
  "command_id": "uuid",
  "type": "parameter.set",
  "expected_revision": 120,
  "actor": {"type": "web", "id": "operator-session"},
  "target": {"type": "server_group", "id": "uuid"},
  "execute_at_show_time_ns": null,
  "payload": {
    "parameter_path": "composition/.../opacity",
    "value": 0.75,
    "ownership": "temporary"
  }
}

23.3 WebSocket

Kanäle beziehungsweise Eventtypen:

• State Snapshot/Delta;
• Parameter Updates;
• Playback Position;
• Audio Features, gedrosselt;
• Art-Net Status;
• Node Discovery/Pairing;
• Cluster Health, Clock Offset und Revisionen;
• Content-Sync-Fortschritt und Preflight;
• Renderer Telemetry;
• Plugin Status;
• Jobs/Imports;
• Alerts;
• Command Acks/Errors.

Der Server begrenzt Frequenz und Payload. Hochfrequente Telemetrie wird gebündelt. Kein Client bekommt unkontrolliert jeden internen Framezustand.

23.4 Fehlerformat

{
  "error": {
    "code": "PLUGIN_SHADER_COMPILE_FAILED",
    "message": "Gaussian Blur konnte nicht geladen werden.",
    "details": {},
    "correlation_id": "uuid",
    "recoverable": true,
    "suggested_action": "bypass_plugin"
  }
}

Interne Stacktraces werden geloggt, aber nicht ungefiltert an LAN-Clients ausgegeben.

---

24. Persistenz, Projekte und Migrationen

24.1 SQLite

• WAL-Modus;
• Foreign Keys aktiv;
• kurze Transaktionen;
• keine Datenbankoperation im Renderthread;
• automatisches Backup vor Migration;
• Integritätscheck beim Start nach unsauberem Shutdown.

24.2 Trennung

• SQLite speichert Index, Einstellungen, Pluginstatus und Projektmetadaten.
• Große Medien liegen als Dateien.
• Projekt-Export kann ein portables Projektpaket erzeugen.
• Livezustand und dauerhafter Projektzustand werden getrennt behandelt.

24.3 Autosave und Recovery

• transaktionales Autosave;
• Recovery-Journal für nicht gespeicherte Bedienänderungen;
• letzte stabile Projektversion erhalten;
• keine direkte Überschreibung ohne temporäre Datei und atomaren Replace;
• Crash-Recovery-Dialog beim nächsten Start.

24.4 Migrationen

Jede Schemaänderung benötigt:

• Vorwärtsmigration;
• Test mit Projekt einer vorherigen Version;
• Backup;
• dokumentierte Nicht-Rückwärtskompatibilität;
• aktualisierte schema_version;
• Fixture-/Plugin-Kompatibilitätsprüfung.

---

25. Performance- und Echtzeitanforderungen

25.1 Desktop-Abnahmelast

Auf definierter Referenzhardware für DESKTOP_FULL:

• Master-Canvas 3840 × 2160 @ 60 Hz;
• acht 1920 × 1080 @ 60 Hz Medienquellen;
• normale Blend- und Transformoperationen;
• mindestens vier einfache Effektinstanzen und ein Blur in mittlerer Qualität;
• ein Hauptausgang und ein reduzierter Previewstream;
• Art-Net-Steuerung aktiv.

Ziele:

• Framezeit p99 innerhalb des 16,67-ms-Budgets;
• keine sichtbare Blockade beim Medienimport;
• DMX-zu-sichtbarem-Frame p95 höchstens zwei Frames;
• Browsercommand p95 bis bestätigte Zustandsübernahme höchstens 100 ms im LAN;
• mindestens vier Stunden Soak-Test ohne Speicherwachstum oder Prozessabbruch;
• verworfene Frames werden erfasst und im Testreport ausgewiesen.

Diese Werte sind ein Abnahmeziel und keine Behauptung für beliebige Codecs oder GPUs. Phase 0 und die spätere Performance-Matrix bestimmen die konkrete Referenzhardware.

25.2 Windows-Mini-PC-Abnahmelast (DESKTOP_LITE)

Auf einer fest dokumentierten Referenzplattform mit schneller integrierter GPU, 32 GB Dual-Channel-RAM, NVMe und aktuellem Treiber:

• 1920 × 1080 @ 60 Hz Master;
• vier hardwaredecodierbare 1080p-Quellen mit definiertem H.264-/H.265-Testmaterial;
• zwei einfache Effekte und ein Blur mit Quality: Auto;
• ein physischer Ausgang und ein adaptives Browserpreview;
• Art-Net, Web-UI und Cluster-Heartbeat aktiv;
• mindestens vier Stunden Soak-Test.

Ziele:

• D3D11Memory bleibt vom Decoder durch Composite/FX bis zur Ausgabe nachgewiesen GPU-resident;
• p99-Framezeit liegt nach Einregelung innerhalb 16,67 ms;
• Ausgangsauflösung, Refresh Rate, aktive Layer und Parametersemantik ändern sich während Adaptive Quality nicht;
• ein künstlicher Lastsprung wird zunächst durch Preview-/interne Qualitätsreduktion abgefangen;
• Qualitätsstufen oszillieren nicht und werden nach längerer Reserve schrittweise wieder erhöht;
• kein sichtbarer Shader-Kompilierungsruckler, da alle Varianten vor Aktivierung kompiliert sind.

25.3 Raspberry-Pi-Abnahmelast

• 1920 × 1080 @ 60 Hz;
• zwei hardwaredecodierbare Quellen oder eine Quelle plus Generator;
• mindestens ein einfacher Filter;
• ein Ausgang;
• Browserbedienung und Art-Net aktiv;
• zweistündiger Soak-Test.

25.4 Budgetierung

Telemetrie muss Zeit und Speicher je Stufe ausweisen:

• Decode;
• Upload/Interop;
• Effektpässe;
• Compositing;
• Output-Mapping;
• Preview;
• GPU-/VRAM-Nutzung;
• CPU je Prozess.
• aktuell gewählte Adaptive-Quality-Stufe und Grund jeder Änderung;
• Hardware-Fingerprint und Ergebnisse des letzten Capability-Selbsttests.

25.5 Schutzmaßnahmen

• maximale Layerzahl je Capability-Tier;
• VRAM-Schätzung vor Aktivierung;
• Effekt-Qualitätsstufen;
• Warnung vor zu hoher Renderlast;
• Preload-Budget;
• begrenzte Queuegrößen;
• Backpressure;
• kein unbeschränktes Caching;
• kein stilles Entfernen von Effekten zur Lastreduktion.
• Hysterese und Mindesthaltezeit je Qualitätsstufe;
• harte Untergrenze je Plugin und Output;
• Preflight-Warnung, bevor eine Show die gemessenen Decoder-/Speicherbudgets überschreitet;
• automatische Änderungen nur an manifestierten, vorab getesteten Qualitätsvarianten.

---

26. Betriebs- und Ausfallsicherheit

26.1 Fail-Safe-Verhalten

Konfigurierbare Renderer-Policy bei Fehlern:

• letztes gültiges Bild halten;
• definierte Fallback-Szene;
• Fade to Black;
• sofort Blackout nur für explizite Sicherheitsfälle.

26.2 Watchdog

• Supervisor überwacht Control Core und Renderer getrennt.
• Renderer sendet Frame-/Heartbeatstatus.
• Control Core darf neu starten, ohne den Output sofort zu verlieren.
• Renderer-Neustart lädt den letzten autoritativen Snapshot.
• Crashloop-Erkennung verhindert endlose Neustarts.
• Fehler bleibt in der UI und im Log sichtbar.

26.3 Show Lock

Ein aktivierbarer Show-Lock verhindert:

• Plugininstallation/-update;
• Schema-/Datenmigration;
• Display-Neuzuordnung;
• Medienverschiebung;
• kritische Konfigurationsänderungen;
• automatische Softwareupdates.

26.4 Shutdown

• laufende Writes abschließen;
• Projektzustand sichern;
• Output kontrolliert auf Fallback oder Black setzen;
• Worker mit Timeout beenden;
• bei Zwangsbeendigung Recovery-Markierung setzen.

---

27. Sicherheit

27.1 Netzwerk

• Default-Bind nur 127.0.0.1;
• LAN-Modus explizit;
• Token/Passwort;
• Rate Limits;
• restriktives CORS;
• keine Debug-Endpunkte im Release;
• WebSocket-Authentisierung;
• Art-Net-Empfang auf wählbarer Schnittstelle und optional Sender-Allowlist.
• Discovery-Nachrichten enthalten keine Tokens oder Secrets.
• Node-Paarung prüft eine kurzlebige PIN beziehungsweise einen sichtbaren Zertifikats-Fingerprint.
• Nach Paarung verwendet Coordinator↔Node gegenseitig authentisierte, widerrufbare Identitäten mit getrennten Scopes für Lesen, Steuern, Content-Sync und Administration.
• Ein gefundener, aber ungepaarter Node darf ausschließlich minimale Discovery-/Pairing-Informationen liefern.

27.2 Dateien und Plugins

• Schutz vor Path Traversal;
• ZIP-Bomb-Limits;
• Dateigrößenlimits;
• MIME/Signaturprüfung soweit sinnvoll;
• keine Ausführung hochgeladener nativer Binärdateien;
• Plugins nur in vorgesehenem Verzeichnis;
• Pluginquarantäne;
• Hash und Herkunft speichern.

27.3 KI

• Scopes und Allowlist;
• kein Secretzugriff;
• keine Roh-Shell;
• keine direkten Dateipfade als freie KI-Aktion;
• Dry-run und Bestätigung für riskante Aktionen;
• Auditlog;
• Abschaltknopf;
• KI ist im Show-Lock standardmäßig eingeschränkt.

---

28. Beobachtbarkeit und Diagnose

28.1 Logs

• strukturierte JSON-Logs intern;
• menschenlesbare Rollings Logs zusätzlich oder per Viewer;
• Korrelations-ID über Web, Control Core und Renderer;
• Logrotation nach Größe und Anzahl;
• keine Secrets;
• Export eines Diagnosepakets.

28.2 Metriken

• Output FPS;
• Renderframe p50/p95/p99;
• Dropped/Duplicated Frames;
• Decoder pro Layer;
• CPU/RAM/GPU/VRAM soweit verfügbar;
• Queuefüllstände;
• Art-Net Paketrate/Jitter/Timeouts;
• WebSocketclients;
• Audiopegel/Dropouts;
• Pluginfehler;
• Previewlast.
• Renderbackend, GPU-Memory-Typ und unerwartete Copy-/Interop-Stufen;
• Adaptive-Quality-Stufe, Wechselgrund und Wechselhäufigkeit;
• Node-/Coordinator-Heartbeat, Clock-Offset/Drift und Cue-Startabweichung;
• Projekt-/Content-Revision, fehlende Hashes und Sync-Fortschritt je Node;
• Universe-Überschneidungen und Art-Net-Sender je Node.

28.3 Diagnosepaket

Exportiert nach Nutzerfreigabe:

• Versionsinformationen;
• Hardware-/Treiberübersicht;
• Capability-Ergebnis;
• bereinigte Konfiguration;
• Logs;
• Pluginliste;
• letzter Test-/Healthstatus;
• keine Medieninhalte und keine Secrets.

---

29. Teststrategie und Quality Gates

29.1 Unit Tests

• Parameterkonvertierung und Clamping;
• 8-/16-Bit-DMX-Mapping;
• signed Speed-Mapping;
• Triggerflanken;
• Ownership/HTP/LTP;
• Timelineinterpolation;
• Schema- und Projektmigrationen;
• Pluginmanifestvalidierung;
• Pfadsicherheit;
• Audio-Mappingkurven;
• Command-Idempotenz.
• Adaptive-Quality-Hysterese, Prioritätsleiter und unveränderliche Schutzparameter;
• Discovery-Registry, Node-ID-Duplikate und manuelle Fallback-Adressen;
• Contentmanifest-/Chunk-Hashes und atomare Revision;
• Cluster-Command-Idempotenz und Showzeit→lokale-Monotonic-Abbildung.

29.2 Integrationstests

• Control Core ↔ Renderer Handshake;
• Snapshot/Delta/Reconnect;
• GStreamer-Pipeline mit Testvideo;
• Hardwaredecodererkennung;
• Shader Load/Bypass;
• Medienpreload und atomarer Wechsel;
• Art-Net-Empfang mehrerer Universen;
• WebSocket State Sync;
• Projekt speichern/laden;
• Timeline + DMX Override;
• Audiofeature → Parameter → Renderer.
• mDNS-Discovery sowie manuelles Hinzufügen über mindestens zwei Nodes;
• Pairing, Zertifikats-/Tokenwiderruf und Reconnect;
• Content-/Project-Sync mit Abbruch, Resume, Hashfehler und atomarer Aktivierung;
• Preload/Arm/Execute/Ack eines zeitgestempelten Gruppen-Commands;
• ein Lichtpult steuert zwei Art-Net-Nodes über konfliktfreie Universe-Bereiche.

29.3 Renderingstests

• Golden Images pro Generator, Filter und Blend-Modus;
• definierte Auflösung, Seed und Zeit;
• toleranzbasierter Bildvergleich;
• Alpha/Premultiplication;
• Farbkonvertierung;
• Multi-Pass-Effekte;
• Warp-/Edge-Masks;
• Test auf Windows D3D11/HLSL, Linux OpenGL/GLSL und Raspberry Pi OpenGL ES;
• automatischer Test, dass der normale Windows-Testpfad keinen CPU-Readback enthält;
• identische semantische Effektparameter und toleranzbasierter Bildvergleich über Backends;
• atomarer Wechsel aller Adaptive-Quality-Varianten ohne Shader-Stall.

29.4 End-to-End

• Projekt anlegen;
• Medien importieren;
• Layer laden;
• Effekt hinzufügen;
• DMX-Patch setzen;
• Art-Net-Werte simulieren;
• Szene speichern und starten;
• Timeline abspielen;
• Anwendung neu starten und Projekt wiederherstellen.
• zwei Server finden und paaren;
• Projekt/Medien synchronisieren und Preflight bestehen;
• vom Control Center denselben Presetabruf zeitgestempelt auf beiden Nodes auslösen;
• beide Server mit einem Lichtpult getrennt steuern;
• Node-Verlust simulieren und laufenden Output gemäß Policy halten.

29.5 Fehler- und Soak-Tests

• Art-Net-Paketverlust und Senderausfall;
• Browserdisconnect;
• Control-Core-Neustart;
• Rendererabsturz;
• ungültiges Plugin;
• Shaderkompilierungsfehler;
• fehlendes Medium;
• Display-Hotplug;
• volle oder schreibgeschützte Platte;
• vier Stunden Desktop-Soak;
• zwei Stunden Pi-Soak;
• wiederholtes Laden von 1.000 Szenenwechseln.
• Coordinator-Ausfall bei weiterlaufenden Render-Nodes;
• Clock-Drift, Latenzspitzen, Paketumordnung und 1–5 % kontrollierter Cluster-Paketverlust;
• blockiertes mDNS mit erfolgreichem manuellen Fallback;
• Universe-Kollision und doppelte Node-ID;
• wechselnde GPU-Last mit Nachweis, dass Adaptive Quality nicht pumpt.

29.6 Portabilitätstest

Auf einer sauberen Windows-VM beziehungsweise einem sauberen Testrechner:

• kein Python installiert;
• kein Node.js installiert;
• kein GStreamer installiert;
• keine Administratorrechte;
• Anwendung aus beliebigem Pfad und USB-/zweitem Laufwerk starten;
• Browser öffnen;
• Testvideo rendern;
• Art-Net-Testpaket empfangen;
• Projekt speichern und nach Neustart laden.

29.7 CI-Gates

Jeder Merge beziehungsweise Release benötigt:

• Ruff/Lint grün;
• Typprüfung grün;
• Python Unit/Integration grün;
• Frontend Unit grün;
• Frontend Build grün;
• Playwright Kernflow grün;
• Schema-Validierung grün;
• Shader-Compile-Gate grün;
• Dependency-/Lizenzreport;
• portabler Build erfolgreich;
• keine offenen P0-Fehler;
• P1-Fehler explizit bewertet.

GPU-, Display- und Art-Net-Hardwaretests laufen zusätzlich auf dedizierten Testmaschinen und dürfen nicht durch reine Mocks ersetzt werden.

---

30. Build, Release und Updates

30.1 Reproduzierbarkeit

• Python- und Frontend-Lockfiles verpflichtend;
• GStreamer-Version und Pluginmenge exakt manifestieren;
• Shader- und Fixture-Schemaversionen manifestieren;
• Buildnummer und Git-Commit in Diagnoseansicht;
• SBOM und Lizenzverzeichnis erzeugen;
• reproduzierbares Buildskript ohne manuelles Kopieren.

30.2 Windows-Paket

• Onefolder/Standalone;
• Frontend als statische Assets;
• nur benötigte GStreamer-Plugins bündeln;
• Plugin-Scanner-Cache lokal;
• Anwendungspfade beim Start setzen;
• ZIP mit Versionsnummer;
• SHA-256-Prüfsumme;
• optional Code Signing später;
• keine Internetverbindung zum Start erforderlich.

30.3 Linux/Raspberry Pi

• ARM64-Tarball oder Debian-Paket plus portable Projekt-/Pluginstruktur;
• Hardwaretreiber bleiben Bestandteil des Zielbetriebssystems;
• gleiche API und Projektschemata;
• capability-basierte Effektfreigabe;
• kein Fork der Geschäftslogik;
• plattformspezifische Anpassungen nur in Adapterpaketen.

30.4 Updates

• niemals Dateien im laufenden Programm überschreiben;
• Anwendung und Nutzerdaten trennen;
• neues Verzeichnis parallel entpacken;
• Projekt-/DB-Backup;
• Versionskompatibilität prüfen;
• Rollback auf vorherige Programmversion ermöglichen;
• Plugins separat versionieren;
• automatische Updates im Show-Lock deaktiviert.

---

31. Implementierungsphasen

Die Zeitangaben sind grobe Größenordnungen für einen erfahrenen Entwickler mit KI-Unterstützung und echter Testhardware. Sie sind keine Festpreise.

Phase 0 – technischer Spike und Go/No-Go, etwa 2–4 Wochen

Ziel: Kritische Leistungs- und Portabilitätsrisiken vor Produktentwicklung beseitigen.

Umsetzen:

• GPU-/Decoder-/Display-Capabilities automatisch erfassen und Hardware-Fingerprint bilden;
• Testvideo über Windows-D3D11-Hardwaredecoder laden;
• durchgängigen D3D11Memory-Pfad ohne regulären CPU-Readback nachweisen;
• minimalen nativen Renderkern beziehungsweise GStreamer-D3D11-Plugin als belastbaren Effekt-/Compositing-Pfad festlegen;
• zwei Videos über D3D11 auf der GPU mischen;
• einen HLSL-Passthrough-/Effektparameter live ändern;
• denselben semantischen Effektvertrag mit einer GLSL-Testimplementierung validieren;
• drei vorab kompilierte Blur-Qualitätsstufen automatisch und ruckelfrei wechseln;
• Output in randlosem Vollbild auf wählbarem Display;
• ArtDMX empfangen und Opacity innerhalb maximal zwei Frames ändern;
• minimale FastAPI-/WebSocket-Bedienung;
• portable Windows-Onefolder-Ausgabe auf sauberem Rechner testen;
• erste Messwerte für 1080p60 auf Standard-Mini-PC-Hardware und 4K60 auf DESKTOP_FULL;
• GStreamer-/Packaging-Variante per ADR entscheiden.

Gate 0: Kein Weiterbau, wenn D3D11-Hardwaredecoding, GPU-residentes Compositing, ruckelfreie Adaptive-Quality-Varianten, Art-Net-Latenz oder portable Auslieferung nicht reproduzierbar funktionieren.

Phase 1 – Fundament und Netzwerkbasis, etwa 3–5 Wochen

• Repository und CI;
• Supervisor;
• Control Core;
• Rendererprozess;
• versioniertes IPC;
• Capability-Handshake;
• zentrale Parameter-Engine;
• Basislogging und Healthchecks;
• SQLite und Migrationen;
• leere Projektstruktur;
• persistente Node-ID und Rollen;
• mDNS/DNS-SD-Discovery und manuelle Node-Liste;
• sichere Paarung und Node-Vertrauen;
• Coordinator-Registry, Heartbeats und Reconnect;
• Cluster-Nachrichtenhülle mit Idempotenz und Revisionen.

Gate 1: Zwei Server werden automatisch gefunden beziehungsweise manuell eingetragen, sicher gepaart und nach IP-/Prozesswechsel korrekt wiederverbunden; Snapshot, Crash-Recovery und portable Starts bestehen die Tests.

Phase 2 – Medien-, Layer- und Basissync-Engine, etwa 4–8 Wochen

• Master-Canvas;
• acht Layer;
• Video, Bild, Solid und Generator-Grundquelle;
• Playback;
• Opacity, Transform, Crop, Blend-Modi;
• Preload und atomarer Clipwechsel;
• ein bis zwei Outputs;
• Rendertelemetrie;
• Contentmanifest mit SHA-256, resumierbare Übertragung und Staging;
• Project-/State-Snapshot mit monotonen Revisionen;
• Servergruppen und Zielrouting;
• Clock-Offset-/Driftmessung;
• zeitgestempelte, vorgepufferte Presetaktivierung auf zwei Nodes.

Gate 2: Das Mini-PC-Desktopprofil läuft stabil; zwei Nodes erhalten dieselbe geprüfte Projekt-/Content-Revision und starten ein vorbereitetes Preset im verkabelten Referenz-LAN mit p95 höchstens 10 ms auseinander. Medienimport/-sync blockiert keinen Output.

Phase 3 – Plugin-SDK und Effekte, etwa 3–5 Wochen

• Pluginmanifest und Validator;
• Shader-Pluginloader;
• D3D11/HLSL- sowie GL/GLES-Backendadapter;
• Multi-Pass;
• deklarative Adaptive-Quality-Varianten;
• Parameter-UI-Schema;
• Failure Bypass;
• Pluginquarantäne;
• alle zehn Pflichtgeneratoren und vierzehn Pflichtfilter aus Abschnitt 15;
• SDK-Dokumentation und Beispielplugin.

Gate 3: Ein externes Beispielplugin lässt sich ohne Kernänderung installieren und steuern; alle deklarierten Backends kompilieren, und Auto Quality wechselt Varianten ohne Semantik- oder Renderstall.

Phase 4 – Art-Net-Fixtures, etwa 2–4 Wochen

• ArtPoll/ArtPollReply;
• ArtDMX;
• Patchverwaltung;
• zentraler Mehrserver-Universe-Plan und Kollisionsprüfung;
• Master32 und Layer64;
• 16-Bit, Trigger, Ownership und Signalverlust;
• Emulator- und Hardwaretest;
• Kanalliste exportieren.

Gate 4: Ein Lichtpult steuert mindestens zwei Server mit zusammen mindestens acht Layern sowie deren Master-Fixtures stabil; Universe-Kollision, Paketverlust und Failsafe sind getestet.

Phase 5 – vollständige Browser-Liveoberfläche, etwa 4–7 Wochen

• eigenständiges dunkles, QLab-inspiriertes Designsystem;
• dichte Layer-Tabelle statt Karten-Dashboard;
• andockbarer unterer Inspector;
• rechte Seitenleiste für Active Layers, Media Banks, Nodes und Alerts;
• Mixer;
• Media Library;
• Effekteditor;
• DMX-Seite;
• Pluginseite;
• Diagnostics;
• Cluster-Control-Center, Nodefilter und Sync-/Preflightstatus;
• dezente Quality: Auto-Anzeige ohne störende Dialoge;
• Preview;
• Tabletlayout;
• Auth für LAN;
• Playwright-Referenzbilder und Zoom-/Density-Tests;
• ausdrücklich kein GO-, Standby-, Cue-Cart- oder Timeline-Bereich.

Gate 5 / Kernrelease V1.0: Die komplette Layer-/Effektshow kann ohne lokale Desktop-UI vorbereitet und live bedient werden. Ein Control Center bedient mindestens zwei Nodes; der visuelle Stil besteht die Referenzabnahme, ohne QLab-Assets oder QLab-Cue-Funktionen zu kopieren.

Phase 6 – optionaler Cue-/Timeline-Workspace nach V1.0, etwa 4–8 Wochen

Diese Phase beginnt nur nach neuer Freigabe. Erst hier werden QLab-ähnliche Bedienfähigkeiten ergänzt.

• Cue List mit Playhead, Standby und optionalem GO;
• Cue Carts als optionaler Live-Abrufmodus;
• Übergänge;
• Preload;
• Timeline-Tracks;
• Clips und Keyframes;
• Automation;
• Override/Release mit DMX;
• Autosave/Undo;
• zeitgestempelte Cue-/Timeline-Ausführung über Servergruppen.

Gate 6: Eine mindestens zehnminütige programmierte Show läuft reproduzierbar und ist nach Neustart identisch.

Phase 7 – Audio und Modulatoren, etwa 2–5 Wochen

• Audio Device Handling;
• FFT/Bänder/RMS/Peak;
• Beat/Onset/BPM;
• Mapping Engine;
• LFO/Envelope/Step Sequencer;
• Audio UI;
• Latenz- und Dropouttest.

Gate 7: Sound-to-Light funktioniert deterministisch ohne KI und ohne Renderstörungen.

Phase 8 – Mapping und Edge-Blending, etwa 4–8 Wochen

• Output Slices;
• Mappingeditor;
• 4-Corner-Warp;
• Mesh-Warp;
• Edge-Masks;
• Gamma und Black Level;
• Testpattern;
• atomare Liveaktivierung.

Gate 8: Zwei Projektoren können als gemeinsame Canvas kalibriert und gespeichert werden.

Phase 9 – Art-Net-Pixel-Ausgabe, etwa 2–5 Wochen

• Pixel Mapper;
• RGB/RGBW;
• Universe-Packing;
• ArtSync;
• asynchroner GPU-Readback;
• Bandbreiten-/Lasttest.

Gate 9: Definiertes LED-Testsetup läuft ohne Renderthread-Stall und mit synchronen Universen.

Phase 10 – KI- und Advanced Automation, etwa 3–8 Wochen

• versioniertes KI-Command-Gateway;
• Provideradapter;
• Scopes, Dry-run, Audit und Freigaben;
• Offline-Musikanalyse;
• Timeline-/Szenenvorschläge;
• Live-Autopilot nur innerhalb freigegebener Regeln.

Gate 10: KI kann einen prüfbaren Entwurf erzeugen, aber keine Sicherheits- oder Prioritätsgrenze umgehen.

Phase 11 – Raspberry Pi 5, etwa 2–5 Wochen

• ARM64-Build;
• GStreamer-Hardwarepfad;
• OpenGL-ES-Shaderprüfung;
• PI_LITE-Profil;
• reduzierte Qualitätsstufen;
• portable Startstruktur;
• Soak-Test.

Gate 11: Das definierte 1080p60-PI_LITE-Profil läuft stabil auf realer Hardware.

Phase 12 – Produktionshärtung, fortlaufend mindestens 4–8 Wochen

• Installer-freies Releaseverfahren;
• Update/Rollback;
• Langzeittests;
• breite GPU-/Pultmatrix;
• Bedienerdokumentation;
• Diagnoseexport;
• Lizenzprüfung;
• Release Candidate und Feldtest.

---

32. Pflichtdokumente während der Entwicklung

STATUS.md

• aktuelle Phase;
• letzter grüner Commit;
• bestandene Gates;
• laufende Arbeit;
• nächste drei Aufgaben;
• bekannte Blocker.

ERRORS.md

Jeder Fehler mit:

• ID;
• Priorität P0–P3;
• Reproduktionsschritte;
• erwartetes/tatsächliches Verhalten;
• Plattform/Hardware;
• Logs/Screenshots;
• Ursache;
• Fixcommit;
• Regressionstest.

TEST_REPORT.md

• Testdatum und Commit;
• Hardware/OS/Treiber;
• automatisierte Testergebnisse;
• Performancewerte;
• Art-Net-Hardwaretest;
• Portabilitätstest;
• Soak-Zeit;
• offene Abweichungen.

ADRs

Mindestens erforderlich:

1. Packaging: Nuitka oder PyInstaller;
2. Frontend: React oder Svelte;
3. IPC und Serialisierung;
4. GStreamer GPU-Memory-Pfad je Plattform;
5. Renderbackend-Vertrag und Shader-Sprachprofile HLSL/GLSL/GLES;
6. Projektpersistenz;
7. Preview-Technik;
8. zusätzlicher Show-Codec;
9. Control-Ownership;
10. Output-/Displayabstraktion;
11. Capability-Selbsttest und Adaptive-Quality-Policy;
12. Node-Discovery und manueller Subnetz-Fallback;
13. Coordinator-/Clusterprotokoll;
14. Node-Paarung, TLS und Berechtigungsscopes;
15. Clock-Sync, execute_at und messbare Softwaregrenzen;
16. QLab-inspirierte, aber eigenständige UI-Design-Tokens und Density-Regeln.

---

33. Verbotene Abkürzungen und Architekturfehler

Die ausführende KI darf ausdrücklich nicht:

• Videoframes mit NumPy/Pillow/OpenCV im Livepfad pro Pixel bearbeiten;
• aus Python pro Frame einzelne GPU-Drawcalls oder Texturkopien ausführen;
• das Operatorbild als Browser-Canvas ausgeben;
• UI, Art-Net und Renderloop als untrennbaren Monolithen bauen;
• Plugins direkt interne Klassen importieren lassen;
• jedem Plugin einen variablen DMX-Footprint geben;
• absolute Medienpfade ohne Portabilitätsschicht speichern;
• Softwaredecoding unbemerkt als Fallback aktivieren;
• Windows-Videoframes im Normalpfad aus D3D11 in CPU-RAM und zurück kopieren;
• Render-/Pluginverträge fest an nur eine Grafik-API koppeln;
• Layer, Ausgangsauflösung oder Showlogik zur Lastreduktion unbemerkt verändern;
• Qualitätsstufen zur Laufzeit erstmals kompilieren;
• mDNS-Discovery als Authentisierung behandeln;
• Nodes ohne Paarung oder gültige Berechtigung steuern;
• WLAN als garantierten Cue-/Frame-Sync-Pfad ausgeben;
• Softwarezeit-Synchronisation als Genlock/Framelock bezeichnen;
• Mapping erst nachträglich ohne OutputSurface-Datenmodell anflanschen;
• KI direkten Datenbank- oder Shellzugriff geben;
• unbeschränkte Queues oder unkontrollierte Caches verwenden;
• Renderfehler durch pauschales try/except verschlucken;
• auf echter Hardware notwendige Tests durch Mocks ersetzen;
• Docker als primären Desktop-/GPU-Auslieferungsweg verwenden;
• neue Frameworks ohne ADR und messbaren Bedarf hinzufügen;
• den gesamten Renderkern vor Phase 0 selbst neu schreiben.

---

34. Risikoregister

Risiko	Auswirkung	Gegenmaßnahme
GPU-Frames fallen auf System-RAM zurück	massive Last/Framedrops	Phase-0-Memory-Pfad messen; sichtbarer Decoderstatus
GStreamer-Bündelung unter Windows	Portable Build startet nicht	sauberer VM-Test in Phase 0; Runtime manifestieren
Shader laufen auf Desktop, nicht Pi	Plugininkompatibilität	GLSL/GLES-Subset; Cross-Compile-/Hardwaretest
Long-GOP-Medien triggern langsam	unbrauchbare Livebedienung	Preload, Codecprofil, Medientest und Warnung
Heavy Blur/Feedback überlastet GPU	Framedrops	Qualitätsstufen, Framebudget, Capability-Tier
Auto Quality schaltet sichtbar hin und her	unruhiges Bild	Hysterese, Mindesthaltezeit, Interpolation, Preview zuerst reduzieren
Browserpreview belastet Renderer	Showoutput ruckelt	gedrosselte separate Pipeline, abschaltbar
mehrere Steuerquellen kämpfen	springende Parameter	zentrale Ownership-/Prioritätsengine
Plugin beschädigt Projekte	Show nicht ladbar	Versionierung, Bypass, Missing-Plugin-Fallback
Display-ID ändert sich	falscher Output	EDID/Metadaten, Zuordnungsdialog, Safe Mode
Pi wird als Desktop-Ersatz erwartet	Zielverfehlung	eigenes PI_LITE-Abnahmeprofil
KI verändert Livezustand unkontrolliert	Betriebsrisiko	Scopes, Dry-run, niedrigste Priorität, Audit
Edge-Blending sieht trotz Geometrie schlecht aus	unprofessionelles Bild	Gamma, Black Level, Testbilder, realer Projektortest
mDNS ist in VLAN/Netz blockiert	Server erscheinen nicht automatisch	manuelle Node-Liste, optionale zentrale DNS-SD-Registrierung
doppelte Universen auf mehreren Nodes	falsche Layer reagieren	zentraler Universe-Plan, Preflight-Blocker, Unicast
Content-/Pluginstand weicht ab	verschiedene Bilder trotz gleichem Command	Hashmanifest, Staging und atomare Revision
Clock-Drift zwischen Rechnern	sichtbarer Startversatz	Driftmessung, geplante Commands, verkabeltes LAN, Genlock-Hinweis
Coordinator fällt aus	zentrale UI/Sync vorübergehend weg	Nodes halten Zustand und direkten Art-Net-Empfang; vorbereiteter Ersatz

---

35. Definition of Done für Version 1.0

Version 1.0 gilt nur als fertig, wenn alle folgenden Punkte erfüllt sind:

• portable Windows-Anwendung startet auf sauberem Rechner ohne Installation;
• Browseroberfläche funktioniert lokal und autorisiert im LAN;
• Browserneustart beeinflusst den Output nicht;
• acht Layer sind patch- und steuerbar;
• Videos werden auf Referenzhardware nachweislich hardwaredecodiert;
• GPU-Compositing und Windows-D3D11Memory-Pfad sind ohne regulären CPU-Rundweg nachgewiesen;
• Hardware/Decoder/Displays werden automatisch erkannt und einem gemessenen Profil zugeordnet;
• Adaptive Quality hält das Ausgabeformat stabil und wechselt nur vorab getestete interne Qualitätsstufen;
• Media-, Generator- und Adjustment-Layer funktionieren;
• zwei Effekt-Slots je Layer funktionieren;
• alle Pflichtgeneratoren und Pflichtfilter aus Abschnitt 15 bestehen Bild-, Parameter-, Backend- und Performance-Abnahme;
• externe Shaderplugins lassen sich ohne Kernänderung installieren;
• Master32- und Layer64-Art-Net-Fixtures sind vollständig dokumentiert;
• ein Lichtpult steuert mindestens zwei Server über getrennte Universe-Bereiche; Failsafe ist auf realem Netzwerk getestet;
• mindestens zwei Server werden gefunden beziehungsweise manuell hinzugefügt, sicher gepaart und in einer gemeinsamen Oberfläche bedient;
• Content-/Project-/State-Sync, Preflight und zeitgestempelte Presetaktivierung auf zwei Nodes sind getestet;
• Presets/Szenen sind speicherbar und direkt abrufbar, ohne GO-/Standby-/Cue-Logik;
• die Weboberfläche verwendet die definierte dunkle, kompakte QLab-inspirierte Designsprache, jedoch keine QLab-Assets oder Cue-Funktionen;
• Performance- und Soak-Gates sind dokumentiert bestanden;
• keine offenen P0-Fehler;
• alle P1-Fehler sind behoben oder ausdrücklich für Release akzeptiert;
• Projektmigration, Backup und Crash-Recovery sind getestet;
• Diagnoseansicht zeigt Decoder-, Frame- und Art-Net-Status;
• Plugin-, API- und Operator-Dokumentation liegt vor;
• SBOM und Drittanbieter-Lizenzen liegen bei;
• Release-ZIP, Prüfsumme und reproduzierbares Buildskript sind vorhanden.

Cue-/GO-/Timeline-Funktionen, Audioanalyse, Mapping/Edge-Blending, Art-Net-Pixeloutput, KI und Raspberry Pi besitzen eigene spätere Gates und sind nicht Voraussetzung für V1.0, dürfen durch V1.0 aber nicht architektonisch blockiert sein.

---

36. Erster konkreter Arbeitsauftrag für die Entwicklungs-KI

Die ausführende KI beginnt nicht mit dem vollständigen UI und nicht mit einem großen Plugin-Katalog. Sie führt exakt diese ersten Schritte aus:

1. Repository gemäß Eigentumsgrenzen initialisieren.
2. STATUS.md, ERRORS.md, TEST_REPORT.md und ADR-Vorlage anlegen.
3. GStreamer-Version für Windows pinnen.
4. Minimalen Windows-Renderer bauen: Testvideo → D3D11-Hardwaredecode → D3D11Memory → Vollbild.
5. Zweite Quelle und D3D11-GPU-Compositing ohne CPU-Readback ergänzen.
6. HLSL-Passthrough-Plugin mit einem live änderbaren Parameter sowie eine semantisch gleiche GLSL-Testvariante ergänzen.
7. Minimalen Art-Net-Empfänger mit einem Universe bauen.
8. DMX-Kanal auf Layer-Opacity mappen.
9. Minimalen FastAPI-/WebSocket-Endpunkt für denselben Parameter bauen.
10. Capability-Selbsttest und drei Adaptive-Quality-Varianten implementieren.
11. Framezeit, Decoder, Memory-Pfad, Qualitätswechsel und DMX-Latenz messen.
12. Portable Onefolder-Ausgabe erzeugen.
13. Auf einem sauberen Windows-Rechner ohne Entwicklungsumgebung testen.
14. Ergebnisse in TEST_REPORT.md dokumentieren.
15. ADRs zu Packaging, GPU-Pfad, Adaptive Quality und IPC entscheiden.
16. Erst bei bestandenem Gate 0 mit Phase 1 fortfahren.

Gate-0-Demo

Die Abnahmevorführung muss zeigen:

• portables Starten aus einem entpackten Ordner;
• Browser öffnet sich;
• zwei Videos laufen gleichzeitig;
• ein Shader verändert sichtbar das Bild;
• zusätzliche Last führt zu einem atomaren, nicht auffälligen Auto-Quality-Wechsel, ohne Ausgangsauflösung oder Layer zu ändern;
• ein Art-Net-Fader steuert die Opacity;
• ein Browserregler steuert einen Effektparameter;
• Videooutput bleibt beim Schließen des Browsers aktiv;
• Diagnose zeigt Hardwaredecoder und stabile Framezeit;
• Anwendung beendet sich kontrolliert.

---

37. Strategische Schlussentscheidung

Das Produkt wird Windows-first, aber nicht Windows-only entwickelt. Die erste belastbare Renderplattform ist Windows mit GStreamer und einem GPU-residenten D3D11-Pfad; Linux nutzt OpenGL und Raspberry Pi OpenGL ES hinter demselben Backend-Vertrag. Control Core, Projektmodell, Pluginmanifest, Parameter-Engine, Art-Net, spätere Timeline/Audiofunktionen und Web-UI bleiben plattformneutral. Raspberry Pi wird als separates Leistungsprofil behandelt und nicht als gleichwertiger Ersatz für eine Desktop-GPU vermarktet.

Die V1-Weboberfläche übernimmt nur die visuelle Ruhe, Dichte und Paneelstruktur professioneller QLab-Arbeitsflächen. GO, Standby, Cue-Carts und Cue-Timeline werden nicht vorgetäuscht, sondern erst als späteres Modul gebaut. Discovery, Paarung und Mehrserver-Steuerung sind dagegen Teil des Fundaments, weil sie sich nicht sauber nachträglich an ein Einzelsystem anflanschen lassen.

Der wichtigste Projekterfolg ist nicht eine möglichst große Featureliste, sondern ein stabiler Echtzeitkern mit folgenden festen Grenzen:

• keine Python-Pixelpipeline;
• kein browserbasierter Showoutput;
• keine direkte KI-Steuerung am Kern vorbei;
• kein Pluginwildwuchs ohne versionierten Vertrag;
• keine Performanceaussage ohne Messung auf echter Hardware;
• keine neue Phase ohne grünes Gate.

Damit bleibt der kleine Medienserver zunächst realistisch baubar und kann anschließend kontrolliert zu einem leistungsfähigen Medien-, VJ-, Pixel- und Automationssystem wachsen.

---

38. Technische Primärquellen

• Art-Net 4 – offizielle Spezifikation
• GStreamer D3D11 H.264 Hardwaredecoder
• GStreamer D3D11 Compositor
• GStreamer D3D11 Converter
• GStreamer D3D11 Video Sink
• GStreamer NVIDIA H.264 Decoder und GPU-Memory-Ausgaben
• GStreamer OpenGL Video Mixer
• GStreamer GLSL Shader Filter
• RFC 6762 – Multicast DNS
• RFC 6763 – DNS-Based Service Discovery
• MADRIX 5 – offizielle Liste der Static Color Effects
• MADRIX 5 – offizielle Filterübersicht
• MADRIX 5 – offizielles Beispiel SCE Plasma und dessen Parameter
• Resolume – offizielles Effektmodell, Effektketten, Presets und Scopes
• Resolume – offizielle Transform-/Slice-Transform-Dokumentation
• Resolume – offizielle Generator-/Source-Dokumentation
• QLab 5 – offizieller Workspace-Aufbau und UI-Abbildungen
• QLab 5 – offizielle Cue-Cart-Abbildung
• AMD Ryzen 7 8845HS – offizielle Produktspezifikation
• Intel Processor N100 – offizielle Produktspezifikation
• wgpu – mögliche spätere portable native Renderbasis
• Raspberry Pi 5 – offizielle Hardwaredaten