5.3 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 HEADLESS-1 |
virtual monitors: name, width, height, refresh, scale |
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.