AUFGERAUMT: Root auf 10 sichtbare Elemente reduziert

Der Nutzer hat recht: Der Ordner war voller Entwicklungs-Muell. Jetzt ist sauber getrennt: ROOT (was der Nutzer sieht und braucht): - run.py = das Programm - hms_app/ = der Anwendungscode - HMS MediaEngine.app = macOS Doppelklick-Starter - HMS-Start.vbs = Windows Doppelklick-Starter - HMS-Install.vbs = Windows Erst-Installation - HMS-Mac-Install.command = macOS Homebrew-Installation - HMS-Portable-Install.command = macOS Portable-Installation (16GB-Fix) - installer_gui.py = grafischer Installer - launcher.pyw + launcher_core.py = interne Start-Logik - LIESMICH.txt = 10-Zeilen-Kurzanleitung - .gitignore _entwicklung/ (alles andere, NICHT benoetigt): - packages/ apps/ native/ plugins/ tools/ schemas/ tests/ docs/ build/ fixture_profiles/ - PLAN.md STATUS.md ERRORS.md TEST_REPORT.md CHANGELOG.md README.md - pyproject.toml uv.lock setup_*.sh/ps1 make_mac_app.py Diese Trennung gilt ab sofort fuer alle Commits. Der Nutzer kann _entwicklung/ loeschen wenn er Platz braucht - die App laeuft ohne. Verifiziert: App startet nach Aufraeumen unveraendert (Health 200).
2026-09-11 23:44:06 +02:00
parent 696e8eb1b3
commit 362e089be0
338 changed files with 24 additions and 387 deletions
@@ -0,0 +1,131 @@
+# HMS MediaEngine – Native Render Bridge (ADR-0004)
+
+Rust/GStreamer-D3D11-Renderkern für den HMS MediaEngine Render-Worker (§6.1C).
+Dieser Crate implementiert den nativen Rendergraph als GStreamer-Plugin-Ansatz:
+
+- **GStreamer-Plugin** `hmsrender` mit eigenem Compositor-Element `hmscompositor`
+- **D3D11-Layer-Compositor** mit den Blend-Modi V1 (§12.4)
+- **HLSL-Shader-Loader** mit dem Standard-cbuffer-Layout `hms_params` (§14.4)
+- **FrameReceiver** für binäres MessagePack-`FrameSnapshot` (§11.4)
+- **Pipeline-Builder** für die D3D11-Elementkette (§13.1)
+
+## Architektur
+
+```text
+Python Render-Worker (§6.1C)
+        │  FrameSnapshot (MessagePack, IPC)
+        ▼
+FrameReceiver ──► LayerCompositor (D3D11)
+        │
+        ▼
+GStreamer-Pipeline: d3d11h264dec → d3d11convert → hmscompositor → d3d11videosink
+```
+
+Kein CPU-Readback im Normalpfad (§12.6, §33): Alle Operationen laufen auf
+GPU-residenten D3D11-Texturen.
+
+## Build-Anleitung (Windows)
+
+### Voraussetzungen
+
+- **Rust Toolchain** (stable, Edition 2021): <https://rustup.rs>
+- **GStreamer MSVC Runtime + Development** (1.22+):
+  <https://gstreamer.freedesktop.org/download/>
+  - Installiere `gstreamer-1.0-devel-msvc-x86_64` und `gstreamer-1.0-runtime-msvc-x86_64`
+  - Setze `GSTREAMER_1_0_ROOT_MSVC_X86_64` auf den Installationspfad
+- **Windows SDK** (für D3D11, DXGI, HLSL): Teil von Visual Studio Build Tools
+- **pkg-config** (für gstreamer-rs): über MSYS2 oder `vcpkg`
+
+### Build
+
+```bash
+cd native/render_bridge
+cargo build --release
+```
+
+Die kompilierte Bibliothek liegt unter `target/release/hms_render_bridge.dll`
+(cdylib).
+
+### Umgebungsvariablen
+
+```bash
+export GST_PLUGIN_PATH="$(pwd)/target/release"
+export GST_PLUGIN_SYSTEM_PATH_1_0="C:/gstreamer/1.0/msvc_x86_64/lib/gstreamer-1.0"
+```
+
+## Integration mit dem Python-Orchestrator
+
+Der Python-Render-Worker (§6.1C) lädt die cdylib und ruft die FFI-Funktionen auf:
+
+```python
+import ctypes
+
+bridge = ctypes.CDLL("target/release/hms_render_bridge.dll")
+
+# Pipeline bauen (JSON-Konfiguration)
+config = {
+    "canvas_width": 1920,
+    "canvas_height": 1080,
+    "fps": 60.0,
+    "media_uri": "C:/media/clip.mp4",
+    "layers": {"layer_1": "normal"},
+    "output_device": None,
+}
+config_json = json.dumps(config).encode("utf-8")
+bridge.hms_build_pipeline(config_json)
+
+# FrameSnapshot als MessagePack übergeben
+snapshot = {
+    "frame_index": 0,
+    "monotonic_ns": 0,
+    "state_revision": 0,
+    "parameters": {"layer_1/opacity": 1.0, "audio/rms": 0.5},
+    "source_positions": {},
+    "source_states": {},
+    "active_asset_ids": {},
+}
+payload = msgpack.packb(snapshot)
+bridge.hms_push_frame(payload, len(payload))
+```
+
+## FrameSnapshot-Vertrag (§11.4)
+
+Die Feldnamen im Rust-`FrameSnapshot` sind identisch zum Python-`FrameSnapshot`
+in `apps/renderer/hms_renderer/engine.py`:
+
+| Feld | Typ | Bedeutung |
+| --- | --- | --- |
+| `frame_index` | int | Frame-Nummer |
+| `monotonic_ns` | int | Monotone Zeitbasis (ns) |
+| `state_revision` | int | Showzustands-Revision |
+| `parameters` | dict[str, float] | Flache Parameter-Pfade |
+| `source_positions` | dict[str, float] | source_id → Position |
+| `source_states` | dict[str, str] | source_id → TransportState |
+| `active_asset_ids` | dict[str, str\|None] | layer_key → asset_id |
+
+## Blend-Modi (§12.4)
+
+`normal`, `add`, `multiply`, `screen`, `lighten`, `darken`, `difference`,
+`overlay`, `alpha_premultiplied`. Müssen mit Golden-Image-Tests geprüft werden.
+
+## Standard-Shaderinputs (§14.4)
+
+Jeder Shader erhält das cbuffer `hms_params` (register b0):
+
+- `u_resolution` (float4: xy = Pixel, zw = 1/xy)
+- `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 Plugin-Parameter
+
+## Windows-Abhängigkeiten
+
+- GStreamer MSVC (Runtime + Development)
+- Windows SDK (D3D11, DXGI, HLSL)
+- Visual Studio Build Tools (Linker, pkg-config)
+
+## Hinweis
+
+Der Code wird im Container nicht kompiliert (kein cargo). Die Kompilierung
+erfolgt im Windows-Durchlauf gemäß ADR-0004. Gate-0-Messungen bestätigen das
+Elementpfad-Budget oder lösen eine Revision aus (eigenständige D3D11-Bridge).