diff --git a/docs/usage/investigating-a-recording.md b/docs/usage/investigating-a-recording.md index bc09a7f0..ad2095ec 100644 --- a/docs/usage/investigating-a-recording.md +++ b/docs/usage/investigating-a-recording.md @@ -134,6 +134,7 @@ and `event:12.end` when it finished. | `motion [--region x,y,w,h]` | When, and how hard, a display or a region of it was moving: segments with start, duration, frame count, peak share of pixels changed and peak mean brightness delta (replaces scripting ffmpeg `tblend`) | | `framediff A B [--region ..] [--png FILE] [--against SESSION]` | How two frames differ: changed share, mean and peak brightness delta, the box of change, and a PNG with the changed pixels in red | | `blank --region x,y,w,h` | When a region was blank (one colour, named: `white`, `black`, a hex code) or frozen (identical to the frame before): "the window went white for 200 ms" | +| `measure [--region x,y,w,h] [--stat mean\|peak\|width] [--hz N] [--background 0-255]` | A statistic of a region on a fixed-rate timeline (default 30 Hz): each sample is the last frame shown at or before its time (the video has no fixed frame rate), with when that frame was shown. `mean` and `peak` are brightness 0 to 255; `width` is the *drawn width*: the horizontal extent, in display points, of the pixels that differ by more than 24 of 255 from the background (the most common brightness of the region, or `--background`), from the leftmost to the rightmost such column; 0 if none. Replaces ffmpeg scripts that crop and average. Samples with no frame (before the first one, or in a gap) are `null`. `--json` gives `measure/1` | | `compare A B` | Two recordings side by side: duration, frames, effective fps, worst frame gap, motion, findings by kind, annotations, and the difference | | `assert --check "KIND ARGS METRIC<=N"` | Pass/fail checks for a scripted scenario, repeatable. Kinds: `findings kind=K [severity=S] count<=N`, `log "" count==N`, `motion [region=x,y,w,h] [from=T] [to=T] segments\|active_ms\|peak_share<=N`, `blank region=x,y,w,h [from=T] [to=T] [color=white] ms<=N`, `annotations kind=note\|bug\|finding count>=N`. Operators `== != <= >= < >`. Prints `PASS`/`FAIL` per check; exit 0 if all pass, 6 if one fails, 4 if one cannot be measured (no video), 2 if malformed. `--json` gives `assert/1` | | `annotate`, `annotations` | Add, change and list bug regions, notes and findings | diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index cf3bdf2c..b1edb10d 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -106,7 +106,8 @@ locations as hints. `overview` says nothing about it. - To measure the picture instead of scripting `ffmpeg`: `motion` (when a display or `--region x,y,w,h` moved, and how hard), `framediff ` (what changed between two moments; `--png` shows where), - `blank --region x,y,w,h` (when a region went one colour, such as white, or froze) and + `blank --region x,y,w,h` (when a region went one colour, such as white, or froze), + `measure [--region x,y,w,h] [--stat mean|peak|width] [--hz N]` (mean or peak brightness, or drawn width, of a region on a fixed-rate timeline: the frame on screen at each sample time, so the numbers can be plotted or compared though the video has no fixed frame rate) and `compare ` (two recordings' frames, motion and findings side by side). Regions are in display points, the same as the `bbox_points` of `changes`. They need a host that can decode the video. - A session recorded with the window track (on by default; `--no-window-track` turns it off) has `windows.jsonl`: every top-level window's rect,