reelkit-cli 0.4.0 → 0.6.0

package/src/remotion/kit/Sfx.tsx

@@ -1,11 +1,17 @@
 import React from "react";
-import { useMedia } from "./media";
+import { useGain, useMedia } from "./media";
 import { Audio, Sequence } from "remotion";
 
 // Plays one sound effect starting at a frame. at is counted from the start of the enclosing scene, or of the video
 // when placed outside the scenes. Keep volume well under the voiceover.
-export const Sfx: React.FC<{ src: string; at?: number; volume?: number }> = ({ src, at = 0, volume = 0.35 }) => (
-  <Sequence from={Math.max(0, Math.round(at))} layout="none">
-    <Audio src={useMedia(src)} volume={volume} />
-  </Sequence>
-);
+// A sound pulled from the library is levelled when it is pulled (the manifest's soundGain), and that is applied here by itself, so the same
+// volume sounds equally loud for every file: 0.2 to 0.45 is the range for an effect.
+export const Sfx: React.FC<{ src: string; at?: number; volume?: number }> = ({ src, at = 0, volume = 0.35 }) => {
+  const url = useMedia(src);
+  const gain = useGain(src);
+  return (
+    <Sequence from={Math.max(0, Math.round(at))} layout="none">
+      <Audio src={url} volume={volume * gain} />
+    </Sequence>
+  );
+};

package/src/remotion/kit/beat.ts

@@ -0,0 +1,23 @@
+// Helpers for putting things on the beat. `beatFrames` is manifest.music.beatFrames: composition frames, ascending.
+// Inside a scene, subtract the scene's startFrame to get a frame the scene's own useCurrentFrame() can use.
+
+// The beat nearest to `frame`, or undefined when the track has no beats.
+export function nearestBeat(beatFrames: number[], frame: number): number | undefined {
+  let best: number | undefined;
+  for (const b of beatFrames) if (best === undefined || Math.abs(b - frame) < Math.abs(best - frame)) best = b;
+  return best;
+}
+
+// The first beat at or after `frame`, or undefined when there is none.
+export function nextBeat(beatFrames: number[], frame: number): number | undefined {
+  return beatFrames.find((b) => b >= frame);
+}
+
+// 0 to 1: 1 on a beat, falling to 0 over `decayFrames` (default 10) after it, and 0 before the first beat.
+export function beatPulse(beatFrames: number[], frame: number, decayFrames = 10): number {
+  let last: number | undefined;
+  for (const b of beatFrames) { if (b <= frame) last = b; else break; }
+  if (last === undefined) return 0;
+  const x = (frame - last) / Math.max(1, decayFrames);
+  return x >= 1 ? 0 : (1 - x) * (1 - x);
+}

package/src/remotion/kit/caption-groups.ts

@@ -0,0 +1,65 @@
+import type { WordTiming } from "../../pipeline/schema";
+
+export type CaptionGroup = "none" | "word" | "phrase";
+
+export const MAX_GROUP_WORDS = 6;
+export const MAX_GROUP_CHARS = 32;
+// A pause between two words at least this long ends a group.
+export const PAUSE_SEC = 0.35;
+// A comma or a dash ends a group only when it already holds this many words.
+export const MIN_WORDS_AT_COMMA = 3;
+
+// Sentence ends in Latin, Hebrew and Arabic text: . ! ? … ؟ ۔ ׃ and the full-width forms, possibly followed by a closing quote or bracket.
+const SENTENCE_END = /[.!?…؟۔׃。！？]["'”’»)\]]*$/;
+const CLAUSE_END = /[,،，;؛:–—―-]["'”’»)\]]*$/;
+// A word that is only a dash.
+const LONE_DASH = /^[–—―-]+$/;
+// Small joining words: a line breaks better before one of them than after it.
+const JOINING = new Set(["and", "or", "but", "so", "to", "of", "in", "on", "at", "for", "with", "that", "the", "a", "an", "as", "if", "then", "from", "by", "into", "than", "nor", "yet", "who", "which", "when", "while",
+  "ו", "של", "על", "את", "עם", "או", "אבל", "כי", "אם", "כדי", "אל", "מן", "גם", "ש", "עד", "לא"]);
+
+const clean = (w: string) => w.trim();
+const endsSentence = (w: string) => SENTENCE_END.test(clean(w));
+const endsClause = (w: string) => CLAUSE_END.test(clean(w)) || LONE_DASH.test(clean(w));
+const isJoining = (w: string) => JOINING.has(clean(w).toLowerCase().replace(/[^\p{L}\p{N}]/gu, ""));
+const chars = (ws: WordTiming[]) => ws.reduce((n, w, i) => n + clean(w.word).length + (i ? 1 : 0), 0);
+const fits = (ws: WordTiming[]) => ws.length <= MAX_GROUP_WORDS && chars(ws) <= MAX_GROUP_CHARS;
+
+// Index ranges [start, end) into `words`, one per caption. "word": one word each. "phrase": grouped the way the words are spoken.
+export function captionGroups(words: WordTiming[], group: "word" | "phrase"): [number, number][] {
+  if (group === "word") return words.map((_, i) => [i, i + 1]);
+  const groups: [number, number][] = [];
+  let start = 0;
+  const gapAfter = (i: number) => (words[i + 1] ? words[i + 1]!.startSec - words[i]!.endSec : Infinity);
+  for (let i = 0; i < words.length; i++) {
+    const current = words.slice(start, i + 1);
+    if (!fits(current) && current.length > 1) {
+      // Too long: break before the new word, or a little earlier when that is after a comma or before a joining word.
+      let at = i;
+      for (let k = i - 1; k >= Math.max(start + 2, i - 2); k--) {
+        if (endsClause(words[k - 1]!.word) || isJoining(words[k]!.word)) { at = k; break; }
+      }
+      groups.push([start, at]);
+      start = at;
+    }
+    const size = i + 1 - start;
+    const ends = endsSentence(words[i]!.word) || (endsClause(words[i]!.word) && size >= MIN_WORDS_AT_COMMA) || gapAfter(i) >= PAUSE_SEC;
+    if (ends || i === words.length - 1) { groups.push([start, i + 1]); start = i + 1; }
+  }
+  // A lone word left at the end of a sentence reads better with the words before it, when they run on without a pause and it still fits.
+  const merged: [number, number][] = [];
+  for (const g of groups) {
+    const prev = merged[merged.length - 1];
+    if (prev && g[1] - g[0] === 1 && !endsSentence(words[prev[1] - 1]!.word) && words[g[0]]!.startSec - words[g[0] - 1]!.endSec < PAUSE_SEC && fits(words.slice(prev[0], g[1]))) prev[1] = g[1];
+    else merged.push([...g]);
+  }
+  return merged;
+}
+
+// The group whose words are on screen at `t` seconds: the one holding the last word that has started (the first group before any has).
+export function groupAt(words: WordTiming[], groups: [number, number][], t: number): { index: number; active: number } {
+  let active = 0;
+  for (let i = 0; i < words.length; i++) if (words[i]!.startSec <= t) active = i;
+  const index = Math.max(0, groups.findIndex(([a, b]) => active >= a && active < b));
+  return { index, active };
+}

package/src/remotion/kit/docs.ts

@@ -13,9 +13,10 @@ LowerThird { title: string; subtitle?: string; accent?: string }
   Name/label strip that slides in from the left, low on the screen.
   <LowerThird title="Step 1" subtitle="Connect your account" />
 
-Captions { words: WordTiming[]; mode?: "highlight" | "pop" | "karaoke"; highlight?: string; color?: string; perLine?: number; uppercase?: boolean; bottom?: number; face?: string; rtl?: boolean }
+Captions { words: WordTiming[]; mode?: "highlight" | "pop" | "karaoke"; highlight?: string; color?: string; perLine?: number; group?: "none" | "word" | "phrase"; uppercase?: boolean; bottom?: number; face?: string; rtl?: boolean }
   Word-timed captions near the bottom. Pass the scene's words from the manifest. Pick one mode for the whole video:
   "highlight" (a line, spoken word coloured), "pop" (1-3 words popping in as spoken), "karaoke" (a line filling with colour).
+  group decides which words share the screen: "word" is one word at a time, "phrase" groups words as they are spoken (a group ends at a sentence end, at a comma after three words, at a pause of 0.35 s, and never holds more than 6 words or about 32 characters), "none" draws nothing. Pass the plan's choice straight through: group={manifest.captions}. Without group, perLine counts the words as before.
   bottom is the distance from the bottom edge as a fraction of the height (default 0.16).
   For Hebrew narration pass face={font("heebo")} and rtl.
   <Captions words={s.words} mode="pop" highlight={palette.hero} uppercase />
@@ -58,6 +59,14 @@ WordReveal { text: string; delay?: number; per?: number; highlight?: string; hig
   Headline that rises in word by word from behind a mask. highlight colours one word.
   <WordReveal text="Stretch first, phone second" highlight="first" highlightColor={palette.hero} style={{ fontFamily: fonts.display, fontWeight: 800, fontSize: width * 0.09, color: palette.ink }} />
 
+Carry { keys: { frame: number; x: number; y: number; width: number; height: number; radius?: number; opacity?: number; rotate?: number }[]; lead?: number; stiffness?: number; damping?: number; children | (box) => children }
+  One element held through several scenes. Place it once, beside the SceneFrames and above them, so it is still on screen when a scene changes. Each key says where the box must have arrived by an absolute composition frame: x, y are its centre and width, height are fractions of the frame (0 to 1); radius is the corner radius as a fraction of the frame width; rotate is in degrees. The move toward a key starts lead frames before the key's frame (default 12, or at the previous key's frame when the keys are closer) on a spring (default springs.smooth) and lands on the key's frame exactly; between moves the box holds. Before the first key nothing is drawn unless that key sets an opacity; after the last the box holds. Children fill the box; a function child gets { x, y, width, height, radius, opacity, rotate, widthPx, heightPx } for the current moment, so the content can change as the box does.
+  <Carry keys={[{ frame: a.startFrame + 6, x: 0.5, y: 0.45, width: 0.8, height: 0.3 }, { frame: b.startFrame, x: 0.5, y: 0.5, width: 1, height: 1, radius: 0 }]}>{(box) => <Card compact={box.width < 0.5} />}</Carry>
+
+Camera { keys: { frame: number; x?: number; y?: number; zoom?: number; rotate?: number }[]; drift?: number; lead?: number; stiffness?: number; damping?: number; children }
+  Moves the whole picture. Wrap all the scenes for one camera that never cuts, or wrap one scene's content. x, y are the point of the content, as fractions, that sits at the middle of the frame (default 0.5, 0.5); zoom 1 shows the content as it fits; rotate is in degrees. A key that leaves a value out keeps the one before it. The timing rule is the same as Carry's: the move toward a key starts lead frames before its frame and lands on it. drift is a very slow continuous push, as a fraction of the zoom per second (0.02 is two percent a second), so a held shot is never perfectly still.
+  <Camera keys={[{ frame: 0, zoom: 1 }, { frame: b.startFrame, x: 0.7, y: 0.4, zoom: 4 }]} drift={0.01}>{scenes}</Camera>
+
 fonts { display: string; body: string }
   Loaded font families. Use fonts.display (weights 600-800) for headlines and numbers, fonts.body for supporting text. Never leave hero text on a default font.
 
@@ -98,8 +107,17 @@ ScreenOverlay { src: string; durationSec?: number; opacity?: number }
 
 Sfx { src: string; at?: number; volume?: number }
   Plays one sound effect from the shared library, starting at the frame given by "at", counted from the start of the enclosing scene. Pull one with: reelkit assets search "<description>" --kind sfx, then reelkit assets pull <id>.
+  A pulled sound is levelled when it is pulled (the manifest's soundGain), and Sfx and Music apply that by themselves: the same volume sounds equally loud for every file. Nothing to pass.
   <Sfx src={urls["assets/lib/<id>/clip.mp3"]} at={10} volume={0.35} />
 
+Music { src: string; volume?: number; duckTo?: number }
+  The video's one music track (pull it with: reelkit assets pull <id> --music). Place it once, outside the scenes. It sits at duckTo (default 0.12) while the voiceover is heard and comes up to volume (default 0.5) in gaps longer than 0.6 s, loops if the video is longer than the track, and fades out over the last second. It follows the manifest, so nothing else is passed.
+  <Music src={urls[manifest.music.key]} />
+
+nearestBeat(beatFrames, frame): number | undefined    nextBeat(beatFrames, frame): number | undefined    beatPulse(beatFrames, frame, decayFrames = 10): number
+  Beat helpers; beatFrames is manifest.music.beatFrames (composition frames). nearestBeat is the closest beat, nextBeat the first at or after the frame, beatPulse a number from 0 to 1 that is 1 on a beat and falls to 0 after it. Inside a scene, subtract s.startFrame from a beat to get a frame for that scene's own clock.
+  const b = nextBeat(manifest.music?.beatFrames ?? [], s.startFrame + 20) ?? s.startFrame + 20;  // <Entrance delay={b - s.startFrame}>
+
 Voiceover { src: string; volume?: number }
   The scene's narration audio. One per narrated scene, inside its SceneFrame. Guard it with s.voiceoverKey so a scene without a recording still renders.
   {s.voiceoverKey ? <Voiceover src={urls[s.voiceoverKey]} /> : null}

package/src/remotion/kit/index.ts

@@ -1,4 +1,7 @@
+export { Camera } from "./Camera";
 export { Captions } from "./Captions";
+export { Carry } from "./Carry";
+export type { CarryBox } from "./Carry";
 export { ClipLayer } from "./ClipLayer";
 export { Counter } from "./Counter";
 export { Entrance, WordReveal } from "./Entrance";
@@ -13,10 +16,14 @@ export { LowerThird } from "./LowerThird";
 export { SceneFrame } from "./SceneFrame";
 export { ScreenOverlay } from "./ScreenOverlay";
 export { useMedia } from "./media";
+export { Music } from "./Music";
+export { beatPulse, nearestBeat, nextBeat } from "./beat";
 export { Sfx } from "./Sfx";
 export { TitleCard } from "./TitleCard";
 export { Voiceover } from "./Voiceover";
 export type { VideoProps } from "../types";
 export { ease, font, fonts, palettes, springs } from "./theme";
 export type { CaptionMode } from "./Captions";
+export type { CaptionGroup } from "./caption-groups";
+export type { BoxKey, CameraKey } from "./motion-math";
 export type { KitFont, Palette } from "./theme";

package/src/remotion/kit/media.ts

@@ -1,10 +1,27 @@
 import { createContext, useContext } from "react";
+import type { AssetManifest } from "../../pipeline/schema";
 
 // The project's media links, keyed by project path (assets/...). Root provides them, so a kit component works whether it is
 // given a link (urls[key]) or just the project path (key).
 export const UrlsContext = createContext<Record<string, string>>({});
+// The manifest of the video being made, provided by Root, so Music can duck under the voice and Sfx and Music can be levelled without being told.
+export const ManifestContext = createContext<AssetManifest | undefined>(undefined);
 
 export function useMedia(src: string): string {
   const urls = useContext(UrlsContext);
   return urls[src] ?? src;
 }
+
+export const useManifest = () => useContext(ManifestContext);
+
+// The linear gain that levels a sound, from the manifest's soundGain. The sound may be named by its project path or by its link.
+export function gainFor(gains: Record<string, number> | undefined, urls: Record<string, string>, src: string): number {
+  if (!gains) return 1;
+  if (gains[src] !== undefined) return gains[src]!;
+  const path = Object.keys(gains).find((k) => urls[k] === src);
+  return path ? gains[path]! : 1;
+}
+
+export function useGain(src: string): number {
+  return gainFor(useContext(ManifestContext)?.soundGain, useContext(UrlsContext), src);
+}

package/src/remotion/kit/motion-math.ts

@@ -0,0 +1,113 @@
+// The arithmetic behind Carry and Camera, with no React in it, so that it can be tested without rendering.
+// Everything here is a pure function of the frame: the same frame always gives the same picture, which a renderer needs
+// because it draws frames out of order and in parallel.
+import { springs } from "./theme";
+
+// How many frames before a key's frame the move toward it begins.
+export const DEFAULT_LEAD = 12;
+
+export type SpringConfig = { stiffness: number; damping: number };
+
+// The unit step response of a mass-spring-damper with mass 1, at `seconds` after the push.
+function step({ stiffness, damping }: SpringConfig, seconds: number): number {
+  const k = Math.max(1e-6, stiffness);
+  const w = Math.sqrt(k);
+  const z = Math.max(0, damping) / (2 * w);
+  if (z < 1) {
+    const wd = w * Math.sqrt(1 - z * z);
+    return 1 - Math.exp(-z * w * seconds) * (Math.cos(wd * seconds) + ((z * w) / wd) * Math.sin(wd * seconds));
+  }
+  if (z === 1) return 1 - (1 + w * seconds) * Math.exp(-w * seconds);
+  const root = Math.sqrt(z * z - 1);
+  const r1 = -w * (z - root), r2 = -w * (z + root);
+  return 1 - (r2 * Math.exp(r1 * seconds) - r1 * Math.exp(r2 * seconds)) / (r2 - r1);
+}
+
+// How far a move has got, from 0 to 1, when t (0..1) of its time has passed. The move lasts `frames` frames and follows a spring,
+// then a small correction, shaped like a smoothstep, closes the little that a real spring still has left at that moment, so that a
+// move always arrives on its frame exactly and does not jump when it does.
+export function travel(t: number, fps: number, config: SpringConfig = springs.smooth, frames = DEFAULT_LEAD): number {
+  if (!(t > 0)) return 0;
+  if (t >= 1) return 1;
+  const left = 1 - step(config, frames / fps);
+  return step(config, (t * frames) / fps) + left * (3 * t * t - 2 * t * t * t);
+}
+
+// Orders keys by frame. A key that shares its frame with another keeps its place in the list, so the later one wins.
+export const sortKeys = <K extends { frame: number }>(keys: readonly K[]): K[] => [...keys].sort((a, b) => a.frame - b.frame);
+
+type Timing = { lead?: number; stiffness?: number; damping?: number };
+const springOf = (o: Timing): SpringConfig => ({ stiffness: o.stiffness ?? springs.smooth.stiffness, damping: o.damping ?? springs.smooth.damping });
+
+// Where a value stands at `frame` among sorted keys. The move toward key N starts `lead` frames before key N's frame (or at key N-1's
+// frame when they are closer than that) and ends on key N's frame; before and after a move the value holds. It returns the two keys
+// the frame is between and how far along the move is (from === to when it is holding).
+function locate<K extends { frame: number }>(sorted: K[], frame: number, fps: number, o: Timing): { from: K; to: K; p: number } {
+  const lead = Math.max(1, o.lead ?? DEFAULT_LEAD);
+  let from = sorted[0]!;
+  for (let j = 1; j < sorted.length; j++) {
+    const to = sorted[j]!;
+    if (frame >= to.frame) { from = to; continue; }
+    const start = Math.max(to.frame - lead, from.frame);
+    if (frame < start) return { from, to: from, p: 0 };
+    return { from, to, p: travel((frame - start) / (to.frame - start), fps, springOf(o), to.frame - start) };
+  }
+  return { from, to: from, p: 0 };
+}
+
+const mix = (a: number, b: number, p: number) => a + (b - a) * p;
+
+export type BoxKey = { frame: number; x: number; y: number; width: number; height: number; radius?: number; opacity?: number; rotate?: number };
+export type Box = { x: number; y: number; width: number; height: number; radius: number; opacity: number; rotate: number };
+
+const fullBox = (k: BoxKey): Box => ({ x: k.x, y: k.y, width: k.width, height: k.height, radius: k.radius ?? 0, opacity: k.opacity ?? 1, rotate: k.rotate ?? 0 });
+
+// The box of a Carry at `frame`, or null when nothing should be drawn: before the first key the box is not there, unless that key
+// sets an opacity, which says it is there from the start.
+export function boxAt(keys: readonly BoxKey[], frame: number, fps: number, timing: Timing = {}): Box | null {
+  if (!keys.length) return null;
+  const sorted = sortKeys(keys);
+  const first = sorted[0]!;
+  if (frame < first.frame) return first.opacity === undefined ? null : fullBox(first);
+  const { from, to, p } = locate(sorted, frame, fps, timing);
+  const a = fullBox(from), b = fullBox(to);
+  // A spring can overshoot; a size below nothing or an opacity outside 0..1 would be nonsense, so they are held to their range.
+  return {
+    x: mix(a.x, b.x, p), y: mix(a.y, b.y, p), width: Math.max(0, mix(a.width, b.width, p)), height: Math.max(0, mix(a.height, b.height, p)),
+    radius: Math.max(0, mix(a.radius, b.radius, p)), opacity: Math.min(1, Math.max(0, mix(a.opacity, b.opacity, p))), rotate: mix(a.rotate, b.rotate, p),
+  };
+}
+
+export type CameraKey = { frame: number; x?: number; y?: number; zoom?: number; rotate?: number };
+export type CameraView = { x: number; y: number; zoom: number; rotate: number };
+
+// A key that leaves a value out keeps the one before it; the first key starts from the centre, at zoom 1, level.
+export function resolveCameraKeys(keys: readonly CameraKey[]): (CameraView & { frame: number })[] {
+  let last: CameraView = { x: 0.5, y: 0.5, zoom: 1, rotate: 0 };
+  return sortKeys(keys).map((k) => {
+    last = { x: k.x ?? last.x, y: k.y ?? last.y, zoom: k.zoom ?? last.zoom, rotate: k.rotate ?? last.rotate };
+    return { frame: k.frame, ...last };
+  });
+}
+
+// The camera at `frame`. drift is a slow push on top of the keys, as a fraction of the zoom per second, counted from frame 0, so that
+// a shot that is held is never perfectly still.
+export function cameraAt(keys: readonly CameraKey[], frame: number, fps: number, o: Timing & { drift?: number } = {}): CameraView {
+  const resolved = resolveCameraKeys(keys);
+  if (!resolved.length) return { x: 0.5, y: 0.5, zoom: 1 * (1 + (o.drift ?? 0) * Math.max(0, frame) / fps), rotate: 0 };
+  const { from, to, p } = locate(resolved, frame, fps, o);
+  return {
+    x: mix(from.x, to.x, p), y: mix(from.y, to.y, p), rotate: mix(from.rotate, to.rotate, p),
+    zoom: Math.max(0.01, mix(from.zoom, to.zoom, p)) * (1 + (o.drift ?? 0) * (Math.max(0, frame) / fps)),
+  };
+}
+
+const px = (n: number) => `${Math.round(n * 1000) / 1000}px`;
+
+// The CSS that puts the point (x, y) of the content in the middle of a frame of w by h pixels, scaled and turned about that point.
+export function cameraTransform(c: CameraView, w: number, h: number): { origin: string; transform: string } {
+  return {
+    origin: `${Math.round(c.x * 10000) / 100}% ${Math.round(c.y * 10000) / 100}%`,
+    transform: `translate(${px((0.5 - c.x) * w)}, ${px((0.5 - c.y) * h)}) rotate(${Math.round(c.rotate * 1000) / 1000}deg) scale(${Math.round(c.zoom * 10000) / 10000})`,
+  };
+}

package/src/remotion/kit/music-math.ts

@@ -0,0 +1,42 @@
+import type { WordTiming } from "../../pipeline/schema";
+
+export const DUCK_PAD_SEC = 0.25;
+export const DUCK_RAMP_SEC = 0.2;
+// A gap between words at least this long lets the music come back up; a shorter one keeps it down so it does not pump.
+export const DUCK_GAP_SEC = 0.6;
+export const FADE_OUT_SEC = 1;
+
+export type SpeechScene = { startFrame: number; words: WordTiming[] };
+
+// The stretches of the video, in seconds, during which a voice is heard (with the padding around each word); words closer than
+// DUCK_GAP_SEC are one stretch.
+export function speechSpans(scenes: SpeechScene[], fps: number): [number, number][] {
+  const words = scenes.flatMap((s) => s.words.map((w) => [s.startFrame / fps + w.startSec, s.startFrame / fps + w.endSec] as const)).sort((a, b) => a[0] - b[0]);
+  const spans: [number, number][] = [];
+  for (const [start, end] of words) {
+    const last = spans[spans.length - 1];
+    if (last && start - (last[1] - DUCK_PAD_SEC) <= DUCK_GAP_SEC) last[1] = Math.max(last[1], end + DUCK_PAD_SEC);
+    else spans.push([start - DUCK_PAD_SEC, end + DUCK_PAD_SEC]);
+  }
+  return spans;
+}
+
+// How far down the music is at `t` seconds, 0 (not at all) to 1 (fully): full inside a stretch, ramping over DUCK_RAMP_SEC just outside its edges.
+function duckAmount(spans: [number, number][], t: number): number {
+  let amount = 0;
+  for (const [a, b] of spans) {
+    const edge = Math.min((t - a) / DUCK_RAMP_SEC + 1, (b - t) / DUCK_RAMP_SEC + 1);
+    amount = Math.max(amount, Math.max(0, Math.min(1, edge)));
+  }
+  return amount;
+}
+
+// The music's volume at a composition frame: `volume` in gaps, `duckTo` under a voice, and a fade to nothing over the last second.
+// `gain` is the track's levelling (linear). Looping needs no handling here: the frame is the composition's, not the track's.
+export function musicVolume(frame: number, o: { fps: number; totalFrames: number; volume: number; duckTo: number; spans: [number, number][]; gain?: number }): number {
+  const t = frame / o.fps;
+  const duck = duckAmount(o.spans, t);
+  const base = o.volume + (Math.min(o.duckTo, o.volume) - o.volume) * duck;
+  const fade = Math.max(0, Math.min(1, (o.totalFrames - frame) / (FADE_OUT_SEC * o.fps)));
+  return base * fade * (o.gain ?? 1);
+}

package/src/render/continuity.ts

@@ -0,0 +1,87 @@
+// Did anything on screen survive a scene change? The two frames on either side of a change are reduced to a small grey picture, an edge
+// map is made of each (a smooth background has almost no edges, content has many), and the share of the earlier frame's edges that are
+// still there in the later one says whether something was carried across. Everything here works on plain pixel arrays.
+export const SAMPLE_WIDTH = 128;
+const EDGE_THRESHOLD = 16;
+// An element that moves a little between the two frames still counts as the same one, so each edge is widened by this many pixels.
+const DILATE_RADIUS = 3;
+export const CARRIED_AT = 0.25;
+// Below this share of the frame being edges there is nothing to carry.
+const MIN_EDGE_SHARE = 0.002;
+
+export type Gray = ArrayLike<number>;
+export type BoundaryKind = "carried" | "cut" | "empty";
+
+// 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 {
+  const out = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = y * w + x;
+      const gx = x + 1 < w ? Math.abs(gray[i + 1]! - gray[i]!) : 0;
+      const gy = y + 1 < h ? Math.abs(gray[i + w]! - gray[i]!) : 0;
+      if (gx + gy > threshold) out[i] = 1;
+    }
+  }
+  return out;
+}
+
+// The share of the frame's height, from the bottom, where the kit's captions can sit. Captions default to a baseline 16% up, and
+// their lines are as tall as 0.075 of the width at most, so the strip covers the baseline, two lines and some room, and never more than
+// 40% of the frame, which a wide frame would otherwise reach.
+export function captionBand(w: number, h: number): number {
+  return Math.min(0.4, 0.16 + 2 * 0.075 * 1.15 * (w / h) + 0.03);
+}
+
+const clearBottom = (map: Uint8Array, w: number, h: number, share: number) => {
+  map.fill(0, Math.floor(h * (1 - share)) * w);
+  return map;
+};
+
+export function dilate(map: Uint8Array, w: number, h: number, radius: number): Uint8Array {
+  // Two passes, along the rows and then down the columns, give the square neighbourhood without visiting all of it for each pixel.
+  const rows = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (!map[y * w + x]) continue;
+      for (let k = Math.max(0, x - radius); k <= Math.min(w - 1, x + radius); k++) rows[y * w + k] = 1;
+    }
+  }
+  const out = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (!rows[y * w + x]) continue;
+      for (let k = Math.max(0, y - radius); k <= Math.min(h - 1, y + radius); k++) out[k * w + x] = 1;
+    }
+  }
+  return out;
+}
+
+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);
+  const after = dilate(clearBottom(edgeMap(later, w, h), w, h, band), w, h, DILATE_RADIUS);
+  let edges = 0, kept = 0;
+  for (let i = 0; i < before.length; i++) if (before[i]) { edges++; if (after[i]) kept++; }
+  if (edges < MIN_EDGE_SHARE * w * Math.floor(h * (1 - band))) return { survived: 0, edges, kind: "empty" };
+  const survived = kept / edges;
+  return { survived, edges, kind: survived >= CARRIED_AT ? "carried" : "cut" };
+}
+
+export type Boundary = { from: string; to: string; survived: number; kind: BoundaryKind };
+
+// 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 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."] };
+  return {
+    score: carried / counted,
+    lines: [
+      `${carried} of ${counted} scene changes carry something across${empty ? ` (${empty} more had nothing on screen to compare)` : ""}.`,
+      ...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/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 });
+  }
+};