reelkit-cli 0.6.0 → 0.8.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

@@ -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/pipeline/beatsnap.ts

@@ -12,6 +12,9 @@ export type SnapInput = {
   // Beats as frame numbers, ascending. They should reach past the end of the video.
   beatFrames: number[];
   fps: number;
+  // "next" holds a scene to the next whole beat (narration cannot be cut). "nearest" moves each end to the closest point on a finer grid
+  // (a film with no voice can be shortened as well as lengthened, so its total stays near the plan).
+  grid?: "next" | "nearest";
 };
 
 const firstAtOrAfter = (beats: number[], frame: number): number | undefined => beats.find((b) => b >= frame);
@@ -21,6 +24,7 @@ const firstAtOrAfter = (beats: number[], frame: number): number | undefined => b
 export function snapToBeats(input: SnapInput): number[] {
   const { naturalFrames, beatFrames, fps } = input;
   if (beatFrames.length < 2) return [...naturalFrames];
+  if (input.grid === "nearest") return snapToNearest(naturalFrames, beatFrames);
   const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
   const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
   let cursor = 0;
@@ -40,6 +44,74 @@ export function snapToBeats(input: SnapInput): number[] {
   });
 }
 
+// How far a scene change of a narrated film may move to reach a beat, in frames, either way.
+export const NARRATED_SNAP_FRAMES = 4;
+// A boundary never comes closer than this to the last word of the scene it ends, in frames.
+export const NARRATED_WORD_CLEARANCE = 2;
+
+// Scene changes for a narrated film. The voice sets where a scene ends; a boundary is moved to the nearest beat only when that is at most
+// `maxMove` frames away either way and leaves at least `clearance` frames after the scene's last word (a boundary never cuts into a word). The
+// next scene's audio starts on its first frame, so it moves with the boundary. Every other boundary stays where the narration puts it, and the
+// last scene is not touched: the film's end is not a scene change. Each boundary is judged from where its scene actually starts, so
+// nothing adds up. `lastWordEndFrames[i]` is when scene i's last word ends, in frames from its own start.
+export function snapNarrated(input: { naturalFrames: number[]; lastWordEndFrames: number[]; beatFrames: number[]; maxMove?: number; clearance?: number }): { frames: number[]; onBeat: boolean[] } {
+  const { naturalFrames, lastWordEndFrames, beatFrames } = input;
+  const maxMove = input.maxMove ?? NARRATED_SNAP_FRAMES, clearance = input.clearance ?? NARRATED_WORD_CLEARANCE;
+  let cursor = 0;
+  const onBeat: boolean[] = [];
+  const frames = naturalFrames.map((natural, i) => {
+    let end = cursor + natural;
+    if (i < naturalFrames.length - 1) {
+      const floor = cursor + (lastWordEndFrames[i] ?? 0) + clearance;
+      let best: number | undefined;
+      for (const b of beatFrames) {
+        if (Math.abs(b - end) > maxMove || b < floor) continue;
+        if (best === undefined || Math.abs(b - end) < Math.abs(best - end) || (Math.abs(b - end) === Math.abs(best - end) && b > best)) best = b;
+      }
+      if (best !== undefined) end = best;
+      onBeat.push(beatFrames.includes(end));
+    }
+    const length = end - cursor;
+    cursor = end;
+    return length;
+  });
+  return { frames, onBeat };
+}
+
+// The beat frames with `divisions - 1` evenly spaced points between each pair, rounded to frames. The last beat is followed by one more
+// at the median spacing, so a point just after it exists too.
+export function gridPoints(beatFrames: number[], divisions: number): number[] {
+  if (beatFrames.length < 2) return [...beatFrames];
+  const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
+  const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
+  const all = [...beatFrames, beatFrames[beatFrames.length - 1]! + period];
+  const out = new Set<number>();
+  for (let i = 0; i + 1 < all.length; i++) for (let k = 0; k < divisions; k++) out.add(Math.round(all[i]! + ((all[i + 1]! - all[i]!) * k) / divisions));
+  out.add(all[all.length - 1]!);
+  return [...out].sort((a, b) => a - b);
+}
+
+// A scene of at least 1.5 beats ends on the nearest whole beat; a shorter one on the nearest half beat, and under half a beat the nearest
+// quarter. The target is the planned end (the sum of the natural lengths), so rounding errors do not add up; a scene is never made empty.
+function snapToNearest(naturalFrames: number[], beatFrames: number[]): number[] {
+  const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
+  const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
+  const grids = new Map<number, number[]>();
+  const grid = (d: number) => grids.get(d) ?? (grids.set(d, gridPoints(beatFrames, d)), grids.get(d)!);
+  let cursor = 0, planned = 0;
+  return naturalFrames.map((natural) => {
+    planned += natural;
+    const beats = natural / period;
+    const points = grid(beats >= 1.5 ? 1 : beats >= 0.5 ? 2 : 4).filter((f) => f > cursor);
+    let target = planned;
+    if (points.length) target = points.reduce((best, f) => (Math.abs(f - planned) < Math.abs(best - planned) ? f : best));
+    else target = Math.max(planned, cursor + 1);
+    const frames = target - cursor;
+    cursor = target;
+    return frames;
+  });
+}
+
 // Beats in seconds, continued at the tempo's own spacing until `untilSec`, for a video longer than the track (the track loops).
 export function extendBeats(beats: number[], bpm: number, untilSec: number): number[] {
   if (!beats.length) return [];

package/src/pipeline/review.ts

@@ -1,16 +1,23 @@
-import { WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
+import { gapSec, isVoiceless, LAST_TAIL_SEC, PACE_SPEED, VOICE_WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
 
 const words = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
 
-// The same estimate the length advice below is based on: narration words at the voice's usual pace.
+// What the voice speaks at, in words a second, for this plan's pace.
+const speechRate = (plan: ScenePlan) => VOICE_WORDS_PER_SEC * PACE_SPEED[plan.pace ?? "normal"];
+
+// The estimate the length advice below is based on: each scene's words at the voice's real speed (2.25 words a second at the normal pace, the
+// pauses within a sentence included), the plan's silence between sentences after every scene but the last, and the last scene's tail after its
+// last word. It matches the manifest `reelkit assets voiceover` builds. A video with no voice has no words to count: its length is the sum of the
+// scenes' own seconds.
 export function estimateLength(plan: ScenePlan): { words: number; seconds: number } {
+  if (isVoiceless(plan)) return { words: 0, seconds: plan.scenes.reduce((n, s) => n + (s.seconds ?? 0), 0) };
   const total = plan.scenes.reduce((n, s) => n + words(s.narration), 0);
-  return { words: total, seconds: total / WORDS_PER_SEC };
+  return { words: total, seconds: total / speechRate(plan) + (plan.scenes.length - 1) * gapSec(plan) + LAST_TAIL_SEC };
 }
 
-// Each scene's estimated length in seconds, from its narration at the same pace as the whole-video estimate above.
+// Each scene's estimated length in seconds: its speech and what follows it (the gap, or the tail for the last scene), so they add up to the whole estimate.
 export function sceneSeconds(plan: ScenePlan): { id: string; seconds: number }[] {
-  return plan.scenes.map((s) => ({ id: s.id, seconds: words(s.narration) / WORDS_PER_SEC }));
+  return plan.scenes.map((s, i) => ({ id: s.id, seconds: isVoiceless(plan) ? (s.seconds ?? 0) : words(s.narration) / speechRate(plan) + (i === plan.scenes.length - 1 ? LAST_TAIL_SEC : gapSec(plan)) }));
 }
 
 // How uneven the scene lengths are: the standard deviation over the mean (0 when they are all the same).
@@ -29,12 +36,14 @@ export function rhythmNote(plan: ScenePlan): string | undefined {
   const cv = lengthVariation(values);
   if (cv >= 0.25 && values.some((v) => v < mean / 2)) return undefined;
   const shortest = lengths.reduce((a, b) => (b.seconds < a.seconds ? b : a)), longest = lengths.reduce((a, b) => (b.seconds > a.seconds ? b : a));
-  return `The scenes are too even in length (the shortest, ${shortest.id}, is about ${shortest.seconds.toFixed(1)}s and the longest, ${longest.id}, about ${longest.seconds.toFixed(1)}s). Make one or two scenes much shorter (a hit of a few words) and let one run long.`;
+  const fix = isVoiceless(plan) ? "Make one or two scenes much shorter (under a second) and let one run long." : "Make one or two scenes much shorter (a hit of a few words) and let one run long.";
+  return `The scenes are too even in length (the shortest, ${shortest.id}, is about ${shortest.seconds.toFixed(1)}s and the longest, ${longest.id}, about ${longest.seconds.toFixed(1)}s). ${fix}`;
 }
 
 // Soft quality checks on a plan that already passes the hard rules in validatePlan.
 // These are things worth improving in the script; they never fail a video on their own.
 export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
+  if (isVoiceless(plan)) return reviewVoicelessPlan(plan, ctx);
   const issues: string[] = [];
   const { words: total, seconds } = estimateLength(plan);
 
@@ -53,7 +62,30 @@ export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): str
     // A hit of a few words is wanted in the rhythm of a video, so only a scene with almost nothing to say is flagged.
     if (!ctx.footage && n < 3) issues.push(`Scene ${s.id} has only ${n} word${n === 1 ? "" : "s"} of narration; give it at least a short phrase.`);
     if (n > 45) issues.push(`Scene ${s.id} has ${n} words of narration; split it or cut it to under 45.`);
-    if (s.onScreenText.length > 3) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 3.`);
+    if (s.onScreenText.length > 5) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 5 (the items of one list on screen count as one text, but the plan cannot say which they are).`);
+    for (const t of s.onScreenText) if (words(t) > 7) issues.push(`Scene ${s.id}: on-screen text "${t}" is too long; keep each item to 7 words or fewer.`);
+  }
+  const rhythm = rhythmNote(plan);
+  if (rhythm) issues.push(rhythm);
+  issues.push(...structureNotes(plan, ctx));
+  return issues;
+}
+
+// The same kind of advice for a video with no voice: no words to count, so length and rhythm come from `seconds`, and every word the
+// viewer reads is on screen. A video of this kind needs at least one quick hit, so a plan with no scene under a second is flagged.
+function reviewVoicelessPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
+  const issues: string[] = [];
+  const { seconds } = estimateLength(plan);
+  if (seconds < 10) issues.push(`The video runs ${seconds.toFixed(1)}s. A video with no voice needs at least 10 seconds to get across; aim for 15 to 45.`);
+  if (seconds > 60) issues.push(`The video runs ${seconds.toFixed(1)}s. Cut it to 60 seconds or less; aim for 15 to 45.`);
+  if (!plan.scenes.some((s) => (s.seconds ?? 0) < 1)) issues.push("No scene is under 1 second. A film like this needs at least one quick hit; shorten one or two scenes to under a second.");
+  if (!ctx.footage) {
+    const illustrations = plan.scenes.filter((s) => s.treatment === "illustration").length;
+    if (illustrations > Math.ceil(plan.scenes.length / 2)) issues.push(`${illustrations} of ${plan.scenes.length} scenes are illustrations. Use illustrations for at most half the scenes.`);
+  }
+  for (const s of plan.scenes) {
+    if (!s.onScreenText.length && !s.notes.trim()) issues.push(`Scene ${s.id} has neither onScreenText nor notes. Say what is on screen, since no voice explains it.`);
+    if (s.onScreenText.length > 5) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 5 (the items of one list on screen count as one text, but the plan cannot say which they are).`);
     for (const t of s.onScreenText) if (words(t) > 7) issues.push(`Scene ${s.id}: on-screen text "${t}" is too long; keep each item to 7 words or fewer.`);
   }
   const rhythm = rhythmNote(plan);
@@ -75,14 +107,16 @@ export function firstSentence(text: string): string {
 export function structureNotes(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
   const notes: string[] = [];
   if (ctx.footage) return notes;
-  if (plan.scenes.length >= 4 && !plan.scenes.some(hasPicture)) {
+  // A film with no voice is made of type and interface pieces on purpose (reference/launch-film.md), so it is not asked for a picture.
+  const voiceless = isVoiceless(plan);
+  if (!voiceless && plan.scenes.length >= 4 && !plan.scenes.some(hasPicture)) {
     notes.push("Every scene is type and shapes: no illustration, no clip and none of the user's own files. Give at least one scene a picture so the video has something to look at; see reference/scene-treatments.md.");
   }
   const first = plan.scenes[0]!;
-  if (!hasPicture(first)) {
+  if (!voiceless && !hasPicture(first)) {
     notes.push(`The opening has no picture, clip or user asset (scene ${first.id}). The first second decides whether the video is watched, so open on something to look at; see reference/scriptwriting.md.`);
   }
-  const n = words(firstSentence(first.narration));
+  const n = isVoiceless(plan) ? 0 : words(firstSentence(first.narration));
   if (n > 12) notes.push(`The first sentence of the opening is ${n} words. Open with a sentence of 12 words or fewer; see reference/scriptwriting.md.`);
   return notes;
 }