reelkit-cli 0.6.0 → 0.10.0

package/src/commands/build.ts

@@ -1,21 +1,26 @@
 import { execFile } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { Ctx, Result } from "../context";
-import type { AssetManifest, ScenePlan } from "../pipeline/schema";
-import { compareFrames, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
+import { isVoiceless, type AssetManifest, type ScenePlan } from "../pipeline/schema";
+import { compareAcross, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
 import { buildManifest, missingAssets } from "../project/manifest";
+import { readBackground } from "../project/background";
 import { beatReport } from "../project/music";
 import { FILES, openProject, type Project } from "../project/project";
 import { structureNotes } from "../pipeline/review";
 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 { 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";
 import { FILE_NAME, MAIN_FILE, jsxUses, staticCheck, typecheck } from "../render/validate";
 import { loadPlan } from "./plan";
+import { MAX_WORD_FRAMES, usesWordTiming, WORD_FRAME_AFTER, wordCalls, wordErrors, wordTargets } from "../render/word-check";
 
 const exec = promisify(execFile);
 const MEDIA_PATH = /["'`](assets\/[^"'`\s]+\.(?:mp3|wav|m4a|mp4|mov|webm|png|jpe?g|webp|svg|gif))["'`]/g;
@@ -35,6 +40,13 @@ function inspect(project: Project): { errors: string[]; manifest?: AssetManifest
       if (!project.exists(m[1])) errors.push(`${name} uses "${m[1]}", which is not in this project. Get it with \`reelkit assets pull <id>\` first.`);
     }
   }
+  // A word given to wordFrame, onWord or onWordBeat that its scene never says would stop the render, so it is an error here.
+  if (!isVoiceless(plan)) {
+    const ids = plan.scenes.map((s) => s.id);
+    for (const name of names.filter((n) => FILE_NAME.test(n))) {
+      errors.push(...wordErrors(name, wordCalls(readFileSync(project.path(join("src", name)), "utf8"), ids, name), plan.scenes));
+    }
+  }
   if (errors.length) return { errors };
   const typeErrors = typecheck(names.map((n) => project.path(join("src", n))));
   if (typeErrors.length) return { errors: typeErrors };
@@ -43,14 +55,39 @@ function inspect(project: Project): { errors: string[]; manifest?: AssetManifest
 }
 
 // Advice about a composition that passes: never an error.
-function compositionNotes(project: Project, plan: ScenePlan): string[] {
+function compositionNotes(project: Project, plan: ScenePlan, manifest?: AssetManifest): string[] {
   const notes: string[] = [];
   const names = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f));
   const sources = names.map((n) => [n, readFileSync(project.path(join("src", n)), "utf8")] as const);
   const rendersCaptions = sources.some(([n, src]) => jsxUses(src, n, "Captions").length > 0);
   if (plan.captions === "none" && rendersCaptions) notes.push('The plan says captions: "none" but the composition renders <Captions>. Remove them, or change the plan if the user wants captions.');
   if ((plan.captions === "word" || plan.captions === "phrase") && !rendersCaptions) notes.push(`The plan asks for captions (${plan.captions}) but the composition renders no <Captions>. Add <Captions words={s.words} group={manifest.captions} /> in each scene, or set captions to "none" in the plan if the user does not want them.`);
+  if (!isVoiceless(plan) && !sources.some(([n, src]) => usesWordTiming(src, n))) {
+    notes.push("Nothing on screen is timed to a spoken word: the composition never uses wordFrame, onWord, onWordBeat or a scene's words (other than to draw the subtitles). Place what illustrates a word on that word, e.g. <Entrance delay={onWord(s, \"tasks\")}>; see reference/voice-sync.md.");
+  }
   notes.push(...structureNotes(plan, { footage: project.footage() }));
+  if (isVoiceless(plan) && manifest) {
+    notes.push(...soundNotes(sources.map(([name, source]) => ({ name, source })), { seconds: manifest.totalFrames / manifest.fps, fps: manifest.fps, musicSet: manifest.music !== undefined }));
+  }
+  // A ground that was chosen and then never drawn is wasted: say so. A video ground with a low dim under type is hard to read.
+  const bg = readBackground(project);
+  const recorded = [...(bg.film ? [bg.film.key] : []), ...Object.values(bg.scenes).map((e) => e.key)];
+  const usesBackground = (src: string) => /\.background\b|bgPerScene/.test(src) || recorded.some((k) => src.includes(k));
+  if (recorded.length && !sources.some(([, src]) => usesBackground(src))) notes.push(`A background is recorded (${recorded[0]}) but the composition never uses it. Draw it with <BgVideo> or <BgImage> from manifest.background, or <BgSequence items={bgPerScene(...)}>; see reference/backgrounds.md.`);
+  if (plan.scenes.some((s) => s.onScreenText.length)) {
+    for (const [name, src] of sources) {
+      const lowDim = jsxUses(src, name, "BgVideo").some((u) => { const m = /\bdim=\{\s*(\d*\.?\d+)\s*\}/.exec(u.example); return m !== null && Number(m[1]) < 0.2; });
+      if (lowDim) { notes.push(`${name}: a BgVideo with a dim under 0.2 sits behind on-screen text, which will be hard to read. Raise dim to 0.3 or more, or blur the clip.`); break; }
+    }
+  }
+  // An image scene with words on it is built in layers. Decidable only when the composition names one of the two components, or names the scene's image (its key, or
+  // imageKey): a composition that never mentions the picture says nothing here.
+  const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const layered = sources.some(([n, src]) => jsxUses(src, n, "ImageLayers").length > 0 || jsxUses(src, n, "TextOnImage").length > 0);
+  const withText = plan.scenes.filter((sc) => sc.treatment === "illustration" && sc.onScreenText.length > 0 && images[sc.id]);
+  if (!layered && withText.length && sources.some(([, src]) => /\bimageKey\b/.test(src) || withText.some((sc) => src.includes(images[sc.id]!)))) {
+    notes.push(`Scene ${withText.map((sc) => sc.id).join(", ")} ${withText.length === 1 ? "has" : "have"} an image and on-screen text, but the composition uses neither <ImageLayers> nor <TextOnImage>: the text is not a layer of the picture. Put the words in the picture's calm zone with <TextOnImage layers={s.imageLayers}> inside <ImageLayers layers={s.imageLayers}> (run \`reelkit assets layers --scene <id>\` for a hero picture so the words can pass behind its subject), not on a flat card beside it.`);
+  }
   const { pulled, written } = libraryUse(project);
   if (!pulled.length && plan.scenes.length >= 4) {
     const searched = project.readJsonOr<SearchRecord[]>(FILES.searches, []).filter((s) => s.kind === "component").length;
@@ -63,9 +100,9 @@ const failed = (errors: string[]): Result => ({ ok: false, data: { errors }, sum
 
 export async function check(ctx: Ctx): Promise<Result> {
   const project = openProject(ctx.cwd);
-  const { errors } = inspect(project);
+  const { errors, manifest } = inspect(project);
   if (errors.length) return failed(errors);
-  const shouldImprove = compositionNotes(project, loadPlan(project));
+  const shouldImprove = compositionNotes(project, loadPlan(project), manifest);
   return {
     ok: true, data: { errors: [], shouldImprove, library: libraryUse(project) },
     summary: ["The composition passes. Run `reelkit preview` to see it.", ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : [])].join("\n"),
@@ -102,33 +139,54 @@ export async function ensureBrowserWithNotice(ctx: Ctx, ensure: EnsureBrowser =
 const ffmpegToJpeg = (png: string, jpg: string) => exec("ffmpeg", ["-y", "-loglevel", "error", "-i", png, "-vf", "scale=540:-2", "-q:v", "5", jpg]).then(() => undefined);
 
 type PreviewPoint = { sceneId: string; point: "early" | "late" | "middle" | "end" | "start"; frame: number; name: string };
+type WordFrameFile = { sceneId: string; word: string; label: string; frame: number; wordStart: number; name: string };
+
+// Whether any file of the composition draws a Scene3D, which is the only case that needs the software GL in the browser.
+export const usesScene3D = (project: Project): boolean => readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx")).some((n) => /<Scene3D[\s>/]/.test(readFileSync(project.path(join("src", n)), "utf8")));
 
-// Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it.
-// A scene under 4 frames has no room for two distinct frames and gets its middle one. The scene's number leads each name
-// so the files sort by scene order and then by time, whatever the scene ids are.
-export function previewPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): PreviewPoint[] {
+// How many frames at each end of a scene SceneFrame may be fading or moving: 8 unless the composition asks for longer with a literal
+// transitionFrames={N} (at most 20, as SceneFrame allows). A value that is not a literal cannot be read, so the default is used.
+export const DEFAULT_FADE = 8;
+export function fadeFrames(sources: string[]): number {
+  let n = DEFAULT_FADE;
+  for (const src of sources) for (const m of src.matchAll(/transitionFrames=\{\s*(\d+)\s*\}/g)) n = Math.max(n, Math.min(20, Number(m[1])));
+  return n;
+}
+
+// The frames of a scene, counted from its start, where it is fully visible: SceneFrame fades or moves it at both ends for up to `fade` frames,
+// but never more than half its length.
+const visibleRange = (d: number, fade: number) => { const edge = Math.max(1, Math.min(fade, Math.floor(d / 2))); return { lo: edge, hi: d - edge, edge }; };
+
+// Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it, both moved into the
+// part where the scene is fully visible (a quick scene's 90% falls inside its fade and would look dim). A scene too short to have two distinct
+// fully visible frames gets its middle one. The scene's number leads each name so the files sort by scene order and then by time.
+export function previewPoints(scenes: { id: string; startFrame: number; durationFrames: number }[], fade = DEFAULT_FADE): PreviewPoint[] {
   return scenes.flatMap((s, i) => {
     const at = (point: PreviewPoint["point"], offset: number): PreviewPoint => ({ sceneId: s.id, point, frame: s.startFrame + offset, name: `${String(i + 1).padStart(2, "0")}-${s.id}-${point}` });
-    if (s.durationFrames < 4) return [at("middle", Math.floor(s.durationFrames / 2))];
-    const inside = (share: number) => Math.min(s.durationFrames - 1, Math.round(s.durationFrames * share));
+    const { lo, hi } = visibleRange(s.durationFrames, fade);
+    if (s.durationFrames < 4 || hi - lo < 2) return [at("middle", Math.floor(s.durationFrames / 2))];
+    const inside = (share: number) => Math.max(lo, Math.min(hi, Math.round(s.durationFrames * share)));
     return [at("early", inside(0.3)), at("late", inside(0.9))];
   });
 }
 
-type BoundaryPoint = { from: string; to: string; end: PreviewPoint; start: PreviewPoint };
+type BoundaryPoint = { from: string; to: string; end: PreviewPoint; start: PreviewPoint; settled: PreviewPoint };
 
-// SceneFrame fades each scene in and out over up to 8 frames, so the very last and very first frames of two scenes are nearly empty.
-// The frames that show what a scene really holds are the last one at full strength and the first one at full strength: those are the two
-// either side of every change. The files are named by the change, b01-end-<scene> then b01-start-<scene>, so that they sort in order.
-export function boundaryPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): BoundaryPoint[] {
-  const edge = (d: number) => Math.max(1, Math.min(8, Math.floor(d / 2)));
+// SceneFrame fades or moves each scene in and out, so the very last and very first frames of two scenes are nearly empty. The frames that show
+// what a scene really holds are the last one at full strength and the first one at full strength. A third frame, six frames after the first,
+// catches a move that is still settling; it is measured but not saved. The files are named by the change, b01-end-<scene> then b01-start-<scene>.
+export function boundaryPoints(scenes: { id: string; startFrame: number; durationFrames: number }[], fade = DEFAULT_FADE): BoundaryPoint[] {
   return scenes.slice(0, -1).map((a, i) => {
     const b = scenes[i + 1]!;
     const n = `b${String(i + 1).padStart(2, "0")}`;
+    const ea = visibleRange(a.durationFrames, fade), eb = visibleRange(b.durationFrames, fade);
+    const startOffset = Math.min(b.durationFrames - 1, eb.edge);
+    const settledOffset = Math.min(b.durationFrames - 1, Math.max(startOffset, Math.min(startOffset + 6, eb.hi)));
     return {
       from: a.id, to: b.id,
-      end: { sceneId: a.id, point: "end", frame: a.startFrame + Math.max(0, a.durationFrames - edge(a.durationFrames)), name: `${n}-end-${a.id}` },
-      start: { sceneId: b.id, point: "start", frame: b.startFrame + Math.min(b.durationFrames - 1, edge(b.durationFrames)), name: `${n}-start-${b.id}` },
+      end: { sceneId: a.id, point: "end", frame: a.startFrame + Math.max(0, ea.hi), name: `${n}-end-${a.id}` },
+      start: { sceneId: b.id, point: "start", frame: b.startFrame + startOffset, name: `${n}-start-${b.id}` },
+      settled: { sceneId: b.id, point: "start", frame: b.startFrame + settledOffset, name: `${n}-settled-${b.id}` },
     };
   });
 }
@@ -147,17 +205,25 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   const dir = project.path("out/preview");
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
-  const sceneFrames = previewPoints(manifest.scenes);
-  const boundaries = boundaryPoints(manifest.scenes);
+  const plan = loadPlan(project);
+  const intended = new Set(plan.scenes.filter((s) => s.cutIn).map((s) => s.id));
+  const fade = fadeFrames(readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx")).map((n) => readFileSync(project.path(join("src", n)), "utf8")));
+  const sceneFrames = previewPoints(manifest.scenes, fade);
+  const boundaries = boundaryPoints(manifest.scenes, fade);
   const points = [...sceneFrames, ...boundaries.flatMap((b) => [b.end, b.start])];
+  // A narrated film also gets one frame just after each word its code times something to: the thing the word names should already be there.
+  const srcNames = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f));
+  const wordPlan = isVoiceless(plan) ? undefined : wordTargets(srcNames.flatMap((n) => wordCalls(readFileSync(project.path(join("src", n)), "utf8"), plan.scenes.map((sc) => sc.id), n)), manifest);
+  const wordFiles: WordFrameFile[] = (wordPlan?.targets ?? []).map((t, i) => ({ ...t, name: `w${String(i + 1).padStart(2, "0")}-${t.sceneId}-${t.word.toLowerCase().replace(/[^a-z0-9]+/g, "") || "word"}` }));
+  const measuredFrames = [...points.map((p) => p.frame), ...boundaries.map((b) => b.settled.frame), ...wordFiles.map((w) => w.frame)];
   try {
     try {
       await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, [...new Set(points.map((p) => p.frame))], dir));
+      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, [...new Set(measuredFrames)], dir, { uses3D: usesScene3D(project) }));
     } catch (e) {
       return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
     }
-    const frames: { sceneId: string; point: PreviewPoint["point"]; path: string }[] = [];
+    const frames: { sceneId: string; point: PreviewPoint["point"] | "word"; path: string; word?: string; label?: string }[] = [];
     try {
       for (const m of points) {
         // Shrunk to phone width: small enough to read cheaply, and what is unreadable here is unreadable on a phone.
@@ -165,9 +231,23 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
         await toJpeg(join(dir, `still-${m.frame}.png`), project.path(path));
         frames.push({ sceneId: m.sceneId, point: m.point, path });
       }
+      for (const w of wordFiles) {
+        const path = `out/preview/${w.name}.jpg`;
+        await toJpeg(join(dir, `still-${w.frame}.png`), project.path(path));
+        frames.push({ sceneId: w.sceneId, point: "word", path, word: w.word, label: w.label });
+      }
     } catch {
       return failed(["Could not write the preview frames: ffmpeg failed. Check that ffmpeg is installed (macOS: `brew install ffmpeg`) and run `reelkit preview` again."]);
     }
+    // One picture of all the frames, so that a look at it comes before opening single frames. It is a convenience: failing to make it changes nothing else.
+    let sheetLine = "";
+    let sheet: { path: string; cols: number; rows: number } | undefined;
+    try {
+      const names = frames.map((f) => (f.point === "word" ? f.label! : `${f.sceneId} ${f.point === "early" || f.point === "late" || f.point === "middle" ? f.point : `change ${f.point}`}`));
+      const r = await contactSheet(frames.map((f) => project.path(f.path)), names, project.path("out/preview/sheet.jpg"), manifest.width / manifest.height, { newRowAt: wordFiles.length ? points.length : undefined });
+      sheet = { path: "out/preview/sheet.jpg", cols: r.cols, rows: r.rows };
+      sheetLine = `Contact sheet, one picture of all ${frames.length} frames in the order below${r.labelled ? ", each labelled with its scene and early, late or change" : ""} (${r.cols} across${wordFiles.length ? `; the word frames are in the last row${r.labelled ? ", labelled word > scene" : ""}` : ""}): out/preview/sheet.jpg. Look at it first, then open single frames where something needs a closer look.\n`;
+    } catch { /* no sheet */ }
     // Whether anything survives each scene change is advice. If it cannot be measured, the preview is still the preview.
     let continuity: { score: number | null; boundaries: Boundary[] } | undefined;
     let continuityLines: string[] = [];
@@ -175,9 +255,9 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
       const h = Math.round((SAMPLE_WIDTH * manifest.height) / manifest.width);
       const measured: Boundary[] = [];
       for (const b of boundaries) {
-        const [a, c] = await Promise.all([decodeGray(join(dir, `still-${b.end.frame}.png`), SAMPLE_WIDTH, h), decodeGray(join(dir, `still-${b.start.frame}.png`), SAMPLE_WIDTH, h)]);
-        const r = compareFrames(a, c, SAMPLE_WIDTH, h);
-        measured.push({ from: b.from, to: b.to, survived: Math.round(r.survived * 100) / 100, kind: r.kind });
+        const [a, c, d] = await Promise.all([b.end.frame, b.start.frame, b.settled.frame].map((f) => decodeGray(join(dir, `still-${f}.png`), SAMPLE_WIDTH, h)));
+        const r = compareAcross(a!, [c!, d!], SAMPLE_WIDTH, h);
+        measured.push({ from: b.from, to: b.to, survived: Math.round(r.survived * 100) / 100, kind: intended.has(b.to) && r.kind !== "empty" ? "cut (intended)" : r.kind });
       }
       if (measured.length) {
         const summary = summariseContinuity(measured);
@@ -185,24 +265,27 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
         continuityLines = summary.lines;
       }
     } catch { /* no continuity report */ }
-    const sceneLines = `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.filter((f) => f.point !== "end" && f.point !== "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}`;
+    const wordLines = wordPlan && (wordFiles.length || wordPlan.skipped)
+      ? `\nWord frames: ${wordFiles.length} frame${wordFiles.length === 1 ? "" : "s"}, each ${WORD_FRAME_AFTER} frames AFTER its word starts, in a row of their own on the sheet (labelled "word ▸ scene"). Each word frame should already show the thing that word names: if it does not, the thing is late (or on the wrong word) and its timing needs fixing.${wordFiles.length ? `\n${wordFiles.map((w) => `${w.label}: out/preview/${w.name}.jpg`).join("\n")}` : ""}${wordPlan.skipped ? `\n${wordPlan.skipped} word timing${wordPlan.skipped === 1 ? " was" : "s were"} not shown (${[wordPlan.undecidable ? `${wordPlan.undecidable} name${wordPlan.undecidable === 1 ? "s" : ""} a word or a scene the code does not give as a literal` : "", wordPlan.capped ? `${wordPlan.capped} beyond the first ${MAX_WORD_FRAMES}` : ""].filter(Boolean).join(", ")}).` : ""}`
+      : wordPlan ? "\nWord frames: none, because the composition has no wordFrame, onWord or onWordBeat call with a literal scene and word." : "";
+    const sceneLines = `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.filter((f) => f.point !== "end" && f.point !== "start" && f.point !== "word").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}`;
     const changeLines = boundaries.length ? `\nThe last and first frames either side of each scene change are saved too (b01-end-<scene>, b01-start-<scene>, ...), so that you can see what carries across:\n${frames.filter((f) => f.point === "end" || f.point === "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}` : "";
-    const beat = beatReport(manifest);
-    return { ok: true, data: { frames, ...(continuity ? { continuity } : {}), ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) }, summary: `${sceneLines}${changeLines}${continuityLines.length ? `\nContinuity: ${continuityLines.join("\n")}` : ""}${beat ? `\nBeat: ${beat.line}.` : ""}` };
+    const beat = beatReport(manifest, { finer: isVoiceless(plan) });
+    return { ok: true, data: { frames, ...(wordPlan ? { wordFrames: { shown: wordFiles.map((w) => ({ scene: w.sceneId, word: w.word, wordStart: w.wordStart, frame: w.frame })), skipped: wordPlan.skipped } } : {}), ...(sheet ? { sheet } : {}), ...(continuity ? { continuity } : {}), ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) }, summary: `${sheetLine}${sceneLines}${changeLines}${wordLines}${continuityLines.length ? `\nContinuity: ${continuityLines.join("\n")}` : ""}${beat ? `\nBeat: ${beat.line}.` : ""}` };
   } finally {
     // The full-size stills are only inputs; none stays behind however this ends.
     for (const f of readdirSync(dir)) if (/^still-\d+\.png$/.test(f)) rmSync(join(dir, f), { force: true });
   }
 }
 
-export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean } = {}): Promise<Result> {
+export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean; measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport> } = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
   if (!manifest) return failed(errors);
   const path = "out/video.mp4";
   try {
     await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path)));
+    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path), { uses3D: usesScene3D(project) }));
   } catch (e) {
     return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
   }
@@ -216,9 +299,39 @@ export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; ma
   } catch (e) {
     masterNote = ` It was not mastered to ${MASTER_LUFS} LUFS (${e instanceof Error ? e.message : String(e)}); the video is kept as rendered.`;
   }
+  // How the finished film sounds against what it shows. It is advice, so a measurement that fails leaves the render as it was.
+  let sound: SoundReport | undefined;
+  let soundLine: string | undefined;
+  try {
+    const voiceless = isVoiceless(loadPlan(project));
+    sound = await (deps.measure ?? measureSound)(project.path(path), loudness?.outputLufs, voiceless ? undefined : spokenWords(manifest));
+    if (voiceless) soundLine = soundAdvice(sound);
+    else if (sound.voice) soundLine = voiceAdvice(sound.voice);
+  } catch { sound = undefined; }
   const share = await shareAfterRender(ctx, project, { noShare: deps.noShare });
   return {
-    ok: true, data: { path, seconds, ...(loudness ? { loudness } : {}), ...(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}`, ...share.lines].join("\n"),
+    ok: true, data: { path, seconds, ...(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"),
   };
 }
+
+// `reelkit sound [file]`: the same measurement on any film, by default the last render. `--detail` lists every picture change with its nearest hit, every swell and the first sound.
+export async function soundCommand(ctx: Ctx, file?: string, opts: { detail?: boolean } = {}, deps: { measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport> } = {}): Promise<Result> {
+  let project: Project | undefined;
+  try { project = openProject(ctx.cwd); } catch { project = undefined; }
+  const path = file ? resolve(ctx.cwd, file) : project ? project.path("out/video.mp4") : resolve(ctx.cwd, "out/video.mp4");
+  if (!existsSync(path)) return { ok: false, summary: `${file ?? "out/video.mp4"} does not exist. ${file ? "Check the path." : "Run `reelkit render` first, or give the file."}` };
+  let narrated = false;
+  try { narrated = project ? !isVoiceless(loadPlan(project)) : false; } catch { narrated = false; }
+  // A narrated film is also measured against its words: the manifest has their times.
+  let words: SpokenWord[] | undefined;
+  if (narrated && project?.exists(FILES.manifest) && (!file || resolve(ctx.cwd, file) === resolve(project.path("out/video.mp4")))) { try { words = spokenWords(project.readJson<AssetManifest>(FILES.manifest)); } catch { words = undefined; } }
+  let report: SoundReport;
+  try { report = await (deps.measure ?? measureSound)(path, undefined, words); } catch (e) { return { ok: false, summary: `Could not measure the sound: ${e instanceof Error ? e.message : String(e)}` }; }
+  const numbers = `${report.hitsPerSecond} hits a second, ${report.swellsPerSecond} swells a second, ${report.changesWithHit} of ${report.pictureChanges} picture changes with a hit within 0.1s, first sound at ${report.firstSoundSec ?? "never"}s${report.loudnessLufs !== undefined ? `, ${report.loudnessLufs} LUFS` : ""}.`;
+  const { detail, ...counts } = report;
+  const body = narrated ? `${numbers}${report.voice ? `\n${voiceAdvice(report.voice)}` : ""}` : `${soundAdvice(report)}\n${numbers}`;
+  if (opts.detail && detail) return { ok: true, data: { path, ...counts, detail }, summary: `${body}\n${detailLines(detail).join("\n")}` };
+  return { ok: true, data: { path, ...counts }, summary: `${body}\nRun with --detail to see each event.` };
+}

package/src/commands/init.ts

@@ -31,7 +31,7 @@ export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?:
     summary: [
       `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
       project.config().shareComponents === false
-        ? "Nothing from this project is shared automatically."
+        ? "This project is private: nothing from it is sent to the library, not its components and not the images, clips or graphics generated for it, whatever the plan says."
         : "After a render, new components written in this project are sent to the Reelkit library for review (their source, a description and an example; nothing else). To turn this off: `reelkit init <name> --private` for a new project, `reelkit render --no-share`, or REELKIT_NO_SHARE=1.",
     ].join("\n"),
   };

package/src/commands/install.ts

@@ -17,7 +17,7 @@ export async function install(ctx: Ctx, opts: { agent?: string; force?: boolean
   }
   const name = (id: string) => AGENTS.find((a) => a.id === id)!.name;
   const lines = [
-    ...report.installed.map((i) => `Installed the Reelkit skill for ${name(i.agent)}: ${i.path}`),
+    ...report.installed.map((i) => `Installed the Reelkit skill for ${name(i.agent)}: ${i.path}${i.commands.length ? ` and the commands ${i.commands.map((c) => `/${c}`).join(" and ")}` : ""}`),
     ...report.skipped.filter((s) => agents || s.reason !== "not installed on this machine").map((s) => `Skipped ${name(s.agent)}: ${s.reason}`),
   ];
   return { ok: true, data: report, summary: lines.join("\n") };

package/src/commands/plan.ts

@@ -1,7 +1,8 @@
 import { client, type Ctx, type Result } from "../context";
 import { loadCredentials } from "../credentials";
 import { estimateLength, lengthVariation, reviewPlan, sceneSeconds } from "../pipeline/review";
-import { ScenePlanSchema, validatePlan, type ScenePlan } from "../pipeline/schema";
+import { isVoiceless, ScenePlanSchema, validatePlan, type ScenePlan } from "../pipeline/schema";
+import { snappedSeconds } from "../project/manifest";
 import { FILES, issueLines, openProject, type Project } from "../project/project";
 
 export function loadPlan(project: Project): ScenePlan {
@@ -52,7 +53,8 @@ export async function planCheck(ctx: Ctx): Promise<Result> {
   }
   const footage = project.footage();
   const assets = project.assets().filter((a) => a.id !== footage?.id);
-  const voiceIds = loadCredentials(ctx.env) ? (await client(ctx)("voices", {})).voices.map((v) => v.id) : undefined;
+  const voiceless = isVoiceless(parsed.data);
+  const voiceIds = !voiceless && loadCredentials(ctx.env) ? (await client(ctx)("voices", {})).voices.map((v) => v.id) : undefined;
   const ref = referenceChecks(project, parsed.data);
   const mustFix = [...validatePlan(parsed.data, { aspect: project.config().aspect, footage, assets, voiceIds }), ...ref.mustFix];
   const shouldImprove = mustFix.length ? [] : [...reviewPlan(parsed.data, { footage }), ...ref.improve];
@@ -60,11 +62,12 @@ export async function planCheck(ctx: Ctx): Promise<Result> {
   const estimatedSeconds = Math.round(length.seconds);
   const perScene = sceneSeconds(parsed.data).map((s) => ({ id: s.id, seconds: Math.round(s.seconds * 10) / 10 }));
   const variation = Math.round(lengthVariation(sceneSeconds(parsed.data).map((s) => s.seconds)) * 100) / 100;
+  const snapped = voiceless ? snappedSeconds(project, parsed.data) : undefined;
   const lines = [
     mustFix.length ? `Fix these:\n- ${mustFix.join("\n- ")}` : "The plan is valid.",
-    `Estimated length: about ${estimatedSeconds}s (${length.words} words).`,
+    voiceless ? `Length: ${(Math.round(length.seconds * 10) / 10).toFixed(1)}s over ${parsed.data.scenes.length} scenes${snapped !== undefined ? `; about ${snapped.toFixed(1)}s once the cuts are on the beat` : ""}.` : `Estimated length: about ${estimatedSeconds}s (${length.words} words).`,
     ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : []),
-    ...(voiceIds ? [] : ["The voice was not checked because you are not logged in. Run `reelkit auth login`."]),
+    ...(voiceIds || voiceless ? [] : ["The voice was not checked because you are not logged in. Run `reelkit auth login`."]),
   ];
-  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove, estimatedSeconds, words: length.words, sceneSeconds: perScene, lengthVariation: variation }, summary: lines.join("\n") };
+  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove, estimatedSeconds, words: length.words, sceneSeconds: perScene, lengthVariation: variation, ...(snapped !== undefined ? { snappedSeconds: Math.round(snapped * 10) / 10 } : {}) }, summary: lines.join("\n") };
 }

package/src/commands/ref.ts

@@ -60,11 +60,14 @@ const realYtdlp: YtdlpRunner = {
 
 const YTDLP_MISSING = "yt-dlp is not installed, and links need it. Install it (macOS: `brew install yt-dlp`, or `pipx install yt-dlp`) and run the command again; a video file on this machine works without it.";
 
+// The duration filter uses "<=?": some sites (Instagram) give no duration before the download, and without the "?" such a video is
+// skipped as if it were too long. A video that turns out longer is refused after it is probed.
+// No "--max-downloads 1": yt-dlp exits with an error code after reaching it even when the one video was saved.
 // One video, at most 1080p, as mp4, and nothing longer than the limit: the flags that keep a link from fetching a playlist, a channel or a huge file.
 export function ytdlpArgs(url: string, dest: string): string[] {
   return [
-    "--ignore-config", "--no-playlist", "--max-downloads", "1", "--no-progress", "--no-warnings",
-    "--match-filter", `duration<=${MAX_REF_SECONDS}`,
+    "--ignore-config", "--no-playlist", "--no-progress", "--no-warnings",
+    "--match-filter", `duration<=?${MAX_REF_SECONDS}`,
     "-f", "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]/bv*[height<=1080]+ba/b[height<=1080]",
     "--merge-output-format", "mp4", "-o", dest, "--", url,
   ];

package/src/contract/index.ts

@@ -14,7 +14,7 @@
 // - A library item `id` (pull, commit) matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; a `deviceCode` is 1 to 200 characters of plain text.
 // - A `voiceId` is 1 to 64 letters and digits and must be one of the voices the server lists (`voices`), otherwise 400 invalid_request.
 // - A user's component is uploaded for review through the same two calls as any other file (`kind: "component"`). The server checks its source
-//   at commit with the same static check a pulled component gets (only react, remotion and reelkit/kit imports, no network, no globals that reach
+//   at commit with the same static check a pulled component gets (only react, reelkit/frame and reelkit/kit imports, no network, no globals that reach
 //   outside the video) and refuses a source that fails it with 400 `invalid_request` and the first problem. It stays in `review`, is never found
 //   by search or the public listing, and is published only by the owner. A component upload is: `contentType` `text/plain`, `bytes` up to 65,536,
 //   `shareable` true, `filename` matching `^[A-Z][A-Za-z0-9]*\.tsx$`, a `description` of at least 20 characters, and `meta.example` a string of at most
@@ -210,10 +210,12 @@ export const routes = {
   voiceover: route("POST", "/voiceover", true,
     z.object({ text: text(5000).refine((t) => /\S/.test(t), "must contain a non-space character"), voiceId: z.string().regex(/^[A-Za-z0-9]{1,64}$/).optional(), speed: z.number().min(0.7).max(1.3).optional() }),
     z.object({ url: z.string(), ext: z.enum(["mp3", "wav", "m4a"]), contentType: z.string(), durationSec: z.number().positive(), words: z.array(WordTimingSchema), chars: z.number() })),
+  // `format` is "png" (a raster image, the default) or "svg" (a vector graphic). An SVG counts as one image against the image quota, takes about 45 s, and the
+  // server returns only a cleaned SVG: no scripts, no event attributes, no outside references. Its `ext` is "svg" and its contentType `image/svg+xml`.
   images: route("POST", "/images", true,
-    z.object({ prompt: text(2000).min(1), aspect: AspectSchema, shareable: z.boolean(), tags: z.array(text(40)).max(12) }),
+    z.object({ prompt: text(2000).min(1), aspect: AspectSchema, shareable: z.boolean(), tags: z.array(text(40)).max(12), format: z.enum(["png", "svg"]).default("png") }),
     // libraryId is set when the image was also added to the shared library.
-    z.object({ url: z.string(), ext: z.enum(["png", "jpg", "jpeg", "webp"]), contentType: z.string(), libraryId: z.string().optional() })),
+    z.object({ url: z.string(), ext: z.enum(["png", "jpg", "jpeg", "webp", "svg"]), contentType: z.string(), libraryId: z.string().optional() })),
   clipStart: route("POST", "/clips", true,
     z.object({
       prompt: text(2000).min(1), aspect: AspectSchema, greenScreen: z.boolean().default(false), durationSec: z.union([z.literal(5), z.literal(10)]).default(5),

package/src/hyperframes/Root.tsx

@@ -0,0 +1 @@
+export { mountVideo, mountVideo as makeRoot } from "./host";

package/src/hyperframes/fonts.ts

@@ -0,0 +1,54 @@
+import { delayRender, continueRender } from "./frame";
+const loaded = new Set<string>();
+export function loadFont(family: string, slug: string) {
+  if (typeof document !== "undefined" && !loaded.has(slug)) {
+    loaded.add(slug);
+    const handle = delayRender(`font ${family}`);
+    const link = document.createElement("link");
+    link.onload = () => continueRender(handle);
+    link.onerror = () => { continueRender(handle); throw new Error(`Font stylesheet failed: ${slug}`); };
+    link.rel = "stylesheet"; link.href = `./fonts/${slug}.css`; document.head.appendChild(link);
+  }
+  return { fontFamily: `"${family}"` };
+}
+export const fontFamilies = {
+  "Inter": "inter",
+  "Sora": "sora",
+  "ArchivoBlack": "archivo-black",
+  "BebasNeue": "bebas-neue",
+  "GreatVibes": "great-vibes",
+  "JetBrainsMono": "jetbrains-mono",
+  "Kanit": "kanit",
+  "Modak": "modak",
+  "Montserrat": "montserrat",
+  "Roboto": "roboto",
+  "RobotoSlab": "roboto-slab",
+  "Sacramento": "sacramento",
+  "Unbounded": "unbounded",
+  "BungeeShade": "bungee-shade",
+  "Cinzel": "cinzel",
+  "Creepster": "creepster",
+  "Heebo": "heebo",
+  "KaushanScript": "kaushan-script",
+  "LilitaOne": "lilita-one",
+  "MrsSaintDelafield": "mrs-saint-delafield",
+  "Orbitron": "orbitron",
+  "Outfit": "outfit",
+  "PermanentMarker": "permanent-marker",
+  "PlayfairDisplay": "playfair-display",
+  "Rubik": "rubik",
+  "Rye": "rye",
+  "Syne": "syne",
+  "Yellowtail": "yellowtail",
+  "Alef": "alef",
+  "AmaticSC": "amatic-sc",
+  "Assistant": "assistant",
+  "DavidLibre": "david-libre",
+  "FrankRuhlLibre": "frank-ruhl-libre",
+  "Fredoka": "fredoka",
+  "Karantina": "karantina",
+  "NotoSansHebrew": "noto-sans-hebrew",
+  "SecularOne": "secular-one",
+  "SuezOne": "suez-one",
+  "VarelaRound": "varela-round"
+} as const;

package/src/hyperframes/frame.tsx

@@ -0,0 +1,46 @@
+import React, { createContext, useContext, useId } from "react";
+export * from "./math";
+export type VideoConfig = { width: number; height: number; fps: number; durationInFrames: number; id?: string };
+export type FrameState = { frame: number; offset: number; duration: number; config: VideoConfig; loop?: number; collecting?: boolean };
+export const FrameContext = createContext<FrameState>({ frame: 0, offset: 0, duration: 1, config: { width: 1080, height: 1920, fps: 30, durationInFrames: 1 } });
+export const useCurrentFrame = () => useContext(FrameContext).frame;
+export const useVideoConfig = () => { const s = useContext(FrameContext); return { ...s.config, durationInFrames: s.duration }; };
+export const AbsoluteFill = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(({ style, ...props }, ref) => <div ref={ref} {...props} style={{ position: "absolute", inset: 0, display: "flex", flexDirection: "column", ...style }} />);
+export const Img = React.forwardRef<HTMLImageElement, React.ImgHTMLAttributes<HTMLImageElement>>((props, ref) => <img {...props} ref={ref} />);
+export const Sequence: React.FC<{ from?: number; durationInFrames?: number; layout?: "none" | "absolute-fill"; children?: React.ReactNode; name?: string; style?: React.CSSProperties; premountFor?: number }> = ({ from = 0, durationInFrames, layout, children, style }) => {
+  const s = useContext(FrameContext), duration = Math.min(durationInFrames ?? s.duration - from, s.duration - from);
+  if (!s.collecting && (s.frame < from || s.frame >= from + duration)) return null;
+  const content = <FrameContext.Provider value={{ ...s, frame: s.frame - from, offset: s.offset + from, duration }}>{children}</FrameContext.Provider>;
+  return layout === "none" ? content : <AbsoluteFill style={style}>{content}</AbsoluteFill>;
+};
+export const Freeze: React.FC<{ frame: number; children?: React.ReactNode }> = ({ frame, children }) => { const s = useContext(FrameContext); return <FrameContext.Provider value={{ ...s, frame }}>{children}</FrameContext.Provider>; };
+export const Loop: React.FC<{ durationInFrames: number; children?: React.ReactNode; times?: number; layout?: "none" | "absolute-fill" }> = ({ durationInFrames, children }) => {
+  const s = useContext(FrameContext); return <FrameContext.Provider value={{ ...s, frame: ((s.frame % durationInFrames) + durationInFrames) % durationInFrames, loop: durationInFrames }}>{children}</FrameContext.Provider>;
+};
+export type AudioRecord = { id: string; src: string; start: number; end: number; mediaStart: number; layer: number; volume: number; volumeKeyframes: { time: number; volume: number }[]; type: "audio" | "video"; loop: boolean };
+export const audioRecords = new Map<string, AudioRecord>();
+type MediaProps = { src: string; volume?: number | ((frame: number) => number); startFrom?: number; endAt?: number; trimBefore?: number; trimAfter?: number; playbackRate?: number; loopVolumeCurveBehavior?: "extend" | "repeat" };
+function recordAudio(id: string, props: MediaProps & { loop?: boolean }, type: "audio" | "video", state: FrameState) {
+  const { config: { fps } } = state;
+  const volume = typeof props.volume === "function" ? props.volume(state.frame) : props.volume ?? 1;
+  const start = state.offset / fps, end = Math.min(state.config.durationInFrames, state.offset + state.duration) / fps;
+  let record = audioRecords.get(id);
+  if (!record) { record = { id, src: props.src, start, end, mediaStart: (props.trimBefore ?? props.startFrom ?? 0) / fps, layer: audioRecords.size, volume, volumeKeyframes: [], type, loop: props.loop ?? false }; audioRecords.set(id, record); }
+  const time = (state.frame + state.offset) / fps;
+  if (time >= start && time < end && typeof props.volume === "function") record.volumeKeyframes.push({ time, volume });
+}
+export const Audio: React.FC<MediaProps & { loop?: boolean }> = (props) => {
+  const s = useContext(FrameContext), id = useId(); recordAudio(id, props, "audio", s);
+  return <audio id={`hf-audio-${id.replace(/[^a-z0-9]/gi, "")}`} src={props.src} preload="none" data-start={s.offset / s.config.fps} data-duration={s.duration / s.config.fps} />;
+};
+export const OffthreadVideo: React.FC<Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "volume"> & MediaProps & { transparent?: boolean; pauseWhenBuffering?: boolean }> = ({ volume, startFrom, endAt, trimBefore, trimAfter, transparent, pauseWhenBuffering, playbackRate = 1, ...props }) => {
+  const s = useContext(FrameContext), id = useId();
+  if (!props.muted) recordAudio(id, { ...props, src: props.src!, volume, startFrom, trimBefore }, "video", s);
+  return <video {...props} muted playsInline preload="auto" data-hf-frame-video="true" data-hf-time={Math.max(0, s.frame / s.config.fps * playbackRate + (trimBefore ?? startFrom ?? 0) / s.config.fps)} data-hf-loop={props.loop || s.loop ? "true" : undefined} />;
+};
+export const Video = OffthreadVideo;
+let nextHandle = 0;
+const pending = new Map<number, { promise: Promise<void>; resolve: () => void }>();
+export function delayRender(_label?: string): number { const id = ++nextHandle; let resolve!: () => void; const promise = new Promise<void>((r) => { resolve = r; }); pending.set(id, { promise, resolve }); return id; }
+export function continueRender(handle: number): void { pending.get(handle)?.resolve(); pending.delete(handle); }
+export async function waitForRender(): Promise<void> { while (pending.size) await Promise.all([...pending.values()].map((p) => p.promise)); }

package/src/hyperframes/host.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import type { HfProtocol } from "@hyperframes/engine";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { audioRecords, FrameContext, waitForRender } from "./frame";
+import { ManifestContext, UrlsContext } from "./kit/media";
+import type { VideoProps } from "./types";
+
+declare global { interface Window { __reelkitProps: VideoProps; __reelkitReady: Promise<void>; __reelkitAudio: typeof audioRecords; __hf?: HfProtocol; } }
+async function settleMedia() {
+  await waitForRender();
+  await document.fonts.ready;
+  await Promise.all([...document.images].map(async (img) => { if (!img.complete) await new Promise<void>((resolve, reject) => { img.addEventListener("load", () => resolve(), { once: true }); img.addEventListener("error", () => reject(new Error(`Image failed: ${img.src}`)), { once: true }); }); if (img.naturalWidth === 0) throw new Error(`Image failed: ${img.src}`); await img.decode(); }));
+  await Promise.all([...document.querySelectorAll<HTMLVideoElement>("video[data-hf-frame-video]")].map(async (video) => {
+    if (video.readyState < 1) await new Promise<void>((resolve, reject) => { video.addEventListener("loadedmetadata", () => resolve(), { once: true }); video.addEventListener("error", () => reject(new Error(`Video failed: ${video.src}`)), { once: true }); });
+    const time = Number(video.dataset.hfTime), duration = video.duration;
+    const target = video.dataset.hfLoop ? time % duration : Math.min(time, Math.max(0, duration - 0.00001));
+    if (video.readyState < 2 || Math.abs(video.currentTime - target) > 0.00001) await new Promise<void>((resolve, reject) => { video.addEventListener("seeked", () => resolve(), { once: true }); video.addEventListener("error", () => reject(new Error(`Video seek failed: ${video.src}`)), { once: true }); video.currentTime = target; });
+    video.pause();
+  }));
+  await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+}
+export function mountVideo(Video: React.ComponentType<VideoProps>, previewProps?: VideoProps) {
+  const props = previewProps ?? window.__reelkitProps, m = props.manifest;
+  const stage = document.getElementById("stage")!;
+  stage.style.width = `${m.width}px`; stage.style.height = `${m.height}px`;
+  stage.dataset.compositionId = "Video"; stage.dataset.noTimeline = "true"; stage.dataset.duration = String(m.totalFrames / m.fps);
+  stage.dataset.width = String(m.width); stage.dataset.height = String(m.height);
+  const root = createRoot(stage);
+  window.__reelkitAudio = audioRecords;
+  const seek = (time: number) => {
+    const frame = Math.min(m.totalFrames - 1, Math.max(0, Math.round(time * m.fps)));
+    flushSync(() => root.render(<FrameContext.Provider value={{ frame, offset: 0, duration: m.totalFrames, config: { width: m.width, height: m.height, fps: m.fps, durationInFrames: m.totalFrames } }}><UrlsContext.Provider value={props.urls}><ManifestContext.Provider value={m}><Video {...props} /></ManifestContext.Provider></UrlsContext.Provider></FrameContext.Provider>));
+    window.__reelkitReady = settleMedia();
+  };
+  window.__hf = { duration: m.totalFrames / m.fps, seek };
+  seek(0);
+}