Files
hyprland-headless-stream-pl…/docs/CONTRACT.md
T
Hermenix a7d9357b43 capture: an in-process Wayland backend, and the measurements that justify it
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.
2026-10-11 20:34:33 +00:00

134 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```
<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/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 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> ...] [--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=<token>` form is accepted as well, and
the two may be mixed. When absent, the server derives `grim -t <format> -`.
- `--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 requires
`--format png`, and the server refuses `jpeg` rather 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.