Files

5.3 KiB
Raw Permalink Blame History

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.socketPath says. Default /run/hyprland-headless-stream/stream.sock.
  • Ownership: the service user (user option, default hhstream), mode 0660.
  • 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/height in 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 as user, on a private XDG_RUNTIME_DIR, with no physical output.
  • hyprland-headless-stream.service — the frame server, After= the compositor, with Restart=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> ...]
  • --format takes the short name (png, jpeg), not a MIME type; the server maps it to image/png / image/jpeg for the Hello.
  • --capture-command is 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 derives grim -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.