# 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. ``` --output --frames --warmup \ --mode {raw|jpeg} --json --all --frames --warmup --mode {raw|jpeg} --json ``` | Flag | Meaning | |---|---| | `--output NAME` | capture exactly this `wl_output` (e.g. `hh-`, 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 whole `fork`+`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 ```json { "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`: ```json "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//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_frame` is 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_frame` separates "the capture is expensive" from "the capture made the compositor expensive". Read `/proc//stat` fields 14+15 (utime+stime, in clock ticks — divide by `os.sysconf("SC_CLK_TCK")`). If the file is unreadable, say so in `notes` rather than reporting zero. - `rss_peak_mb`: `resource.getrusage(RUSAGE_SELF).ru_maxrss` for a persistent route; `RUSAGE_CHILDREN` for 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 - `protocol` must name what really ran, not what you hoped: if `ext-image-copy-capture-v1` is unavailable and you fell back to `zwlr-screencopy-v1`, say so. If you had to fall back at runtime, say that too. - `persistent` separates "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_frame` is process CPU (`/proc/self/stat` utime+stime, or `getrusage`) 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: 1. **Geometry**: `--output ` (1280×720) and `--all` (2560×720). 2. **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. 3. **Mode**: `raw` and `jpeg`. 4. **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.