Files
hyprland-headless-stream-pl…/docs/ARCHITECTURE.md
T

4.3 KiB

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

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.