reelkit-cli 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 What changed in each published version of `reelkit-cli`, newest first. A push to `main` publishes the version in
 `package.json` when it is not on npm yet, and it must have an entry here.
 
+## 0.12.0 - 2026-10-09
+
+- Templates: `reelkit template push` saves a whole project in your private files (the plan, the composition, everything under `assets/` and the rendered video), and `reelkit template clone <id>` unpacks one into a new project to continue or remix. `reelkit template list` and `reelkit template delete <id>` manage them.
+- Your templates page on reelkit.cc shows each one: its video, a timeline of its scenes, text, voice, music, beats and sound effects, and its files.
+- `reelkit render` writes `out/sounds.json`: which sound plays when. A template pushed after that names each sound effect on its timeline.
+
 ## 0.11.0 - 2026-10-09
 
 Ported from the reelkit-cli 0.9 toolset (written against the Remotion 0.8.0 CLI) onto the HyperFrames renderer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelkit-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "CLI and Claude skill for making short-form video with a shared asset library.",
   "license": "MIT",
   "author": "Daniel Livshin",

package/skill/SKILL.md

@@ -15,7 +15,7 @@ For image or video cutouts, editable Blender product shots, custom 3D materials,
 
 To implement a chosen style, read its row in `reference/style-recipes.md` for action, timing, sound and proof. `reference/style-components.md` maps the shared components and built-in kit to shot roles; inspect the selected source before using its props.
 
-This skill targets `reelkit-cli` 0.11.0 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
+This skill targets `reelkit-cli` 0.12.0 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
 
 ## What decides whether the film is accepted
 
@@ -185,6 +185,7 @@ The pane never changes the project by itself. Its buttons (Edit this scene, Chan
 - A revision changes only what was asked. `reelkit render --allow <frames>` is how that is proved. Do not tidy, retime or recolour anything outside the list.
 - Never regenerate a voice the user did not ask you to touch, and never pick a take when they asked to hear the options.
 - On-screen text never has vowel points. Pointing belongs in the voice request only.
+- `reelkit template push` saves the whole project in the user's private files: the plan, the composition, everything under `assets/` (their own pictures, footage and recorded voice too) and the rendered video. Run it only when the user asks to save, back up or reuse the project, and say in one sentence what it sends. Only they can see it, on their templates page and with `reelkit template list`. `reelkit template clone <id> [folder]` unpacks one into a new project to continue or remix; `reelkit template delete <id>` removes it.
 - A private project means `reelkit render --no-share` on every render, and neither `reelkit components share` nor `reelkit assets upload --share`.
 - Never print an API key, a token, or the contents of a credentials file.
 - If a command reports that a quota is used up, tell the user what ran out and when it resets. Do not work around it. A message that says to wait a minute or an hour ("Too many searches", "Too many uploads started") is a throttle, not a used-up quota: wait and retry once instead of stopping.

package/src/cli.ts

@@ -1,3 +1,4 @@
+import { templateClone, templateDelete, templateList, templatePush } from "./commands/template";
 import { Command } from "commander";
 import { ApiFailure } from "./api/client";
 import { assetsGenClip, assetsGenImage, assetsGenSvg, assetsLayers, assetsPull, assetsSearch, assetsUpload, assetsVoiceover, assetsVoices } from "./commands/assets";
@@ -150,6 +151,14 @@ program.command("tools").description("Print where the voice scripts that ship wi
     const names = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".py") && !f.startsWith("_")).sort() : [];
     return { ok: names.length > 0, data: { dir, scripts: names }, summary: names.length ? `${dir}\n${names.map((n) => `  python3 ${dir}/${n} --help`).join("\n")}\nRead ${dir}/README.md for the order to use them in.` : "The voice scripts are missing from this installation. Reinstall reelkit." };
   }));
+const template = program.command("template").description("Whole projects kept in your private files, to continue later or to start a new video from");
+template.command("push").description("Save this project as a template in your private files: the plan, the composition, everything under assets/ (your own files too), the rendered video when there is one, and a picture of each scene. Only you can see it")
+  .option("--name <name>", "what to call the template (default: the project's name)")
+  .action(run((ctx, opts: { name?: string }) => templatePush(ctx, opts)));
+template.command("list").description("List your templates").action(run((ctx) => templateList(ctx)));
+template.command("clone <id> [folder]").description("Unpack one of your templates into a new project folder, as a copy of its own to continue or to remix")
+  .action(run((ctx, id: string, folder: string | undefined) => templateClone(ctx, id, folder)));
+template.command("delete <id>").description("Delete one of your templates from your private files").action(run((ctx, id: string) => templateDelete(ctx, id)));
 const components = program.command("components").description("Components written in this project");
 components.command("share [names...]").description("Share components written in this project with the library for review (all of them with no name): their source, a description and an example are sent, nothing else")
   .option("--describe <text>", "what it shows and when to use it (one component)").option("--example <jsx>", "an example use with plain values, such as '<StatRing value={42} />' (one component)").option("--tags <tags>", "comma-separated tags, 3 to 6 (one component)")

package/src/commands/build.ts

@@ -101,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);
@@ -334,6 +346,7 @@ export async function render(ctx: Ctx, deps: RenderDeps = {}): Promise<Result> {
         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;
@@ -343,7 +356,10 @@ export async function render(ctx: Ctx, deps: RenderDeps = {}): Promise<Result> {
       }));
     } 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)), { onRetry: (n, e) => ctx.log(`The browser failed (${(e instanceof Error ? e.message : String(e)).split("\n")[0]}); rendering again (attempt ${n + 1}).`) });
+      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)}${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."}`]);

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/render/render.ts

@@ -75,8 +75,9 @@ async function render(dir: string, props: VideoProps, mode: "stills" | "video",
 export async function renderStills(dir: string, props: VideoProps, frames: number[], outDir: string, options?: RenderOptions) {
   await mkdir(outDir, { recursive: true }); await render(dir, props, "stills", outDir, frames, options);
 }
-export async function renderVideo(dir: string, props: VideoProps, outPath: string, options?: RenderOptions) {
-  await mkdir(dirname(outPath), { recursive: true }); await render(dir, props, "video", outPath, [], options);
+// `audioFile`, when given, receives the audio records the film registered (which sound plays from when to when), as JSON.
+export async function renderVideo(dir: string, props: VideoProps, outPath: string, options?: RenderOptions, audioFile?: string) {
+  await mkdir(dirname(outPath), { recursive: true }); await render(dir, props, "video", outPath, [], options, audioFile ? { audioSidecar: audioFile } : undefined);
 }
 // One inclusive range of frames as a silent file, plus the audio records those frames registered (`${outPath}.audio.json`).
 export async function renderVideoRange(dir: string, props: VideoProps, outPath: string, from: number, to: number, options?: RenderOptions) {

package/src/testing/fake-api.ts

@@ -5,7 +5,7 @@ import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { MAX_UPLOAD_BYTES, routes, type ErrorCode, type LibraryItem, type RouteName, type Voice } from "../contract";
+import { MAX_TEMPLATES, MAX_UPLOAD_BYTES, TEMPLATE_BUNDLE_TYPE, routes, type ErrorCode, type LibraryItem, type RouteName, type Template, type TemplateFilm, type Voice } from "../contract";
 import { staticCheck } from "../render/validate";
 import { FAKE_SVG, PIXEL_PNG, silentWav } from "./fixtures";
 
@@ -124,6 +124,9 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
   const secret = () => randomBytes(16).toString("hex");
   let origin = "";
   // Every call makes a new URL for its own blob. The URL says nothing about the item behind it.
+  // A user's templates: the files as they were uploaded, and whether the template was committed.
+  type TemplateJob = { owner: string; record: Template; film: TemplateFilm; committed: boolean; bundle?: Uint8Array; video?: Uint8Array; sources?: Uint8Array; thumbs: (Uint8Array | undefined)[] };
+  const templates = new Map<string, TemplateJob>();
   const fileUrl = (blob: Blob) => { const t = secret(); blobs.set(t, blob); return `${origin}/files/${t}`; };
   const words = (s: string) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? []);
 
@@ -323,6 +326,51 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
       };
       return job.result;
     },
+    templateStart: (input, { userId }) => {
+      const owner = userId ?? "u-test";
+      if ([...templates.values()].filter((t) => t.owner === owner && t.committed).length >= MAX_TEMPLATES) throw new Fail(400, "invalid_request", `You already keep ${MAX_TEMPLATES} templates. Delete one with \`reelkit template delete <id>\` and push again.`);
+      const id = `tpl-${randomBytes(6).toString("hex")}`;
+      const film = input.film;
+      const record: Template = {
+        id, name: input.name, ...(input.title ? { title: input.title } : {}), createdAt: new Date().toISOString(), bundleBytes: input.bundleBytes,
+        ...(input.videoBytes ? { videoBytes: input.videoBytes } : {}), aspect: film.aspect, durationSec: Math.round((film.totalFrames / film.fps) * 100) / 100,
+        scenes: film.scenes.length, thumbs: input.thumbBytes.length, ...(input.from ? { from: input.from } : {}),
+      };
+      const job: TemplateJob = { owner, record, film, committed: false, thumbs: (input.thumbBytes as number[]).map(() => undefined) };
+      templates.set(id, job);
+      const put = (contentType: string, bytes: number, has: () => boolean, set: (b: Uint8Array) => void) => {
+        const token = secret();
+        uploads.set(token, { contentType, bytes, used: false, sink: { has, put: set } });
+        return `${origin}/upload/${token}`;
+      };
+      return {
+        id, bundleUrl: put(TEMPLATE_BUNDLE_TYPE, input.bundleBytes, () => Boolean(job.bundle), (b) => { job.bundle = b; }),
+        ...(input.videoBytes ? { videoUrl: put("video/mp4", input.videoBytes, () => Boolean(job.video), (b) => { job.video = b; }) } : {}),
+        ...(input.sourcesBytes ? { sourcesUrl: put("application/json", input.sourcesBytes, () => Boolean(job.sources), (b) => { job.sources = b; }) } : {}),
+        thumbUrls: (input.thumbBytes as number[]).map((n, i) => put("image/jpeg", n, () => Boolean(job.thumbs[i]), (b) => { job.thumbs[i] = b; })),
+      };
+    },
+    templateCommit: ({ id }, { userId }) => {
+      const job = templates.get(id);
+      if (!job || job.owner !== (userId ?? "u-test")) throw new Fail(404, "not_found", "No such template.");
+      if (!job.bundle || (job.record.videoBytes && !job.video)) throw new Fail(400, "invalid_request", "The template's files have not been uploaded. Run `reelkit template push` again.");
+      job.committed = true;
+      return { template: job.record };
+    },
+    templateList: (_input, { userId }) => ({
+      templates: [...templates.values()].filter((t) => t.owner === (userId ?? "u-test") && t.committed).map((t) => t.record).sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
+    }),
+    templateGet: ({ id }, { userId }) => {
+      const job = templates.get(id);
+      if (!job || !job.committed || job.owner !== (userId ?? "u-test")) throw new Fail(404, "not_found", "No such template.");
+      return { template: job.record, film: job.film, bundleUrl: fileUrl({ filename: "bundle.tgz", contentType: TEMPLATE_BUNDLE_TYPE, bytes: job.bundle! }) };
+    },
+    templateDelete: ({ id }, { userId }) => {
+      const job = templates.get(id);
+      if (!job || !job.committed || job.owner !== (userId ?? "u-test")) throw new Fail(404, "not_found", "No such template.");
+      templates.delete(id);
+      return { deleted: true as const };
+    },
     publicLibrary: ({ q, kind, page, sort }) => {
       // Published items only. Newest first, or oldest first when asked; with a query, best match first and equal matches newest first.
       const want = q ? words(q) : undefined;