The frame server could only capture by running a program once per frame
(grim). That works, but ~95% of a grim frame is waiting -- fork, connect,
handshake, round trip -- not encoding, and grim makes the compositor import
a *new* shared-memory buffer for every single frame.
This adds `--capture wayland[:OUTPUT]`: one long-lived zwlr-screencopy-v1
client per server, with one shm buffer reused for the whole run, capturing
inside the process. Measured here at 1280x720 (spike capture-speed, 200
frames; live re-check on Virtual-1, 60 frames):
grim (subprocess) 117.3 ms/frame 8.1 fps compositor 116.4 ms
grim-rs (Rust crate) 124.6 ms/frame 7.5 fps compositor 123.1 ms
this backend 78.0 ms/frame 13.9 fps compositor 67.5 ms
live, PNG both sides: this 128.5 ms/frame against grim's 389.3 ms (3.0x)
Three findings, each of which shaped the code:
* The win is buffer reuse, not language. grim and grim-rs both hand the
compositor a fresh buffer per frame, which is why their compositor CPU is
nearly double ours. The per-frame allocate-copy-swizzle that grim-rs pays
was measured in isolation at 2.4 ms of *client* time; the rest of its
deficit lands inside the compositor.
* ext-image-copy-capture-v1 is no faster (78.0 vs 77.7 ms) and its
create_frame path appears in a Hyprland segfault stack, so this keeps the
deprecated protocol grim uses. The switch is one constant when that crash
is fixed.
* PNG only, deliberately: PNG is the one encoding this package produces
without a dependency, so --format jpeg is refused rather than publishing a
Hello whose MIME type the frames do not have. A PNG frame is ~2.1 MB
against ~120 KB for JPEG q80, which is why the command backend stays the
default and why a libjpeg-turbo encoder (1.7 ms/frame, measured) is the
obvious follow-up.
The timeout is the load-bearing part of the client: pywayland only reads
events from read()/dispatch(block=True), neither of which takes a timeout,
and the server captures in a worker thread where SIGALRM is unavailable. It
therefore polls the display fd itself, so a compositor that stops answering
produces a CaptureError instead of a capture thread that never returns.
The protocol bindings are vendored under src/hhstream/_protocol/ exactly the
way hhstream_pointer already vendors its two, with regenerate.py recording
where each XML came from. No new dependency: pywayland was already required
by the input driver.
Contract: the new server flag and the two new module options are documented
in docs/CONTRACT.md, and docs/ARCHITECTURE.md's prediction that a native
screencopy client would be "a swap rather than a rewrite" is now the record
of what the swap cost.
Unit suite: 977 passed, 2 skipped, 0 failed (nix build -L .#checks.unit).
The live numbers were taken on this VM against the real compositor.
6.8 KiB
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.socketPathsays. Default/run/hypr-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/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); wayland needs format = "png" |
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 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> ...] [--capture wayland[:NAME]]
--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> -.--captureselects a named backend instead of a program:waylandcaptures the compositor's first output in-process,wayland:NAMEthe output Hyprland callsNAME. It is exclusive with--capture-command(the backend replaces the command; passing both is a caller error). It requires--format png, and the server refusesjpegrather than publish a Hello whose MIME type the frames do not have — the in-process client can encode PNG without a dependency and nothing else.- 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.