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.
134 lines
6.8 KiB
Markdown
134 lines
6.8 KiB
Markdown
# 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. |