A machine running this module has a GPU. aquamarine's headless backend has no allocator of its own -- `CHeadlessBackend::drmFD()` returns -1 and `CBackend::start()` takes the allocator from the first backend with a drm fd -- so the session always rides on the DRM backend and always has the host's own connectors. `HEADLESS-1` is a name no connector will ever have, which made the shipped default a monitor rule Hyprland silently ignored, and made `vm-hyprland`'s assertion on that name unsatisfiable. `outputs` now means "monitor rules applied to whatever outputs the machine has". `name` is a regex against the real connector names and defaults to the empty string -- Hyprland's own wildcard form, as in its shipped `monitor=,preferred,auto,1` -- so `enable = true` alone gives a session at a known size on any host. Nothing else about the option changed. SEATD_VTBOUND=0 moves from checks/lib/gpu-session.nix into the compositor unit, where it belongs: libseat finds no seatd socket and no logind session for a system service, falls back to its embedded seatd, and that seat is VT-bound by default -- so it opens /dev/tty0, which the service user cannot, and every device open is refused. That is true on any host, not just in the test. gpu-session.nix keeps only the two things that really are the test machine's business: a render node and Mesa. vm-hyprland now asserts over `hyprctl -j monitors` that at least one monitor exists at the configured mode, with no monitor name anywhere in the check. It also gains a wallpaper, because `--reject-blank` could not otherwise mean anything: the session the module configures by default is a flat black field, which grim captures as an all-zero 1280x720 RGBA PNG of exactly 3653 bytes -- `blank_png_size()` to the byte. Runs that passed that assertion were reading Hyprland's startup notification overlay, which expires after about fifteen seconds. With `misc:force_default_wallpaper` on, the frame is 85267 bytes with all 921600 pixels non-zero and is byte-identical at +15s, +30s and +60s. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r
5.7 KiB
Wire contract (v1)
This file is the interface. Code on either side may change freely; this document may not, without bumping the version.
Socket
- Transport:
AF_UNIX,SOCK_STREAM. - Path: whatever
services.hyprland-headless-stream.socketPathsays. Default/run/hyprland-headless-stream/stream.sock. - Ownership: the service user (
useroption, defaulthhstream), mode0660. - The server accepts any number of concurrent clients. Each client gets its own copy of the header and of every subsequent frame. A client disconnecting (or dying mid-frame) must never take the server down and must never disturb the other clients.
- The server runs whether or not anyone is connected. No client is privileged.
- The socket path is removed and recreated on start; a stale socket file must not prevent startup.
Message sequence
1. Hello. Immediately on connect, the server writes exactly one UTF-8 JSON
object followed by a single \n:
{"magic":"HHS1","width":1280,"height":720,"format":"image/png","fps":30}
Fields: magic (protocol tag, HHS1), width/height (pixels of the captured
output), format (image/png or image/jpeg), fps (target capture rate,
advisory — the server does not buffer to keep up).
2. Frames. Then, forever, one frame per message:
<ascii-decimal byte length><0x0A><payload — exactly that many bytes>
payload is one complete, independently decodable image in format.
Notes:
- Byte length counts the payload only, never the length prefix.
- The length prefix is plain ASCII digits; no leading zeros, no
+, no spaces. - Frames are never split, merged or interleaved on the wire. One length, one payload.
- A client that stalls or reads slowly is slowed, not queued: the server drops frames for that client rather than buffering them. Backpressure must never grow unbounded memory.
- Shutdown: either side closes the socket. Nothing else is negotiated.
Client → server direction
Reserved. In v1 a client sends nothing; any bytes received from a client are read and ignored. (This leaves room to add a control channel later without breaking v1 readers, which never expect inbound data.)
Failure semantics
- Compositor not running / capture tool erroring: the server keeps the socket up and retries; it does not exit and it does not send partial frames.
- Hello timing. The Hello is written the moment the server can produce it, which in practice is the moment of the first successful capture. A client that connects before that has received zero bytes and simply waits: the server never sends a Hello with a zero or unknown size. ("Immediately" above means "before any frame", not "before the first capture".)
width/heightin the Hello are measured from the captured frame, not taken from configuration, so they cannot disagree with the pixels actually being sent.- A client that is torn down or killed mid-frame may see a truncated final frame. "Never sends partial frames" is about the server failing to capture, not about a client that has already gone away.
NixOS module surface
Namespace: services.hyprland-headless-stream
| Option | Type | Default | Meaning |
|---|---|---|---|
enable |
bool | false |
turn everything on |
socketPath |
str | /run/hyprland-headless-stream/stream.sock |
published socket |
user / group |
str | hhstream |
owner of the session and the socket |
frameRate |
int | 30 |
capture target, becomes fps in Hello |
format |
enum png/jpeg |
png |
frame encoding |
outputs |
list of attrsets | one 1280×720@30 rule with an empty name |
monitor rules applied to the outputs the machine has: name, width, height, refresh, scale. name is a regex matched against the real connector names (eDP-1, Virtual-1, …) and empty means every output; a name no connector has is silently ignored. The compositor never creates an output — a session started by this module drives the host's GPU. |
extraConfig |
str | "" |
extra lines appended to hyprland.conf |
hyprlandPackage |
package | pkgs.hyprland |
which compositor |
package |
package | the flake's own build | the frame server/client |
captureCommand |
list of str | [ "grim" … ] |
override the capture backend — used by tests |
Services (names are part of the contract, tests refer to them):
hyprland-headless.service— the compositor, running asuser, on a privateXDG_RUNTIME_DIR, with no physical output.hyprland-headless-stream.service— the frame server,After=the compositor, withRestart=always, connected to the same session.
Server command line
The module drives the server, so its flags are an interface too — the same status as the wire format. Exactly this shape, and no others:
hhstream-server --socket <socketPath> --fps <frameRate> --format <png|jpeg> \
[--capture-command <token> ...]
--formattakes the short name (png,jpeg), not a MIME type; the server maps it toimage/png/image/jpegfor the Hello.--capture-commandis repeated, one argv token per occurrence:--capture-command grim --capture-command -t --capture-command png --capture-command -. A single shell string cannot carry a leading-unambiguously. The--capture-command=<token>form is accepted as well, and the two may be mixed. When absent, the server derivesgrim -t <format> -.- There is deliberately no
--width/--height: the Hello reports the captured frame's real size (see above). - The socket's mode (0660) is the server's business; its ownership is
the systemd unit's (
user/group), because the server cannot chown.