Phase 0: Repository-Initialisierung nach Bauplan v1.2

- Struktur gemäß §8 (Eigentumsgrenzen), PLAN.md als normative Basis - Pflichtdokumente: STATUS.md, ERRORS.md, TEST_REPORT.md, CHANGELOG.md, ADRs - ADR-0001 Python 3.13-Pin, ADR-0002 GStreamer 1.28.6-Pin (Windows), ADR-0003 IPC TCP+MessagePack v1 - Kernpakete: hms_protocol, hms_domain, hms_parameter, hms_artnet, hms_adaptive, hms_capabilities, hms_plugin_sdk - Renderer-Spike: D3D11-Primärpfad + Dev-GL-Pfad (§36 Nr. 4-5) - Control Core: FastAPI REST + WebSocket (§36 Nr. 9) - Beispielplugins: Passthrough + Gaussian Blur (3 Adaptive-Quality- Varianten, HLSL/GLSL/GLES) - Tools: Art-Net-Emulator, Fixture-Generator (Master32/Layer64-CSV), Capability-Probe - JSON-Schemas: IPC, Plugin, Projekt, Cluster - 121 Unit-/Integrationstests grün, Ruff grün Gate 0 bleibt offen: Hardwaremessungen nur auf echter Windows-Referenz- hardware gültig (§29.7, §33).
2026-09-11 00:36:59 +02:00
commit 0922cc1d68
133 changed files with 7939 additions and 0 deletions
@@ -0,0 +1,9 @@
+"""hms_control_server – minimaler Control Core (PLAN.md §6.1B, §36 Nr. 9).
+
+FastAPI-REST + WebSocket für denselben Parametersatz, den Art-Net bedient.
+Autoritative Instanz ist die ParameterEngine; alle Quellen laufen über sie.
+"""
+
+from hms_control_server.app import create_app
+
+__all__ = ["create_app"]
@@ -0,0 +1,10 @@
+"""Control-Core-Start (Entwicklung): python -m hms_control_server"""
+
+from __future__ import annotations
+
+import uvicorn
+
+if __name__ == "__main__":
+    # Phase 0: Development-Start. Produktion startet über den Launcher,
+    # bindet 127.0.0.1 und wählt freie Ports (§3.1, §9.2).
+    uvicorn.run("hms_control_server.app:app", host="127.0.0.1", port=8000)
@@ -0,0 +1,159 @@
+"""FastAPI-Anwendung des Control Core (Phase-0-Minimalversion).
+
+Endpunkte:
+- GET /api/v1/system/health
+- GET /api/v1/system/capabilities
+- GET /api/v1/parameters
+- POST /api/v1/commands  (parameter.set mit Revision-Prüfung und Idempotenz)
+- POST /api/v1/commands/{command_id}/release
+- GET /api/v1/diagnostics
+- WS  /ws  (State-Snapshot + Updates)
+
+Commands folgen §23.2: command_id, type, expected_revision, actor, payload.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from hms_capabilities.probe import CapabilityReport
+from hms_parameter.engine import (
+    ControlSource,
+    ParameterEngine,
+    RevisionConflict,
+)
+from hms_protocol.idempotency import IdempotencyRegistry
+from pydantic import BaseModel, Field
+
+
+class SetParameterCommand(BaseModel):
+    """parameter.set-Command (§23.2)."""
+
+    command_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    type: str = "parameter.set"
+    expected_revision: int | None = None
+    actor: dict = Field(default_factory=lambda: {"type": "web", "id": "operator-session"})
+    payload: dict
+
+
+class ReleaseCommand(BaseModel):
+    source: str = "web"
+
+
+class _State:
+    def __init__(self) -> None:
+        self.engine = ParameterEngine()
+        self.registry = IdempotencyRegistry()
+        self.report = CapabilityReport()
+        self.subscribers: list[asyncio.Queue] = []
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="HMS MediaEngine Control Core", version="0.1.0")
+    state = _State()
+
+    def _broadcast(event: dict) -> None:
+        for queue in list(state.subscribers):
+            queue.put_nowait(event)
+
+    @app.get("/api/v1/system/health")
+    async def health() -> dict:
+        return {"status": "ok", "phase": 0, "revision": state.engine.revision}
+
+    @app.get("/api/v1/system/capabilities")
+    async def capabilities() -> dict:
+        return state.report.as_dict()
+
+    @app.get("/api/v1/parameters")
+    async def parameters() -> dict:
+        snap = state.engine.snapshot()
+        return {"revision": snap.revision, "values": snap.as_dict()}
+
+    @app.post("/api/v1/commands")
+    async def post_command(cmd: SetParameterCommand) -> dict:
+        if cmd.type != "parameter.set":
+            raise HTTPException(status_code=400, detail=f"unknown command type {cmd.type!r}")
+        if not state.registry.register(cmd.command_id):
+            prior = state.registry.result(cmd.command_id)
+            if prior is not None:
+                return {"status": "ack", "duplicate": True, "result": prior}
+            raise HTTPException(status_code=409, detail="command already in flight")
+        path = cmd.payload.get("parameter_path")
+        value = cmd.payload.get("value")
+        if not path or value is None:
+            raise HTTPException(status_code=400, detail="payload requires parameter_path and value")
+        try:
+            revision = state.engine.set_value(
+                path=path,
+                value=float(value),
+                source=ControlSource.WEB,
+                expected_revision=cmd.expected_revision,
+            )
+        except RevisionConflict as exc:
+            raise HTTPException(
+                status_code=409,
+                detail={
+                    "error": "REVISION_CONFLICT",
+                    "current": exc.current,
+                    "expected": exc.expected,
+                },
+            ) from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        result = {
+            "status": "ack",
+            "command_id": cmd.command_id,
+            "revision": revision,
+            "effective": state.engine.effective_value(path),
+        }
+        state.registry.complete(cmd.command_id, result)
+        _broadcast(
+            {
+                "type": "parameter.update",
+                "parameter_path": path,
+                "value": value,
+                "revision": revision,
+            }
+        )
+        return result
+
+    @app.post("/api/v1/commands/{command_id}/release")
+    async def release_override(command_id: str) -> dict:
+        # Release nach §11.3; command_id referenziert den ursprünglichen Command.
+        return {"status": "not_implemented_in_phase0"}
+
+    @app.get("/api/v1/diagnostics")
+    async def diagnostics() -> dict:
+        return {
+            "renderer": "not_connected",  # IPC-Handshake folgt in Phase 1 (ADR-0003)
+            "artnet": "not_started",
+            "revision": state.engine.revision,
+        }
+
+    @app.websocket("/ws")
+    async def websocket_endpoint(ws: WebSocket) -> None:
+        await ws.accept()
+        queue: asyncio.Queue = asyncio.Queue(maxsize=256)
+        state.subscribers.append(queue)
+        try:
+            snap = state.engine.snapshot()
+            await ws.send_json(
+                {"type": "snapshot", "revision": snap.revision, "values": snap.as_dict()}
+            )
+            while True:
+                try:
+                    event = await asyncio.wait_for(queue.get(), timeout=15.0)
+                    await ws.send_json(event)
+                except TimeoutError:
+                    await ws.send_json({"type": "heartbeat"})
+        except WebSocketDisconnect:
+            pass
+        finally:
+            state.subscribers.remove(queue)
+
+    return app
+
+
+app = create_app()
@@ -0,0 +1,10 @@
+"""hms_launcher – Supervisor/Launcher (PLAN.md §6.1A, §9).
+
+Phase-0-Umfang: portable Pfadauflösung, Portwahl, GStreamer-Environment,
+kontrollierter Start von Control Core und Renderer. Vollständige
+Heartbeat-/Crash-Recovery-Logik folgt in Phase 1 (§31).
+"""
+
+from hms_launcher.paths import AppPaths, resolve_app_root
+
+__all__ = ["AppPaths", "resolve_app_root"]
@@ -0,0 +1,111 @@
+"""Portable Pfadregeln (PLAN.md §9, §9.1).
+
+- Alle Pfade relativ zum Anwendungsroot; keine Laufwerksbuchstaben.
+- Keine Abhängigkeit vom Working Directory.
+- Temporäre Dateien in userdata/cache, nicht im OS-Profil.
+- Schreibbarkeit wird beim Start geprüft (Read-only-Modus folgt Phase 1).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AppPaths:
+    """Alle portablen Pfade je Anwendungsroot (§9-Struktur)."""
+
+    root: Path
+
+    @property
+    def app(self) -> Path:
+        return self.root / "app"
+
+    @property
+    def runtime(self) -> Path:
+        return self.root / "runtime"
+
+    @property
+    def gstreamer_bin(self) -> Path:
+        return self.runtime / "gstreamer" / "bin"
+
+    @property
+    def gstreamer_plugins(self) -> Path:
+        return self.runtime / "gstreamer" / "lib" / "gstreamer-1.0"
+
+    @property
+    def web(self) -> Path:
+        return self.root / "web"
+
+    @property
+    def projects(self) -> Path:
+        return self.root / "projects"
+
+    @property
+    def media(self) -> Path:
+        return self.root / "media"
+
+    @property
+    def userdata(self) -> Path:
+        return self.root / "userdata"
+
+    @property
+    def database(self) -> Path:
+        return self.userdata / "database"
+
+    @property
+    def cache(self) -> Path:
+        return self.userdata / "cache"
+
+    @property
+    def identity(self) -> Path:
+        return self.userdata / "identity" / "node_id"
+
+    @property
+    def config(self) -> Path:
+        return self.root / "config"
+
+    @property
+    def logs(self) -> Path:
+        return self.root / "logs"
+
+    def ensure_writable(self) -> bool:
+        """Prüft Schreibbarkeit des Roots (§9.1)."""
+        probe = self.root / ".write_probe"
+        try:
+            probe.write_text("ok", encoding="ascii")
+            probe.unlink()
+            return True
+        except OSError:
+            return False
+
+    def portable_environment(self) -> dict[str, str]:
+        """Umgebungsvariablen für gebündelte GStreamer-Runtime (§9.2, ADR-0002).
+
+        System-Plugins werden unterdrückt (leerer GST_PLUGIN_SYSTEM_PATH_1_0),
+        damit ausschließlich die gebündelte, manifestierte Untermenge lädt.
+        """
+        env = dict(os.environ)
+        gs_bin = self.gstreamer_bin
+        if gs_bin.is_dir():
+            path_var = "PATH"
+            existing = env.get(path_var, "")
+            env[path_var] = f"{gs_bin}{os.pathsep}{existing}" if existing else str(gs_bin)
+        env["GST_PLUGIN_PATH_1_0"] = str(self.gstreamer_plugins)
+        env["GST_PLUGIN_SYSTEM_PATH_1_0"] = ""
+        return env
+
+
+def resolve_app_root(start_from: Path | None = None) -> Path:
+    """Bestimmt den Anwendungsroot anhand der PORTABLE_MODE-Markierung (§9).
+
+    Sucht vom gegebenen Pfad (Default: dieses Paket) aufwärts nach der
+    Datei PORTABLE_MODE; im Entwickungsbaum ist das Repo-Root gemeint.
+    """
+    current = Path(start_from or __file__).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "PORTABLE_MODE").is_file() or (candidate / "pyproject.toml").is_file():
+            return candidate
+    raise RuntimeError("app root not found (PORTABLE_MODE or pyproject.toml missing)")
@@ -0,0 +1,22 @@
+"""hms_renderer – Render-Worker-Spike (PLAN.md §6.1C, §12, §36 Nr. 4–6).
+
+Python orchestriert native GStreamer-Komponenten; keine Pixelverarbeitung
+in Python (§2.1, §33). Pipelines werden als gst-launch-Strings definiert
+und auf dem Zielsystem ausgeführt/messbar.
+"""
+
+from hms_renderer.pipelines import (
+    D3D11Pipeline,
+    DevGLPipeline,
+    build_compositor_pipeline,
+    build_single_video_pipeline,
+    gst_available,
+)
+
+__all__ = [
+    "D3D11Pipeline",
+    "DevGLPipeline",
+    "build_single_video_pipeline",
+    "build_compositor_pipeline",
+    "gst_available",
+]
@@ -0,0 +1,52 @@
+"""Renderer-CLI (Phase-0-Spike).
+
+Aufruf:
+    python -m hms_renderer --pipeline d3d11 --video-a A --video-b B
+
+Ohne GStreamer-Installation: kontrollierter Abbruch mit Exit-Code 2 und
+klarer Meldung – niemals Erfolgssimulation (§1.1 Nr. 5, §33).
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+
+from hms_renderer.pipelines import build_compositor_pipeline, build_single_video_pipeline
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="hms-renderer")
+    parser.add_argument("--pipeline", choices=["d3d11", "devgl"], default="d3d11")
+    parser.add_argument("--video-a", required=True)
+    parser.add_argument("--video-b", default=None, help="zweite Quelle für Compositing")
+    parser.add_argument("--dry-run", action="store_true", help="nur Pipeline-String ausgeben")
+    args = parser.parse_args(argv)
+
+    use_d3d11 = args.pipeline == "d3d11"
+    if args.video_b:
+        pipeline = build_compositor_pipeline(args.video_a, args.video_b, d3d11=use_d3d11)
+    else:
+        pipeline = build_single_video_pipeline(args.video_a, d3d11=use_d3d11)
+
+    if args.dry_run:
+        print(pipeline)
+        return 0
+
+    gst_launch = shutil.which("gst-launch-1.0")
+    if gst_launch is None:
+        print(
+            "ERROR: gst-launch-1.0 nicht gefunden. GStreamer 1.28.6 muss gebündelt "
+            "oder installiert sein (build/windows/GSTREAMER.md).",
+            file=sys.stderr,
+        )
+        return 2
+
+    result = subprocess.run([gst_launch, "-v", pipeline], check=False)
+    return result.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,79 @@
+"""Renderer-Pipeline-Definitionen (PLAN.md §12, §13, §36 Nr. 4–5).
+
+Windows-Primärpfad (§12.6): d3d11h264dec → D3D11Memory → d3d11compositor
+→ d3d11videosink. Kein CPU-Rundweg (Decoder → RAM → Upload verboten).
+
+DevGL-Pfad: Nur für Entwicklung/CI-Umgebungen ohne D3D11; ausdrücklich
+gekennzeichnet, kein stiller Ersatz im Normalbetrieb (§5.2, §33).
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class D3D11Pipeline:
+    """Primärpipeline Windows: durchgängig D3D11Memory."""
+
+    video_a: str
+    video_b: str
+    width: int = 1920
+    height: int = 1080
+    fullscreen: bool = True
+
+    def launch_string(self) -> str:
+        sink = "d3d11videosink fullscreen=true" if self.fullscreen else "d3d11videosink"
+        # Zwei Quellen → Compositor → Ausgabe (§36 Nr. 5: zwei Videos GPU-mischen)
+        return (
+            f"d3d11compositor name=mix sink_0::xpos=0 sink_0::ypos=0 "
+            f"sink_0::width={self.width // 2} sink_0::height={self.height} "
+            f"sink_1::xpos={self.width // 2} sink_1::ypos=0 "
+            f"sink_1::width={self.width // 2} sink_1::height={self.height} ! "
+            f"d3d11convert ! video/x-raw(memory:D3D11Memory),format=RGBA,"
+            f"width={self.width},height={self.height} ! {sink} "
+            f"uridecodebin uri=file:///{self.video_a} ! queue ! "
+            f"d3d11convert ! mix. "
+            f"uridecodebin uri=file:///{self.video_b} ! queue ! "
+            f"d3d11convert ! mix."
+        )
+
+
+@dataclass(frozen=True)
+class DevGLPipeline:
+    """Entwicklungspfad ohne D3D11 (explizit gekennzeichnet, kein Normalpfad).
+
+    Nur für CI/Dev ohne Windows-GPU; die Backend-Schnittstelle bleibt
+    identisch (§12.6)."""
+
+    video_a: str
+    video_b: str
+    width: int = 960
+    height: int = 540
+
+    def launch_string(self) -> str:
+        return (
+            f"glvideomixer name=mix ! glimagesink "
+            f"uridecodebin uri=file:///{self.video_a} ! queue ! glupload ! mix. "
+            f"uridecodebin uri=file:///{self.video_b} ! queue ! glupload ! mix."
+        )
+
+
+def build_single_video_pipeline(video: str, d3d11: bool = True) -> str:
+    """Minimale Einzelquellen-Pipeline (§36 Nr. 4: Testvideo → Vollbild)."""
+    if d3d11:
+        return f"uridecodebin uri=file:///{video} ! d3d11convert ! d3d11videosink fullscreen=true"
+    return f"uridecodebin uri=file:///{video} ! glupload ! glimagesink"
+
+
+def build_compositor_pipeline(video_a: str, video_b: str, d3d11: bool = True) -> str:
+    """Zwei-Quellen-Compositing (§36 Nr. 5: GPU-Mischen ohne CPU-Readback)."""
+    if d3d11:
+        return D3D11Pipeline(video_a=video_a, video_b=video_b).launch_string()
+    return DevGLPipeline(video_a=video_a, video_b=video_b).launch_string()
+
+
+def gst_available() -> bool:
+    """True, wenn ein GStreamer-CLI auf dem System liegt (Diagnose, kein Fake)."""
+    return shutil.which("gst-launch-1.0") is not None