# Wire contract (v2) **v2 changes nothing on the wire.** The published socket's documented *default* moved from `/run/hyprland-headless-stream/stream.sock` to `/run/hypr-stream/stream.sock`: the old runtime directory pushed the compositor's own IPC *event* socket past `sun_path`'s 108-byte limit, so it never bound (see `docs/CONTRACT-sessions.md` §5). Message sequence, framing and failure semantics are unchanged, so a v1 reader is still a correct reader. 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/hypr-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`: ```json {"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: ``` <0x0A> ``` `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/hypr-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 *command* — used by tests | | `captureBackend` | `"command"` \| `"wayland"` | `"command"` | capture by command or in-process (`zwlr-screencopy-v1`); both `format` values work | | `captureOutput` | str or null | `null` | output to capture by name when `captureBackend = "wayland"`; null = the first one | 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 --fps --format \ [--capture-quality <1..100>] \ [--capture-command ...] [--capture wayland[:NAME]] ``` - `--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=` form is accepted as well, and the two may be mixed. When absent, the server derives `grim -t -`. - `--capture` selects a **named backend** instead of a program: `wayland` captures the compositor's first output in-process, `wayland:NAME` the output Hyprland calls `NAME`. It is exclusive with `--capture-command` (the backend replaces the command; passing both is a caller error). It honours both `--format` values: `png` through the stdlib, `jpeg` through libjpeg-turbo. If libjpeg-turbo is missing and `--format jpeg` was asked for, the server **refuses to start** rather than serving a socket it can never produce a frame for. - `--capture-quality` is the JPEG quality for the in-process backend (1..100, default 80, matching the default command's `-q 80`); `--format png` ignores it. - 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.