agvid 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Illia Puzanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# agvid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/agvid)](https://www.npmjs.com/package/agvid)
+[![license](https://img.shields.io/npm/l/agvid)](LICENSE)
+[![node](https://img.shields.io/node/v/agvid)](package.json)
+
+**Let coding agents watch video without drowning in frames.**
+
+`agvid` is a small CLI that turns a local video into a few timestamped JPEGs, labeled contact sheets, and a `manifest.json` that ties every image to its source time. An agent looks at a cheap overview first, then zooms in on the moments that matter.
+
+- **Progressive:** overview → find changes → inspect a window → grab one frame.
+- **Timestamped:** every tile is labeled with its timecode; the manifest maps files to source seconds.
+- **Screen-recording aware:** `changes` finds the moments where the UI actually changes.
+- **Crop and zoom:** cut a region at source resolution so small text stays legible.
+- **Bounded:** frame width capped at 640 px by default, runs at 240 frames, change scans at 300 s of source.
+- **No npm dependencies:** just Node.js and FFmpeg.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [Output](#output)
+- [Limitations](#limitations)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- Node.js 20+
+- FFmpeg 5.1+ (`ffmpeg` and `ffprobe` on `PATH`)
+
+## Install
+
+```sh
+npm install -g agvid
+```
+
+### Agent skill
+
+The package ships an agent skill, [`skill/agvid/SKILL.md`](skill/agvid/SKILL.md), with an [advanced reference](skill/agvid/references/advanced.md). Copy the whole directory into your agent's skills directory:
+
+```sh
+# Claude Code (user scope)
+mkdir -p ~/.claude/skills && cp -R "$(npm root -g)/agvid/skill/agvid" ~/.claude/skills/
+
+# Claude Code (project scope, from the project root)
+mkdir -p .claude/skills && cp -R "$(npm root -g)/agvid/skill/agvid" .claude/skills/
+
+# Codex
+mkdir -p ~/.codex/skills && cp -R "$(npm root -g)/agvid/skill/agvid" ~/.codex/skills/
+```
+
+Use the same Node and npm that installed agvid: nvm and Volta keep global packages per version.
+
+## Quick start
+
+```sh
+agvid probe demo.mov                                     # duration, size, fps, codec
+agvid overview demo.mov                                  # 12 evenly spaced frames + sheet
+agvid changes demo.mov                                   # frames where the picture changes
+agvid inspect demo.mov --around 00:07.5 --window 2s --fps 4
+agvid frame demo.mov --at 00:07.5
+agvid frame demo.mov --at 00:07.5 --crop 0.5,0,0.5,0.5   # zoom into the top-right quarter
+```
+
+Each image command prints where it wrote its files:
+
+```json
+{
+  "directory": "/repo/.agvid/runs/demo-overview",
+  "sheets": ["/repo/.agvid/runs/demo-overview/sheet-01.jpg"],
+  "manifest": "/repo/.agvid/runs/demo-overview/manifest.json",
+  "frames": 12
+}
+```
+
+## Commands
+
+| Command | What it does | Key options |
+| --- | --- | --- |
+| `probe <video>...` | Prints source metadata as JSON | `--video-stream` |
+| `overview <video>` | Evenly spaced frames | `--frames` (1–64, default 12), `--start`, `--end` |
+| `changes <video>` | Range start plus each frame where the picture changes | `--threshold`, `--max`, `--start`, `--end` |
+| `inspect <video>` | Frames at a fixed rate around a moment or over a range | `--around`, `--window` (default 2s), `--fps` (default 4), `--start`, `--end` |
+| `frame <video>` | Frames at exact moments | `--at` |
+
+Image commands accept `--crop`, `--width`, `--output` and `--video-stream`. Times accept seconds, `MM:SS.s` or `HH:MM:SS.s`; durations accept seconds with an optional `s`. A time shows the frame on screen then: the last frame at or before it. `--at` and `--around` take comma lists or repeated flags; each `--around` gets its own window and sheets. A run makes at most 240 frames.
+
+The [advanced reference](skill/agvid/references/advanced.md) covers exact detection settings, `--video-stream`, multi-file `probe`, unusual formats and timeline rules.
+
+### Crop
+
+`--crop x,y,w,h` takes fractions 0–1 of the displayed frame (left, top, width, height). Estimate them from a sheet tile: a button about 80% across and 40% down, roughly 15% wide and 20% tall, is `--crop 0.8,0.4,0.15,0.2`. The region is cut at source resolution before `--width` scaling, never enlarged, and must be at least 16×16 source pixels.
+
+### Change detection
+
+`changes` decodes the range once, samples up to 30 fps, and keeps the range start plus each frame where more than `--threshold` (default `0.002`) of the pixels changed in any RGB channel since the last detected change, at least `--min-gap` (default `0.5s`) apart.
+
+- **Small changes:** a cursor-sized box stays below the default threshold. `--crop` to the region or lower `--threshold`.
+- **Long videos:** `--analysis-budget` (default `300`) caps the source seconds one decode attempt may cover, so an oversized scan fails before decoding and says how to narrow `--start/--end`. It is not wall-clock time.
+- **Progress:** scans longer than 5 s report progress on stderr; stdout stays JSON.
+- **Truncation:** past `--max` (default 48) candidates, the strongest change of each time slice is kept so quiet stretches stay covered. Output reports `candidates` and `truncated`.
+
+`--analysis-fps` and `--analysis-width` trade decode time for sensitivity.
+
+## Output
+
+Each run writes to a fresh directory, `.agvid/runs/<video>-<command>[-N]/`, under the git root (else the current directory). `.agvid/` ignores itself in git. `--output DIR` picks another directory, which must be new or empty.
+
+```
+.agvid/runs/demo-overview/
+├── frame-0000_00-01.066.jpg
+├── ...
+├── sheet-01.jpg
+└── manifest.json
+```
+
+- **Frames:** JPEGs named `frame-<index>_<timecode>.jpg`, at most `--width` pixels wide (default 640, range 64–4096, never above the displayed width), aspect ratio preserved.
+- **Sheets:** `overview`, `inspect`, `changes`, and `frame` with several `--at` times write `sheet-01.jpg`, … with tiles labeled by timecode, at most 1568 px per side.
+- **Manifest:** `manifest.json` records the `command`, the `source` metadata, and every frame's `file`, requested `time` (seconds) and `timecode`. Depending on the command it also holds `sheets`, `crop`, `range`, `windows` and `detection`; `changes` frames add a `score`.
+
+```json
+{
+  "command": "changes",
+  "frames": [
+    { "file": "frame-0000_00-00.000.jpg", "time": 0, "timecode": "00:00.000", "score": null },
+    { "file": "frame-0001_00-00.717.jpg", "time": 0.7166666666666667, "timecode": "00:00.717", "score": 0.003955 }
+  ]
+}
+```
+
+A run holds `DIR/.agvid.lock`, so a concurrent run on the same directory fails. Errors, Ctrl-C and SIGTERM remove the run's files. A run killed outright leaves its lock and `.agvid.lock.work-*` staging directory; agvid never removes them, so delete them by hand once no agvid run uses the directory.
+
+## Limitations
+
+- **Frames are evidence for a moment, not frame-accurate.** FFmpeg seeking can land on a nearby frame for some codecs.
+- **Raw elementary streams** (`.h264`, `.m2v`) have no timestamps and are rejected. Wrap them first: `ffmpeg -r FPS -i video.h264 video.mp4`.
+- **MPEG-TS** decodes from the video start, and other formats retry from there when seeking finds no frame, so late times can be slow.
+- **No audio, subtitles or coordinate grids:** agvid covers visual inspection only.
+
+## Development
+
+```sh
+git clone https://github.com/zoilorys/agvid.git
+cd agvid
+npm link        # puts the checkout's agvid on PATH
+npm test
+npm pack --dry-run
+```
+
+To make the skill track your checkout, symlink it (this replaces any existing copy):
+
+```sh
+mkdir -p ~/.claude/skills && rm -rf ~/.claude/skills/agvid && ln -s "$PWD/skill/agvid" ~/.claude/skills/agvid
+```
+
+Tests run against real videos generated with FFmpeg and the fixture in `test/fixtures`.
+
+### Benchmark
+
+`scripts/benchmark.js` times every command, including Node startup, on the bundled fixture and a generated 20 s 1080p60 clip (`--video long` adds a 120 s one; clips are cached in `benchmark/.cache/`). `benchmark/baseline-src/` is a frozen copy of the CLI before the performance work, and `benchmark/baseline.json` holds its results:
+
+```sh
+# Recreate the baseline
+node scripts/benchmark.js --cli benchmark/baseline-src/bin/agvid.js --video bundled --video short --runs 3 --json benchmark/baseline.json
+
+# Compare the checkout against it
+node scripts/benchmark.js --video bundled --video short --runs 3 --compare benchmark/baseline.json
+```
+
+`--case` picks cases (`probe`, `overview12`, `overview48`, `frame1`, `frame5`, `inspect8`, `inspect100`, `changes`, `changesCrop`). Compare runs on the same machine under similar load.
+
+## License
+
+[MIT](LICENSE) © Illia Puzanov

package/bin/agvid.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`agvid: ${error.message}`);
+  process.exitCode = error.exitCode ?? 1;
+});

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "agvid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Video frames and metadata for coding agents",
+  "license": "MIT",
+  "author": "Illia Puzanov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoilorys/agvid.git"
+  },
+  "homepage": "https://github.com/zoilorys/agvid#readme",
+  "bugs": "https://github.com/zoilorys/agvid/issues",
+  "keywords": [
+    "video",
+    "ffmpeg",
+    "frames",
+    "cli",
+    "agents"
+  ],
+  "type": "module",
+  "bin": {
+    "agvid": "bin/agvid.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/skill/agvid/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: agvid
+description: Inspect local video clips with timecode-labeled frame sheets, change detection for screen recordings, short frame sequences, and source metadata using the agvid CLI.
+---
+
+# Inspect video with agvid
+
+Use when a task requires understanding a local video. Needs Node.js 20+ and FFmpeg/FFprobe 5.1+ on `PATH`. Look at cheap sheets first, then zoom in.
+
+1. `agvid probe video.mov` when source size matters: `start`/`end`/`duration`, displayed size, fps, codec.
+2. `agvid overview video.mov` writes 12 evenly spaced frames (`--frames 1-64`). Open the printed `sheets` first; each tile is labeled bottom-left with its timecode.
+3. Screen recording or UI flow: `agvid changes video.mov` writes the range start plus each frame where the picture changes. Use `--start/--end` on long videos and `--crop` for small UI changes; a cursor-sized change stays under the default `--threshold 0.002`. Its planned scan may span at most 300 s of source per decode attempt (`--analysis-budget`; not wall-clock time, and seeking back to a keyframe is extra) and it reports progress on stderr every 5 s. With more than `--max` (48) candidates, it keeps the strongest per time slice and prints `truncated: true`.
+4. Motion near a moment: `agvid inspect video.mov --around 00:07.5 --window 2s --fps 4` (`--window` is the total centered duration, clipped to the video), or `--start 00:05 --end 00:09` instead.
+5. One moment: `agvid frame video.mov --at 00:07.5`.
+
+Batch instead of repeating calls: `--at 1,4.5,9` and `--around 3,12` (comma lists or repeated flags). A run makes at most 240 frames.
+
+Zoom with `--crop x,y,w,h` on any image command: fractions 0-1 of the displayed frame (left, top, width, height). Estimate from a tile: a button about 80% across and 40% down, roughly 15% wide and 20% tall, is `--crop 0.8,0.4,0.15,0.2`. The crop is cut at source resolution before `--width` (default 640) scaling, so small text becomes legible.
+
+TIME is seconds, `MM:SS.s` or `HH:MM:SS.s`; DURATION is seconds with an optional `s`. A time shows the frame on screen then (the last frame at or before it). Image commands print JSON with `directory`, `manifest`, the frame count and `sheets` (omitted for a single-time `frame`); `manifest.json` maps each frame `file` to its requested `time` and `timecode`. Report observations with manifest times.
+
+Output goes to a fresh `.agvid/runs/<video>-<command>[-N]/` under the git root, or `--output DIR` (new or empty). If agvid reports a directory in use or holding a killed run's work, use another `--output`, or delete its `.agvid.lock` and `.agvid.lock.work-*` only when no agvid run is using it.
+
+Read [references/advanced.md](references/advanced.md) for exact change-detection settings and truncation, `--video-stream` and multi-file `probe`, MPEG-TS/AVI/raw streams, timeline and overlap rules, and crop/aspect details.

package/skill/agvid/references/advanced.md

@@ -0,0 +1,59 @@
+# agvid advanced reference
+
+Read this when the core workflow in `SKILL.md` is not enough: tuning `changes`, multi-stream files, unusual formats, exact timeline semantics, or a refused output directory.
+
+## Change detection
+
+`changes` decodes the range once and keeps source timestamps without resampling. It thins frames to at most `--analysis-fps` per second, scales them to `--analysis-width` wide with the area capped at 512×512 (`detection.analysis` holds the actual size), and compares RGB. A pixel counts as changed when any channel differs by more than 16/255 from the last detected candidate; the first reference is the frame on screen at the range start. A frame becomes a candidate when its changed-pixel share exceeds `--threshold` and it is at least `--min-gap` after the previous candidate.
+
+| Option | Default | Range | Effect |
+| --- | --- | --- | --- |
+| `--threshold` | `0.002` | above 0, up to 1 | changed-pixel share needed |
+| `--min-gap` | `0.5s` | 0–3600 s | spacing between candidates |
+| `--max` | `48` | 1–239 | changes kept (plus the range-start baseline) |
+| `--analysis-fps` | `30` | 1–60 | higher catches shorter changes, costs decode time |
+| `--analysis-width` | `256` | 64–512 | higher catches smaller changes |
+| `--analysis-budget` | `300` | 1–1000000 s | source seconds one decode attempt may cover |
+
+- **Small changes:** a cursor-sized box stays under the default threshold. `--crop` to the region (detection then runs on the crop) or lower `--threshold`.
+- **Truncation:** with at most `--max` candidates, all are kept. Otherwise the range is split into `--max` equal time slices, the strongest candidate of each slice is kept, and slots left by empty slices go to the strongest remaining candidates (earlier wins ties). A quiet late change is not crowded out by a busy stretch. Stdout reports `changes`, `candidates` and `truncated`; the manifest's `detection` adds `max`, `candidates`, `truncated` and `selection` (`method`, and when truncated `slices`, `sliceDuration`, `fromSlices`, `byScore`). Each frame has a `score` (`null` for the baseline).
+- **Budget:** `--analysis-budget DURATION` (default 300) limits the source seconds one decode attempt covers, from where it starts decoding to the range end. That start is the range start, or the video start for MPEG-TS, for a range starting within 0.5 s of the video start, and for the fallback taken when seeking finds no frame at the range start. An over-budget plan, including that fallback, fails before FFmpeg runs and says whether `--start/--end` or only `--end` narrows it. The budget is not wall-clock time, is not summed across attempts, and excludes decoding back to the keyframe before the range start. The manifest's `detection.scan` (`from`, `to`, `seconds`, `budget`) records the attempt that succeeded.
+- **Progress:** every 5 s a running scan writes `agvid changes: scanned T of END (P%), N candidates, Ss elapsed` to stderr. Stdout holds only the final JSON.
+
+## Timeline and evidence
+
+- Times are seconds on the container timeline, as players and `ffmpeg -ss` show them. The selected video stream spans probe `start` to `end`; `start` is above 0 when, for example, audio begins first.
+- `overview` and `changes` default to that span. `--start/--end` are clamped to it and the start must come before the end. `--at`/`--around` outside it fail. `--start/--end` replace `--around/--window` on `inspect`; combining them fails.
+- `--window` is the total centered duration, clipped to the span: `--around 7.5 --window 2s` covers 6.5–8.5 s.
+- A time shows the frame on screen then: the last frame at or before it. Manifest times are the requested times at full precision; `changes` times are exact source frame times. Filenames and sheet labels round to milliseconds. Report findings with manifest times. Seeking may land on a nearby frame for some codecs, so treat a frame as evidence for a moment.
+- `--at` values are deduped and sorted. Each `--around` keeps its own window (`windows[]`: `around`, `start`, `end`, the `frames` index range and `sheets`) and sheets, so overlapping windows repeat a moment as separate entries and files. Times that show the same source frame stay separate entries.
+
+## Crop and size
+
+- `--crop x,y,w,h` uses fractions of the displayed frame, after rotation and sample aspect ratio (SAR). It is cut at source resolution before `--width` scaling, never enlarged, and must cover at least 16×16 source pixels.
+- Output never exceeds the displayed width of the frame or crop in square pixels: SAR is applied to the coded horizontal axis, then rotation. A 160×90 source with SAR 1:2 gives at most 80×90, or 90×80 rotated 90 degrees.
+- The manifest's `crop` holds the requested fractions and `pixels`: the even stored-pixel `x`, `y`, `width`, `height` and the `displayed` size.
+
+## Streams and probe
+
+- `--video-stream N` picks the zero-based video stream, as in FFmpeg's `0:v:N` (default 0). This is not the container's absolute stream index: use 1 when, for example, stream 0 is cover art. `probe` reports `videoStream` and `streamIndex`; manifests record both in `source`.
+- `probe` prints the stream's `start`, `end`, `duration` (with `durationSource`), `containerStart`, displayed and coded size, `sar`, `rotation`, `fps`, `frameCount`, `codec`, `pixelFormat`, `bitDepth` and `hasAudio`.
+- `probe a.mov b.mov` prints an array in argument order. A failed file, including one without the requested stream, becomes `{ "video": "/abs/path", "error": "..." }`, and the exit code is 1.
+
+## Unusual formats
+
+- **MPEG-PS/TS:** spans come from a packet scan, because FFmpeg's estimate can stop short. MPEG-TS always decodes from the video start, so only `--end` reduces a `changes` budget.
+- **Seek fallback:** other formats retry from the video start when seeking finds no frame, so late times in sparse or oddly muxed files can be slow.
+- **Raw elementary streams** (`.h264`, `.m2v`) have no timestamps and are rejected. Wrap them first: `ffmpeg -r FPS -i video.h264 video.mp4`.
+- **AVI with B-frames:** FFmpeg rebuilds missing timestamps, so a cut at 1 s can read 1.04 s. Extraction uses the same timestamps, so that time still shows the changed frame.
+- **Variable frame rate and long holds:** a time inside a hold shows the held frame.
+
+## Output directory and locks
+
+- Each run writes a fresh `.agvid/runs/<video>-<command>[-N]/` under the git root (else cwd). `--output DIR` must be new or empty.
+- A run holds `DIR/.agvid.lock` (pid and host) and stages files in a private `DIR/.agvid.lock.work-*` directory. A concurrent run on the same directory fails. Errors, Ctrl-C and SIGTERM stop FFmpeg and remove the run's files and any directory it created.
+- A run killed outright (SIGKILL, crash) leaves its lock and staging directory. agvid never removes them itself. When it reports the directory in use or holding a killed run's work, first make sure no agvid run (check the pid in the lock) is still writing there, then delete `.agvid.lock` and `.agvid.lock.work-*` by hand, or use a new `--output`.
+
+## Requirements
+
+Node.js 20+ and FFmpeg/FFprobe 5.1+ on `PATH`: extraction and `changes` use `-fps_mode`. Run size is capped at 240 frames; `overview` takes 1–64 frames.

package/src/changes.js

@@ -0,0 +1,215 @@
+import { run, start } from './process.js';
+import { TIME_TOLERANCE, attempts, seekArgs, trimEnd } from './seek.js';
+import { checkBudget } from './plan.js';
+import { formatTimecode } from './time.js';
+
+const PIXEL_DELTA = 16;
+// Bounds one RGB analysis frame to 768 KiB however tall a crop is, and frames queued for their times to about 16 MiB.
+const ANALYSIS_PIXELS = 512 * 512;
+const PENDING_BYTES = 16 * 1024 * 1024;
+
+// One decode pass over the range: RGB source frames thinned to at most analysisFps/s (select keeps source pts;
+// no fps resampling), each scored as the share of pixels with any channel differing by more than 16/255 from the last reported frame
+// (initially the one on screen at the range start). -copyts keeps source pts; times come from showinfo's integer
+// pts and time base, since its pts_time can be rounded (%.6g in FFmpeg 5.1). Passing such a time to -ss selects that frame:
+// FFmpeg truncates -ss to microseconds, at or before the pts, then rounds it to the nearest tick of the stream time base.
+// Streams rawvideo; keeps only the reference frame and frames still waiting for their pts line.
+// changes uses -fps_mode (FFmpeg 5.1+). Unparseable versions, such as git builds, are let through.
+export async function requireFfmpeg51() {
+  const first = (await run('ffmpeg', ['-version'])).split('\n')[0];
+  const match = /^ffmpeg version n?(\d+)\.(\d+)/.exec(first);
+  if (match && (Number(match[1]) < 5 || (Number(match[1]) === 5 && Number(match[2]) < 1))) {
+    throw new Error(`changes needs FFmpeg 5.1 or newer, found ${match[1]}.${match[2]}; upgrade FFmpeg or use overview/inspect instead`);
+  }
+}
+
+// Even analysis size at most `analysisWidth` wide and ANALYSIS_PIXELS in area, keeping the source aspect ratio.
+function analysisSize(analysisWidth, sourceWidth, sourceHeight) {
+  const aspect = sourceHeight / sourceWidth;
+  const width = Math.max(2, Math.min(analysisWidth, Math.floor(Math.sqrt(ANALYSIS_PIXELS / aspect) / 2) * 2));
+  const height = Math.max(2, Math.min(Math.round(width * aspect / 2) * 2, Math.floor(ANALYSIS_PIXELS / width / 2) * 2));
+  return { width, height };
+}
+
+// Whether event a is kept over b: higher score, then the earlier time.
+const stronger = (a, b) => a.score > b.score || (a.score === b.score && a.time < b.time);
+
+// `progress` gets the attempt's decode start and span, each decoded frame's source time and the candidate count, for
+// progress reports. An attempt falling back to the video start must fit the budget too: it fails before it starts.
+function detectChanges(video, info, range, crop, settings, progress, attempt = 0) {
+  const { threshold, minGap, max, analysisFps, analysisWidth } = settings;
+  const { width, height } = analysisSize(analysisWidth, crop?.pixels.width ?? info.width, crop?.pixels.height ?? info.height);
+  const pixels = width * height;
+  const size = pixels * 3;
+  // Frames normally wait at most a pipe read for their showinfo time; a longer queue means pairing broke.
+  const maxPending = Math.max(8, Math.min(64, Math.floor(PENDING_BYTES / size)));
+  const cut = crop ? `crop=${crop.pixels.width}:${crop.pixels.height}:${crop.pixels.x}:${crop.pixels.y},` : '';
+  const plan = attempts(info, range.start);
+  const { slow, window } = plan[attempt];
+  const retry = attempt + 1 < plan.length;
+  // The baseline is the frame on screen at the range start, so frames up to it pass (from `window` before it);
+  // the last becomes the reference. Later frames are thinned to analysisFps. With copyts, trimming must use absolute
+  // source PTS and precede select/showinfo to keep frame/time pairing intact. Thread counts stay automatic: an output
+  // -threads:v 1 also made the filter graph single-threaded, scanning 1.4-1.8x slower with identical events.
+  const startPts = range.start + info.containerStart + TIME_TOLERANCE;
+  const before = Number.isFinite(window) ? `gte(t,${startPts - window})` : '1';
+  const select = `if(lte(t,${startPts}),${before},isnan(prev_selected_t)+gte(t-prev_selected_t,${1 / analysisFps - 1e-6}))`;
+  const args = ['-hide_banner', '-nostats', '-loglevel', 'info', ...seekArgs(slow, range.start), '-i', video,
+    '-map', `0:v:${info.videoStream}`, '-vf', `${trimEnd(info, range.end + info.containerStart)},${cut}select='${select}',scale=${width}:${height},format=rgb24,showinfo`,
+    '-fps_mode', 'passthrough', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'];
+  const from = slow ? info.start : range.start;
+  return new Promise((resolve, reject) => {
+    if (slow && !plan[0].slow) {
+      checkBudget(from, range.end, settings.budget, 'input seeking found no frame at the range start, so it is decoded from the video start');
+    }
+    Object.assign(progress, { from, seconds: range.end - from, time: from, candidates: 0 });
+    const child = start('ffmpeg', args);
+    const pendingFrames = [];
+    const pendingTimes = [];
+    // The `max` strongest candidates, strongest first, and the strongest in each of `max` equal slices of the range.
+    // Together they hold every event a truncated selection can keep (see findChanges).
+    const events = [];
+    const slices = new Array(max).fill(null);
+    let candidates = 0;
+    const errors = [];
+    // Set when this attempt found no frame at or before the range start; the next attempt replaces it.
+    let missed = false;
+    let failed;
+    let reference;
+    let lastReport = range.start;
+    let timeBase;
+    let partial = Buffer.alloc(size);
+    let filled = 0;
+    let line = '';
+    const score = (frame) => {
+      let changed = 0;
+      for (let i = 0; i < size; i += 3) {
+        if (Math.abs(frame[i] - reference[i]) > PIXEL_DELTA ||
+            Math.abs(frame[i + 1] - reference[i + 1]) > PIXEL_DELTA ||
+            Math.abs(frame[i + 2] - reference[i + 2]) > PIXEL_DELTA) changed++;
+      }
+      return changed / pixels;
+    };
+    const drain = () => {
+      while (!missed && pendingFrames.length && pendingTimes.length) {
+        const frame = pendingFrames.shift();
+        const time = pendingTimes.shift();
+        if (time <= range.start + TIME_TOLERANCE) { reference = frame; continue; }
+        if (!reference) {
+          if (retry) { missed = true; child.kill(); return; }
+          reference = frame;
+          continue;
+        }
+        if (!(time < range.end) || time - lastReport < minGap - 1e-9) continue;
+        const value = score(frame);
+        if (value > threshold) {
+          const event = { time, score: Math.round(value * 1e6) / 1e6 };
+          progress.candidates = ++candidates;
+          const index = events.findIndex((kept) => stronger(event, kept));
+          if (index >= 0) events.splice(index, 0, event);
+          else if (events.length < max) events.push(event);
+          if (events.length > max) events.pop();
+          const slice = Math.min(max - 1, Math.floor((time - range.start) / (range.end - range.start) * max));
+          if (!slices[slice] || stronger(event, slices[slice])) slices[slice] = event;
+          reference = frame;
+          lastReport = time;
+        }
+      }
+    };
+    child.stdout.on('data', (chunk) => {
+      if (missed) return;
+      for (let offset = 0; offset < chunk.length;) {
+        const count = Math.min(size - filled, chunk.length - offset);
+        chunk.copy(partial, filled, offset, offset + count);
+        filled += count;
+        offset += count;
+        if (filled === size) { pendingFrames.push(partial); partial = Buffer.alloc(size); filled = 0; }
+      }
+      drain();
+      if (pendingFrames.length > maxPending && !failed) {
+        failed = new Error('ffmpeg frame/pts mismatch: frames arrived without showinfo times');
+        child.kill();
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      const lines = (line + chunk).split('\n');
+      line = lines.pop();
+      for (const text of lines) {
+        if (/Parsed_showinfo/.test(text)) {
+          const base = /\bconfig in time_base:\s*(\d+)\/(\d+)/.exec(text);
+          if (base) timeBase = [Number(base[1]), Number(base[2])];
+          const match = /\bn:\s*\d+\s+pts:\s*(-?\d+)\s/.exec(text);
+          if (match && !timeBase && !failed) {
+            failed = new Error('ffmpeg showinfo logged no time base');
+            child.kill();
+          }
+          if (match && timeBase) {
+            progress.time = Number(match[1]) * timeBase[0] / timeBase[1] - info.containerStart;
+            pendingTimes.push(progress.time);
+          }
+          if (pendingTimes.length > 4096 && !failed) {
+            failed = new Error('ffmpeg frame/pts mismatch: showinfo times arrived without frames');
+            child.kill();
+          }
+        } else if (text.trim()) {
+          errors.push(text.trim());
+          if (errors.length > 20) errors.shift();
+        }
+      }
+      drain();
+    });
+    child.on('error', (error) => reject(new Error(`ffmpeg: ${error.message}`)));
+    child.on('close', (code) => {
+      if (missed) return resolve(detectChanges(video, info, range, crop, settings, progress, attempt + 1));
+      if (failed) return reject(failed);
+      if (code !== 0) return reject(new Error(`ffmpeg exited ${code}: ${errors.join('\n')}`));
+      drain();
+      if (missed) return resolve(detectChanges(video, info, range, crop, settings, progress, attempt + 1));
+      if (pendingFrames.length || pendingTimes.length || filled) {
+        return reject(new Error(`ffmpeg frame/pts mismatch: ${pendingFrames.length} frames and ${pendingTimes.length} times unpaired, ${filled} trailing bytes`));
+      }
+      if (!reference && retry) return resolve(detectChanges(video, info, range, crop, settings, progress, attempt + 1));
+      // A valid sparse range may contain no new PTS. Baseline extraction still validates its displayed frame.
+      resolve({ events, slices, candidates, from, width, height });
+    });
+  });
+}
+
+// Reports scan progress on stderr every PROGRESS_INTERVAL ms, so short scans stay quiet and stdout keeps only JSON.
+const PROGRESS_INTERVAL = 5000;
+
+// Detects changes in `range` per `settings` ({ threshold, minGap, max, analysisFps, analysisWidth, budget }) and
+// returns the kept { time, score } events in time order with the manifest's detection summary. Up to `max` candidates
+// are all kept. Beyond that, the strongest candidate of each of `max` equal slices of the range is kept, so quiet
+// stretches stay represented however strong one busy stretch is, and slots left by empty slices go to the strongest
+// remaining candidates.
+export async function findChanges({ video, info, range, crop, settings }) {
+  const { threshold, minGap, max, analysisFps, budget } = settings;
+  const began = Date.now();
+  const progress = {};
+  const timer = setInterval(() => {
+    const { from, seconds, time } = progress;
+    const share = Math.min(1, Math.max(0, (time - from) / seconds));
+    process.stderr.write(`agvid changes: scanned ${formatTimecode(Math.max(from, Math.min(range.end, time)))} of ${formatTimecode(range.end)}`
+      + ` (${Math.floor(share * 100)}%), ${progress.candidates} candidates, ${Math.round((Date.now() - began) / 1000)}s elapsed\n`);
+  }, PROGRESS_INTERVAL);
+  let result;
+  try { result = await detectChanges(video, info, range, crop, settings, progress); }
+  finally { clearInterval(timer); }
+  const { events, slices, candidates, from, ...analysis } = result;
+  const truncated = candidates > max;
+  let kept = events;
+  let selection = { method: 'all candidates' };
+  if (truncated) {
+    kept = slices.filter(Boolean);
+    const fromSlices = kept.length;
+    const chosen = new Set(kept);
+    for (const event of events) if (kept.length < max && !chosen.has(event)) kept.push(event);
+    selection = { method: 'strongest per time slice, then strongest remaining', slices: max, sliceDuration: (range.end - range.start) / max,
+      fromSlices, byScore: kept.length - fromSlices };
+  }
+  const detection = { metric: `RGB any-channel-diff>${PIXEL_DELTA}@${analysis.width}x${analysis.height}px,${analysisFps}fps vs last detected candidate`,
+    analysis: { ...analysis, fps: analysisFps }, threshold, minGap, max, candidates, truncated, selection,
+    scan: { from, to: range.end, seconds: range.end - from, budget } };
+  return { events: kept.sort((a, b) => a.time - b.time), detection };
+}