agvid 0.0.0-stage → 0.1.0

package/src/cli.js

@@ -0,0 +1,122 @@
+import { readFile, rename, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findChanges, requireFfmpeg51 } from './changes.js';
+import { extractFrames } from './media.js';
+import { outputDirectory, release, saveManifest } from './output.js';
+import { parseArgs, parseOptions, planRun, videoStreamOption } from './plan.js';
+import { probe } from './probe.js';
+import { cancel, cancellationError, cancelled, pool } from './process.js';
+import { buildSheets } from './sheets.js';
+
+export { displayedSize, parseCrop } from './geometry.js';
+export { resolveRange } from './plan.js';
+export { labelScale, planSheets, renderLabel, sheetLayout } from './sheets.js';
+export { formatTimecode, parseTime } from './time.js';
+
+const HELP = `agvid <command> <video> [options]
+
+Work progressively: probe, overview, changes (screen recordings), then inspect or frame.
+
+Commands:
+  probe <video>...               Source metadata as JSON; several videos print an array
+  overview <video>               Evenly spaced frames: --frames N (1-64, default 12)
+  changes <video>                Range start plus each frame where the picture changes
+  inspect <video> --around TIME [--window DURATION] [--fps N]
+  inspect <video> --start TIME --end TIME [--fps N]
+                                 Frames at --fps (default 4) in a centered window (total, default 2s) or range
+  frame <video> --at TIME        The frame on screen at each time
+
+Options:
+  --start TIME --end TIME   Limit overview, changes or inspect to a range
+  --crop X,Y,W,H            Region as fractions 0-1 of the displayed frame (left, top, width, height)
+  --width PX                Maximum frame width, 64-4096, default 640
+  --output DIR              New or empty directory; default .agvid/runs/ under the git root (else cwd)
+  --video-stream N          Zero-based video stream (0:v:N), default 0; works with probe too
+
+changes tuning: --threshold X (changed-pixel share, default 0.002), --min-gap DURATION (0.5s),
+--max N (48, up to 239), --analysis-fps N (30, 1-60), --analysis-width PX (256, 64-512),
+--analysis-budget DURATION (300s: source video per decode attempt). Progress goes to stderr
+every 5s; past --max candidates it keeps the strongest per time slice and reports truncated: true.
+
+TIME is seconds, MM:SS.s or HH:MM:SS.s; DURATION is seconds with an optional s. --at and --around take
+comma lists or repeat; a run makes at most 240 frames. A time shows the last frame at or before it,
+and the manifest records the requested time. Writes JPEG frames, timecode-labeled sheets and
+manifest.json, and prints their paths as JSON. A killed run leaves DIR/.agvid.lock; if no agvid run
+uses DIR, delete it and any .agvid.lock.work-* directories. Needs Node 20+ and FFmpeg/FFprobe 5.1+.
+Details: README.md and skill/agvid/references/advanced.md in the package.`;
+
+export async function main(args) {
+  if (args.length === 0 || ['--help', '-h', 'help'].includes(args[0])) {
+    console.log(HELP);
+    return;
+  }
+  if (args[0] === '--version' || args[0] === '-v') {
+    const pkg = JSON.parse(await readFile(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+  const parsed = parseArgs(args, HELP);
+  process.on('SIGINT', cancel);
+  process.on('SIGTERM', cancel);
+  try { await execute(parsed); }
+  catch (error) { throw cancelled ? cancellationError() : error; }
+  finally {
+    process.off('SIGINT', cancel);
+    process.off('SIGTERM', cancel);
+  }
+}
+
+async function execute({ command, video, videos, options }) {
+  const videoStream = videoStreamOption(options['video-stream'] ?? '0');
+  if (command === 'probe') {
+    if (videos.length === 1) {
+      console.log(JSON.stringify(await probe(videos[0], videoStream), null, 2));
+      return;
+    }
+    const results = await pool(videos, Math.min(os.availableParallelism(), 8),
+      (file) => probe(file, videoStream).catch((error) => ({ video: file, error: error.message })));
+    if (cancelled) throw cancellationError();
+    if (results.some((entry) => 'error' in entry)) process.exitCode = 1;
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  const parsed = parseOptions(command, options);
+  const info = await probe(video, videoStream);
+  const { crop, width, range, settings, windows, ...plan } = planRun(command, options, info, parsed);
+  if (settings) await requireFfmpeg51();
+  // Claimed before change detection, so an unusable output fails before the scan.
+  const output = await outputDirectory(video, command, options.output);
+  const { directory, work } = output;
+  const produced = [];
+  try {
+    let { times } = plan;
+    let scores;
+    let detection;
+    if (settings) {
+      const changes = await findChanges({ video, info, range, crop, settings });
+      times = [range.start, ...changes.events.map((event) => event.time)];
+      scores = [null, ...changes.events.map((event) => event.score)];
+      ({ detection } = changes);
+    }
+    const frames = await extractFrames({ video, info, times, width, crop, directory: work, produced, command, windows });
+    if (scores) frames.forEach((frame, i) => { frame.score = scores[i]; });
+    const sheets = command !== 'frame' || frames.length > 1
+      ? await buildSheets({ directory: work, frames, windows, width, info, crop, produced }) : undefined;
+    // No FFmpeg runs past here, so honor a cancellation that arrived during the last steps before committing.
+    if (cancelled) throw cancellationError();
+    for (const file of [...frames.map((frame) => frame.file), ...(sheets ?? []).map((sheet) => sheet.file)]) {
+      produced.push(path.join(directory, file));
+      await rename(path.join(work, file), path.join(directory, file));
+    }
+    produced.push(path.join(directory, 'manifest.json.tmp'), path.join(directory, 'manifest.json'));
+    const manifest = await saveManifest(directory, { command, source: info, outputWidth: width, ...(crop ? { crop } : {}), ...(range && (options.start !== undefined || options.end !== undefined) ? { range } : {}), ...(detection ? { detection } : {}), frames, ...(windows ? { windows } : {}), ...(sheets ? { sheets } : {}) });
+    await rm(work, { recursive: true, force: true });
+    await rm(output.lock, { force: true });
+    console.log(JSON.stringify({ directory, ...(sheets ? { sheets: sheets.map((sheet) => path.join(directory, sheet.file)) } : {}), manifest, frames: frames.length, ...(detection ? { changes: frames.length - 1, candidates: detection.candidates, truncated: detection.truncated } : {}) }, null, 2));
+  } catch (error) {
+    await release(output, produced);
+    throw error;
+  }
+}

package/src/geometry.js

@@ -0,0 +1,31 @@
+// Parses --crop fractions and maps them to even pixel offsets and sizes in the source's displayed orientation.
+// FFmpeg auto-rotates before -vf. SAR stretches one displayed axis uniformly, so equal fractions of stored pixels
+// still name the displayed region; `displayed` is that region's size in square pixels (see displayedSize).
+export function parseCrop(value, info) {
+  const parts = String(value).split(',');
+  const numbers = parts.map((part) => (/^\s*\d*\.?\d+\s*$/.test(part) ? Number(part) : NaN));
+  if (parts.length !== 4 || numbers.some((n) => !Number.isFinite(n) || n < 0 || n > 1)) {
+    throw new Error(`--crop must be four fractions from 0 to 1 (x,y,w,h): ${value}`);
+  }
+  const [x, y, w, h] = numbers;
+  if (w <= 0 || h <= 0) throw new Error(`--crop width and height must be above 0: ${value}`);
+  if (x + w > 1 + 1e-9 || y + h > 1 + 1e-9) throw new Error(`--crop region must fit in the frame (x+w and y+h at most 1): ${value}`);
+  const axis = (start, size, total) => {
+    const offset = Math.floor(start * total / 2) * 2;
+    return [offset, Math.min(Math.round(size * total / 2) * 2, Math.floor((total - offset) / 2) * 2)];
+  };
+  const [px, width] = axis(x, w, info.width);
+  const [py, height] = axis(y, h, info.height);
+  if (width < 16 || height < 16) throw new Error(`--crop region is ${width}x${height} source pixels; it must be at least 16x16`);
+  return { x, y, w, h, pixels: { x: px, y: py, width, height, displayed: displayedSize(width, height, info) } };
+}
+
+// Square-pixel size of width x height stored pixels in displayed orientation. SAR scales the coded horizontal axis,
+// keeping the other at stored resolution; after a 90/270 turn that axis is displayed vertically. info.sar is
+// rotation-adjusted (inverted on a turn, as FFmpeg's transpose does), so dividing by it applies the coded SAR.
+export function displayedSize(width, height, info) {
+  const sar = info.sar ?? 1;
+  return info.rotation === 90 || info.rotation === 270
+    ? { width, height: Math.max(2, Math.round(height / sar)) }
+    : { width: Math.max(2, Math.round(width * sar)), height };
+}

package/src/media.js

@@ -0,0 +1,163 @@
+import { copyFile, rename } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { nonempty } from './output.js';
+import { cancellationError, cancelled, lines, pool, run } from './process.js';
+import { TICK, TIME_TOLERANCE, attempts, seekArgs, trimEnd } from './seek.js';
+import { formatTimecode } from './time.js';
+
+// setpts numbers the kept frames in whole seconds, the encoder's time base, so frames sharing a source pts (which the
+// JPEG encoder rejects as invalid timestamps) reach it in decode order; select and showinfo before it see source pts.
+function filters(width, crop) {
+  const cut = crop ? `crop=${crop.pixels.width}:${crop.pixels.height}:${crop.pixels.x}:${crop.pixels.y},` : '';
+  return `setpts=N/TB,${cut}scale=${width}:max(2\\,round(${width}/dar/2)*2),setsar=1`;
+}
+
+async function extract(video, info, time, width, filename, crop, decoding) {
+  const target = time + info.containerStart + TIME_TOLERANCE;
+  let emptyError;
+  // A time before the first decoded frame (AVI rebuilds pts from dts, delaying it) shows that first frame.
+  for (const { slow, window } of [...attempts(info, time), { slow: true, window: 0 }]) {
+    const select = window === 0 ? '' : `${trimEnd(info, target)},select='${Number.isFinite(window) ? `between(t,${target - window},${target})` : `lte(t,${target})`}',`;
+    try {
+      // image2 -update rewrites the file per kept frame, leaving the last one at or before `time` (of frames sharing a
+      // pts, the last decoded). Passthrough keeps
+      // every kept frame; the default constant-rate sync drops a VFR frame that lands in the same output tick.
+      await run('ffmpeg', ['-hide_banner', '-loglevel', 'error', ...decoding, ...seekArgs(slow, time), '-i', video, '-map', `0:v:${info.videoStream}`, ...(window === 0 ? ['-frames:v', '1'] : []), '-vf', `${select}${filters(width, crop)}`, '-fps_mode', 'passthrough', '-enc_time_base:v', '1', '-update', '1', '-threads:v', '1', '-q:v', '4', '-y', filename]);
+    } catch (error) {
+      // FFmpeg 8 can fail to initialize MJPEG at EOF when seeking yielded no decoded frame.
+      if (await nonempty(filename) || !/Non full-range YUV[\s\S]*Could not open encoder before EOF/.test(error.message)) throw error;
+      emptyError ??= error;
+    }
+    if (await nonempty(filename)) return;
+  }
+  if (emptyError) throw emptyError;
+}
+
+// Dense times (consecutive ones at most DENSE_GAP apart) share one decode, split into chunks of at least CHUNK_SPAN
+// seconds so several can run at once. Wider gaps seek per time instead, skipping the frames between.
+const DENSE_GAP = 1;
+const CHUNK_SPAN = 1;
+// Packets are listed past the last time by this much: decode order can put frames shown before it after later ones.
+const REORDER = 1;
+
+function denseChunks(info, times) {
+  const groups = [];
+  for (const [i, time] of times.entries()) {
+    if (i && time - times[i - 1] <= DENSE_GAP) groups.at(-1).push(time);
+    else groups.push([time]);
+  }
+  return groups.filter((group) => group.length > 1).flatMap((group) => {
+    // Every chunk of a group decoded from the origin (MPEG-TS, near the start) would decode the same frames again.
+    if (attempts(info, group.at(-1))[0].slow) return [group];
+    const count = Math.max(1, Math.min(group.length >> 1, Math.floor((group.at(-1) - group[0]) / CHUNK_SPAN)));
+    return Array.from({ length: count }, (_, k) => group.slice(Math.round(k * group.length / count), Math.round((k + 1) * group.length / count)));
+  });
+}
+
+// Extracts the frames shown at `times` (sorted, unique) in one decode from the keyframe before the first (or the
+// origin, where `extract` would decode from there), encoding each shown frame once. The frame shown at a time needs
+// the next frame's pts to recognize, so a demux-only packet listing guesses the shown pts and select keeps exactly
+// those: every frame at a kept pts, as frames sharing one show the last decoded. showinfo before select reports every
+// frame decoded up to the trim end, so each guess is checked against every frame that could be shown, including any
+// the listing missed (stopping after as many frames as guesses could cut that evidence short). Returns Map time =>
+// file for the verified times; the caller extracts the rest one by one.
+async function extractChunk(video, info, times, width, crop, decoding, directory, prefix, produced) {
+  const slow = attempts(info, times[0])[0].slow;
+  const target = (time) => time + info.containerStart + TIME_TOLERANCE;
+  const end = target(times.at(-1));
+  const listed = [];
+  let untimed = false;
+  await lines('ffprobe', ['-v', 'error', '-select_streams', `v:${info.videoStream}`, '-read_intervals',
+    `${slow ? '' : Math.max(0, target(times[0]) - REORDER)}%${end + REORDER}`, '-show_entries', 'packet=pts,flags', '-of', 'csv=p=0', video],
+  'stdout', (line) => {
+    // Discarded packets (before an edit list start) decode to no frame.
+    const [, pts, flags] = /^(-?\d+|N\/A),(\S*)$/.exec(line.trim()) ?? [];
+    if (pts === 'N/A') untimed = true;
+    if (pts !== undefined && !flags.includes('D') && Number.isSafeInteger(Number(pts))) listed.push(Number(pts));
+  });
+  // The last pts at or before a time, as select's t compares it: pts times the time base as a double.
+  const shown = (candidates, tick, time) => candidates.reduce((best, pts) => (pts * tick <= target(time) && !(pts <= best) ? pts : best), undefined);
+  const guesses = [...new Set(times.map((time) => shown(listed, info[TICK], time)).filter((pts) => pts !== undefined))].sort((a, b) => a - b);
+  // Without every pts (AVI rebuilds reordered frames' pts from dts) guesses would miss; those times seek instead.
+  if (untimed || !guesses.length) return new Map();
+  const file = (k) => path.join(directory, `${prefix}-${String(k).padStart(4, '0')}.jpg`);
+  const kept = new Set(guesses);
+  const files = Array.from({ length: listed.filter((pts) => kept.has(pts)).length }, (_, k) => file(k));
+  produced.push(...files);
+  const decoded = [];
+  const encoded = [];
+  let timeBase;
+  await lines('ffmpeg', ['-hide_banner', '-nostats', '-loglevel', 'info', ...decoding, ...seekArgs(slow, times[0]), '-i', video,
+    '-map', `0:v:${info.videoStream}`, '-vf', `${trimEnd(info, end)},showinfo=checksum=0,select='${guesses.map((pts) => `eq(pts,${pts})`).join('+')}',showinfo=checksum=0,${filters(width, crop)}`,
+    '-fps_mode', 'passthrough', '-enc_time_base:v', '1', '-threads:v', '1', '-q:v', '4', '-start_number', '0', '-y',
+    path.join(directory, `${prefix}-%04d.jpg`)], 'stderr', (line) => {
+    const [, filter, rest] = /\[Parsed_showinfo_(\d+) @ [^\]]*\] (.*)/.exec(line) ?? [];
+    if (filter === undefined) return;
+    timeBase = /^config in time_base:\s*(\d+)\/(\d+)/.exec(rest)?.slice(1).map(Number) ?? timeBase;
+    const pts = /^n:\s*\d+\s+pts:\s*(-?\d+)\s/.exec(rest)?.[1];
+    if (pts !== undefined) (filter === '1' ? decoded : encoded).push(Number(pts));
+  });
+  // Frames the listing missed add files beyond those expected; the run's work directory is removed whole regardless.
+  for (let k = files.length; k < encoded.length; k++) produced.push(files[k] = file(k));
+  const result = new Map();
+  if (!timeBase?.[1]) return result;
+  for (const time of times) {
+    const pts = shown(decoded, timeBase[0] / timeBase[1], time);
+    const k = pts === undefined ? -1 : encoded.lastIndexOf(pts);
+    if (k >= 0 && k < files.length && await nonempty(files[k])) result.set(time, files[k]);
+  }
+  return result;
+}
+
+// Extracts the frame on screen at each of `times` into `directory`, at most `width` wide, and returns { file, time,
+// timecode } entries in the order of `times`. Every file it expects to write is added to `produced` before
+// FFmpeg starts. Equal times are extracted once and copied. Dense inspect times are decoded in chunks, choosing each
+// shown frame before encoding; other times, and any a chunk could not verify, seek per time.
+export async function extractFrames({ video, info, times, width, crop, directory, produced, command }) {
+  const unique = [...new Set(times)].sort((a, b) => a - b);
+  const cores = os.availableParallelism();
+  // Concurrent jobs share the cores between their decoders; one job keeps FFmpeg's automatic count. On 16 cores this
+  // made multi-frame runs 8-18% faster, while one decoder thread per job slowed long-GOP single frames 2x.
+  const share = (count) => {
+    const jobs = Math.min(count, cores, 8);
+    return { jobs, decoding: jobs > 1 ? ['-threads', String(Math.max(1, Math.floor(cores / jobs)))] : [] };
+  };
+  const names = times.map((time, i) => `frame-${String(i).padStart(4, '0')}_${formatTimecode(time).replaceAll(':', '-')}.jpg`);
+  const sources = new Map();
+  const chunks = command === 'inspect' ? denseChunks(info, unique) : [];
+  if (chunks.length) {
+    const { jobs, decoding } = share(chunks.length);
+    await pool(chunks, jobs, async (chunk, c) => {
+      let found;
+      try { found = await extractChunk(video, info, chunk, width, crop, decoding, directory, `.chunk-${String(c).padStart(3, '0')}`, produced); }
+      catch {
+        if (cancelled) throw cancellationError();
+        return;
+      }
+      for (const [time, file] of found) sources.set(time, file);
+    });
+  }
+  const rest = unique.filter((time) => !sources.has(time));
+  const { jobs, decoding } = share(rest.length);
+  await pool(rest, jobs, async (time) => {
+    const target = path.join(directory, names[times.indexOf(time)]);
+    produced.push(target);
+    await extract(video, info, time, width, target, crop, decoding);
+    if (!(await nonempty(target))) throw new Error(`FFmpeg produced no frame for ${time}s`);
+    sources.set(time, target);
+  });
+  // The first entry showing a file takes it; later ones (equal times, or times sharing a shown frame) get copies.
+  const placed = new Map();
+  for (const [i, time] of times.entries()) {
+    const source = sources.get(time);
+    const target = path.join(directory, names[i]);
+    if (source !== target) {
+      produced.push(target);
+      if (placed.has(source)) await copyFile(placed.get(source), target);
+      else await rename(source, target);
+    }
+    if (!placed.has(source)) placed.set(source, target);
+  }
+  return times.map((time, i) => ({ file: names[i], time, timecode: formatTimecode(time) }));
+}

package/src/output.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, readdir, rename, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+async function findProjectRoot(cwd) {
+  for (let dir = cwd; ; dir = path.dirname(dir)) {
+    try { await stat(path.join(dir, '.git')); return dir; }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+    if (path.dirname(dir) === dir) return cwd;
+  }
+}
+
+// Removes the empty parents of `directory` that mkdir created, up to and including `first`.
+async function removeParents(directory, first) {
+  if (!first) return;
+  for (let dir = path.dirname(directory); ; dir = path.dirname(dir)) {
+    try { await rmdir(dir); }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTEMPTY') throw error; }
+    if (dir === first || path.dirname(dir) === dir) return;
+  }
+}
+
+const LOCK = '.agvid.lock';
+const WORK = `${LOCK}.work-`;
+
+// Claims `directory` for this run by exclusively creating a lock file holding its pid and host. Whichever run creates
+// it first owns the directory. agvid never removes a lock it did not create: a killed run's lock stays until someone
+// deletes it by hand, because no automatic staleness check is safe against pid reuse, other hosts and stalled runs.
+async function claim(directory) {
+  const lock = path.join(directory, LOCK);
+  let handle;
+  try { handle = await open(lock, 'wx'); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const [pid, host] = (await readFile(lock, 'utf8').catch(() => '')).split('\n');
+    const holder = pid ? ` (pid ${pid} on ${host || 'an unknown host'})` : '';
+    throw Object.assign(new Error(`output directory is in use by another agvid run${holder}: ${directory}\n`
+      + `agvid never removes a lock it did not create. If no agvid run is using it, delete ${lock} and any ${WORK}* `
+      + 'directories beside it, then retry.'), { inUse: true });
+  }
+  try { await handle.writeFile(`${process.pid}\n${os.hostname()}\n`); }
+  catch (error) { await handle.close().catch(() => {}); await unlink(lock).catch(() => {}); throw error; }
+  await handle.close();
+  return lock;
+}
+
+// Adds a work directory private to this run, where its FFmpeg writes. FFmpeg survives a SIGKILL of agvid, so finished
+// files are moved into place only once this run's FFmpeg has exited; an orphan keeps writing only into its own run's
+// work directory. Work left by killed runs is never removed automatically: its name alone does not prove agvid made it.
+async function workspace(output) {
+  const work = path.join(output.directory, `${WORK}${randomUUID()}`);
+  try { await mkdir(work); }
+  catch (error) { await release(output, []); throw error; }
+  return { ...output, work };
+}
+
+// Returns the claimed output directory: { directory, lock, work, created, firstParent }.
+export async function outputDirectory(video, command, requested) {
+  if (requested) {
+    const directory = path.resolve(requested);
+    const firstParent = await mkdir(path.dirname(directory), { recursive: true });
+    let created = true;
+    try { await mkdir(directory); }
+    catch (error) {
+      if (error.code !== 'EEXIST') { await removeParents(directory, firstParent); throw error; }
+      created = false;
+    }
+    // A competing run that claimed the directory first owns it, even if this run created it. That run treats it as
+    // pre-existing, so if it fails the directory stays, empty; removing it here instead could race with its files.
+    const lock = await claim(directory).catch(async (error) => {
+      if (created && !error.inUse) await rmdir(directory).then(() => removeParents(directory, firstParent)).catch(() => {});
+      throw error;
+    });
+    const other = created ? [] : (await readdir(directory)).filter((name) => name !== LOCK);
+    if (other.length) {
+      await rm(lock, { force: true });
+      if (other.every((name) => name.startsWith(WORK))) {
+        throw new Error(`output directory holds work left by a killed agvid run: ${directory}\n`
+          + `If no agvid run is using it, delete ${other.join(', ')} and retry.`);
+      }
+      throw new Error(`output directory is not empty: ${directory}`);
+    }
+    return workspace({ directory, lock, created, firstParent: created ? firstParent : undefined });
+  }
+  const agvid = path.join(await findProjectRoot(process.cwd()), '.agvid');
+  const root = path.join(agvid, 'runs');
+  try {
+    await mkdir(root, { recursive: true });
+    try { await writeFile(path.join(agvid, '.gitignore'), '*\n', { flag: 'wx' }); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  } catch (error) {
+    throw new Error(`cannot write output under ${agvid} (${error.code ?? error.message}); pass --output DIR`);
+  }
+  const base = `${path.parse(video).name.replace(/[^a-zA-Z0-9._-]/g, '_')}-${command}`;
+  for (let suffix = 0; ; suffix++) {
+    const directory = path.join(root, suffix ? `${base}-${suffix}` : base);
+    try {
+      await mkdir(directory);
+    } catch (error) {
+      if (error.code === 'EEXIST') continue;
+      throw error;
+    }
+    const lock = await claim(directory).catch(async (error) => { await rmdir(directory).catch(() => {}); throw error; });
+    return workspace({ directory, lock, created: true });
+  }
+}
+
+// Deletes this run's files, then its lock, then the directory and parents it created if nothing else is in them.
+export async function release({ directory, lock, work, created, firstParent }, produced) {
+  if (work) await rm(work, { recursive: true, force: true }).catch(() => {});
+  await Promise.all(produced.map((file) => rm(file, { force: true }).catch(() => {})));
+  await rm(lock, { force: true }).catch(() => {});
+  if (created) await rmdir(directory).then(() => removeParents(directory, firstParent)).catch(() => {});
+}
+
+export async function nonempty(filename) {
+  try { return (await stat(filename)).size > 0; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function saveManifest(directory, result) {
+  const filename = path.join(directory, 'manifest.json');
+  const temporary = path.join(directory, 'manifest.json.tmp');
+  await writeFile(temporary, `${JSON.stringify(result, null, 2)}\n`);
+  await rename(temporary, filename);
+  return filename;
+}

package/src/plan.js

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import { displayedSize, parseCrop } from './geometry.js';
+import { SOURCE_FORMAT, attempts } from './seek.js';
+import { formatTimecode, parseTime } from './time.js';
+
+const OPTIONS = {
+  overview: new Set(['frames', 'start', 'end', 'crop', 'width', 'output', 'video-stream']),
+  inspect: new Set(['around', 'window', 'fps', 'start', 'end', 'crop', 'width', 'output', 'video-stream']),
+  frame: new Set(['at', 'crop', 'width', 'output', 'video-stream']),
+  changes: new Set(['start', 'end', 'crop', 'threshold', 'min-gap', 'max', 'analysis-fps', 'analysis-width', 'analysis-budget', 'width', 'output', 'video-stream']),
+  probe: new Set(['video-stream']),
+};
+
+const MULTI = new Set(['at', 'around']);
+
+const ANALYSIS_FPS = 30;
+const ANALYSIS_WIDTH = 256;
+// Seconds of source video changes may decode unless --analysis-budget allows more.
+const ANALYSIS_BUDGET = 300;
+
+function numberOption(value, name, min, max, integer = false) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < min || number > max || (integer && !Number.isInteger(number))) {
+    throw new Error(`--${name} must be ${integer ? 'an integer' : 'a number'} from ${min} to ${max}`);
+  }
+  return number;
+}
+
+export function videoStreamOption(value) {
+  if (!/^(0|[1-9]\d*)$/.test(String(value)) || !Number.isSafeInteger(Number(value))) {
+    throw new Error('--video-stream must be a non-negative integer');
+  }
+  return Number(value);
+}
+
+// Resolves optional --start/--end (TIME strings or seconds) to { start, end } seconds within the video's span on the
+// container timeline.
+export function resolveRange(options, info) {
+  const seconds = (value) => (typeof value === 'number' ? value : parseTime(value));
+  const start = options.start === undefined ? info.start : Math.max(info.start, seconds(options.start));
+  const end = options.end === undefined ? info.end : Math.min(info.end, seconds(options.end));
+  if (start >= info.end) throw new Error(`--start ${formatTimecode(start)} must be before the video ends`);
+  if (start >= end) throw new Error(`--start ${formatTimecode(start)} must be before --end ${formatTimecode(end)}`);
+  return { start, end };
+}
+
+// Splits argv into { command, video | videos, options }; `help` is appended to usage errors.
+export function parseArgs(args, help) {
+  const [command, ...rest] = args;
+  if (!OPTIONS[command]) throw new Error(`unknown command: ${command ?? ''}\n\n${help}`);
+  const options = {};
+  let video;
+  const videos = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg.startsWith('--')) {
+      const equals = arg.indexOf('=');
+      const key = equals < 0 ? arg.slice(2) : arg.slice(2, equals);
+      const name = `--${key}`;
+      if (!OPTIONS[command].has(key)) throw new Error(`unknown option: ${name}`);
+      if (!MULTI.has(key) && options[key] !== undefined) throw new Error(`duplicate option: ${name}`);
+      const value = equals < 0 ? rest[++i] : arg.slice(equals + 1);
+      if (!value || (equals < 0 && value.startsWith('--'))) throw new Error(`missing value for ${name}`);
+      if (MULTI.has(key)) {
+        const items = value.split(',');
+        if (items.some((item) => !item)) throw new Error(`empty item in ${name}: ${value}`);
+        (options[key] ??= []).push(...items);
+      } else options[key] = value;
+    } else if (command === 'probe') videos.push(arg);
+    else if (!video) video = arg;
+    else throw new Error(`unexpected argument: ${arg}`);
+  }
+  if (command === 'probe') {
+    if (!videos.length) throw new Error(`missing video path\n\n${help}`);
+    return { command, videos: videos.map((file) => path.resolve(file)), options };
+  }
+  if (!video) throw new Error(`missing video path\n\n${help}`);
+  return { command, video: path.resolve(video), options };
+}
+
+// Validates a command's source-independent options (numbers, times, crop syntax and option combinations) before
+// anything runs, and returns them parsed for planRun.
+export function parseOptions(command, options) {
+  // A huge nominal frame checks --crop syntax; planRun checks its pixel size against the source.
+  if (options.crop !== undefined) parseCrop(options.crop, { width: 2 ** 30, height: 2 ** 30 });
+  const time = (name) => (options[name] === undefined ? undefined : parseTime(options[name]));
+  const parsed = { width: numberOption(options.width ?? 640, 'width', 64, 4096, true), start: time('start'), end: time('end') };
+  if (parsed.start >= parsed.end) throw new Error(`--start ${formatTimecode(parsed.start)} must be before --end ${formatTimecode(parsed.end)}`);
+  if (command === 'overview') parsed.count = numberOption(options.frames ?? 12, 'frames', 1, 64, true);
+  if (command === 'inspect') {
+    parsed.ranged = options.start !== undefined || options.end !== undefined;
+    if (parsed.ranged && (options.around !== undefined || options.window !== undefined)) throw new Error('--start/--end cannot be combined with --around/--window');
+    if (!parsed.ranged && options.around === undefined) throw new Error('inspect requires --around or --start/--end');
+    parsed.fps = numberOption(options.fps ?? 4, 'fps', 0.1, 60);
+    if (!parsed.ranged) {
+      parsed.arounds = [...new Set(options.around.map(parseTime))].sort((a, b) => a - b);
+      parsed.window = numberOption(parseTime(options.window ?? '2s'), 'window', 0.001, 3600);
+    }
+  }
+  if (command === 'changes') {
+    const threshold = Number(options.threshold ?? 0.002);
+    if (!(threshold > 0 && threshold <= 1)) throw new Error('--threshold must be a fraction above 0 and at most 1');
+    parsed.settings = {
+      threshold,
+      minGap: numberOption(parseTime(options['min-gap'] ?? '0.5'), 'min-gap', 0, 3600),
+      // One of the 240 frames is the range-start baseline.
+      max: numberOption(options.max ?? 48, 'max', 1, 239, true),
+      analysisFps: numberOption(options['analysis-fps'] ?? ANALYSIS_FPS, 'analysis-fps', 1, 60),
+      analysisWidth: numberOption(options['analysis-width'] ?? ANALYSIS_WIDTH, 'analysis-width', 64, 512, true),
+      budget: numberOption(parseTime(options['analysis-budget'] ?? String(ANALYSIS_BUDGET)), 'analysis-budget', 1, 1e6),
+    };
+  }
+  if (command === 'frame') {
+    if (options.at === undefined) throw new Error('frame requires --at');
+    // [time, as given] pairs, deduped by time and sorted.
+    parsed.at = [...new Map(options.at.map((value) => [parseTime(value), value]))].sort(([a], [b]) => a - b);
+    if (parsed.at.length > 240) throw new Error('frame would create over 240 frames; reduce --at values');
+  }
+  return parsed;
+}
+
+// Rejects a scan decoding source seconds `from` to `end` over `budget`. `origin` says why it decodes from the video
+// start, where only --end narrows it.
+export function checkBudget(from, end, budget, origin) {
+  if (end - from <= budget + 1e-9) return;
+  throw new Error(`changes would decode ${formatTimecode(end - from)} of video (${formatTimecode(from)} to ${formatTimecode(end)}`
+    + `${origin ? `; ${origin}` : ''}), over --analysis-budget ${budget}s; narrow it with ${origin ? '--end' : '--start/--end'} or raise --analysis-budget`);
+}
+
+// Validates a command's options against the probed source and plans its output: { crop, width } plus, by command,
+// overview { range, times }, inspect { times, windows, and range with --start/--end }, changes { range, settings }
+// (times follow detection), frame { times }. Times are source seconds on the container timeline.
+export function planRun(command, options, info, parsed = parseOptions(command, options)) {
+  const crop = options.crop === undefined ? undefined : parseCrop(options.crop, info);
+  // Cap at the displayed width so square-pixel output is never larger than the displayed frame or crop.
+  const displayedWidth = (crop?.pixels.displayed ?? displayedSize(info.width, info.height, info)).width;
+  const width = Math.min(displayedWidth, parsed.width);
+  if (command === 'overview') {
+    const { count } = parsed;
+    const range = resolveRange(parsed, info);
+    const { start, end } = range;
+    return { crop, width, range, times: Array.from({ length: count }, (_, i) => start + (end - start) * (i + 0.5) / count) };
+  }
+  if (command === 'inspect') {
+    const { fps, window } = parsed;
+    const range = parsed.ranged ? resolveRange(parsed, info) : undefined;
+    const spans = range ? [{ around: null, ...range }] : parsed.arounds.map((around) => {
+      if (around > info.end) throw new Error(`--around ${formatTimecode(around)} is beyond the video end ${formatTimecode(info.end)}`);
+      if (around < info.start) throw new Error(`--around ${formatTimecode(around)} is before the video starts at ${formatTimecode(info.start)}`);
+      return { around, start: Math.max(info.start, around - window / 2), end: Math.min(info.end, around + window / 2) };
+    });
+    const times = [];
+    const windows = [];
+    for (const { around, start, end } of spans) {
+      // Float noise in a centered window (1.4000000000000001 - 0.8) must not add a frame.
+      const count = Math.ceil((end - start) * fps - 1e-6);
+      if (count < 1) throw new Error('inspect window contains no frames');
+      if (times.length + count > 240) throw new Error('inspect would create over 240 frames; reduce --window, --fps or --around values');
+      const first = times.length;
+      for (let i = 0; i < count; i++) {
+        const segmentStart = start + i / fps;
+        times.push(segmentStart + Math.min(0.5 / fps, (end - segmentStart) / 2));
+      }
+      windows.push({ around, start, end, frames: [first, times.length - 1] });
+    }
+    return { crop, width, times, windows, ...(range ? { range } : {}) };
+  }
+  if (command === 'changes') {
+    const range = resolveRange(parsed, info);
+    // Scans decode from the video start where input seeking is unreliable: MPEG-TS, where only --end narrows them, or
+    // a range start near the video start. findChanges checks the budget again before falling back to the video start
+    // when input seeking finds no frame.
+    const ts = info[SOURCE_FORMAT].split(',').includes('mpegts');
+    const from = attempts(info, range.start)[0].slow ? info.start : range.start;
+    checkBudget(from, range.end, parsed.settings.budget, ts ? 'MPEG-TS is decoded from the video start' : undefined);
+    return { crop, width, range, settings: parsed.settings };
+  }
+  const times = parsed.at.map(([time, value]) => {
+    if (time >= info.end) throw new Error(`--at ${value} must be before the video ends at ${formatTimecode(info.end)}`);
+    if (time < info.start) throw new Error(`--at ${value} is before the video starts at ${formatTimecode(info.start)}`);
+    return time;
+  });
+  return { crop, width, times };
+}