reelkit-cli 0.10.6 → 0.12.0

package/src/commands/build.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { Ctx, Result } from "../context";
@@ -14,7 +14,10 @@ import type { SearchRecord } from "./assets";
 import { libraryUse, shareAfterRender } from "./components";
 import { mediaUrls, serveDir } from "../project/serve";
 import { contactSheet } from "../render/contact-sheet";
-import { bundleProject, disposeBundle, ensureRenderBrowser, renderStills, renderVideo, writeEntry, type EnsureBrowser } from "../render/render";
+import { bundleProject, disposeBundle, ensureRenderBrowser, mixCapturedAudio, renderStills, renderVideo, renderVideoRange, writeEntry, type EnsureBrowser } from "../render/render";
+import { DEFAULT_CHUNK_FRAMES, countFrames, mergeAudioRecords, renderChunked, renderKey, withRetry, type CapturedAudio, type ChunkedResult } from "../render/chunked";
+import { fullDecode, syncFile } from "../media/ffmpeg";
+import { compareFilms, diffSummary, type DiffReport } from "./diff";
 import { MASTER_LUFS, MASTER_TRUE_PEAK_DB, masterLoudness, type Master, type Mastered } from "../render/master";
 import { detailLines, measureSound, soundAdvice, spokenWords, voiceAdvice, type SoundReport, type SpokenWord } from "../project/soundreport";
 import { soundNotes } from "../render/sound-notes";
@@ -98,6 +101,18 @@ function compositionNotes(project: Project, plan: ScenePlan, manifest?: AssetMan
 
 const failed = (errors: string[]): Result => ({ ok: false, data: { errors }, summary: `${errors.length} problem(s):\n- ${errors.join("\n- ")}` });
 
+// Which sound plays when, as the last render registered it: the project path of each sound, and its start and end in seconds. Written
+// beside the video so that a timeline (the studio's, a template's) can name each sound effect instead of guessing from the mix.
+export const SOUND_MAP = "out/sounds.json";
+const SOUND_RECORDS = "out/.sound-records.json";
+export type SoundMapEntry = { path: string; start: number; end: number; volume: number };
+function saveSoundMap(project: { writeJson(rel: string, value: unknown): void }, urls: Record<string, string>, records: { src: string; start: number; end: number; volume: number }[]): void {
+  const pathOf = new Map(Object.entries(urls).map(([path, url]) => [url, path]));
+  const r3 = (n: number) => Math.round(n * 1000) / 1000;
+  const map: SoundMapEntry[] = records.flatMap((r) => { const path = pathOf.get(r.src); return path ? [{ path, start: r3(r.start), end: r3(r.end), volume: r3(r.volume) }] : []; }).sort((a, b) => a.start - b.start);
+  try { project.writeJson(SOUND_MAP, map); } catch { /* the map is a convenience: a render never fails for it */ }
+}
+
 export async function check(ctx: Ctx): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
@@ -278,17 +293,80 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   }
 }
 
-export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean; measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport> } = {}): Promise<Result> {
+// The last render, kept beside the new one so that `reelkit diff` (or `render --guard previous`) can prove what a revision changed.
+export const PREVIOUS_RENDER = "out/previous.mp4";
+const CHUNK_DIR = ".reelkit/chunks";
+
+export type RenderDeps = {
+  ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean; measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport>;
+  // Render in pieces of this many frames that survive a crash and are reused by the next run (true: the default size).
+  chunk?: number | boolean;
+  // Compare the new render with this film (a path, or "previous" for the last render) and fail when anything outside `allow` changed.
+  guard?: string; allow?: string; allowAudio?: string; threshold?: string | number;
+  // What a test may replace: the check that the written file is whole. Resolves to a problem, or undefined when the file is good.
+  verify?: (path: string, frames: number) => Promise<string | undefined>;
+};
+
+// A render is only reported when its file is on the disk, decodes from end to end and holds every frame.
+export async function verifyRender(path: string, frames: number): Promise<string | undefined> {
+  if (!existsSync(path) || statSync(path).size === 0) return "the file was not written";
+  syncFile(path);
+  const decoded = await fullDecode(path);
+  if (decoded.errorLines.length) return `the file does not decode cleanly (${decoded.errorLines[0]})`;
+  if (decoded.frames !== frames) return `the file holds ${decoded.frames} frames instead of ${frames}`;
+  return undefined;
+}
+
+export async function render(ctx: Ctx, deps: RenderDeps = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
   if (!manifest) return failed(errors);
   const path = "out/video.mp4";
+  // Keep the render about to be replaced: it is the only proof of what the film was before this change.
+  let keptPrevious = false;
+  if (project.exists(path) && statSync(project.path(path)).size > 0) {
+    try { copyFileSync(project.path(path), project.path(PREVIOUS_RENDER)); syncFile(project.path(PREVIOUS_RENDER)); keptPrevious = true; } catch { keptPrevious = false; }
+  }
+  const guardPath = deps.guard === undefined && deps.allow === undefined && deps.allowAudio === undefined ? undefined : !deps.guard || deps.guard === "previous" ? project.path(PREVIOUS_RENDER) : resolve(ctx.cwd, deps.guard);
+  if (guardPath && !existsSync(guardPath)) return failed([`The film to compare with, ${deps.guard && deps.guard !== "previous" ? deps.guard : PREVIOUS_RENDER}, does not exist. Render once first, or give a file with --guard.`]);
+  let chunked: ChunkedResult | undefined;
   try {
     await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path), { uses3D: usesScene3D(project) }));
+    const options = { uses3D: usesScene3D(project) };
+    if (deps.chunk) {
+      const chunkFrames = typeof deps.chunk === "number" && deps.chunk > 0 ? Math.floor(deps.chunk) : DEFAULT_CHUNK_FRAMES;
+      const names = readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx")).sort();
+      const sources = Object.fromEntries(names.map((n) => [n, readFileSync(project.path(join("src", n)), "utf8")]));
+      const media: Record<string, number> = {};
+      for (const src of Object.values(sources)) for (const m of src.matchAll(MEDIA_PATH)) if (project.exists(m[1]!)) { const st = statSync(project.path(m[1]!)); media[m[1]!] = st.size + Math.round(st.mtimeMs); }
+      const key = renderKey({ sources, manifest, media, chunkFrames });
+      const chunkDir = project.path(CHUNK_DIR);
+      chunked = await withBundle(project, (serveUrl, urls) => renderChunked(chunkDir, key, manifest.totalFrames, chunkFrames, project.path(path), {
+        renderRange: (from, to, out) => renderVideoRange(serveUrl, { manifest, urls }, out, from, to, options),
+        renderSound: async (out) => {
+          const lists = readdirSync(chunkDir).filter((f) => f.endsWith(".audio.json")).map((f) => JSON.parse(readFileSync(join(chunkDir, f), "utf8")) as CapturedAudio[]);
+          const merged = mergeAudioRecords(lists);
+          saveSoundMap(project, urls, merged);
+          if (!merged.length) return false;
+          await mixCapturedAudio(merged, out, manifest.totalFrames / manifest.fps);
+          return existsSync(out) && statSync(out).size > 44;
+        },
+        countFrames, log: ctx.log,
+        reuseExtra: (file) => existsSync(`${file}.audio.json`),
+      }));
+    } else {
+      // The browser can fail to start or drop its connection; that is no fault of the composition, so it gets another go.
+      await withRetry(() => withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path), options, project.path(SOUND_RECORDS)).then(() => {
+        const file = project.path(SOUND_RECORDS);
+        if (existsSync(file)) { saveSoundMap(project, urls, JSON.parse(readFileSync(file, "utf8")) as { src: string; start: number; end: number; volume: number }[]); rmSync(file, { force: true }); }
+      })), { onRetry: (n, e) => ctx.log(`The browser failed (${(e instanceof Error ? e.message : String(e)).split("\n")[0]}); rendering again (attempt ${n + 1}).`) });
+    }
   } catch (e) {
-    return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
+    return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}${deps.chunk ? " The finished pieces are kept: run the same command again to continue from them." : " For a long film, \`reelkit render --chunk\` keeps finished pieces and continues from them."}`]);
   }
+  const problem = await (deps.verify ?? verifyRender)(project.path(path), manifest.totalFrames).catch((e) => `it could not be checked (${e instanceof Error ? e.message : String(e)})`);
+  if (problem) return failed([`The render finished but ${problem}. Render again${deps.chunk ? "; finished pieces are reused" : ""}.`]);
+  if (chunked) rmSync(project.path(CHUNK_DIR), { recursive: true, force: true });
   const seconds = manifest.totalFrames / manifest.fps;
   // One last pass brings the whole programme to the loudness platforms play at. If it fails the render is still the render.
   let loudness: Mastered | undefined;
@@ -308,11 +386,24 @@ export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; ma
     if (voiceless) soundLine = soundAdvice(sound);
     else if (sound.voice) soundLine = voiceAdvice(sound.voice);
   } catch { sound = undefined; }
+  // The guard: what changed against the film before, and whether any of it lies outside what was asked for. A failed guard shares nothing.
+  let guard: { report: DiffReport; ok: boolean; lines: string[] } | undefined;
+  if (guardPath) {
+    try {
+      const report = await compareFilms(guardPath, project.path(path), { allow: deps.allow ?? "", allowAudio: deps.allowAudio, threshold: deps.threshold });
+      guard = { report, ...diffSummary(report, true) };
+    } catch (e) { return failed([`The render is written, but it could not be compared with ${guardPath}: ${e instanceof Error ? e.message : String(e)}`]); }
+  }
+  const pieces = chunked ? [`Rendered in ${chunked.chunks} pieces (${chunked.reused} reused from an earlier run, ${chunked.rendered} rendered${chunked.retries ? `, ${chunked.retries} retr${chunked.retries === 1 ? "y" : "ies"}` : ""}).`] : [];
+  const kept = keptPrevious ? [`The render before this one is kept as ${PREVIOUS_RENDER}; \`reelkit diff ${PREVIOUS_RENDER} ${path} --allow <frames>\` shows what changed.`] : [];
+  if (guard && !guard.ok) {
+    return { ok: false, data: { path, seconds, guard: guard.report }, summary: [`Video: ${project.path(path)} was rendered, but it changed more than was allowed.`, ...guard.lines, "Nothing was shared. Fix the composition, or widen --allow if the change is wanted."].join("\n") };
+  }
   const share = await shareAfterRender(ctx, project, { noShare: deps.noShare });
   return {
-    ok: true, data: { path, seconds, ...(loudness ? { loudness } : {}),
+    ok: true, data: { path, seconds, ...(guard ? { guard: guard.report } : {}), ...(chunked ? { chunked } : {}), ...(loudness ? { loudness } : {}),
       ...(sound ? { sound: { hitsPerSecond: sound.hitsPerSecond, swellsPerSecond: sound.swellsPerSecond, pictureChanges: sound.pictureChanges, changesWithHit: sound.changesWithHit, firstSoundSec: sound.firstSoundSec }, ...(sound.voice ? { voice: sound.voice } : {}) } : {}), ...(share.data ? { shared: share.data.shared.map((s) => s.name) } : {}) },
-    summary: [`Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height}).${masterNote}`, ...(soundLine ? [soundLine] : []), ...share.lines].join("\n"),
+    summary: [`Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height}).${masterNote}`, ...pieces, ...(soundLine ? [soundLine] : []), ...(guard ? guard.lines : []), ...kept, ...share.lines].join("\n"),
   };
 }
 

package/src/commands/clock.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Ctx, Result } from "../context";
+import { clockFromSource, describe, filmLength, parseKeep, pieces, validateClock, type Clock } from "../clock/clock";
+
+export type ClockOpts = { keep?: string; opening?: string | number; film?: boolean; fps?: string | number };
+
+// The clock of this project: from the flags, else clock.json, else constants in src/Video.tsx.
+export function loadClock(cwd: string, opts: ClockOpts = {}): { clock: Clock; from: string } | undefined {
+  if (opts.keep) return { clock: { opening: Number(opts.opening ?? 0), keep: parseKeep(opts.keep) }, from: "--keep" };
+  const file = join(cwd, "clock.json");
+  if (existsSync(file)) {
+    const j = JSON.parse(readFileSync(file, "utf8")) as Partial<Clock>;
+    return { clock: { opening: Number(j.opening ?? 0), keep: (j.keep ?? []) as [number, number][] }, from: "clock.json" };
+  }
+  const video = join(cwd, "src", "Video.tsx");
+  if (existsSync(video)) { const clock = clockFromSource(readFileSync(video, "utf8")); if (clock) return { clock, from: "src/Video.tsx (SEGS)" }; }
+  return undefined;
+}
+
+// `reelkit clock [frames...]`: where a frame of the reference lands in the film, or (--film) which reference frame a film frame shows.
+export async function clockCommand(ctx: Ctx, values: string[], opts: ClockOpts = {}): Promise<Result> {
+  let loaded;
+  try { loaded = loadClock(ctx.cwd, opts); } catch (e) { return { ok: false, summary: e instanceof Error ? e.message : String(e) }; }
+  if (!loaded) return { ok: false, summary: 'No clock found. Give the kept reference ranges with --keep 152-653,782-1028 (and --opening <frames>), or write clock.json: { "opening": 179, "keep": [[152, 653], [782, 1028]] }.' };
+  const problems = validateClock(loaded.clock);
+  if (problems.length) return { ok: false, summary: `The clock (${loaded.from}) is not valid:\n- ${problems.join("\n- ")}` };
+  const fps = Number(opts.fps ?? 30);
+  const nums = values.map(Number);
+  if (nums.some((n) => !Number.isFinite(n))) return { ok: false, summary: "Give frames as whole numbers, such as `reelkit clock 802 1581`." };
+  const table = pieces(loaded.clock).map((p) => `reference ${p.refFrom}-${p.refTo} -> film ${p.filmFrom}-${p.filmTo} (film = reference ${p.filmFrom - p.refFrom >= 0 ? "+" : "-"} ${Math.abs(p.filmFrom - p.refFrom)})`);
+  const lines = describe(loaded.clock, nums, opts.film ? "film" : "ref", fps);
+  return {
+    ok: true, data: { clock: loaded.clock, from: loaded.from, pieces: pieces(loaded.clock), filmFrames: filmLength(loaded.clock), answers: lines },
+    summary: [`Clock from ${loaded.from}: opening ${loaded.clock.opening} frames, film ${filmLength(loaded.clock)} frames. End frames are exclusive.`, ...table, ...(lines.length ? ["", ...lines] : [])].join("\n"),
+  };
+}

package/src/commands/diff.ts

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Ctx, Result } from "../context";
+import { DEFAULT_AUDIO_DB, DEFAULT_THRESHOLD, DIFF_HEIGHT, DIFF_WIDTH, judgePicture, judgeSound, meanAbsDiff, parseAllow, rangesText, windowLevels, type PictureVerdict, type Range, type SoundVerdict } from "../diff/framediff";
+import { grayFrames, monoSamples, videoFacts } from "../media/ffmpeg";
+
+export type DiffOpts = { allow?: string; allowAudio?: string; threshold?: string | number; audioThreshold?: string | number; audio?: boolean };
+
+const AUDIO_RATE = 8000;
+
+// The difference of every frame of two films, decoded side by side as small grey pictures. Memory holds one film's small frames (about 58 KB each) at a time
+// only as long as the other catches up, so the old film is decoded first into a list and the new one is compared as it streams.
+export async function pictureDiffs(oldPath: string, newPath: string): Promise<{ diffs: number[]; old: number; new: number }> {
+  const old: Uint8Array[] = [];
+  await grayFrames(oldPath, DIFF_WIDTH, DIFF_HEIGHT, (f) => { old.push(f); });
+  const diffs: number[] = [];
+  const count = await grayFrames(newPath, DIFF_WIDTH, DIFF_HEIGHT, (f, i) => { if (i < old.length) diffs.push(meanAbsDiff(old[i]!, f)); });
+  return { diffs, old: old.length, new: count };
+}
+
+export type DiffReport = { fps: number; allow: Range[]; picture: PictureVerdict; sound?: SoundVerdict };
+
+export async function compareFilms(oldPath: string, newPath: string, opts: DiffOpts = {}): Promise<DiffReport> {
+  const facts = await videoFacts(newPath);
+  const fps = facts.fps || 30;
+  const allow = parseAllow(opts.allow, fps);
+  const threshold = opts.threshold === undefined ? DEFAULT_THRESHOLD : Number(opts.threshold);
+  if (!Number.isFinite(threshold) || threshold < 0) throw new Error(`--threshold must be a number of grey levels, such as 1.0 (got "${opts.threshold}").`);
+  const { diffs, old, new: count } = await pictureDiffs(oldPath, newPath);
+  const picture = judgePicture(diffs, allow, threshold, { old, new: count });
+  let sound: SoundVerdict | undefined;
+  if (opts.audio !== false) {
+    const [a, b] = [await monoSamples(oldPath, AUDIO_RATE), await monoSamples(newPath, AUDIO_RATE)];
+    if (a && b) {
+      const db = opts.audioThreshold === undefined ? DEFAULT_AUDIO_DB : Number(opts.audioThreshold);
+      if (!Number.isFinite(db) || db <= 0) throw new Error(`--audio-threshold must be a level difference in dB, such as 1.5 (got "${opts.audioThreshold}").`);
+      // The sound has its own allowed ranges when given; otherwise the picture's ranges apply to it too.
+      sound = judgeSound(windowLevels(a, AUDIO_RATE), windowLevels(b, AUDIO_RATE), opts.allowAudio !== undefined ? parseAllow(opts.allowAudio, fps) : allow, fps, db);
+    }
+  }
+  return { fps, allow, picture, ...(sound ? { sound } : {}) };
+}
+
+const secs = (rs: { from: number; to: number }[]) => (rs.length ? rs.map((r) => `${r.from.toFixed(1)}-${r.to.toFixed(1)}s`).join(", ") : "none");
+
+export function diffSummary(r: DiffReport, strict: boolean): { ok: boolean; lines: string[] } {
+  const p = r.picture;
+  const lines = [
+    `Picture: ${p.frames} frames compared at ${DIFF_WIDTH}x${DIFF_HEIGHT} grey, a frame counts as changed above a mean difference of ${p.threshold}.`,
+    `Changed frames: ${rangesText(p.changed)}.`,
+    `Largest difference on an unchanged frame: ${p.maxUnchanged}.`,
+  ];
+  let ok = true;
+  if (p.lengthDiffers) { lines.push(`The films differ in length: ${p.lengthDiffers.old} frames before, ${p.lengthDiffers.new} now.`); if (strict) ok = false; }
+  if (strict) {
+    lines.push(`Allowed: ${rangesText(r.allow)}.`);
+    if (p.outside.length) { ok = false; lines.push(`CHANGED OUTSIDE the allowed ranges: ${rangesText(p.outside)}.`); }
+    else lines.push("Nothing changed outside the allowed ranges.");
+    if (p.untouchedAllowed.length) lines.push(`Allowed but identical (a change that was asked for and is not there?): ${rangesText(p.untouchedAllowed)}.`);
+  }
+  if (r.sound) {
+    lines.push(`Sound: ${r.sound.windows} windows of 0.1 s, changed where the level moved by more than ${r.sound.thresholdDb} dB: ${secs(r.sound.changedSec)}.`);
+    if (strict) {
+      if (r.sound.outsideSec.length) { ok = false; lines.push(`SOUND CHANGED OUTSIDE the allowed ranges: ${secs(r.sound.outsideSec)}.`); }
+      else lines.push("No sound changed outside the allowed ranges.");
+    }
+  }
+  return { ok, lines };
+}
+
+// `reelkit diff <old> <new>`: which frames and which stretches of sound differ. With --allow it is a guard: any change outside the allowed ranges fails.
+export async function diffCommand(ctx: Ctx, oldFile: string, newFile: string, opts: DiffOpts = {}): Promise<Result> {
+  const [a, b] = [resolve(ctx.cwd, oldFile), resolve(ctx.cwd, newFile)];
+  for (const [p, name] of [[a, oldFile], [b, newFile]] as const) if (!existsSync(p)) return { ok: false, summary: `${name} does not exist. Check the path.` };
+  let report: DiffReport;
+  try { ctx.log("Decoding both films..."); report = await compareFilms(a, b, opts); }
+  catch (e) { return { ok: false, summary: e instanceof Error ? e.message : String(e) }; }
+  const strict = opts.allow !== undefined || opts.allowAudio !== undefined;
+  const { ok, lines } = diffSummary(report, strict);
+  return { ok, data: report, summary: lines.join("\n") };
+}

package/src/commands/export.ts

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import type { Ctx, Result } from "../context";
+import { EXPORT_PRESETS, checkTable, exportArgs, outputSize, presetById, topLevelBoxes, verifyExport, type ExportCheck, type ExportPreset } from "../export/presets";
+import { fullDecode, probeStreams, readBytes, syncFile, videoFacts } from "../media/ffmpeg";
+import { tool } from "../project/refmeasure";
+
+export type ExportOpts = { preset?: string; out?: string; list?: boolean; verifyOnly?: boolean };
+// What a test may replace: the encode itself.
+export type ExportDeps = { encode?: (args: string[]) => Promise<void> };
+
+export const defaultExportPath = (input: string, preset: ExportPreset) => join(dirname(input), `${basename(input, extname(input))}.${preset.id}.mp4`);
+
+// Measures an encoded file against what its preset promises.
+export async function verifyFile(output: string, source: string, preset: ExportPreset): Promise<ExportCheck[]> {
+  const bytes = existsSync(output) ? statSync(output).size : 0;
+  if (!bytes) return verifyExport({ preset, size: { width: 0, height: 0 }, streams: [], frames: 0, sourceFrames: -1, decodeErrors: 1, moovAt: -1, mdatAt: -1, bytes: 0, sourceHasAudio: false });
+  syncFile(output);
+  const src = await videoFacts(source);
+  const [{ streams }, decoded, sourceDecoded] = [await probeStreams(output), await fullDecode(output), source === output ? undefined : await fullDecode(source)];
+  const file = readBytes(output);
+  let boxes;
+  try { boxes = topLevelBoxes(file.read, file.size); } finally { file.close(); }
+  return verifyExport({ preset, size: outputSize(src, preset.shortSide), streams, frames: decoded.frames, sourceFrames: sourceDecoded?.frames ?? decoded.frames, decodeErrors: decoded.errorLines.length, ...boxes, bytes, sourceHasAudio: src.hasAudio });
+}
+
+// `reelkit export [file]`: a delivery copy of a finished render that a phone plays, then proof that it is one.
+export async function exportCommand(ctx: Ctx, file: string | undefined, opts: ExportOpts = {}, deps: ExportDeps = {}): Promise<Result> {
+  if (opts.list) return { ok: true, data: { presets: EXPORT_PRESETS }, summary: EXPORT_PRESETS.map((p) => `${p.id}: ${p.purpose}`).join("\n") };
+  const input = resolve(ctx.cwd, file ?? "out/video.mp4");
+  if (!existsSync(input)) return { ok: false, summary: `${file ?? "out/video.mp4"} does not exist. ${file ? "Check the path." : "Run `reelkit render` first, or give the file."}` };
+  const preset = presetById(opts.preset ?? "iphone");
+  if (!preset) return { ok: false, summary: `Unknown preset "${opts.preset}". Use one of: ${EXPORT_PRESETS.map((p) => p.id).join(", ")}.` };
+  const output = opts.verifyOnly ? input : resolve(ctx.cwd, opts.out ?? defaultExportPath(input, preset));
+  if (!opts.verifyOnly) {
+    if (output === input) return { ok: false, summary: "The output would overwrite the input. Give another path with --out." };
+    const src = await videoFacts(input);
+    mkdirSync(dirname(output), { recursive: true });
+    ctx.log(`Encoding ${preset.id}: ${outputSize(src, preset.shortSide).width}x${outputSize(src, preset.shortSide).height}, ${preset.profile} profile level ${preset.level}...`);
+    try { await (deps.encode ?? (async (args) => { await tool("ffmpeg", args); }))(exportArgs(input, output, src, preset)); }
+    catch (e) { return { ok: false, summary: `The encode failed: ${(e instanceof Error ? e.message : String(e)).trim().split("\n").at(-1)}` }; }
+  }
+  ctx.log("Verifying: tags, full decode, frame count, index position...");
+  const checks = await verifyFile(output, input, preset);
+  const ok = checks.every((c) => c.ok);
+  const size = existsSync(output) ? `${(statSync(output).size / 1e6).toFixed(1)} MB` : "missing";
+  return {
+    ok, data: { path: output, preset: preset.id, bytes: existsSync(output) ? statSync(output).size : 0, checks },
+    summary: `${opts.verifyOnly ? "Checked" : "Export"}: ${output} (${preset.id}, ${size})\n${checkTable(checks)}\n${ok ? "All checks pass." : `${checks.filter((c) => !c.ok).length} check(s) FAILED: do not send this file.`}`,
+  };
+}

package/src/commands/lint.ts

@@ -0,0 +1,94 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { Ctx, Result } from "../context";
+import { loadClock } from "./clock";
+import { meanAbsDiff } from "../diff/framediff";
+import { edgeHits, flashes, frameStat, persistentEdgeHits, type EdgeFinding, type EdgeHit, type Flash, type FrameStat } from "../lint/pixel-rules";
+import { nestedSequenceFindings, niqqudFindings, rtlFindings, shotFindings, type Finding } from "../lint/source-rules";
+import { grayFrames, videoFacts } from "../media/ffmpeg";
+
+export type LintOpts = { video?: boolean; minFrames?: string | number; from?: string | number; to?: string | number; allowNiqqud?: boolean };
+
+const LINT_LONG_SIDE = 480;
+const THUMB = 5;
+
+// Each frame shrunk by whole blocks, small enough to keep every one in memory for the flash measurement.
+function thumb(frame: Uint8Array, w: number, h: number): Uint8Array {
+  const tw = Math.floor(w / THUMB), th = Math.floor(h / THUMB);
+  const out = new Uint8Array(tw * th);
+  for (let y = 0; y < th; y++) for (let x = 0; x < tw; x++) {
+    let sum = 0;
+    for (let dy = 0; dy < THUMB; dy++) for (let dx = 0; dx < THUMB; dx++) sum += frame[(y * THUMB + dy) * w + x * THUMB + dx]!;
+    out[y * tw + x] = Math.round(sum / (THUMB * THUMB));
+  }
+  return out;
+}
+
+export type PictureLint = { frames: number; firstFrame: number; edges: EdgeFinding[]; flashes: Flash[] };
+
+export async function lintPicture(path: string, opts: { minFrames?: number; from?: number; to?: number } = {}): Promise<PictureLint> {
+  const facts = await videoFacts(path);
+  const k = LINT_LONG_SIDE / Math.max(facts.width, facts.height);
+  const w = Math.round((facts.width * k) / 2) * 2, h = Math.round((facts.height * k) / 2) * 2;
+  const perFrame: EdgeHit[][] = [], thumbs: Uint8Array[] = [], stats: FrameStat[] = [], toPrev: number[] = [];
+  const frames = await grayFrames(path, w, h, (f) => {
+    perFrame.push(edgeHits(f, w, h));
+    const t = thumb(f, w, h);
+    toPrev.push(thumbs.length ? meanAbsDiff(thumbs.at(-1)!, t) : 0);
+    thumbs.push(t); stats.push(frameStat(t));
+  }, { from: opts.from, to: opts.to });
+  const first = opts.from ?? 0;
+  return {
+    frames, firstFrame: first,
+    edges: persistentEdgeHits(perFrame, opts.minFrames ?? 4, first),
+    flashes: flashes({ toPrev, stats, across: (a, b) => meanAbsDiff(thumbs[a]!, thumbs[b]!) }).map((f) => ({ ...f, from: f.from + first, to: f.to + first })),
+  };
+}
+
+// The source rules for every component file of a project.
+export function lintSources(dir: string, opts: { allowNiqqud?: boolean } = {}): Finding[] {
+  const srcDir = join(dir, "src");
+  if (!existsSync(srcDir)) return [];
+  const config = existsSync(join(dir, "reelkit.json")) ? (JSON.parse(readFileSync(join(dir, "reelkit.json"), "utf8")) as { lint?: { allowNiqqud?: boolean } }) : {};
+  const allowNiqqud = opts.allowNiqqud ?? config.lint?.allowNiqqud ?? false;
+  const scenes = existsSync(join(dir, "manifest.json")) ? (JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8")) as { scenes?: { id: string; startFrame: number; durationFrames: number }[] }).scenes : undefined;
+  let clock;
+  try { clock = loadClock(dir)?.clock; } catch { clock = undefined; }
+  const out: Finding[] = [];
+  for (const name of readdirSync(srcDir).filter((f) => f.endsWith(".tsx")).sort()) {
+    const source = readFileSync(join(srcDir, name), "utf8");
+    out.push(...rtlFindings(source, name), ...(allowNiqqud ? [] : niqqudFindings(source, name)), ...nestedSequenceFindings(source, name));
+    if (clock) out.push(...shotFindings(source, name, clock, { scenes }));
+  }
+  return out;
+}
+
+const edgeLine = (e: EdgeFinding) => `frames ${e.from}-${e.to}: strokes cut by the ${e.edge} edge, about ${Math.round(e.at * 100)}% along it`;
+
+// `reelkit lint [file]`: advice from the source and from the rendered film. It never fails a build; it lists what to look at.
+export async function lintCommand(ctx: Ctx, file: string | undefined, opts: LintOpts = {}): Promise<Result> {
+  const findings = lintSources(ctx.cwd, { allowNiqqud: opts.allowNiqqud });
+  const lines: string[] = [];
+  const byRule = new Map<string, Finding[]>();
+  for (const f of findings) byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+  lines.push(findings.length ? `Source: ${findings.length} finding(s).` : "Source: nothing found.");
+  for (const [rule, list] of byRule) lines.push(`[${rule}]`, ...list.map((f) => `- ${f.file} line ${f.line}: ${f.message}`));
+  let picture: PictureLint | undefined;
+  const path = resolve(ctx.cwd, file ?? "out/video.mp4");
+  if (opts.video !== false) {
+    if (!existsSync(path)) lines.push(`Picture: not checked, ${file ?? "out/video.mp4"} does not exist. Render first, or give a film: \`reelkit lint <file.mp4>\`.`);
+    else {
+      ctx.log("Reading the rendered frames...");
+      try {
+        picture = await lintPicture(path, { minFrames: opts.minFrames === undefined ? undefined : Number(opts.minFrames), from: opts.from === undefined ? undefined : Number(opts.from), to: opts.to === undefined ? undefined : Number(opts.to) });
+        lines.push(`Picture: ${picture.frames} frames of ${file ?? "out/video.mp4"} read.`);
+        lines.push(picture.edges.length ? `[text-at-edge] ${picture.edges.length} place(s) where something that looks like lettering is cut by an edge of the frame. Look at each; move or shrink the text if it is a word:` : "[text-at-edge] nothing that looks like lettering is cut by an edge.");
+        lines.push(...picture.edges.map((e) => `- ${edgeLine(e)}`));
+        lines.push(picture.flashes.length ? `[flash-over-shot] ${picture.flashes.length} flash(es) of 1 to 3 frames cover a shot that continues after them. A caption or a spoken word on screen is hidden for those frames: check that none is.` : "[flash-over-shot] no flash covers a held shot.");
+        lines.push(...picture.flashes.map((f) => `- frames ${f.from}-${f.to} (${f.kind === "fill" ? "a plain fill" : "another picture"})`));
+      } catch (e) { lines.push(`Picture: could not be read (${e instanceof Error ? e.message : String(e)}).`); }
+    }
+  }
+  lines.push("These are measurements, not rules: lettering on a photograph is not seen, and a pattern can look like lettering. Lettering on a flat or gently graded plate is. Open the frames named.");
+  return { ok: true, data: { source: findings, ...(picture ? { picture } : {}) }, summary: lines.join("\n") };
+}