reelkit-cli 0.5.0 → 0.8.0

package/src/remotion/kit/word-anchor.ts

@@ -0,0 +1,107 @@
+// Word anchors: where in the film a spoken word falls, so that what illustrates a word can be placed on it.
+// Everything here is a pure function over a manifest scene (`manifest.scenes[i]`, with its `words`), so it is the same in the studio, in a test and in a render.
+// Frames are counted from the start of the scene (what its own useCurrentFrame() gives) unless `absolute: true` adds the scene's startFrame.
+import type { WordTiming } from "../../pipeline/schema";
+
+// The manifest's frame rate is always this one; pass `fps` only for a scene that came from somewhere else.
+export const WORD_FPS = 30;
+// An entrance needs a few frames to become visible, so it starts this many frames before its word.
+export const DEFAULT_LEAD = 3;
+// A beat counts as "at the word" when it is no more than this many frames from the word's start.
+export const DEFAULT_BEAT_WINDOW = 3;
+// The thing a word names is never seen more than this many frames before the word starts.
+export const MAX_EARLY_FRAMES = 3;
+
+export type WordScene = { id?: string; startFrame: number; durationFrames?: number; words: WordTiming[] };
+
+export type WordFrameOptions = {
+  // The 1-based occurrence of the word when the scene says it more than once (default 1).
+  nth?: number;
+  // "start" (default): the frame the word starts. "end": the frame it ends (for a phrase, the end of its last word).
+  edge?: "start" | "end";
+  // Add the scene's startFrame, giving a frame of the whole film.
+  absolute?: boolean;
+  fps?: number;
+};
+
+// A word as it is compared: lower case, with everything but letters and digits removed ("Meetings," is "meetings", "don't" is "dont").
+export const normalizeWord = (w: string): string => w.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+
+const spoken = (scene: WordScene): { norm: string; word: WordTiming }[] =>
+  scene.words.map((word) => ({ norm: normalizeWord(word.word), word })).filter((w) => w.norm !== "");
+
+// The words that make up `phrase`, matched against the scene's words, with where the phrase's `nth` occurrence is.
+function findPhrase(scene: WordScene, phrase: string, nth: number): { first: WordTiming; last: WordTiming } {
+  const parts = phrase.split(/\s+/).map(normalizeWord).filter(Boolean);
+  const list = spoken(scene);
+  const where = scene.id ? `scene "${scene.id}"` : "the scene";
+  if (!parts.length) throw new Error(`wordFrame: the word is empty. ${where} says: ${list.map((w) => w.word.word).join(" ")}`);
+  if (!Number.isInteger(nth) || nth < 1) throw new Error(`wordFrame: nth must be 1 or more, got ${nth}.`);
+  let seen = 0;
+  for (let i = 0; i + parts.length <= list.length; i++) {
+    if (parts.every((p, k) => list[i + k]!.norm === p) && ++seen === nth) return { first: list[i]!.word, last: list[i + parts.length - 1]!.word };
+  }
+  const had = seen ? ` (it is said ${seen} time${seen === 1 ? "" : "s"}, not ${nth})` : "";
+  throw new Error(`wordFrame: "${phrase}"${nth > 1 ? ` (occurrence ${nth})` : ""} is not in ${where}${had}. Its words are: ${list.map((w) => w.word.word).join(" ")}`);
+}
+
+// The frame, inside the scene, at which `word` starts (or ends, with edge: "end"). `word` ignores case and punctuation; a phrase of several words
+// ("whole week") matches consecutive words and gives the first one's start. A word the scene does not say throws an Error that lists the scene's
+// words, so a misspelt word stops the render instead of silently timing to frame 0.
+export function wordFrame(scene: WordScene, word: string, opts: WordFrameOptions = {}): number {
+  const { first, last } = findPhrase(scene, word, opts.nth ?? 1);
+  const fps = opts.fps ?? WORD_FPS;
+  const sec = opts.edge === "end" ? last.endSec : first.startSec;
+  let frame = Math.max(0, Math.round(sec * fps));
+  if (scene.durationFrames !== undefined) frame = Math.min(frame, Math.max(0, scene.durationFrames - 1));
+  return frame + (opts.absolute ? scene.startFrame : 0);
+}
+
+// Several words at once, in the order given.
+export const wordFrames = (scene: WordScene, words: string[], opts: WordFrameOptions = {}): number[] => words.map((w) => wordFrame(scene, w, opts));
+
+// The scene with this id. Throws an Error that lists the ids when there is none.
+export function sceneById<S extends { id: string }>(manifest: { scenes: S[] }, id: string): S {
+  const found = manifest.scenes.find((s) => s.id === id);
+  if (!found) throw new Error(`sceneById: there is no scene "${id}". The scenes are: ${manifest.scenes.map((s) => s.id).join(", ")}`);
+  return found;
+}
+
+export type OnWordOptions = WordFrameOptions & {
+  // How many frames before the word the entrance starts (default 3).
+  lead?: number;
+};
+
+// The frame at which to START an entrance (a `delay`, a `from`, an `at`) so that it is seen landing on its word: the word's frame minus `lead`
+// (default 3), never below 0.
+export function onWord(scene: WordScene, word: string, opts: OnWordOptions = {}): number {
+  const lead = opts.lead ?? DEFAULT_LEAD;
+  const at = wordFrame(scene, word, { ...opts, absolute: false });
+  return Math.max(0, at - lead) + (opts.absolute ? scene.startFrame : 0);
+}
+
+export type OnWordBeatOptions = OnWordOptions & {
+  // A beat counts only when it is at most this many frames from the word's start (default 3).
+  window?: number;
+};
+
+// Beat and word together. The voice is the clock for what illustrates a word, so the word wins; the beat is used only when one lies within `window`
+// frames of the word (default 3), and then only to let the entrance land on it. The result is never earlier than onWord's, so what a word names
+// is never seen more than 3 frames before the word starts. `music` is manifest.music (its beatFrames are frames of the whole film); without a
+// track it is onWord.
+export function onWordBeat(scene: WordScene, word: string, music: { beatFrames: number[] } | undefined, opts: OnWordBeatOptions = {}): number {
+  const lead = opts.lead ?? DEFAULT_LEAD;
+  const window = opts.window ?? DEFAULT_BEAT_WINDOW;
+  const at = wordFrame(scene, word, { ...opts, absolute: false });
+  const wordAbs = scene.startFrame + at;
+  const base = Math.max(0, at - lead);
+  let start = base;
+  let best: number | undefined;
+  for (const b of music?.beatFrames ?? []) {
+    // A beat before the word is never used: it would show the thing early.
+    if (b < wordAbs || b - wordAbs > window) continue;
+    if (best === undefined || b - wordAbs < best - wordAbs) best = b;
+  }
+  if (best !== undefined) start = Math.max(base, best - scene.startFrame - lead);
+  return start + (opts.absolute ? scene.startFrame : 0);
+}

package/src/render/contact-sheet.ts

@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+// The grid of a sheet of `count` tiles for a frame of `aspect` (width over height): 6 across for a tall frame, 4 for a wide one, so that the whole sheet
+// is at most about `maxWidth` pixels across and a phone-shaped frame is still readable.
+export function sheetGrid(count: number, aspect: number, maxWidth = 2400): { cols: number; rows: number; tileW: number; tileH: number } {
+  const cols = Math.max(1, Math.min(count, aspect < 1 ? 6 : aspect > 1.2 ? 4 : 5));
+  const tileW = Math.min(540, Math.floor(maxWidth / cols / 2) * 2);
+  const tileH = Math.max(2, Math.round(tileW / aspect / 2) * 2);
+  return { cols, rows: Math.ceil(count / cols), tileW, tileH };
+}
+
+// The drawn text is plain ASCII (the default font has no arrows): the arrow of a word label is drawn as >.
+const clean = (s: string) => s.replace(/\u25B8/g, ">").replace(/[^A-Za-z0-9 _.>#-]/g, "");
+
+// One picture of many: the files in order, each with its label in a box on its top left corner. Falls back to the same sheet without labels if this ffmpeg
+// has no text drawing; the caller still lists the order. `newRowAt` starts a new row at that tile (the tiles before it are padded with empty ones), so a
+// second kind of frame sits in rows of its own. Returns the grid, and whether the labels were drawn.
+export async function contactSheet(files: string[], labels: string[], out: string, aspect: number, opts: { newRowAt?: number } = {}): Promise<{ cols: number; rows: number; width: number; height: number; labelled: boolean }> {
+  const base = sheetGrid(files.length, aspect);
+  const at = opts.newRowAt !== undefined && opts.newRowAt > 0 && opts.newRowAt < files.length ? opts.newRowAt : undefined;
+  const blanks = at === undefined ? 0 : (base.cols - (at % base.cols)) % base.cols;
+  const g = { ...base, rows: Math.ceil((files.length + blanks) / base.cols) };
+  const build = (labelled: boolean) => {
+    const tile = (i: number) => `[${i}:v]scale=${g.tileW}:${g.tileH},setsar=1${labelled ? `,drawtext=text='${clean(labels[i] ?? "")}':x=6:y=6:fontsize=${Math.max(12, Math.round(g.tileW / 22))}:fontcolor=white:box=1:boxcolor=black@0.65:boxborderw=4` : ""}[t${i}]`;
+    const parts = files.map((_, i) => tile(i));
+    // The empty tiles are extra inputs of plain colour, one frame each.
+    const blankInputs = Array.from({ length: blanks }, () => ["-f", "lavfi", "-i", `color=c=0x202020:s=${g.tileW}x${g.tileH}:r=25`]).flat();
+    const blankParts = Array.from({ length: blanks }, (_, k) => `[${files.length + k}:v]trim=end_frame=1,setpts=PTS-STARTPTS,format=yuvj420p,setsar=1[b${k}]`);
+    const order = [...files.map((_, i) => (i === at ? [...Array.from({ length: blanks }, (_, k) => `[b${k}]`), `[t${i}]`] : [`[t${i}]`])).flat()];
+    const filter = `${[...parts, ...blankParts].join(";")};${order.join("")}concat=n=${files.length + blanks}:v=1:a=0,tile=${g.cols}x${g.rows}:padding=2:color=0x202020[out]`;
+    return ["-y", "-loglevel", "error", ...files.flatMap((f) => ["-i", f]), ...blankInputs, "-filter_complex", filter, "-map", "[out]", "-frames:v", "1", "-q:v", "4", out];
+  };
+  let labelled = true;
+  try { await exec("ffmpeg", build(true)); } catch { labelled = false; await exec("ffmpeg", build(false)); }
+  return { cols: g.cols, rows: g.rows, width: g.cols * g.tileW + (g.cols - 1) * 2, height: g.rows * g.tileH + (g.rows - 1) * 2, labelled };
+}

package/src/render/continuity.ts

@@ -10,7 +10,8 @@ export const CARRIED_AT = 0.25;
 const MIN_EDGE_SHARE = 0.002;
 
 export type Gray = ArrayLike<number>;
-export type BoundaryKind = "carried" | "cut" | "empty";
+// "cut (intended)" is a change the plan marked with cutIn: it is reported but never counts against the score.
+export type BoundaryKind = "carried" | "cut" | "empty" | "cut (intended)";
 
 // A pixel is an edge where the brightness steps by more than the threshold to the pixel on its right or below it.
 export function edgeMap(gray: Gray, w: number, h: number, threshold = EDGE_THRESHOLD): Uint8Array {
@@ -57,6 +58,13 @@ export function dilate(map: Uint8Array, w: number, h: number, radius: number): U
   return out;
 }
 
+// The later scene is compared at two moments, its first fully visible frame and one a few frames on while a move is still settling (a plate
+// that becomes a card has not yet reached its edges at the first). The better of the two says whether something was carried.
+export function compareAcross(earlier: Gray, laters: Gray[], w: number, h: number): ReturnType<typeof compareFrames> {
+  const all = laters.map((l) => compareFrames(earlier, l, w, h));
+  return all.reduce((best, r) => (r.survived > best.survived ? r : best));
+}
+
 export function compareFrames(earlier: Gray, later: Gray, w: number, h: number): { survived: number; edges: number; kind: BoundaryKind } {
   const band = captionBand(w, h);
   const before = clearBottom(edgeMap(earlier, w, h), w, h, band);
@@ -72,15 +80,17 @@ export type Boundary = { from: string; to: string; survived: number; kind: Bound
 
 // The score is carried over carried plus cut: a change with nothing on screen to compare says nothing either way.
 export function summariseContinuity(boundaries: Boundary[]): { score: number | null; lines: string[] } {
+  const intended = boundaries.filter((b) => b.kind === "cut (intended)").length;
   const carried = boundaries.filter((b) => b.kind === "carried").length;
   const cut = boundaries.filter((b) => b.kind === "cut");
   const counted = carried + cut.length;
-  const empty = boundaries.length - counted;
-  if (!counted) return { score: null, lines: ["No scene change could be measured: the picture is nearly empty at the end of every scene."] };
+  const empty = boundaries.length - counted - intended;
+  const hard = intended ? ` ${intended} ${intended === 1 ? "is" : "are"} intended hard cut${intended === 1 ? "" : "s"}, not counted.` : "";
+  if (!counted) return { score: null, lines: [intended && !empty ? `Every scene change that could be measured is an intended hard cut.` : "No scene change could be measured: the picture is nearly empty at the end of every scene."] };
   return {
     score: carried / counted,
     lines: [
-      `${carried} of ${counted} scene changes carry something across${empty ? ` (${empty} more had nothing on screen to compare)` : ""}.`,
+      `${carried} of ${counted} scene changes carry something across${empty ? ` (${empty} more had nothing on screen to compare)` : ""}.${hard}`,
       ...cut.map((b) => `${b.from} → ${b.to}: nothing carries over. Keep one element on screen through the change and move it into the next scene (see reference/continuity.md).`),
     ],
   };

package/src/render/deps.ts

@@ -1,8 +1,20 @@
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 
 const require = createRequire(import.meta.url);
 
 // The directory of an installed dependency of this package, found through its package.json so it does not depend on
-// where the package keeps its main file or on how the package manager lays out node_modules.
-export const packageDir = (name: string): string => dirname(require.resolve(`${name}/package.json`));
+// where the package keeps its main file or on how the package manager lays out node_modules. A package that does not export its
+// package.json (three does not) is found from its main file instead, by walking up to the folder that holds its own package.json.
+export const packageDir = (name: string): string => {
+  try {
+    return dirname(require.resolve(`${name}/package.json`));
+  } catch {
+    for (let dir = dirname(require.resolve(name)); dir !== dirname(dir); dir = dirname(dir)) {
+      const file = join(dir, "package.json");
+      if (existsSync(file) && (JSON.parse(readFileSync(file, "utf8")) as { name?: string }).name === name) return dir;
+    }
+    throw new Error(`Could not find the installed package ${name}.`);
+  }
+};

package/src/render/master.ts

@@ -0,0 +1,31 @@
+import { renameSync, rmSync } from "node:fs";
+import { loudnessLufs, tool } from "../project/refmeasure";
+import { measureLoudnorm } from "../project/loudness";
+
+// The loudness a finished video is brought to: -14 LUFS integrated, the level the big video platforms play at, with the loudest instant
+// kept under -1 dBTP so that re-encoding on upload cannot clip.
+export const MASTER_LUFS = -14;
+export const MASTER_TRUE_PEAK_DB = -1;
+
+export type Mastered = { inputLufs: number; outputLufs: number };
+// What a test may replace: the whole pass.
+export type Master = (path: string) => Promise<Mastered>;
+
+// Two-pass loudnorm: the first pass measures, the second applies exactly the gain that measurement asks for (linear, so the dynamics stay).
+// The video stream is copied untouched. The result replaces the file only when everything worked; otherwise the original stays as it was.
+export const masterLoudness: Master = async (path) => {
+  const first = await measureLoudnorm(path, { i: MASTER_LUFS, tp: MASTER_TRUE_PEAK_DB });
+  const inputLufs = Number(first?.input_i);
+  if (!first || !Number.isFinite(inputLufs)) throw new Error("the video has no sound to measure");
+  const out = path.replace(/(\.[^./]+)?$/, ".mastered$1");
+  const filter = `loudnorm=I=${MASTER_LUFS}:TP=${MASTER_TRUE_PEAK_DB}:LRA=11:measured_I=${first.input_i}:measured_TP=${first.input_tp}:measured_LRA=${first.input_lra}:measured_thresh=${first.input_thresh}:offset=${first.target_offset}:linear=true`;
+  try {
+    await tool("ffmpeg", ["-v", "error", "-y", "-i", path, "-c:v", "copy", "-af", filter, "-ar", "48000", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out]);
+    const outputLufs = await loudnessLufs(out);
+    if (outputLufs === undefined) throw new Error("the mastered file has no readable loudness");
+    renameSync(out, path);
+    return { inputLufs: Math.round(inputLufs * 10) / 10, outputLufs };
+  } finally {
+    rmSync(out, { force: true });
+  }
+};

package/src/render/render.ts

@@ -14,9 +14,10 @@ registerRoot(makeRoot(Video));
 `;
 
 // The project folder has no node_modules. Each dependency is pinned to the one copy installed with this package, so the
-// kit, Root and the user's composition all share a single react and remotion (a second react breaks hooks).
+// kit, Root and the user's composition all share a single react and remotion (a second react breaks hooks), and the 3D layer a single three
+// (two copies of three break instanceof checks). User code still may not import them: only the kit does.
 export function dependencyAliases(): Record<string, string> {
-  return Object.fromEntries(["react", "react-dom", "remotion"].map((n) => [n, packageDir(n)]));
+  return Object.fromEntries(["react", "react-dom", "remotion", "three", "@react-three/fiber", "@remotion/three"].map((n) => [n, packageDir(n)]));
 }
 
 // Writes the bundler's entry file into the project. The composition itself stays where the user's Claude wrote it.
@@ -57,18 +58,24 @@ export const ensureRenderBrowser: EnsureBrowser = async (onDownload) => {
   await ensureBrowser({ onBrowserDownload: () => { onDownload(); return { version: null, onProgress: () => {} }; } });
 };
 
+// Remotion's headless browser has no GPU, so three.js needs a software GL. "angle" is the setting that draws WebGL here; it is used only for a film that
+// has a 3D scene, so every 2D render keeps the browser's own defaults and looks exactly as before. This is the one place that says it.
+export const GL_BACKEND = "angle" as const;
+export type RenderOptions = { uses3D?: boolean };
+const chromium = (o?: RenderOptions) => (o?.uses3D ? { chromiumOptions: { gl: GL_BACKEND } } : {});
+
 const asInput = (props: VideoProps) => props as unknown as Record<string, unknown>;
 
-export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string) {
+export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string, options?: RenderOptions) {
   await mkdir(outDir, { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
+  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props), ...chromium(options) });
   for (const frame of frames) {
-    await renderStill({ composition, serveUrl, frame, output: join(outDir, `still-${frame}.png`), inputProps: asInput(props) });
+    await renderStill({ composition, serveUrl, frame, output: join(outDir, `still-${frame}.png`), inputProps: asInput(props), ...chromium(options) });
   }
 }
 
-export async function renderVideo(serveUrl: string, props: VideoProps, outPath: string) {
+export async function renderVideo(serveUrl: string, props: VideoProps, outPath: string, options?: RenderOptions) {
   await mkdir(dirname(outPath), { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
-  await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: outPath, inputProps: asInput(props) });
+  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props), ...chromium(options) });
+  await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: outPath, inputProps: asInput(props), ...chromium(options) });
 }

package/src/render/sound-notes.ts

@@ -0,0 +1,106 @@
+import ts from "typescript";
+import { sourceFile } from "./static-check";
+
+// Advice about the sound of a film with no voice, read from the composition's source. It is a count of what the code places, never a
+// listening test: a sound that is computed, looped over or hidden behind a variable cannot be counted, so then nothing is said.
+export type SoundCount = {
+  // Sfx elements and literal SoundCues entries.
+  placed: number;
+  // True when some cue is computed (a map, a helper, a variable that is not a plain list), so that the count is only a lower bound.
+  uncertain: boolean;
+  music: boolean;
+  // True when a cue or an effect is placed before this frame; `unknownStart` when one has a start that is not a plain number.
+  early: boolean;
+  unknownStart: boolean;
+};
+
+const numberOf = (e: ts.Expression | undefined): number | undefined => {
+  if (!e) return undefined;
+  if (ts.isNumericLiteral(e)) return Number(e.text);
+  if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(e.operand)) return -Number(e.operand.text);
+  if (ts.isParenthesizedExpression(e)) return numberOf(e.expression);
+  return undefined;
+};
+
+const insideLoop = (node: ts.Node): boolean => {
+  for (let p = node.parent; p; p = p.parent) {
+    if (ts.isCallExpression(p) && ts.isPropertyAccessExpression(p.expression) && ["map", "forEach", "flatMap"].includes(p.expression.name.text)) return true;
+  }
+  return false;
+};
+
+// The value of a prop, looking through a name that the file declares as a constant.
+function propValue(attr: ts.JsxAttribute, sf: ts.SourceFile): ts.Expression | undefined {
+  const init = attr.initializer;
+  if (!init || !ts.isJsxExpression(init) || !init.expression) return undefined;
+  const e = init.expression;
+  if (!ts.isIdentifier(e)) return e;
+  let found: ts.Expression | undefined;
+  const visit = (n: ts.Node) => {
+    if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === e.text && n.initializer && !found) found = n.initializer;
+    ts.forEachChild(n, visit);
+  };
+  visit(sf);
+  return found ?? e;
+}
+
+export function countSounds(source: string, file: string, earlyFrames: number): SoundCount {
+  const sf = sourceFile(source, file);
+  const out: SoundCount = { placed: 0, uncertain: false, music: false, early: false, unknownStart: false };
+  const attr = (el: ts.JsxOpeningLikeElement, name: string) => el.attributes.properties.find((a): a is ts.JsxAttribute => ts.isJsxAttribute(a) && a.name.getText(sf) === name);
+  const atOf = (e: ts.Expression | undefined, absent: number | undefined) => {
+    const n = e === undefined ? absent : numberOf(e);
+    if (n === undefined) out.unknownStart = true;
+    else if (n < earlyFrames) out.early = true;
+  };
+  const visit = (node: ts.Node) => {
+    const el = ts.isJsxSelfClosingElement(node) ? node : ts.isJsxElement(node) ? node.openingElement : undefined;
+    if (el) {
+      const tag = el.tagName.getText(sf);
+      if (tag === "Music") out.music = true;
+      if (tag === "Sfx") {
+        out.placed += 1;
+        if (insideLoop(el)) out.uncertain = true;
+        const at = attr(el, "at");
+        if (!at) out.early = true;
+        else {
+          const v = at.initializer && ts.isJsxExpression(at.initializer) ? at.initializer.expression : undefined;
+          atOf(v, undefined);
+        }
+      }
+      if (tag === "SoundCues") {
+        const cues = attr(el, "cues");
+        const value = cues && propValue(cues, sf);
+        if (!value || !ts.isArrayLiteralExpression(value) || value.elements.some((c) => !ts.isObjectLiteralExpression(c)) || insideLoop(el)) out.uncertain = true;
+        else {
+          out.placed += value.elements.length;
+          for (const c of value.elements as ts.NodeArray<ts.ObjectLiteralExpression>) {
+            const at = c.properties.find((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && p.name.getText(sf) === "at");
+            atOf(at?.initializer, undefined);
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
+}
+
+// The notes for a film with no voice. `seconds` is the film's length, `musicSet` whether a track was pulled with --music.
+export function soundNotes(sources: { name: string; source: string }[], opts: { seconds: number; fps: number; musicSet: boolean }): string[] {
+  const earlyFrames = Math.round(opts.fps / 2);
+  const counts = sources.map((s) => countSounds(s.source, s.name, earlyFrames));
+  const placed = counts.reduce((n, c) => n + c.placed, 0);
+  const uncertain = counts.some((c) => c.uncertain);
+  const notes: string[] = [];
+  if (!opts.musicSet) notes.push("No music track is set. A film with no voice is carried by its music: choose one and pull it with `reelkit assets pull <id> --music` (see reference/launch-film.md).");
+  if (!uncertain && placed < opts.seconds / 2) {
+    notes.push(`The code places ${placed} sound cue${placed === 1 ? "" : "s"} (Sfx elements and SoundCues entries) in ${opts.seconds.toFixed(1)}s of film, fewer than one per two seconds. This is a count of what the composition places, not a listening test; a film with no voice usually has about one placed effect per second on top of the music (see reference/launch-film.md).`);
+  }
+  const startsAtOnce = counts.some((c) => c.music || c.early);
+  if (!startsAtOnce && !uncertain && !counts.some((c) => c.unknownStart)) {
+    notes.push("Nothing is placed in the first half second: the code has no Music, and no Sfx or SoundCues cue that starts there. This is a count of what the composition places, not a listening test; start a sound on the first frame (see reference/launch-film.md).");
+  }
+  return notes;
+}

package/src/render/static-check.ts

@@ -0,0 +1,156 @@
+import ts from "typescript";
+
+// The check a component's source gets before it is used or shared: which modules it may import, which names it may not touch, and that
+// it exports what its file name says. Kept apart from the rest of validation because it needs nothing from this package's own folder
+// or from the machine: it is pure text in, problems out, so a server can bundle it.
+export const MAIN_FILE = "Video.tsx";
+export const FILE_NAME = /^[A-Z][A-Za-z0-9]*\.tsx$/;
+export const componentName = (file: string) => file.replace(/\.tsx$/, "");
+
+export const KIT = "reelkit/kit";
+const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
+
+// This check keeps honest compositions deterministic and self-contained. It is NOT a security boundary:
+// code in src/ runs on the user's machine when it is bundled and rendered, and anyone determined can get around a list of names.
+// It looks at the code (the TypeScript syntax tree), never at text, so words in on-screen copy, strings and comments are not flagged.
+// Only a reference to the global counts: `style.process`, `{ fetch: 1 }`, and a name the file declares itself (a component called
+// `Worker`, a parameter called `window`) are fine. Scope comes from the TypeScript binder, so a declaration only covers where it is in scope.
+const FORBIDDEN_NAMES: Record<string, string> = {
+  require: "require()", eval: "eval()", fetch: "fetch()",
+  process: "process", globalThis: "globalThis", window: "window", self: "self",
+  XMLHttpRequest: "XMLHttpRequest", WebSocket: "WebSocket", EventSource: "EventSource",
+  navigator: "navigator", localStorage: "localStorage", sessionStorage: "sessionStorage", indexedDB: "indexedDB",
+  Function: "Function", Worker: "Worker", SharedWorker: "SharedWorker", importScripts: "importScripts", child_process: "child_process",
+};
+
+export const sourceFile = (source: string, file = "Video.tsx") => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+// True when this identifier names a property, a label or a JSX attribute rather than referring to a variable.
+function isNamePosition(node: ts.Identifier): boolean {
+  const p = node.parent;
+  if (!p) return false;
+  if ((ts.isPropertyAccessExpression(p) || ts.isQualifiedName(p)) && (ts.isQualifiedName(p) ? p.right : p.name) === node) return true;
+  if ((ts.isPropertyAssignment(p) || ts.isPropertyDeclaration(p) || ts.isPropertySignature(p) || ts.isMethodDeclaration(p) || ts.isMethodSignature(p)
+    || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p) || ts.isEnumMember(p) || ts.isJsxAttribute(p)) && p.name === node) return true;
+  if (ts.isBindingElement(p) && p.propertyName === node) return true;
+  if ((ts.isImportSpecifier(p) || ts.isExportSpecifier(p)) && p.propertyName === node) return true;
+  if ((ts.isLabeledStatement(p) || ts.isBreakOrContinueStatement(p)) && p.label === node) return true;
+  return false;
+}
+
+// Looks through the wrappers that do not change what an expression is: (x), x as T, x!, x satisfies T, <T>x.
+export function unwrap(e: ts.Expression): ts.Expression {
+  while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
+  return e;
+}
+
+// A one-file program with no libraries: a name the file declares has a symbol with a declaration in it; a global has none.
+function declaredHere(sf: ts.SourceFile): (id: ts.Identifier) => boolean {
+  const host: ts.CompilerHost = {
+    getSourceFile: (name) => (name === sf.fileName ? sf : undefined),
+    getDefaultLibFileName: () => "lib.d.ts", writeFile: () => {}, getCurrentDirectory: () => "", getCanonicalFileName: (f) => f,
+    useCaseSensitiveFileNames: () => true, getNewLine: () => "\n", fileExists: (f) => f === sf.fileName, readFile: () => undefined, getDirectories: () => [],
+  };
+  const program = ts.createProgram([sf.fileName], { noLib: true, noResolve: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest }, host);
+  const checker = program.getTypeChecker();
+  return (id) => {
+    const p = id.parent;
+    const symbol = p && ts.isShorthandPropertyAssignment(p) && p.name === id ? checker.getShorthandAssignmentValueSymbol(p) : checker.getSymbolAtLocation(id);
+    return Boolean(symbol?.declarations?.some((d) => d.getSourceFile() === sf));
+  };
+}
+
+const textOf = (n: ts.Node | undefined) => (n && (ts.isStringLiteralLike(n)) ? n.text : undefined);
+
+type Finding = { specifiers: string[]; forbidden: string[] };
+
+function inspectSource(source: string, file?: string): Finding {
+  const specifiers: string[] = [];
+  const forbidden = new Set<string>();
+  const add = (s: string | undefined) => { if (s !== undefined) specifiers.push(s); };
+
+  const sf = sourceFile(source, file);
+  const declared = declaredHere(sf);
+  // True when the expression is the global with this name, not a variable the file declares.
+  const isGlobal = (e: ts.Expression | undefined, name: string) => {
+    const x = e && unwrap(e);
+    return Boolean(x && ts.isIdentifier(x) && x.text === name && !declared(x));
+  };
+  const flagMember = (object: ts.Expression | undefined, member: string | undefined) => {
+    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from remotion)");
+    if (isGlobal(object, "Date") && member === "now") forbidden.add("the clock (Date)");
+  };
+  // The key a destructuring element reads: `random` in `{ random }` and in `{ random: r }`, "random" in `{ ["random"]: r }`.
+  const keyOf = (name: ts.PropertyName | undefined) =>
+    name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : ts.isComputedPropertyName(name) ? textOf(name.expression) : undefined);
+
+  const visit = (node: ts.Node, inType: boolean) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(textOf(node.moduleSpecifier));
+    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(textOf(node.moduleReference.expression));
+    else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) add(textOf(node.argument.literal));
+    else if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) { forbidden.add("dynamic import()"); add(textOf(node.arguments[0])); }
+      else if (isGlobal(callee, "require")) add(textOf(node.arguments[0]));
+      else if (ts.isPropertyAccessExpression(callee) && isGlobal(callee.expression, "require")) add(textOf(node.arguments[0]));
+      if (isGlobal(callee, "Function")) forbidden.add("Function()");
+      if (isGlobal(callee, "Date")) forbidden.add("the clock (Date)");
+    } else if (ts.isNewExpression(node)) {
+      if (isGlobal(node.expression, "Function")) forbidden.add("new Function");
+      if (isGlobal(node.expression, "Date")) forbidden.add("the clock (Date)");
+    }
+
+    // Math.random and Date.now, also written Math["random"], (Math).random, or taken out by destructuring.
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      flagMember(node.expression, ts.isPropertyAccessExpression(node) ? node.name.text : textOf(node.argumentExpression));
+    } else if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
+      for (const el of node.name.elements) flagMember(node.initializer, keyOf(el.propertyName) ?? (ts.isIdentifier(el.name) ? el.name.text : undefined));
+    } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrap(node.left))) {
+      for (const prop of (unwrap(node.left) as ts.ObjectLiteralExpression).properties) {
+        if (ts.isShorthandPropertyAssignment(prop)) flagMember(node.right, prop.name.text);
+        else if (ts.isPropertyAssignment(prop)) flagMember(node.right, keyOf(prop.name));
+      }
+    }
+    if (!inType && ts.isIdentifier(node) && !isNamePosition(node) && Object.hasOwn(FORBIDDEN_NAMES, node.text) && !declared(node)) {
+      // A plain call or `new` of Function is already reported as Function() or new Function.
+      const p = node.parent;
+      const reported = node.text === "Function" && (ts.isCallExpression(p) || ts.isNewExpression(p)) && p.expression === node;
+      if (!reported) forbidden.add(FORBIDDEN_NAMES[node.text]);
+    }
+
+    const nextInType = inType || (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node));
+    ts.forEachChild(node, (c) => visit(c, nextInType));
+  };
+  visit(sf, false);
+  return { specifiers, forbidden: [...forbidden] };
+}
+
+// Every module a file pulls in: import and export declarations, import(), require() and require.x(), however they are spaced or commented.
+export function importSpecifiers(source: string): string[] {
+  return inspectSource(source).specifiers;
+}
+
+// Video.tsx may import sibling component files; a component must be self-contained so it can be reused on its own.
+export function staticCheck(source: string, file: string, siblings: string[]): string[] {
+  const errors: string[] = [];
+  const isMain = file === MAIN_FILE;
+  const allowedSiblings = new Set(isMain ? siblings.filter((s) => s !== MAIN_FILE).map((s) => `./${componentName(s)}`) : []);
+  const found = inspectSource(source, file);
+  for (const s of found.specifiers) {
+    if (BASE_IMPORTS.has(s) || allowedSiblings.has(s)) continue;
+    errors.push(
+      isMain
+        ? `${file}: import not allowed: "${s}". Use react, remotion, ${KIT}, or a component file that exists ("./Name").`
+        : `${file}: import not allowed: "${s}". A component may only import react, remotion and ${KIT}.`,
+    );
+  }
+  for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);
+  const exported = isMain ? "Video" : componentName(file);
+  const exportsIt = sourceFile(source, file).statements.some((s) =>
+    ts.isVariableStatement(s) && s.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    && s.declarationList.flags & ts.NodeFlags.Const && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === exported));
+  if (!exportsIt) errors.push(`${file} must contain \`export const ${exported}\`.`);
+  return errors;
+}
+
+// The project folder has no node_modules. These map its imports to the copies installed with this package.