3.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.
- If a Hello cannot be produced (no output size known yet), the server waits until it can, then sends it. It never sends a Hello with zero size.
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.