@hypit/hypit 0.2.6 → 0.2.8

package/packages/video-cli/src/media.ts

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import { copyFile, link, mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
 
@@ -6,6 +6,8 @@ import type { CliIo } from "@hypit/cli";
 import { downloadVideo, isVideoUrl, prepareVideoDownload } from "@hypit/yt-dlp";
 import sharp from "sharp";
 
+import { decodeMediaFrames } from "./media-frames.js";
+import { writeFrameGrid } from "./frame-grid.js";
 import { runProcess, runProcessOutput, runProcessWithInput } from "./process.js";
 import { phraseRanges, readTranscript, wordsAt } from "./transcript.js";
 import type { FrameWords, TranscriptWord } from "./transcript.js";
@@ -35,13 +37,17 @@ function clamp(value: number, low: number, high: number): number { return Math.m
 type Parsed = {
   readonly positionals: readonly string[];
   readonly options: ReadonlyMap<string, string>;
+  readonly repeated: ReadonlyMap<string, readonly string[]>;
   readonly flags: ReadonlySet<string>;
   readonly json: boolean;
 };
 
-function parseArguments(argv: readonly string[], allowed: readonly string[], allowedFlags: readonly string[] = []): Parsed {
+function parseArguments(
+  argv: readonly string[], allowed: readonly string[], allowedFlags: readonly string[] = [], repeatable: readonly string[] = [],
+): Parsed {
   const positionals: string[] = [];
   const options = new Map<string, string>();
+  const repeated = new Map<string, string[]>();
   const flags = new Set<string>();
   let json = false;
   for (let index = 0; index < argv.length; index += 1) {
@@ -56,13 +62,14 @@ function parseArguments(argv: readonly string[], allowed: readonly string[], all
       continue;
     }
     if (!allowed.includes(item)) throw new Error(`unknown option ${item}`);
-    if (options.has(item)) throw new Error(`${item} cannot be repeated`);
+    if (!repeatable.includes(item) && options.has(item)) throw new Error(`${item} cannot be repeated`);
     const value = argv[index + 1];
     if (value === undefined || (value.startsWith("--") && value.length > 2)) throw new Error(`${item} requires a value`);
-    options.set(item, value);
+    if (repeatable.includes(item)) repeated.set(item, [...(repeated.get(item) ?? []), value]);
+    else options.set(item, value);
     index += 1;
   }
-  return { positionals, options, flags, json };
+  return { positionals, options, repeated, flags, json };
 }
 
 function required(parsed: Parsed, option: string, hint: string): string {
@@ -132,14 +139,22 @@ async function destinationDirectory(parsed: Parsed, cwd: string, hint: string):
 // ---------------------------------------------------------------------------------------------------
 // ffmpeg
 
-export type MediaProbe = {
-  readonly duration: number;
+type VideoProbe = {
+  readonly hasVideo: true;
   readonly width: number;
   readonly height: number;
   readonly frameRate: number;
-  readonly hasAudio: boolean;
 };
 
+export type MediaProbe = {
+  readonly duration: number;
+  readonly hasAudio: boolean;
+} & (VideoProbe | { readonly hasVideo: false });
+
+function requireVideo(info: MediaProbe, path: string): asserts info is MediaProbe & VideoProbe {
+  assert(info.hasVideo, `${path}: no video stream`);
+}
+
 export async function probeMedia(path: string): Promise<MediaProbe> {
   const raw = await runProcess("ffprobe", [
     "-v", "error", "-show_entries", "format=duration:stream=codec_type,width,height,r_frame_rate", "-of", "json", path,
@@ -151,16 +166,20 @@ export async function probeMedia(path: string): Promise<MediaProbe> {
   const video = parsed.streams?.find((item) => item.codec_type === "video");
   const duration = Number(parsed.format?.duration);
   assert(Number.isFinite(duration) && duration > 0, `${path}: duration is unavailable`);
-  assert(video?.width !== undefined && video.height !== undefined, `${path}: no video stream`);
+  const hasAudio = parsed.streams?.some((item) => item.codec_type === "audio") ?? false;
+  assert(video !== undefined || hasAudio, `${path}: no audio or video stream`);
+  if (video === undefined) return { duration: round(duration), hasVideo: false, hasAudio };
+  assert(video.width !== undefined && video.height !== undefined, `${path}: video dimensions are unavailable`);
   // ffprobe reports the rate as a ratio; a still image reports none.
   const ratio = (video.r_frame_rate ?? "").split("/");
   const rate = Number(ratio[0]) / Number(ratio[1] ?? 1);
   return {
     duration: round(duration),
+    hasVideo: true,
     width: video.width,
     height: video.height,
     frameRate: Number.isFinite(rate) && rate > 0 ? round(rate) : 0,
-    hasAudio: parsed.streams?.some((item) => item.codec_type === "audio") ?? false,
+    hasAudio,
   };
 }
 
@@ -257,7 +276,7 @@ export async function cutClip(
   start: number,
   end: number,
   target: string,
-  labelInfo?: Pick<MediaProbe, "frameRate">,
+  labelInfo?: Pick<VideoProbe, "frameRate">,
 ): Promise<void> {
   assert(end > start, `the clip must end after it starts (${start} to ${end})`);
   const seconds = round(end - start);
@@ -289,6 +308,64 @@ export async function cutClip(
   }
 }
 
+type CutSpan = { readonly start: number; readonly end: number };
+
+function keptSpan(raw: string, duration: number): CutSpan {
+  const parts = raw.split(":");
+  assert(parts.length === 2 && parts.every((part) => part.trim().length > 0), `--keep needs start:end in seconds, got ${raw}`);
+  const [start, end] = parts.map(Number);
+  assert(Number.isFinite(start) && Number.isFinite(end) && start! >= 0 && end! > start! && end! <= duration + 0.001,
+    `--keep ${raw} must satisfy 0 <= start < end <= ${duration} s`);
+  return { start: start!, end: end! };
+}
+
+/** Decode the selected parts once, join them on a new local clock, and preserve only existing streams. */
+async function cutProduction(source: string, spans: readonly CutSpan[], target: string, info: MediaProbe): Promise<void> {
+  const seek = Math.max(0, spans[0]!.start - SEEK_RUN_UP);
+  const labels: string[] = [];
+  const filters: string[] = [];
+  const videoInputs = spans.map((_, index) => `vsrc${index}`);
+  const audioInputs = spans.map((_, index) => `asrc${index}`);
+  if (info.hasVideo && spans.length > 1) filters.push(`[0:v:0]split=${spans.length}${videoInputs.map((item) => `[${item}]`).join("")}`);
+  if (info.hasAudio && spans.length > 1) filters.push(`[0:a:0]asplit=${spans.length}${audioInputs.map((item) => `[${item}]`).join("")}`);
+  for (const [index, span] of spans.entries()) {
+    const start = round(span.start - seek);
+    const end = round(span.end - seek);
+    if (info.hasVideo) filters.push(`[${spans.length === 1 ? "0:v:0" : videoInputs[index]}]trim=start=${start}:end=${end},setpts=PTS-STARTPTS[v${index}]`);
+    if (info.hasAudio) filters.push(`[${spans.length === 1 ? "0:a:0" : audioInputs[index]}]atrim=start=${start}:end=${end},asetpts=PTS-STARTPTS[a${index}]`);
+    labels.push(`${info.hasVideo ? `[v${index}]` : ""}${info.hasAudio ? `[a${index}]` : ""}`);
+  }
+  if (spans.length > 1) filters.push(`${labels.join("")}concat=n=${spans.length}:v=${info.hasVideo ? 1 : 0}:a=${info.hasAudio ? 1 : 0}${info.hasVideo ? "[v]" : ""}${info.hasAudio ? "[a]" : ""}`);
+  const videoLabel = spans.length === 1 ? "[v0]" : "[v]";
+  const audioLabel = spans.length === 1 ? "[a0]" : "[a]";
+  await runProcess("ffmpeg", [
+    "-hide_banner", "-loglevel", "error", "-y",
+    ...(seek > 0 ? ["-ss", String(round(seek))] : []), "-i", source,
+    "-filter_complex", filters.join(";"),
+    ...(info.hasVideo ? ["-map", videoLabel, "-c:v", "libx264", "-preset", "medium", "-crf", "17", "-pix_fmt", "yuv420p", "-fps_mode", "vfr",
+      ...([".mp4", ".mov"].includes(extname(target).toLowerCase()) ? ["-movflags", "+faststart"] : [])] : []),
+    ...(info.hasAudio ? ["-map", audioLabel, "-c:a", ...(info.hasVideo ? ["aac", "-b:a", "192k"] : ["pcm_s24le"])] : []),
+    target,
+  ]);
+}
+
+/** Publish a completed cut without overwriting a file another process may have created meanwhile. */
+async function writeCut(
+  source: string, spans: readonly CutSpan[], target: string, info: MediaProbe, labeled: boolean,
+): Promise<void> {
+  const work = await mkdtemp(join(dirname(target), ".hypit-cut-"));
+  const staged = join(work, `cut${extname(target)}`);
+  try {
+    if (labeled) {
+      requireVideo(info, source);
+      await cutClip(source, spans[0]!.start, spans[0]!.end, staged, info);
+    } else await cutProduction(source, spans, staged, info);
+    await link(staged, target);
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
 export async function cutFrame(source: string, at: number, target: string, labelTime = false): Promise<number> {
   if (!labelTime) {
     const jump = Math.max(0, at - SEEK_RUN_UP);
@@ -362,29 +439,16 @@ export async function tileFrames(
   const temporary = await mkdtemp(join(tmpdir(), "hypit-tile-"));
   try {
     const frames: SampledFrame[] = [];
-    const cells: { picture: Buffer; label: Buffer; height: number; labelHeight: number }[] = [];
+    const cells: { path: string; label: Buffer }[] = [];
     for (let index = 0; index < times.length; index += 1) {
       const at = times[index]!;
       const path = join(temporary, `${index}.jpg`);
       const actual = await cutFrame(source, at, path);
       const frameWords = words === undefined ? undefined : wordsAt(words, actual);
       frames.push({ requestedAt: at, at: actual, ...(frameWords === undefined ? {} : { words: frameWords }) });
-      const picture = await sharp(path).resize({ width: cellWidth }).png().toBuffer({ resolveWithObject: true });
-      const label = await frameLabel(actual, cellWidth, frameWords);
-      const labelHeight = (await sharp(label).metadata()).height!;
-      cells.push({ picture: picture.data, height: picture.info.height, label, labelHeight });
+      cells.push({ path, label: await frameLabel(actual, cellWidth, frameWords) });
     }
-    const rows = Math.ceil(times.length / columns);
-    const pictureHeight = Math.max(...cells.map((cell) => cell.height));
-    const rowHeight = pictureHeight + Math.max(...cells.map((cell) => cell.labelHeight));
-    await sharp({ create: {
-      width: columns * (cellWidth + 8) + 8, height: rows * (rowHeight + 8) + 8,
-      channels: 3, background: "#0c0c0c",
-    } }).composite(cells.flatMap((cell, index) => {
-      const left = 8 + (index % columns) * (cellWidth + 8);
-      const top = 8 + Math.floor(index / columns) * (rowHeight + 8);
-      return [{ input: cell.picture, left, top }, { input: cell.label, left, top: top + pictureHeight }];
-    })).jpeg({ quality: 90 }).toFile(target);
+    await writeFrameGrid(cells, target, cellWidth, columns);
     return frames;
   } finally {
     await rm(temporary, { recursive: true, force: true });
@@ -490,27 +554,54 @@ async function probe(argv: readonly string[], io: CliIo, cwd: string): Promise<v
   const source = await sourceFile(parsed, cwd);
   const info = await probeMedia(source);
   if (parsed.json) { io.write(`${JSON.stringify({ path: source, ...info }, null, 2)}\n`); return; }
-  io.write(`${source}\n  ${info.duration} s  ${info.width}×${info.height}  ${info.frameRate > 0 ? `${info.frameRate} fps` : "still"}  ${info.hasAudio ? "with audio" : "no audio"}\n`);
+  io.write(`${source}\n  ${info.duration} s  ${info.hasVideo
+    ? `${info.width}×${info.height}  ${info.frameRate > 0 ? `${info.frameRate} fps` : "still"}  ${info.hasAudio ? "with audio" : "no audio"}`
+    : "audio only"}\n`);
 }
 
 async function cut(argv: readonly string[], io: CliIo, cwd: string): Promise<void> {
-  const parsed = parseArguments(argv, ["--start", "--end", "--to"], ["--label-time"]);
+  const parsed = parseArguments(argv, ["--start", "--end", "--keep", "--to"], ["--label-time"], ["--keep"]);
   const source = await sourceFile(parsed, cwd);
-  const start = secondsOption(parsed, "--start", 0);
   const info = await probeMedia(source);
-  const end = secondsOption(parsed, "--end", info.duration);
-  assert(end <= info.duration + 0.001, `--end ${end} is past the end of the file (${info.duration} s)`);
-  const target = await destination(parsed, cwd, "the clip to write, for example notes/hook.mp4");
+  const kept = parsed.repeated.get("--keep") ?? [];
+  assert(kept.length === 0 || (!parsed.options.has("--start") && !parsed.options.has("--end")),
+    "choose --keep intervals or --start/--end");
+  const spans = kept.length > 0 ? kept.map((item) => keptSpan(item, info.duration)) : [{
+    start: secondsOption(parsed, "--start", 0), end: secondsOption(parsed, "--end", info.duration),
+  }];
+  for (const [index, span] of spans.entries()) {
+    assert(span.end > span.start && span.end <= info.duration + 0.001,
+      `range must satisfy 0 <= start < end <= ${info.duration} s`);
+    if (index > 0) assert(span.start >= spans[index - 1]!.end, "--keep intervals must be ordered and non-overlapping");
+  }
   const labeled = parsed.flags.has("--label-time");
-  await cutClip(source, start, end, target, labeled ? info : undefined);
-  if (parsed.json) { io.write(`${JSON.stringify({ path: target, start, end, seconds: round(end - start), labeled }, null, 2)}\n`); return; }
-  io.write(`${target}\n  ${start} s to ${end} s (${round(end - start)} s)${labeled ? ", source time visible" : ""}\n`);
+  assert(!labeled || (info.hasVideo && spans.length === 1), "--label-time needs one video interval");
+  const target = await destination(parsed, cwd, "the clip to write, for example notes/hook.mp4");
+  if (!info.hasVideo) assert(extname(target).toLowerCase() === ".wav", "--to must end in .wav for audio-only media");
+  await writeCut(source, spans, target, info, labeled);
+  const output = await probeMedia(target);
+  const requestedSeconds = round(spans.reduce((total, span) => total + span.end - span.start, 0));
+  if (parsed.json) {
+    let outputAt = 0;
+    const mapping = spans.map((span) => {
+      const item = { sourceStart: span.start, sourceEnd: span.end,
+        nominalOutputStart: round(outputAt), nominalOutputEnd: round(outputAt + span.end - span.start) };
+      outputAt += span.end - span.start;
+      return item;
+    });
+    io.write(`${JSON.stringify({ path: target, ...(spans.length === 1 ? { start: spans[0]!.start, end: spans[0]!.end } : {}),
+      spans, mapping, seconds: requestedSeconds, actualSeconds: output.duration, hasVideo: output.hasVideo, hasAudio: output.hasAudio, labeled }, null, 2)}\n`);
+    return;
+  }
+  io.write(`${target}\n  ${spans.map((span) => `${span.start}–${span.end} s`).join(" + ")} (${output.duration} s output)${labeled ? ", source time visible" : ""}\n`);
 }
 
 async function frames(argv: readonly string[], io: CliIo, cwd: string): Promise<void> {
-  const parsed = parseArguments(argv, [...SAMPLE_OPTIONS, "--to"], ["--label-time"]);
+  const parsed = parseArguments(argv, [...SAMPLE_OPTIONS, "--to"], ["--label-time", "--every-frame"]);
+  if (parsed.flags.has("--every-frame")) { await nativeFrames(parsed, io, cwd, false); return; }
   const source = await sourceFile(parsed, cwd);
   const info = await probeMedia(source);
+  requireVideo(info, source);
   const words = await transcriptOption(parsed, cwd);
   const times = sampleTimes(parsed, info.duration, words, true);
   const to = await destinationDirectory(parsed, cwd, "the new directory to write the frames into");
@@ -538,6 +629,7 @@ async function tile(argv: readonly string[], io: CliIo, cwd: string): Promise<vo
   const parsed = parseArguments(argv, [...SAMPLE_OPTIONS, "--frames", "--cell", "--columns", "--to"]);
   const source = await sourceFile(parsed, cwd);
   const info = await probeMedia(source);
+  requireVideo(info, source);
   const words = await transcriptOption(parsed, cwd);
   const times = sampleTimes(parsed, info.duration, words);
   // Preserve source width unless an exceptionally tiny input needs room for a legible timecode.
@@ -573,9 +665,11 @@ function tileRange(value: unknown, index: number, duration: number): TileRange {
 }
 
 async function tiles(argv: readonly string[], io: CliIo, cwd: string): Promise<void> {
-  const parsed = parseArguments(argv, [...SAMPLE_OPTIONS, "--ranges", "--frames", "--cell", "--columns", "--rows", "--to"]);
+  const parsed = parseArguments(argv, [...SAMPLE_OPTIONS, "--ranges", "--frames", "--cell", "--columns", "--rows", "--to"], ["--every-frame"]);
+  if (parsed.flags.has("--every-frame")) { await nativeFrames(parsed, io, cwd, true); return; }
   const source = await sourceFile(parsed, cwd);
   const info = await probeMedia(source);
+  requireVideo(info, source);
   const words = await transcriptOption(parsed, cwd);
   const rangesPath = parsed.options.get("--ranges");
   let ranges: { id?: string; start: number; end: number; times: readonly number[] }[];
@@ -631,9 +725,65 @@ async function tiles(argv: readonly string[], io: CliIo, cwd: string): Promise<v
   io.write(`${to}\n  ${written.length} time-labeled ${written.length === 1 ? "grid" : "grids"}\n`);
 }
 
+/** Native-frame observation: each requested interval is decoded once, then paginated. */
+async function nativeFrames(parsed: Parsed, io: CliIo, cwd: string, grid: boolean): Promise<void> {
+  for (const key of ["--at", "--every", "--frames"]) assert(!parsed.options.has(key), `--every-frame cannot be combined with ${key}`);
+  const source = await sourceFile(parsed, cwd);
+  const info = await probeMedia(source);
+  requireVideo(info, source);
+  const words = await transcriptOption(parsed, cwd);
+  let ranges: TileRange[];
+  const rangeFile = parsed.options.get("--ranges");
+  if (rangeFile === undefined) ranges = [sampleRange(parsed, info.duration, words)];
+  else {
+    for (const key of ["--start", "--end", "--around", "--padding", "--occurrence"]) assert(!parsed.options.has(key), `--ranges cannot be combined with ${key}`);
+    const raw = JSON.parse(await readFile(resolve(cwd, rangeFile), "utf8"));
+    assert(Array.isArray(raw) && raw.length > 0, "--ranges needs a non-empty JSON array");
+    ranges = raw.map((value, index) => tileRange(value, index, info.duration));
+    assert(ranges.every(range => range.frames === undefined && range.every === undefined), "Native ranges cannot specify frames or every");
+  }
+  const cell = integerOption(parsed, "--cell", Math.max(80, Math.min(TILE_CELL_WIDTH, info.width)), 80);
+  const columns = integerOption(parsed, "--columns", TILE_COLUMNS, 1);
+  const rows = integerOption(parsed, "--rows", 3, 1);
+  const to = await destinationDirectory(parsed, cwd, "the new directory for native frame evidence");
+  const staging = await mkdtemp(join(dirname(to), ".hypit-native-"));
+  const written: { at: number; path: string }[] = [];
+  const grids: { path: string; frames: readonly { at: number }[] }[] = [];
+  try {
+    for (const [rangeIndex, range] of ranges.entries()) {
+      const decodedDirectory = join(staging, "decoded");
+      const decoded = await decodeMediaFrames(source, range.start, range.end, decodedDirectory);
+      if (grid) {
+        const perPage = columns * rows;
+        for (let offset = 0; offset < decoded.length; offset += perPage) {
+          const page = decoded.slice(offset, offset + perPage);
+          const cells = [];
+          for (const frame of page) cells.push({ path: frame.path, label: await frameLabel(frame.at, cell,
+            words === undefined ? undefined : wordsAt(words, frame.at)) });
+          const name = `${String(rangeIndex + 1).padStart(3, "0")}-${range.id ?? "frames"}-p${String(offset / perPage + 1).padStart(3, "0")}.jpg`;
+          await writeFrameGrid(cells, join(staging, name), cell, columns);
+          grids.push({ path: join(to, name), frames: page.map(frame => ({ at: frame.at })) });
+        }
+      } else for (const [index, frame] of decoded.entries()) {
+        const name = `frame-${String(index).padStart(9, "0")}.jpg`;
+        const target = join(staging, name);
+        if (parsed.flags.has("--label-time") || words !== undefined) await writeFrameGrid([{ path: frame.path,
+          label: await frameLabel(frame.at, info.width, words === undefined ? undefined : wordsAt(words, frame.at)) }], target, info.width, 1);
+        else await copyFile(frame.path, target);
+        written.push({ at: frame.at, path: join(to, name) });
+      }
+      await rm(decodedDirectory, { recursive: true, force: true });
+    }
+    await rename(staging, to);
+  } catch (error) { await rm(staging, { recursive: true, force: true }); throw error; }
+  if (parsed.json) io.write(`${JSON.stringify({ directory: to, ...(grid ? { grids } : { frames: written }) }, null, 2)}\n`);
+  else io.write(`${to}\n  ${grid ? `${grids.length} grids` : `${written.length} frames`} from continuous source decoding\n`);
+}
+
 async function boundaries(argv: readonly string[], io: CliIo, cwd: string): Promise<void> {
   const parsed = parseArguments(argv, ["--rate", "--threshold"]);
   const source = await sourceFile(parsed, cwd);
+  requireVideo(await probeMedia(source), source);
   const rate = numberOption(parsed, "--rate", DEFAULT_BOUNDARY_RATE, 1, 120);
   const threshold = numberOption(parsed, "--threshold", DEFAULT_BOUNDARY_THRESHOLD, 0, 1);
   const candidates = await visualBoundaries(source, rate, threshold);
@@ -653,6 +803,7 @@ async function fetch(argv: readonly string[], io: CliIo, cwd: string): Promise<v
   assert([".mp4", ".mkv", ".webm", ".mov"].includes(extname(target).toLowerCase()), "--to must end in .mp4, .mkv, .webm or .mov");
   await downloadVideo(url, target);
   const info = await probeMedia(target);
+  requireVideo(info, target);
   if (parsed.json) { io.write(`${JSON.stringify({ path: target, url, ...info }, null, 2)}\n`); return; }
   io.write(`${target}\n  ${info.duration} s  ${info.width}×${info.height}  ${info.hasAudio ? "with audio" : "no audio"}\n`);
 }
@@ -662,26 +813,27 @@ async function fetch(argv: readonly string[], io: CliIo, cwd: string): Promise<v
 
 export function writeMediaHelp(io: CliIo, topic?: MediaCommand): void {
   const sections: Record<MediaCommand, readonly string[]> = {
-    probe: ["  hypit media probe <file>", "    Duration, size, frame rate and whether there is audio."],
-    cut: ["  hypit media cut <file> --start <s> --end <s> [--label-time] --to <clip.mp4>",
-      "    One exact stretch. --label-time visibly overlays absolute source time on the evidence copy."],
-    frames: ["  hypit media frames <file> (--at <s,s,…> | --every <s>) [--start <s> --end <s>] [--label-time] [--transcript <json>] --to <dir>",
+    probe: ["  hypit media probe <file>", "    Duration and available audio/video streams; video adds size and frame rate."],
+    cut: ["  hypit media cut <file> [--start <s> --end <s> | --keep <start:end> ...] [--label-time] --to <clip.mp4|clip.wav>",
+      "    Keep one stretch or join ordered stretches from one source. Audio-only outputs WAV; MP4 is a useful video target.",
+      "    --label-time overlays source time on a single video evidence copy."],
+    frames: ["  hypit media frames <file> (--at <s,s,…> | --every <s> | --every-frame) [--start <s> --end <s>] [--label-time] [--transcript <json>] --to <dir>",
       "    Individual frames named by source time; --transcript adds word times and context below each picture."],
     tile: ["  hypit media tile <file> [--start <s> --end <s> | --at <s,s,…>] [--every <s> | --frames <n>] [--transcript <json>] [--cell <px>] [--columns <n>] --to <grid.jpg>",
       "    One grid. --every samples from start, excluding end; --frames chooses evenly spaced midpoints."],
-    tiles: ["  hypit media tiles <file> [--start <s> --end <s> | --at <s,s,…> | --ranges <json>] [--every <s> | --frames <n>] [--transcript <json>] [--cell <px>] [--columns <n>] [--rows <n>] --to <dir>",
-      "    Paginated grids (3 rows by default). Range files contain { start, end, id?, frames?, every? }."],
+    tiles: ["  hypit media tiles <file> [--start <s> --end <s> | --at <s,s,…> | --ranges <json>] [--every <s> | --frames <n> | --every-frame] [--transcript <json>] [--cell <px>] [--columns <n>] [--rows <n>] --to <dir>",
+      "    Paginated grids (3 rows by default). --every-frame decodes every original frame once per interval, preserving actual timestamps. Range files contain { start, end, id?, frames?, every? }."],
     boundaries: ["  hypit media boundaries <file> [--rate <samples/s>] [--threshold <0..1>]",
       "    Mechanical adjacent-frame change candidates with scores; never editorial shot labels."],
     "prepare-fetch": ["  hypit media prepare-fetch", "    Explicitly prepare the pinned yt-dlp environment; does not fetch media."],
     fetch: ["  hypit media fetch <url> --to <video.mp4>", "    A link turned into a file with the pinned yt-dlp, video and audio together."],
   };
   const chosen = topic === undefined ? mediaCommands : [topic];
-  io.write(`hypit media\nInspect media at chosen times and scales. Local work; no Runtime Profile, no request, no state.\n\n${
+  io.write(`hypit media\nInspect and prepare media locally. No Runtime Profile, network request or project state.\n\n${
     chosen.map((item) => sections[item].join("\n")).join("\n\n")}\n\nFrames and grids accept --around <phrase> with --transcript instead of --start/--end.\n`
     + "Use --occurrence <n> for a repeated phrase; --padding <s> adds time on each side (default 0.3).\n"
     + "Transcript times must share the input media's clock. An untimed gap is labeled as such, without inferring silence.\n"
-    + "Commands that create evidence write only what --to names and refuse to overwrite. Add --json for the complete machine view.\n");
+    + "Commands write only what --to names and refuse to overwrite. Add --json for the complete machine view.\n");
 }
 
 export async function runMediaCli(argv: readonly string[], io: CliIo, cwd = process.cwd()): Promise<void> {

package/packages/video-cli/src/process.ts

@@ -9,6 +9,7 @@ function run(
   args: readonly string[],
   input: ProcessInput | undefined,
   timeoutMs: number,
+  onStderrLine?: (line: string) => void,
 ): Promise<ProcessOutput> {
   return new Promise((resolveRun, reject) => {
     const child = spawn(executable, [...args], { stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });
@@ -24,7 +25,16 @@ function run(
     };
     const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error(`${executable} timed out after ${timeoutMs} ms`)); }, timeoutMs);
     child.stdout?.on("data", (chunk: Buffer) => out.push(chunk));
-    child.stderr?.on("data", (chunk: Buffer) => { err = `${err}${chunk.toString("utf8")}`.slice(-100_000); });
+    let pendingLine = "";
+    child.stderr?.on("data", (chunk: Buffer) => {
+      const text = chunk.toString("utf8");
+      err = `${err}${text}`.slice(-100_000);
+      if (onStderrLine !== undefined) {
+        const lines = `${pendingLine}${text}`.split(/\r?\n/u);
+        pendingLine = lines.pop()!;
+        for (const line of lines) onStderrLine(line);
+      }
+    });
     child.on("error", (error) => finish(new Error(`${executable} could not start: ${error.message}`)));
     child.on("close", (code) => {
       if (code === 0) finish();
@@ -56,8 +66,8 @@ export async function runProcess(executable: string, args: readonly string[], ti
 }
 
 /** Successful stderr can carry tool metadata, such as the timestamp of an extracted frame. */
-export function runProcessOutput(executable: string, args: readonly string[], timeoutMs = 300_000): Promise<ProcessOutput> {
-  return run(executable, args, undefined, timeoutMs);
+export function runProcessOutput(executable: string, args: readonly string[], timeoutMs = 300_000, onStderrLine?: (line: string) => void): Promise<ProcessOutput> {
+  return run(executable, args, undefined, timeoutMs, onStderrLine);
 }
 
 /** The same process boundary when a deterministic byte stream is one of the program's inputs. */

package/packages/video-cli/src/secret-input.ts

@@ -0,0 +1,14 @@
+/** Keep terminal input as bytes until a complete UTF-8 secret can be decoded. */
+export function acceptSecretBytes(raw: number[], chunk: Uint8Array): "continue" | "done" | "cancelled" {
+  for (const byte of chunk) {
+    if (byte === 3) return "cancelled";
+    if (byte === 10 || byte === 13) return "done";
+    if (byte === 8 || byte === 127) {
+      while (raw.length > 0 && (raw.at(-1)! & 0xc0) === 0x80) raw.pop();
+      raw.pop();
+      continue;
+    }
+    raw.push(byte);
+  }
+  return "continue";
+}

package/packages/video-cli/src/snapshot.ts

@@ -0,0 +1,186 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import { pipeline } from "node:stream/promises";
+import type { CliIo } from "@hypit/cli";
+import { assertHyperframesDocument, hyperframesHtmlAssetUrls, hyperframesHtmlDomain } from "@hypit/hyperframes";
+import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
+import { FileResourceStore } from "@hypit/resource-store-fs";
+import { hyperframesFramesRequest, renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFrames } from "@hypit/render-hyperframes";
+import type { Need } from "@hypit/protocol";
+import { creationEnvironment, selectedProvider, providerLine, providerView } from "./creation.js";
+import type { CreationEnvironment } from "./creation.js";
+import { snapshotFrameLabel, writeFrameGrid } from "./frame-grid.js";
+
+const MEDIA_TYPES: Readonly<Record<string, string>> = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+  ".mp4": "video/mp4", ".webm": "video/webm", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+};
+
+async function readProject(source: string, html: string, resources: FileResourceStore): Promise<HyperframesHtmlProject> {
+  const assets = [];
+  const base = /^https?:/u.test(source) ? new URL(source) : pathToFileURL(source);
+  for (const url of hyperframesHtmlAssetUrls(html)) {
+    const address = new URL(url, base);
+    let mediaType: string | undefined;
+    let stream: Readable;
+    if (address.protocol === "file:") {
+      if (base.protocol !== "file:") throw new Error(`Network HTML cannot read local asset ${url}`);
+      const path = fileURLToPath(address);
+      mediaType = MEDIA_TYPES[extname(path).toLowerCase()];
+      if (mediaType === undefined) throw new Error(`Unsupported snapshot asset ${url}; use compiled HTML with inline scripts and styles`);
+      stream = createReadStream(path);
+    } else if (address.protocol === "http:" || address.protocol === "https:") {
+      const response = await fetch(address);
+      if (!response.ok || response.body === null) throw new Error(`Snapshot asset ${url}: HTTP ${response.status}`);
+      mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (mediaType === undefined || !Object.values(MEDIA_TYPES).includes(mediaType)) {
+        await response.body.cancel();
+        throw new Error(`Unsupported snapshot asset ${url} (${mediaType}); use compiled HTML with inline scripts and styles`);
+      }
+      stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+    } else throw new Error(`Unsupported snapshot asset protocol ${address.protocol}`);
+    try { assets.push({ url, artifact: await resources.putStream(stream, mediaType) }); }
+    finally { stream.destroy(); }
+  }
+  return { html, assets };
+}
+
+const OPTIONS = ["--studio", "--to", "--at-frame", "--start-frame", "--end-frame-exclusive", "--step-frames", "--grid", "--cell", "--runtime", "--workspace"];
+
+export function writeSnapshotHelp(io: CliIo): void {
+  io.write(`hypit snapshot\nCapture exact frames from an existing compiled HyperFrames HTML programme through the selected Runtime Profile.\n\n`
+    + `  hypit snapshot --studio <studio-url> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --start-frame <n> --end-frame-exclusive <n> [--step-frames <n>] --to <directory>\n`
+    + `      [--grid <columns>x<rows>] [--cell <pixels>] [--runtime <profile>] [--workspace <project>] [--json]\n\n`
+    + `Frame indices are zero-based on the original programme clock. Ranges exclude the end.\n`
+    + `Writes full-size PNGs and optional paginated grids. --cell controls grid image width (default 480).\n`
+    + `Uses render-frames, one immediate request. Browser preparation belongs to the selected Provider.\n`
+    + `HTML carries the compiled frame clock and media/font URLs; scripts and styles are inline.\nStudio exposes its current programme at http://<host>:<port>/__studio/visual.html.\n`);
+}
+
+export async function runSnapshotCli(argv: readonly string[], io: CliIo, environment: CreationEnvironment = creationEnvironment()): Promise<void> {
+  if (argv.includes("--help")) { writeSnapshotHelp(io); return; }
+  const options = new Map<string, string>();
+  const positionals = [];
+  const json = argv.includes("--json");
+  for (let index = 1; index < argv.length; index++) {
+    const arg = argv[index]!;
+    if (["--json", "--debug", "--verbose", "--no-color"].includes(arg)) continue;
+    if (arg === "--color") { index++; continue; }
+    if (!arg.startsWith("--")) { positionals.push(arg); continue; }
+    if (!OPTIONS.includes(arg)) throw new Error(`Unknown snapshot option ${arg}`);
+    if (options.has(arg)) throw new Error(`${arg} cannot be repeated`);
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`);
+    options.set(arg, value);
+  }
+  const studio = options.get("--studio");
+  if (positionals.length !== (studio === undefined ? 1 : 0) || !options.has("--to")) throw new Error("snapshot takes one HTML input or --studio <url>, and --to <directory>");
+  const integer = (raw: string | undefined, label: string, minimum = 0): number => {
+    if (raw === undefined || !/^\d+$/u.test(raw) || !Number.isSafeInteger(Number(raw)) || Number(raw) < minimum) throw new Error(`${label} needs an integer >= ${minimum}`);
+    return Number(raw);
+  };
+  const source = studio === undefined
+    ? /^https?:\/\//u.test(positionals[0]!) ? positionals[0]! : resolve(environment.cwd, positionals[0]!)
+    : new URL("/__studio/document", studio).href;
+  let document: HyperframesDocument | undefined;
+  let html: string;
+  if (studio !== undefined) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Studio programme: HTTP ${response.status} ${await response.text()}`);
+    document = await response.json() as HyperframesDocument;
+    assertHyperframesDocument(document);
+    html = document.html;
+  } else if (/^https?:/u.test(source)) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Snapshot HTML: HTTP ${response.status} ${await response.text()}`);
+    html = await response.text();
+  } else html = await readFile(source, "utf8");
+  const domain = document ?? hyperframesHtmlDomain(html);
+  const explicit = options.get("--at-frame");
+  let frames: number[];
+  if (explicit !== undefined) {
+    if (["--start-frame", "--end-frame-exclusive", "--step-frames"].some(key => options.has(key))) throw new Error("Choose --at-frame or a frame range");
+    frames = explicit.split(",").map(value => integer(value, "--at-frame"));
+  } else {
+    const start = integer(options.get("--start-frame"), "--start-frame");
+    const end = integer(options.get("--end-frame-exclusive"), "--end-frame-exclusive");
+    const step = integer(options.get("--step-frames") ?? "1", "--step-frames", 1);
+    if (end <= start || end > domain.frameCount) throw new Error(`The frame range must satisfy 0 <= start < end <= ${domain.frameCount}`);
+    frames = Array.from({ length: Math.ceil((end - start) / step) }, (_, index) => start + index * step);
+  }
+  const grid = options.get("--grid")?.split("x");
+  if (grid !== undefined && grid.length !== 2) throw new Error("--grid needs columns x rows, for example 4x3");
+  const columns = grid === undefined ? undefined : integer(grid[0], "grid columns", 1);
+  const rows = grid === undefined ? undefined : integer(grid[1], "grid rows", 1);
+  if (options.has("--cell") && grid === undefined) throw new Error("--cell requires --grid");
+  const cell = integer(options.get("--cell") ?? "480", "--cell", 32);
+  const to = resolve(environment.cwd, options.get("--to")!);
+  if (await stat(to).then(() => true, () => false)) throw new Error(`Destination ${to} already exists`);
+  const temporary = await mkdtemp(join(tmpdir(), "hypit-snapshot-"));
+  let staging: string | undefined;
+  try {
+    const resources = new FileResourceStore(temporary);
+    let input: { document: HyperframesDocument } | { project: HyperframesHtmlProject };
+    if (document !== undefined) {
+      for (const artifact of document.artifacts) {
+        const response = await fetch(new URL(`/__studio/material/${artifact.resource}`, studio));
+        if (!response.ok || response.body === null) throw new Error(`Studio material ${artifact.resource}: HTTP ${response.status}`);
+        const stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+        try { await resources.writeStream(artifact, stream); }
+        finally { stream.destroy(); }
+      }
+      input = { document };
+    } else input = { project: await readProject(source, html, resources) };
+    const need: Need = { id: "need:hypit-snapshot", capability: renderHyperframesCapabilities.renderFrames,
+      returns: renderHyperframesTypes.frames, result: "record:hypit-snapshot", constraints: hyperframesFramesRequest({ ...input, frames }) };
+    const { host, profile } = await environment.openHost(options.get("--runtime"), options.get("--workspace"));
+    const provider = await selectedProvider(host, need, profile);
+    if (!json) io.write(`Capturing ${frames.length} frames through ${providerLine(provider)}\n`);
+    const report = json ? io.writeProgress : io.writeProgress ?? io.write;
+    const fulfilled = await host.invoke(need, resources, {
+      reportProgress: async progress => { report?.(`  · ${progress.phase}\n`); },
+      reportDiagnostic: async diagnostic => { report?.(`  · ${diagnostic.message}\n`); },
+    });
+    if (fulfilled.value.kind !== "inline") throw new Error("The frame list came back by reference");
+    verifyHyperframesFrames(fulfilled.value.value);
+    const images = fulfilled.value.value;
+    if (images.length !== frames.length) throw new Error(`Requested ${frames.length} frames, received ${images.length}`);
+    await mkdir(dirname(to), { recursive: true });
+    staging = await mkdtemp(join(dirname(to), ".hypit-snapshot-"));
+    const files = [];
+    for (const [index, image] of images.entries()) {
+      const frame = frames[index]!;
+      const name = `frame-${String(frame).padStart(9, "0")}.png`;
+      const stream = await resources.open(image.resource);
+      if (stream === undefined) throw new Error(`Snapshot frame ${frame} is unavailable`);
+      await pipeline(stream, createWriteStream(join(staging, name), { flags: "wx" }));
+      files.push({ frame, seconds: frame * domain.frameRate.denominator / domain.frameRate.numerator, path: join(to, name) });
+    }
+    const grids: string[] = [];
+    if (columns !== undefined && rows !== undefined) {
+      const count = columns * rows;
+      for (let offset = 0; offset < files.length; offset += count) {
+        const page = [];
+        for (const file of files.slice(offset, offset + count)) page.push({ path: join(staging, `frame-${String(file.frame).padStart(9, "0")}.png`),
+          label: await snapshotFrameLabel(file.frame, file.seconds, cell) });
+        const name = `grid-${String(grids.length + 1).padStart(3, "0")}.jpg`;
+        await writeFrameGrid(page, join(staging, name), cell, columns);
+        grids.push(join(to, name));
+      }
+    }
+    await rename(staging, to);
+    staging = undefined;
+    if (json) io.write(`${JSON.stringify({ format: "hypit.video-cli-snapshot@1", source, ...providerView(provider), frames: files, grids }, null, 2)}\n`);
+    else io.write(`Captured ${files.length} PNGs${grids.length === 0 ? "" : ` and ${grids.length} grid${grids.length === 1 ? "" : "s"}`}\n  ${to}\n`);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+    if (staging !== undefined) await rm(staging, { recursive: true, force: true });
+  }
+}