The question is which capture route to ship for live streaming and agent eyes. Speed alone does not decide it, so every route now also reports producer CPU and RSS, machine CPU from /proc/stat, the compositor's own CPU, and a per-frame buffer footprint -- all sampled around the measured loop, with an idle control sample so an animating page's cost is not attributed to the capture. The baseline forks a process per frame and spends 95% of each frame waiting, so the interesting finding is not which route is faster but which one leaves the compositor able to do its job: in-process acquisition roughly halves the compositor's per-frame CPU even though the machine saturates either way.
7.1 KiB
The measurement contract — frozen
Two people are building capture producers in two worktrees. If each invents its own timing, the comparison is worthless. So this file is the interface, and it is frozen: implement to it exactly, do not improve it.
The producer command
Every route is a command that captures frames and reports its own timings as one JSON object. Same argv, same output, whatever language it is written in.
<producer> --output <wl_output_name> --frames <N> --warmup <W> \
--mode {raw|jpeg} --json
<producer> --all --frames <N> --warmup <W> --mode {raw|jpeg} --json
| Flag | Meaning |
|---|---|
--output NAME |
capture exactly this wl_output (e.g. hh-<session-id>, or the main output) |
--all |
capture every output and stitch them, left to right, into one image — this is the 2560×720 geometry hhstream publishes today. Mutually exclusive with --output. |
--frames N |
measured frames (after warm-up) |
--warmup W |
discarded frames, taken first, on the same connection |
--mode raw |
the frame is complete in a userspace buffer; no encode, no format conversion |
--mode jpeg |
the frame is complete as JPEG bytes |
--json |
print the result object (below) as the last line of stdout |
Anything else the producer wants to say goes to stderr. Stdout carries exactly one JSON object, so a runner can parse it without guessing.
What is timed
One frame = from just before the capture is requested, to the moment that frame's bytes are complete in the producer's own userspace buffer.
--mode raw: stop when the compositor's frame is ready and the buffer is mapped and readable. Do not convert ARGB→RGB, do not apply transforms, do not touch the pixels. Reads that a consumer would do (stride, checksum) are outside the measurement.--mode jpeg: stop when the encoded bytes are complete in the buffer, however you encode them (library, subprocess, hardware). Encoding is inside the measurement, because encoding is what a live stream pays.- For the subprocess baseline (
grim), the timed span is the wholefork+exec+run+read: spawn, write to a pipe, read to EOF. That is the honest cost of the route we are trying to beat, and the fork cost is the point. - Exclude warm-up frames from every statistic. Use a monotonic clock.
- The first frame after a connection is established is a warm-up frame by definition — allocate buffers and settle the protocol before measuring.
The result object
{
"route": "grim-subprocess", // short id of the implementation
"language": "python", // python | rust
"protocol": "zwlr-screencopy-v1", // what actually served the frames
"output": "hh-chromium-yrfadn", // or "all"
"geometry": [1280, 720],
"mode": "jpeg",
"warmup": 10,
"frames": 300,
"frame_ms": { "min": 0.0, "p50": 0.0, "mean": 0.0, "p95": 0.0, "max": 0.0 },
"fps_sustained": 0.0, // frames / (sum of frame_ms / 1000)
"wall_ms": 0.0, // total wall time of the measured run
"cpu_ms_per_frame": null, // process CPU time / frames, or null if unknown
"bytes_p50": null, // frame size in bytes (jpeg mode), else null
"persistent": true, // one long-lived connection, or a process per frame
"notes": "" // anything a reader must know to read the numbers
}
Resource fields (added 2026-10-11 — the operator's requirement)
Speed alone does not decide this. A route that hits 15 fps by burning a core is
not a route we can ship on a machine that also renders. Five more fields are
required, measured over the same measured window as frame_ms:
"rss_peak_mb": 0.0, // peak RSS of the producer (children included for subprocess routes)
"rss_peak_kb_raw": 0, // the unrounded value, so nobody re-derives a rounded one
"system_cpu_ms_per_frame": 0.0, // every process on the machine, from /proc/stat
"compositor_cpu_ms_per_frame": 0.0, // the compositor's own utime+stime, from /proc/<hyprland>/stat
"machine_cpu_pct": 0.0, // system_cpu over the window, as % of one core (can exceed 100)
"frames_bytes_allocated_p50": null, // bytes of buffer the route holds per frame (raw mode: the whole frame)
system_cpu_ms_per_frameis the honest "what this costs the machine" number, and it is the one that catches a route which is fast only because the compositor did extra work. Report it even when it is unflattering.compositor_cpu_ms_per_frameseparates "the capture is expensive" from "the capture made the compositor expensive". Read/proc/<pid>/statfields 14+15 (utime+stime, in clock ticks — divide byos.sysconf("SC_CLK_TCK")). If the file is unreadable, say so innotesrather than reporting zero.rss_peak_mb:resource.getrusage(RUSAGE_SELF).ru_maxrssfor a persistent route;RUSAGE_CHILDRENfor a subprocess-per-frame route (it is the peak of the children, which is what actually matters there). ru_maxrss is in KiB on Linux, despite the name.- These are measured around the measured loop only — warm-up excluded — so
they line up with
frame_ms.
The conditions a run is reported under
protocolmust name what really ran, not what you hoped: ifext-image-copy-capture-v1is unavailable and you fell back tozwlr-screencopy-v1, say so. If you had to fall back at runtime, say that too.persistentseparates "one connection, N frames" from "a process per frame" — the two are not comparable and the table must not mix them silently.cpu_ms_per_frameis process CPU (/proc/self/statutime+stime, orgetrusage) divided by frames. A route that is fast by pinning a core is not fast; report it.- Numbers with no measurement behind them stay
null. Never estimate a field.
The conditions a run is reported under
The runner runs every route under identical conditions and records them:
- Geometry:
--output <one container>(1280×720) and--all(2560×720). - Screen: a still pass and a moving pass. Motion is made by a session printing in a loop or a page being scrolled; the runner starts it, waits for it to be visibly moving, and destroys it afterwards. A still screen can make a damage-driven capture wait — if that happens, it is a finding and goes in the verdict, not in a footnote.
- Mode:
rawandjpeg. - Repetition: every cell twice; report both runs, not just the better one.
The rule that keeps this honest
The baseline is grim as it runs today. Whatever beats it, beats that, and
the verdict has to say by how much — or that nothing did. A route that is only
faster in a mode the live stream does not use (raw pixels, when the wire carries
JPEG) must be labelled as such rather than presented as a win.
And the environment caveat that goes in every verdict: this VM has no GPU. Hyprland renders through software (kms_swrast / llvmpipe). Zero-copy dma-buf paths cannot help here, so a route must not be tuned to take one; say what a GPU machine would change, but do not claim it as measured.