reelkit-cli 0.10.6 → 0.12.0

package/src/commands/template.ts

@@ -0,0 +1,217 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { uploadTo } from "../api/client";
+import { client, type Ctx, type Result } from "../context";
+import { MAX_TEMPLATE_FILES, MAX_TEMPLATE_SOURCES_BYTES, MAX_TEMPLATE_THUMBS, MAX_TEMPLATE_THUMB_BYTES, MAX_UPLOAD_BYTES, TEMPLATE_BUNDLE_TYPE, type Template, type TemplateFile, type TemplateFilm } from "../contract";
+import type { AssetManifest, ScenePlan } from "../pipeline/schema";
+import type { MusicRecord } from "../project/music";
+import { FILES, openProject, Project } from "../project/project";
+import { SOUND_MAP, type SoundMapEntry } from "./build";
+import { decodeMono } from "../project/refmeasure";
+import { AUDIO_RATE, hitTimes, swells } from "../project/soundreport";
+
+const sh = promisify(execFile);
+
+// A template is a whole project kept in its owner's private files on the server, to continue later or to start a new video from.
+// What is sent: the project folder as one archive (the plan, the composition, and every file under assets/, including the user's own
+// pictures, footage and the recorded voice), the rendered video when there is one, and a small picture of each scene. What is left on
+// this machine: out/ (renders and previews), refs/ (reference videos), caches and node_modules.
+export const TEMPLATE_SKIP = ["out", "refs", ".reelkit", "node_modules", ".git", ".DS_Store"];
+const VIDEO = "out/video.mp4";
+// Where a project remembers the template it was cloned from, and the last one it was pushed as. Never part of a bundle.
+const LINK = ".reelkit/template.json";
+const TEMPLATE_ID = /^tpl-[a-z0-9]{12}$/;
+
+const mb = (bytes: number) => `${(bytes / 1_048_576).toFixed(bytes < 10_485_760 ? 1 : 0)} MB`;
+const clock = (sec: number) => `${Math.floor(sec / 60)}:${String(Math.round(sec % 60)).padStart(2, "0")}`;
+
+// The timeline as a page can draw it, from the manifest (the real timings) and the plan (the words). Times are in frames of the film;
+// a scene's `words` and the music's `beats` are in seconds.
+export function filmOf(project: Project): TemplateFilm | undefined {
+  const manifest = project.readJsonOr<AssetManifest | undefined>(FILES.manifest, undefined);
+  const plan = project.readJsonOr<ScenePlan | undefined>(FILES.plan, undefined);
+  if (!manifest?.scenes?.length || !plan) return undefined;
+  const byId = new Map(plan.scenes.map((s) => [s.id, s]));
+  const music = project.readJsonOr<MusicRecord | undefined>(FILES.music, undefined);
+  const seconds = manifest.totalFrames / manifest.fps;
+  const cut = (s: string, max: number) => (s.length > max ? s.slice(0, max) : s);
+  return {
+    aspect: plan.aspect, fps: manifest.fps, width: manifest.width, height: manifest.height, totalFrames: Math.round(manifest.totalFrames),
+    scenes: manifest.scenes.slice(0, 200).map((m) => {
+      const p = byId.get(m.id);
+      const narration = p?.narration?.trim();
+      const text = (p?.onScreenText ?? []).map((t) => cut(t, 400)).slice(0, 20);
+      return {
+        id: cut(m.id, 80), start: Math.max(0, Math.round(m.startFrame)), frames: Math.max(0, Math.round(m.durationFrames)),
+        ...(p?.treatment ? { treatment: cut(p.treatment, 60) } : {}), ...(narration ? { narration: cut(narration, 4000) } : {}),
+        ...(text.length ? { text } : {}), ...(m.words.length ? { words: m.words.slice(0, 600).map((w) => Math.max(0, Math.round(w.startSec * 1000) / 1000)) } : {}),
+      };
+    }),
+    ...(music ? { music: { title: cut(music.title, 200), seconds: music.durationSec, ...(music.bpm ? { bpm: music.bpm } : {}), beats: music.beats.filter((b) => b >= 0 && b <= seconds).slice(0, 4000) } } : {}),
+    voice: plan.voice !== "none",
+    ...(manifest.captions ? { captions: manifest.captions } : {}),
+    ...cuesOf(project, manifest, music?.key),
+  };
+}
+
+// The sound effects by name, from what the last render recorded (out/sounds.json): every sound that is not the music or a scene's
+// voice, with the title it has in the library when it was pulled from there, or its file name.
+function cuesOf(project: Project, manifest: AssetManifest, musicKey: string | undefined): Pick<TemplateFilm, "cues"> {
+  const map = project.readJsonOr<SoundMapEntry[]>(SOUND_MAP, []);
+  if (!Array.isArray(map) || !map.length) return {};
+  const pulled = Object.values(project.readJsonOr<Record<string, { path?: string; kind?: string; title?: string; meta?: { durationSec?: number } }>>(FILES.library, {}));
+  const voice = new Set(manifest.scenes.map((s) => s.voiceoverKey).filter(Boolean));
+  const cues = map.filter((e) => e && typeof e.path === "string" && e.path !== musicKey && e.path !== manifest.music?.key && !voice.has(e.path)).flatMap((e) => {
+    const lib = pulled.find((p) => p.path === e.path);
+    if (lib?.kind === "music") return [];
+    const title = (lib?.title ?? basename(e.path).replace(/\.[a-z0-9]+$/i, "")).slice(0, 200);
+    // A sound is registered until the end of the stretch it sits in, which is often the rest of the film: its own length is the file's.
+    const own = typeof lib?.meta?.durationSec === "number" && lib.meta.durationSec > 0 ? lib.meta.durationSec : 0;
+    const seconds = Math.max(0, Math.round(Math.min(own || 0, Math.max(0, e.end - e.start)) * 1000) / 1000);
+    return [{ at: Math.max(0, e.start), seconds, title, ...(lib?.kind ? { kind: lib.kind.slice(0, 24) } : {}) }];
+  }).slice(0, 1500);
+  return cues.length ? { cues } : {};
+}
+
+// One small JPEG per scene, taken from the middle of it in the rendered video. A scene whose frame cannot be read gets none, and the
+// scenes after it still do: the list is in scene order, cut short at the first failure so that positions keep their meaning.
+async function thumbsOf(video: string, film: TemplateFilm, dir: string): Promise<Uint8Array[]> {
+  const out: Uint8Array[] = [];
+  for (const [i, scene] of film.scenes.slice(0, MAX_TEMPLATE_THUMBS).entries()) {
+    const at = (scene.start + scene.frames / 2) / film.fps;
+    const file = join(dir, `thumb-${i}.jpg`);
+    try {
+      await sh("ffmpeg", ["-nostdin", "-v", "error", "-y", "-ss", at.toFixed(3), "-i", video, "-frames:v", "1", "-vf", "scale=320:-2", "-q:v", "7", file]);
+      const bytes = readFileSync(file);
+      if (!bytes.length || bytes.length > MAX_TEMPLATE_THUMB_BYTES) break;
+      out.push(new Uint8Array(bytes));
+    } catch { break; }
+  }
+  return out;
+}
+
+const TEXT_FILE = /\.(tsx?|jsx?|mjs|cjs|json|md|txt|css|html|svg|ya?ml)$/i;
+const MAX_SOURCE_FILE = 200_000;
+
+// What is in the bundle: every file's path and size, and the text of the small text files (the composition, the plan, the records), as
+// one JSON object. The website lists the first and opens the second; media files are listed with their size only.
+export function filesOf(dir: string): { files: TemplateFile[]; sources: Uint8Array | undefined } {
+  const files: TemplateFile[] = [];
+  const texts: Record<string, string> = {};
+  let room = MAX_TEMPLATE_SOURCES_BYTES - 1024;
+  const walk = (rel: string) => {
+    for (const entry of readdirSync(join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!rel && TEMPLATE_SKIP.includes(entry.name)) continue;
+      if (entry.name === ".DS_Store") continue;
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { walk(path); continue; }
+      if (!entry.isFile() || files.length >= MAX_TEMPLATE_FILES || path.length > 400) continue;
+      const bytes = statSync(join(dir, path)).size;
+      files.push({ path, bytes });
+      if (TEXT_FILE.test(entry.name) && bytes <= MAX_SOURCE_FILE && bytes * 1.2 < room) {
+        const text = readFileSync(join(dir, path), "utf8");
+        if (!text.includes("\u0000")) { texts[path] = text; room -= Buffer.byteLength(JSON.stringify(text)) + path.length + 8; }
+      }
+    }
+  };
+  walk("");
+  const sources = Object.keys(texts).length ? new Uint8Array(Buffer.from(JSON.stringify(texts))) : undefined;
+  return { files, sources: sources && sources.length <= MAX_TEMPLATE_SOURCES_BYTES ? sources : undefined };
+}
+
+const readLink = (project: Project): { id?: string; from?: string } => { try { return project.readJsonOr<{ id?: string; from?: string }>(LINK, {}); } catch { return {}; } };
+
+export async function templatePush(ctx: Ctx, opts: { name?: string }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  const film = filmOf(project);
+  if (!film) return { ok: false, summary: "This project has no timeline yet. Make its assets and run `reelkit check` (or `reelkit render`) first, then push it." };
+  const name = (opts.name ?? project.config().name ?? basename(resolve(ctx.cwd))).trim().slice(0, 80);
+  if (!name) return { ok: false, summary: "Give the template a name: `reelkit template push --name \"Launch film\"`." };
+  const plan = project.readJsonOr<ScenePlan | undefined>(FILES.plan, undefined);
+  const work = mkdtempSync(join(tmpdir(), "rk-template-"));
+  try {
+    const bundle = join(work, "bundle.tgz");
+    ctx.log("Packing the project.");
+    await sh("tar", ["-czf", bundle, ...TEMPLATE_SKIP.flatMap((x) => ["--exclude", `./${x}`]), "-C", project.dir, "."], { maxBuffer: 1 << 24 });
+    const bundleBytes = statSync(bundle).size;
+    if (bundleBytes > MAX_UPLOAD_BYTES) return { ok: false, summary: `The project packs to ${mb(bundleBytes)}, over the ${mb(MAX_UPLOAD_BYTES)} a template may be. Remove large files under assets/ that the video does not use and push again.` };
+    const video = project.exists(VIDEO) ? project.path(VIDEO) : undefined;
+    const videoBytes = video ? statSync(video).size : 0;
+    if (videoBytes > MAX_UPLOAD_BYTES) return { ok: false, summary: `The rendered video is ${mb(videoBytes)}, over the ${mb(MAX_UPLOAD_BYTES)} limit. Export a smaller one with \`reelkit export\` or push without a render.` };
+    const thumbs = video ? await thumbsOf(video, film, work) : [];
+    // The sound effects are placed by the composition's code, so where they land is measured from the render itself.
+    if (video) {
+      try {
+        const samples = await decodeMono(video, AUDIO_RATE);
+        const r3 = (n: number) => Math.round(n * 1000) / 1000;
+        film.hits = hitTimes(samples, AUDIO_RATE).slice(0, 3000).map(r3);
+        film.swells = swells(samples, AUDIO_RATE).slice(0, 600).map((w) => ({ start: r3(w.start), length: r3(w.length) }));
+      } catch { /* a render with no sound, or one that cannot be read: the timeline has no sound-effects row */ }
+    }
+    const link = readLink(project);
+    const { files, sources } = filesOf(project.dir);
+    const api = client(ctx);
+    const started = await api("templateStart", {
+      name, ...(plan?.title ? { title: plan.title.slice(0, 200) } : {}), bundleBytes, ...(videoBytes ? { videoBytes } : {}),
+      thumbBytes: thumbs.map((t) => t.length), film, ...(link.from && TEMPLATE_ID.test(link.from) ? { from: link.from } : {}),
+      files, ...(sources ? { sourcesBytes: sources.length } : {}),
+    });
+    ctx.log(`Uploading ${mb(bundleBytes + videoBytes)} to your private files.`);
+    await uploadTo(started.bundleUrl, new Uint8Array(readFileSync(bundle)), TEMPLATE_BUNDLE_TYPE);
+    if (video && started.videoUrl) await uploadTo(started.videoUrl, new Uint8Array(readFileSync(video)), "video/mp4");
+    if (sources && started.sourcesUrl) await uploadTo(started.sourcesUrl, sources, "application/json");
+    for (const [i, url] of started.thumbUrls.entries()) if (thumbs[i]) await uploadTo(url, thumbs[i]!, "image/jpeg");
+    const { template } = await api("templateCommit", { id: started.id });
+    project.writeJson(LINK, { ...link, id: template.id });
+    return {
+      ok: true, data: { template },
+      summary: `Saved the template "${template.name}" as ${template.id} in your private files: the project (${mb(bundleBytes)}, with your own files under assets/)${videoBytes ? `, the rendered video (${mb(videoBytes)})` : ", with no rendered video (render first to keep one)"} and ${thumbs.length} scene picture${thumbs.length === 1 ? "" : "s"}. Only you can see it. Start from it anywhere with \`reelkit template clone ${template.id}\`.`,
+    };
+  } finally { rmSync(work, { recursive: true, force: true }); }
+}
+
+const line = (t: Template) => `${t.id}  ${t.name}  ${t.aspect}  ${clock(t.durationSec)}  ${t.scenes} scene${t.scenes === 1 ? "" : "s"}  ${mb(t.bundleBytes + (t.videoBytes ?? 0))}  ${t.createdAt.slice(0, 10)}${t.from ? `  from ${t.from}` : ""}`;
+
+export async function templateList(ctx: Ctx): Promise<Result> {
+  const { templates } = await client(ctx)("templateList", {});
+  return { ok: true, data: { templates }, summary: templates.length ? `${templates.map(line).join("\n")}\nClone one with \`reelkit template clone <id>\`.` : "You have no templates yet. In a project, run `reelkit template push`." };
+}
+
+// Entries of an archive that would land outside the folder it is unpacked into are refused before anything is written.
+const unsafe = (entry: string) => entry.startsWith("/") || /^[A-Za-z]:/.test(entry) || entry.split(/[\\/]/).includes("..");
+
+export async function templateClone(ctx: Ctx, id: string, dirArg?: string): Promise<Result> {
+  if (!TEMPLATE_ID.test(id)) return { ok: false, summary: `"${id}" is not a template id. List yours with \`reelkit template list\`.` };
+  const got = await client(ctx)("templateGet", { id });
+  const slug = got.template.name.toLowerCase().replace(/[^a-z0-9֐-׿]+/g, "-").replace(/^-+|-+$/g, "") || id;
+  const dir = resolve(ctx.cwd, dirArg ?? slug);
+  if (existsSync(dir) && readdirSync(dir).length) return { ok: false, summary: `${dir} already has files in it. Give another folder: \`reelkit template clone ${id} <folder>\`.` };
+  const work = mkdtempSync(join(tmpdir(), "rk-template-"));
+  try {
+    const res = await fetch(got.bundleUrl);
+    if (!res.ok) return { ok: false, summary: `The template could not be downloaded (${res.status}). Run the command again.` };
+    const bundle = join(work, "bundle.tgz");
+    writeFileSync(bundle, new Uint8Array(await res.arrayBuffer()));
+    const { stdout } = await sh("tar", ["-tzf", bundle], { maxBuffer: 1 << 26 });
+    const bad = stdout.split("\n").filter(Boolean).find(unsafe);
+    if (bad) return { ok: false, summary: `The template holds a path that leaves its folder (${bad}), so nothing was unpacked.` };
+    mkdirSync(dir, { recursive: true });
+    await sh("tar", ["-xzf", bundle, "-C", dir], { maxBuffer: 1 << 24 });
+    if (!existsSync(join(dir, FILES.config))) return { ok: false, summary: `The template unpacked into ${dir}, but it holds no ${FILES.config}: it is not a Reelkit project.` };
+    // The new folder is a project of its own: what is pushed from it is a new template that remembers where it came from.
+    new Project(dir).writeJson(LINK, { from: id });
+    return {
+      ok: true, data: { dir, template: got.template },
+      summary: `Cloned "${got.template.name}" into ${dir}: the plan, the composition and its assets. It is a copy of its own, so changing it does not change the template. Next: \`cd ${dirArg ?? slug}\`, then \`reelkit check\` and \`reelkit preview\`. \`reelkit template push\` there saves it as a new template.`,
+    };
+  } finally { rmSync(work, { recursive: true, force: true }); }
+}
+
+export async function templateDelete(ctx: Ctx, id: string): Promise<Result> {
+  if (!TEMPLATE_ID.test(id)) return { ok: false, summary: `"${id}" is not a template id. List yours with \`reelkit template list\`.` };
+  await client(ctx)("templateDelete", { id });
+  return { ok: true, data: { id }, summary: `Deleted the template ${id} from your private files. Projects cloned from it are not touched.` };
+}

package/src/contract/index.ts

@@ -172,6 +172,49 @@ export const MeSchema = z.object({
 });
 
 const Empty = z.object({});
+// ── Templates ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+// A template is a whole video project kept in its owner's private files: the bundle (the project folder as a .tgz, without out/, refs/
+// and caches), the rendered video when there is one, a small picture per scene, and `film`, a summary of the timeline that a page can
+// draw without opening the bundle. Only its owner can list, read, clone or delete it. Nothing here reaches the shared library.
+export const MAX_TEMPLATES = 20;
+export const MAX_TEMPLATE_THUMBS = 60;
+export const MAX_TEMPLATE_THUMB_BYTES = 200_000;
+export const TEMPLATE_BUNDLE_TYPE = "application/gzip";
+// The bundle's file list, and the text of its small text files (one JSON object, path to text), so a page can show the project's
+// files and open the source ones without unpacking the bundle.
+export const MAX_TEMPLATE_FILES = 3000;
+export const MAX_TEMPLATE_SOURCES_BYTES = 3_145_728;
+export const TemplateFileSchema = z.object({ path: z.string().min(1).max(400), bytes: z.number().int().min(0) });
+export type TemplateFile = z.infer<typeof TemplateFileSchema>;
+const TemplateId = z.string().regex(/^tpl-[a-z0-9]{12}$/);
+const frames = z.number().int().min(0).max(1_000_000);
+export const TemplateFilmSchema = z.object({
+  aspect: z.string().max(8), fps: z.number().min(1).max(120), width: z.number().int().min(16).max(8192), height: z.number().int().min(16).max(8192), totalFrames: frames,
+  // One entry per scene, in order. `words` are the seconds from the scene's start at which each spoken word begins.
+  scenes: z.array(z.object({
+    id: text(80), start: frames, frames, treatment: text(60).optional(), narration: text(4000).optional(),
+    text: z.array(text(400)).max(20).optional(), words: z.array(z.number().min(0)).max(600).optional(),
+  })).min(1).max(200),
+  // The music track, with the seconds at which its beats fall inside the film.
+  music: z.object({ title: text(200), seconds: z.number().min(0), bpm: z.number().optional(), beats: z.array(z.number().min(0)).max(4000).optional() }).optional(),
+  voice: z.boolean().optional(),
+  captions: z.string().max(16).optional(),
+  // What a listener hears besides the voice and the music's pulse, measured from the rendered film's sound: the seconds at which a hit
+  // lands (a click, a pop, an impact) and the swells (a whoosh, a riser), each with its start and length in seconds.
+  hits: z.array(z.number().min(0)).max(3000).optional(),
+  swells: z.array(z.object({ start: z.number().min(0), length: z.number().min(0) })).max(600).optional(),
+  // The sound effects by name, when the render recorded them: each one's title, when it starts and how long it plays, in seconds.
+  cues: z.array(z.object({ at: z.number().min(0), seconds: z.number().min(0), title: text(200), kind: text(24).optional() })).max(1500).optional(),
+});
+export type TemplateFilm = z.infer<typeof TemplateFilmSchema>;
+export const TemplateSchema = z.object({
+  id: TemplateId, name: z.string(), title: z.string().optional(), createdAt: z.string(), bundleBytes: z.number(), videoBytes: z.number().optional(),
+  aspect: z.string(), durationSec: z.number(), scenes: z.number(), thumbs: z.number(),
+  // The template this one was cloned from, when it was pushed from a clone.
+  from: z.string().optional(),
+});
+export type Template = z.infer<typeof TemplateSchema>;
+
 const route = <Q extends z.ZodType, S extends z.ZodType>(method: "GET" | "POST", path: string, auth: boolean, req: Q, res: S) => ({ method, path, auth, req, res });
 
 export const routes = {
@@ -258,6 +301,23 @@ export const routes = {
   transcribeRun: route("POST", "/transcripts/run", true,
     z.object({ id: ItemId }),
     z.object({ id: z.string(), text: z.string(), language: z.string().optional(), segments: z.array(TranscriptSegmentSchema), durationSec: z.number().positive() })),
+  // Starts a template: answers its id and one upload URL per file. Each URL takes one PUT of exactly the size and type named here
+  // (the bundle as application/gzip, the video as video/mp4, each thumb as image/jpeg, in scene order). The template exists for its
+  // owner only after `templateCommit`. A user may keep MAX_TEMPLATES; one more is refused with invalid_request.
+  templateStart: route("POST", "/templates", true,
+    z.object({
+      name: text(80).min(1), title: text(200).optional(), bundleBytes: z.number().int().min(1).max(MAX_UPLOAD_BYTES), videoBytes: z.number().int().min(1).max(MAX_UPLOAD_BYTES).optional(),
+      thumbBytes: z.array(z.number().int().min(1).max(MAX_TEMPLATE_THUMB_BYTES)).max(MAX_TEMPLATE_THUMBS), film: TemplateFilmSchema, from: TemplateId.optional(),
+      files: z.array(TemplateFileSchema).max(MAX_TEMPLATE_FILES).optional(), sourcesBytes: z.number().int().min(2).max(MAX_TEMPLATE_SOURCES_BYTES).optional(),
+    }),
+    z.object({ id: TemplateId, bundleUrl: z.string(), videoUrl: z.string().optional(), thumbUrls: z.array(z.string()), sourcesUrl: z.string().optional() })),
+  // Makes a started template real once its bundle (and its video, when one was named) has been uploaded; otherwise invalid_request.
+  templateCommit: route("POST", "/templates/commit", true, z.object({ id: TemplateId }), z.object({ template: TemplateSchema })),
+  // The caller's own templates, newest first.
+  templateList: route("GET", "/templates", true, z.object({}), z.object({ templates: z.array(TemplateSchema) })),
+  // One of the caller's templates with a link to its bundle that works for ten minutes. Another user's id is not_found.
+  templateGet: route("GET", "/templates/get", true, z.object({ id: TemplateId }), z.object({ template: TemplateSchema, bundleUrl: z.string(), film: TemplateFilmSchema })),
+  templateDelete: route("POST", "/templates/delete", true, z.object({ id: TemplateId }), z.object({ deleted: z.literal(true) })),
   publicLibrary: route("GET", "/public/library", false,
     // `sort` orders a listing without words by when each item was added: "new" is newest first, "old" is oldest first. Without it the
     // server chooses (newest first within a kind; the kinds take turns when none is named). It does not reorder a search by words.

package/src/diff/framediff.ts

@@ -0,0 +1,121 @@
+// Comparing two renders of the same film, to prove that a revision changed only what it was asked to change. Pure: numbers in, verdict out.
+
+export const DIFF_WIDTH = 320;
+export const DIFF_HEIGHT = 180;
+export const DEFAULT_THRESHOLD = 1.0;
+export const AUDIO_WINDOW_SEC = 0.1;
+export const DEFAULT_AUDIO_DB = 1.5;
+// Below this level a window is silence in both films and its level is not compared.
+export const AUDIO_FLOOR_DB = -55;
+
+export type Range = { from: number; to: number };
+
+// "623-679,1432-1436" in frames (inclusive), or "20.7s-22.6s" in seconds; a single value is a range of one. Returns frames.
+export function parseAllow(text: string | undefined, fps: number): Range[] {
+  if (!text?.trim()) return [];
+  return text.split(",").map((part) => {
+    const p = part.trim();
+    const m = /^(\d+(?:\.\d+)?)(s?)(?:\s*-\s*(\d+(?:\.\d+)?)(s?))?$/.exec(p);
+    if (!m) throw new Error(`"${p}" is not a range. Write frames as 623-679 or seconds as 20.7s-22.6s, separated by commas.`);
+    const seconds = m[2] === "s" || m[4] === "s";
+    const a = Number(m[1]), b = m[3] === undefined ? a : Number(m[3]);
+    if (b < a) throw new Error(`"${p}" ends before it starts.`);
+    return seconds ? { from: Math.floor(a * fps), to: Math.max(Math.floor(a * fps), Math.ceil(b * fps) - 1) } : { from: Math.round(a), to: Math.round(b) };
+  });
+}
+
+export function meanAbsDiff(a: Uint8Array, b: Uint8Array): number {
+  const n = Math.min(a.length, b.length);
+  let sum = 0;
+  for (let i = 0; i < n; i++) sum += Math.abs(a[i]! - b[i]!);
+  return n ? sum / n : 0;
+}
+
+// Runs of consecutive indexes whose value is over the threshold.
+export function changedRuns(values: number[], threshold: number): Range[] {
+  const runs: Range[] = [];
+  let start = -1;
+  values.forEach((v, i) => {
+    if (v > threshold) { if (start < 0) start = i; }
+    else if (start >= 0) { runs.push({ from: start, to: i - 1 }); start = -1; }
+  });
+  if (start >= 0) runs.push({ from: start, to: values.length - 1 });
+  return runs;
+}
+
+const allowed = (i: number, allow: Range[]) => allow.some((r) => i >= r.from && i <= r.to);
+
+// The parts of each run that no allowed range covers.
+export function outsideAllowed(runs: Range[], allow: Range[]): Range[] {
+  const out: Range[] = [];
+  for (const run of runs) {
+    let start = -1;
+    for (let i = run.from; i <= run.to; i++) {
+      if (!allowed(i, allow)) { if (start < 0) start = i; }
+      else if (start >= 0) { out.push({ from: start, to: i - 1 }); start = -1; }
+    }
+    if (start >= 0) out.push({ from: start, to: run.to });
+  }
+  return out;
+}
+
+export type PictureVerdict = {
+  frames: number; threshold: number;
+  changed: Range[]; outside: Range[];
+  // The largest difference on a frame that counts as unchanged: how close the quiet frames came to the threshold.
+  maxUnchanged: number;
+  // Allowed ranges in which nothing changed at all: a change that was asked for and did not happen.
+  untouchedAllowed: Range[];
+  lengthDiffers?: { old: number; new: number };
+};
+
+export function judgePicture(diffs: number[], allow: Range[], threshold = DEFAULT_THRESHOLD, lengths?: { old: number; new: number }): PictureVerdict {
+  const changed = changedRuns(diffs, threshold);
+  const quiet = diffs.filter((d) => d <= threshold);
+  return {
+    frames: diffs.length, threshold, changed, outside: outsideAllowed(changed, allow),
+    maxUnchanged: quiet.length ? Math.round(Math.max(...quiet) * 1000) / 1000 : 0,
+    untouchedAllowed: allow.filter((r) => !changed.some((c) => c.from <= r.to && c.to >= r.from)),
+    ...(lengths && lengths.old !== lengths.new ? { lengthDiffers: lengths } : {}),
+  };
+}
+
+// The level of each 100 ms window in dB relative to full scale.
+export function windowLevels(samples: Int16Array, rate: number, windowSec = AUDIO_WINDOW_SEC): number[] {
+  const size = Math.max(1, Math.round(rate * windowSec));
+  const out: number[] = [];
+  for (let at = 0; at + size <= samples.length; at += size) {
+    let sum = 0;
+    for (let i = at; i < at + size; i++) { const v = samples[i]! / 32768; sum += v * v; }
+    out.push(10 * Math.log10(sum / size + 1e-12));
+  }
+  return out;
+}
+
+export type SoundVerdict = { windows: number; thresholdDb: number; changedSec: { from: number; to: number }[]; outsideSec: { from: number; to: number }[]; maxUnchangedDb: number };
+
+// Two films' sound, window by window. A window changed when its level moved by more than `thresholdDb` and it is not silence in both. Levels, not samples,
+// are compared: a lossy codec moves every sample of an unchanged passage, but not its level.
+export function judgeSound(oldDb: number[], newDb: number[], allow: Range[], fps: number, thresholdDb = DEFAULT_AUDIO_DB, windowSec = AUDIO_WINDOW_SEC): SoundVerdict {
+  const n = Math.min(oldDb.length, newDb.length);
+  const delta: number[] = [];
+  for (let i = 0; i < n; i++) delta.push(oldDb[i]! < AUDIO_FLOOR_DB && newDb[i]! < AUDIO_FLOOR_DB ? 0 : Math.abs(oldDb[i]! - newDb[i]!));
+  const runs = changedRuns(delta, thresholdDb);
+  // A window is allowed when any frame it covers is.
+  const windowAllowed = (w: number) => { const a = Math.floor(w * windowSec * fps), b = Math.ceil((w + 1) * windowSec * fps) - 1; return allow.some((r) => a <= r.to && b >= r.from); };
+  const outside: Range[] = [];
+  for (const run of runs) {
+    let start = -1;
+    for (let w = run.from; w <= run.to; w++) {
+      if (!windowAllowed(w)) { if (start < 0) start = w; }
+      else if (start >= 0) { outside.push({ from: start, to: w - 1 }); start = -1; }
+    }
+    if (start >= 0) outside.push({ from: start, to: run.to });
+  }
+  const sec = (r: Range) => ({ from: Math.round(r.from * windowSec * 100) / 100, to: Math.round((r.to + 1) * windowSec * 100) / 100 });
+  const quiet = delta.filter((d) => d <= thresholdDb);
+  return { windows: n, thresholdDb, changedSec: runs.map(sec), outsideSec: outside.map(sec), maxUnchangedDb: quiet.length ? Math.round(Math.max(...quiet) * 100) / 100 : 0 };
+}
+
+export const rangeText = (r: Range) => (r.from === r.to ? String(r.from) : `${r.from}-${r.to}`);
+export const rangesText = (rs: Range[]) => (rs.length ? rs.map(rangeText).join(", ") : "none");

package/src/export/presets.ts

@@ -0,0 +1,147 @@
+// Delivery encodes of a finished render. A HyperFrames render is already yuv420p, TV range, tagged BT.709. An older render, or a file from somewhere
+// else, may still be full-range yuvj420p with no colour tags, which some phones play washed out or refuse. Every preset here converts full range to
+// TV range exactly once (a source that is already TV range is not converted again), tags the stream as BT.709 both in the filter chain (setparams) and
+// in the encoder (x264 params), pins profile and level, encodes AAC at 48 kHz and puts the index at the front of the file. Everything in this module
+// is pure: it builds argument lists and judges ffprobe output, and never runs a program.
+
+export type ExportPreset = {
+  id: string;
+  // What it is for, in one line, shown by `reelkit export --list`.
+  purpose: string;
+  // Output height in pixels on the short side of a 16:9 or 9:16 frame; the width follows the source's shape. undefined keeps the source size (capped at 1080 on the short side).
+  shortSide: number;
+  profile: "main" | "high";
+  level: string;
+  // Constant quality, or a fixed bitrate when `videoKbps` is given.
+  crf?: number;
+  videoKbps?: number;
+  maxrateKbps?: number;
+  bufsizeKbps?: number;
+  audioKbps: number;
+  x264Preset: string;
+};
+
+export const EXPORT_PRESETS: ExportPreset[] = [
+  { id: "iphone", purpose: "full quality for a phone or a desktop: 1080p, High profile level 4.0, CRF 18", shortSide: 1080, profile: "high", level: "4.0", crf: 18, maxrateKbps: 12000, bufsizeKbps: 24000, audioKbps: 192, x264Preset: "slow" },
+  { id: "phone-720", purpose: "a lighter phone copy: 720p, High profile level 4.0, CRF 20 capped at 4 Mb/s", shortSide: 720, profile: "high", level: "4.0", crf: 20, maxrateKbps: 4000, bufsizeKbps: 8000, audioKbps: 160, x264Preset: "slow" },
+  { id: "chat", purpose: "small enough to send in a chat: 720p, Main profile level 4.0, about 900 kb/s", shortSide: 720, profile: "main", level: "4.0", videoKbps: 900, maxrateKbps: 1200, bufsizeKbps: 2400, audioKbps: 128, x264Preset: "slow" },
+];
+
+export const presetById = (id: string): ExportPreset | undefined => EXPORT_PRESETS.find((p) => p.id === id);
+
+export type SourceInfo = { width: number; height: number; pixFmt?: string; colorRange?: string; hasAudio: boolean };
+
+const even = (n: number) => Math.max(2, Math.round(n / 2) * 2);
+
+// The output size: the short side becomes the preset's, the long side keeps the source's shape. A source smaller than the preset is never enlarged.
+export function outputSize(src: { width: number; height: number }, shortSide: number): { width: number; height: number } {
+  const short = Math.min(src.width, src.height);
+  const k = Math.min(1, shortSide / short);
+  return { width: even(src.width * k), height: even(src.height * k) };
+}
+
+// Whether the source's pixels are full range. yuvj420p always is; otherwise the tag decides, and an untagged yuv420p file is taken as TV range.
+export const isFullRange = (src: Pick<SourceInfo, "pixFmt" | "colorRange">): boolean => /^yuvj/.test(src.pixFmt ?? "") || src.colorRange === "pc" || src.colorRange === "jpeg";
+
+// The filter chain. The range is converted here and nowhere else: converting twice lifts the blacks (#101010 becomes #1d1d1d).
+export function videoFilter(src: SourceInfo, preset: ExportPreset): string {
+  const size = outputSize(src, preset.shortSide);
+  const range = isFullRange(src) ? "in_range=full:out_range=tv" : "in_range=tv:out_range=tv";
+  return [
+    `scale=${size.width}:${size.height}:flags=lanczos:${range}:in_color_matrix=bt709:out_color_matrix=bt709`,
+    "format=yuv420p",
+    // Command-line -color_trc / -color_primaries are dropped when a filter chain is present; setparams is what reaches the stream.
+    "setparams=range=tv:color_primaries=bt709:color_trc=bt709:colorspace=bt709",
+  ].join(",");
+}
+
+// The whole ffmpeg argument list. `-nostdin -y` first: a scripted run must never wait on an overwrite question.
+export function exportArgs(input: string, output: string, src: SourceInfo, preset: ExportPreset): string[] {
+  const rate = preset.videoKbps !== undefined
+    ? ["-b:v", `${preset.videoKbps}k`]
+    : ["-crf", String(preset.crf ?? 20)];
+  const cap = preset.maxrateKbps ? ["-maxrate", `${preset.maxrateKbps}k`, "-bufsize", `${preset.bufsizeKbps ?? preset.maxrateKbps * 2}k`] : [];
+  return [
+    "-nostdin", "-y", "-v", "error", "-i", input,
+    "-map", "0:v:0", ...(src.hasAudio ? ["-map", "0:a:0"] : []),
+    "-vf", videoFilter(src, preset),
+    "-c:v", "libx264", "-preset", preset.x264Preset, "-profile:v", preset.profile, "-level:v", preset.level, "-pix_fmt", "yuv420p",
+    ...rate, ...cap,
+    "-color_range", "tv", "-colorspace", "bt709", "-color_trc", "bt709", "-color_primaries", "bt709",
+    "-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709:range=tv",
+    ...(src.hasAudio ? ["-c:a", "aac", "-b:a", `${preset.audioKbps}k`, "-ar", "48000", "-ac", "2"] : ["-an"]),
+    "-movflags", "+faststart", output,
+  ];
+}
+
+// What ffprobe says about a stream, as far as the checks need it.
+export type ProbedStream = { codec_type?: string; codec_name?: string; profile?: string; level?: number; pix_fmt?: string; color_range?: string; color_space?: string; color_transfer?: string; color_primaries?: string; width?: number; height?: number; sample_rate?: string; nb_read_frames?: string; nb_frames?: string };
+
+export type ExportCheck = { name: string; ok: boolean; found: string; want: string };
+
+export type VerifyInput = {
+  preset: ExportPreset;
+  size: { width: number; height: number };
+  streams: ProbedStream[];
+  // Frames counted by decoding the output and the source.
+  frames: number; sourceFrames: number;
+  // Lines ffmpeg printed at -v error while decoding the whole file.
+  decodeErrors: number;
+  // Byte offsets of the two top-level boxes; -1 when one was not found.
+  moovAt: number; mdatAt: number;
+  bytes: number;
+  sourceHasAudio: boolean;
+};
+
+const PROFILE_NAME: Record<ExportPreset["profile"], string> = { main: "Main", high: "High" };
+
+// Every property a phone needs, one row each. The export passes only when all of them do.
+export function verifyExport(v: VerifyInput): ExportCheck[] {
+  const video = v.streams.find((s) => s.codec_type === "video");
+  const audio = v.streams.find((s) => s.codec_type === "audio");
+  const level = Math.round(Number(v.preset.level) * 10);
+  const row = (name: string, found: string | number | undefined, want: string | number, ok?: boolean): ExportCheck => ({ name, found: String(found ?? "missing"), want: String(want), ok: ok ?? String(found) === String(want) });
+  return [
+    row("file", v.bytes > 0 ? `${v.bytes} bytes` : "empty", "written, not empty", v.bytes > 0),
+    row("video codec", video?.codec_name, "h264"),
+    row("profile", video?.profile, PROFILE_NAME[v.preset.profile]),
+    row("level", video?.level, `at most ${level}`, video?.level !== undefined && video.level <= level),
+    row("pixel format", video?.pix_fmt, "yuv420p"),
+    row("colour range", video?.color_range, "tv"),
+    row("colour matrix", video?.color_space, "bt709"),
+    row("colour transfer", video?.color_transfer, "bt709"),
+    row("colour primaries", video?.color_primaries, "bt709"),
+    row("size", video ? `${video.width}x${video.height}` : undefined, `${v.size.width}x${v.size.height}`),
+    row("frames", v.frames, `${v.sourceFrames} (same as the source)`, v.frames === v.sourceFrames && v.frames > 0),
+    row("full decode", `${v.decodeErrors} error line${v.decodeErrors === 1 ? "" : "s"}`, "0 error lines", v.decodeErrors === 0),
+    row("index at the front (faststart)", v.moovAt >= 0 && v.mdatAt >= 0 ? `moov at ${v.moovAt}, mdat at ${v.mdatAt}` : "moov or mdat not found", "moov before mdat", v.moovAt >= 0 && v.mdatAt >= 0 && v.moovAt < v.mdatAt),
+    ...(v.sourceHasAudio ? [row("audio", audio ? `${audio.codec_name} ${audio.sample_rate} Hz` : undefined, "aac 48000 Hz", audio?.codec_name === "aac" && audio.sample_rate === "48000")] : []),
+  ];
+}
+
+// The offsets of the top-level `moov` and `mdat` boxes of an MP4, read from the box headers themselves (a search for the letters would also find them inside the data).
+export function topLevelBoxes(read: (offset: number, length: number) => Uint8Array, size: number): { moovAt: number; mdatAt: number } {
+  let moovAt = -1, mdatAt = -1;
+  for (let at = 0; at + 8 <= size && (moovAt < 0 || mdatAt < 0);) {
+    const h = read(at, 16);
+    if (h.length < 8) break;
+    const view = new DataView(h.buffer, h.byteOffset, h.byteLength);
+    let length = view.getUint32(0);
+    const type = String.fromCharCode(h[4]!, h[5]!, h[6]!, h[7]!);
+    if (length === 1 && h.length >= 16) length = Number(view.getBigUint64(8));
+    else if (length === 0) length = size - at;
+    if (type === "moov") moovAt = at;
+    if (type === "mdat") mdatAt = at;
+    if (length < 8) break;
+    at += length;
+  }
+  return { moovAt, mdatAt };
+}
+
+const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - s.length));
+
+// The pass/fail table as plain text.
+export function checkTable(checks: ExportCheck[]): string {
+  const a = Math.max(...checks.map((c) => c.name.length), 5), b = Math.max(...checks.map((c) => c.found.length), 5);
+  return [`${pad("check", a)}  ${pad("found", b)}  result`, ...checks.map((c) => `${pad(c.name, a)}  ${pad(c.found, b)}  ${c.ok ? "pass" : `FAIL (want ${c.want})`}`)].join("\n");
+}