# Architecture ``` ┌──────────────────────────────────────────┐ │ hyprland-headless.service │ │ Hyprland 0.56.2, no physical monitor │ │ private XDG_RUNTIME_DIR, as `user` │ │ outputs come from `outputs[]` │ └───────────────┬──────────────────────────┘ │ Wayland session ▼ ┌──────────────────────────────────────────┐ │ hyprland-headless-stream.service │ │ hhstream-server │ │ capture ──▶ one "latest frame" slot │ │ accept ──▶ a thread per client │ └───────────────┬──────────────────────────┘ │ AF_UNIX, mode 0660 ▼ many clients ── hhstream-client / any socket reader ``` Three pieces, deliberately separate: 1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual outputs. It knows nothing about frames on a socket. 2. **The frame server** (`hhstream`) captures, holds exactly one frame, and publishes it. It owns the socket, the framing and the drop policy. 3. **The client** is any process that can open a Unix socket and read the contract's byte format. The shipped `hhstream-client` is a convenience, not a requirement. ## Why one frame, not a queue The server keeps a single slot holding the most recent frame. Each client thread sends whatever is in that slot when it is ready. A client that cannot keep up therefore misses frames instead of forcing the server to buffer them: memory use does not grow with the number of stalled clients, and a stalled client cannot delay the others. See `docs/CONTRACT.md` for exactly what a client observes. ## Capture Capturing is a separate program (by default `grim`, a wlr-screencopy client) run inside the compositor's session and pointed at stdout. That choice is what keeps `hhstream` free of Wayland and GPU code — the awkward part lives in a tool that already exists and is already tested — and it is why the capture command is a module option: tests inject a fake, and a future backend (a native screencopy client, a hardware encoder) is a command-line swap rather than a rewrite. ## The hardware requirement, stated plainly `Hyprland` 0.56.2 asks aquamarine for its **headless backend as mandatory** (`src/Compositor.cpp`) and does not accept the DRM backend if it is unavailable. Aquamarine's headless backend still needs an EGL/GBM **render node**; there is no software-only path that works without one. Consequently a host with no graphics device at all (`/dev/dri` missing) cannot run this, and Pyprland fails with `CBackend::create() failed!` before any of its managers come up. So the requirements are: - a render node, i.e. `/dev/dri/renderD*` — from a real GPU, a virtual GPU (`virtio-gpu`, `virtio-gpu-gl`, QXL) or a NixOS test VM's own QEMU display; - the `video`/`render` groups for whichever user runs it (the module sets them). ## Testing, and what each layer proves | Layer | Proves | |---|---| | `tests/unit` | the framing, the capture wrapper and the server's client handling, with no compositor and no GPU | | `checks.vm-basic` | the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program | | `checks.vm-hyprland` | the real thing: headless Hyprland comes up in the VM and `grim` captures a frame of the configured size | | `checks.vm-sessions` | the session broker side: a real application runs as a tracked session on the compositor, the compositor's IPC sees its window, the idle reaper fires for real (and does not fire when the session is touched), and a broker restart adopts its sessions back | `vm-hyprland` is the only check that can fail for reasons outside this repo, so it is kept separate from `vm-basic` on purpose: when it fails, the compositor's log is the answer and the other two layers are already known good.