reelkit-cli 0.5.0 → 0.8.0

package/src/remotion/kit/SoundCues.tsx

@@ -0,0 +1,22 @@
+import React, { useContext } from "react";
+import { Audio, Sequence } from "remotion";
+import { gainFor, ManifestContext, UrlsContext } from "./media";
+import { resolveCues, type SoundCue } from "./sound-cues";
+
+// Plays many sound effects from one place: a list of cues, each a frame of the whole video and a name from `sounds`. Place it once, outside
+// the scenes, when a video is scored with sound (a video with no voice has dozens of cues). Like Sfx it applies the manifest's levelling gain,
+// so the same volume is equally loud for every file. A cue without a volume plays at 0.35.
+export const SoundCues: React.FC<{ cues: SoundCue[]; sounds: Record<string, string>; volume?: number }> = ({ cues, sounds, volume = 1 }) => {
+  const urls = useContext(UrlsContext);
+  const gains = useContext(ManifestContext)?.soundGain;
+  const plan = React.useMemo(() => resolveCues({ cues, sounds, volume, urls, gainFor: (src) => gainFor(gains, urls, src) }), [cues, sounds, volume, urls, gains]);
+  return (
+    <>
+      {plan.map((c, i) => (
+        <Sequence key={`${c.from}-${i}`} from={c.from} layout="none">
+          <Audio src={c.src} volume={c.volume} />
+        </Sequence>
+      ))}
+    </>
+  );
+};

package/src/remotion/kit/TerminalLog.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { Place } from "./Place";
+import { font as loadFont, fonts, springs } from "./theme";
+import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
+import { clock, terminalFrames, type TerminalLine } from "./ui-math";
+
+// A terminal or agent window: a title bar, lines that stream in (`cmd` a typed command, `out` plain output, `ok` a success, `warn` a warning, `edit` a file
+// changed with `add` and `del` counts), an optional checklist whose items get struck through, and a status line with an elapsed counter that turns to
+// "Done" at the end. `rate` is lines a second (default 3); the window shows the last `maxLines` (default 8) and the newest is at the bottom. Times are frames
+// from the component's own mount; terminalFrames(props, fps) gives each line's frame and each tick's for sound. Text is monospace (jetbrainsMono) unless
+// `font` is given. `width` is a fraction of the frame (0.86); `theme` "dark" (default), "light" or "glass".
+export const TerminalLog: React.FC<{
+  lines: TerminalLine[];
+  rate?: number;
+  title?: string;
+  status?: string;
+  checklist?: string[];
+  checkEvery?: number;
+  maxLines?: number;
+  speed?: number;
+  hero?: string;
+  theme?: UiTheme;
+  font?: string;
+  width?: number;
+  delay?: number;
+  y?: number;
+}> = ({ lines, rate = 3, title = "agent", status = "Working", checklist = [], checkEvery, maxLines = 8, speed = 8, hero = DEFAULT_HERO, theme = "dark", font, width: fraction = 0.86, delay = 6, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W } = useVideoConfig();
+  const c = uiColors(theme, hero);
+  const P = W * fraction;
+  const mono = font ?? loadFont("jetbrainsMono");
+  const ev = terminalFrames({ lines, rate, delay, checklist, checkEvery }, fps);
+  const shown = lines.map((_, i) => i).filter((i) => ev.lines[i]! <= frame);
+  const visible = shown.slice(-maxLines);
+  const fs = P * 0.034, row = fs * 1.62;
+  const enter = spring({ frame, fps, config: springs.smooth });
+  const done = frame >= ev.done;
+  const seconds = Math.max(0, ((done ? ev.done : frame) - delay) / fps * speed);
+  const spin = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][Math.floor(frame / 2) % 10];
+  const colorOf = (k: TerminalLine["kind"]) => (k === "cmd" ? c.ink : k === "ok" ? c.ok : k === "warn" ? c.warn : k === "edit" ? c.ink : c.dim);
+  return (
+    <Place y={y}>
+      <div style={{ width: P, opacity: enter, transform: `translateY(${(1 - enter) * P * 0.04}px)`, fontFamily: mono }}>
+        <div style={{ background: c.panel, border: `${Math.max(2, P * 0.0025)}px solid ${c.stroke}`, borderRadius: P * 0.04, overflow: "hidden", boxShadow: `0 ${P * 0.03}px ${P * 0.08}px ${c.shadow}` }}>
+          <div style={{ display: "flex", alignItems: "center", gap: P * 0.018, padding: `${P * 0.032}px ${P * 0.04}px`, background: c.field, borderBottom: `1px solid ${c.stroke}` }}>
+            {["#ff5f57", "#febc2e", "#28c840"].map((d) => <div key={d} style={{ width: P * 0.03, height: P * 0.03, borderRadius: 999, background: d }} />)}
+            <div style={{ flex: 1, textAlign: "center", fontSize: fs * 0.9, color: c.dim, fontFamily: font ?? fonts.body, fontWeight: 600, marginRight: P * 0.1 }}>{title}</div>
+          </div>
+          <div style={{ padding: `${P * 0.04}px ${P * 0.045}px`, height: row * maxLines + P * 0.08, display: "flex", flexDirection: "column", justifyContent: "flex-end" }}>
+            {visible.map((i) => {
+              const l = lines[i]!, age = frame - ev.lines[i]!;
+              const o = interpolate(age, [0, 5], [0, 1], { extrapolateRight: "clamp" });
+              const mark = l.kind === "cmd" ? "$" : l.kind === "ok" ? "✓" : l.kind === "warn" ? "!" : l.kind === "edit" ? "✎" : " ";
+              return (
+                <div key={i} style={{ display: "flex", gap: fs * 0.7, height: row, alignItems: "center", fontSize: fs, color: colorOf(l.kind), opacity: o, transform: `translateY(${(1 - o) * fs * 0.4}px)`, whiteSpace: "nowrap" }}>
+                  <span style={{ width: fs * 0.9, color: l.kind === "cmd" ? hero : colorOf(l.kind), fontWeight: 700, flex: "none" }}>{mark}</span>
+                  <span style={{ overflow: "hidden", textOverflow: "ellipsis", flex: 1, fontWeight: l.kind === "cmd" ? 700 : 400 }}>{l.text}</span>
+                  {l.kind === "edit" ? (
+                    <span style={{ flex: "none", fontWeight: 700 }}>
+                      {l.add !== undefined ? <span style={{ color: c.ok }}>+{l.add} </span> : null}
+                      {l.del !== undefined ? <span style={{ color: c.bad }}>-{l.del}</span> : null}
+                    </span>
+                  ) : null}
+                </div>
+              );
+            })}
+          </div>
+          {checklist.length ? (
+            <div style={{ padding: `${P * 0.03}px ${P * 0.045}px`, borderTop: `1px solid ${c.stroke}`, display: "flex", flexDirection: "column", gap: P * 0.012 }}>
+              {checklist.map((item, i) => {
+                const at = ev.checks[i]!, k = interpolate(frame, [at, at + 6], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+                return (
+                  <div key={i} style={{ display: "flex", alignItems: "center", gap: fs * 0.7, fontSize: fs, color: k > 0.5 ? c.dim : c.ink }}>
+                    <div style={{ width: fs, height: fs, borderRadius: fs * 0.25, border: `2px solid ${k > 0 ? hero : c.dim}`, background: k > 0.5 ? hero : "transparent", display: "flex", alignItems: "center", justifyContent: "center", flex: "none" }}>
+                      {k > 0.5 ? <svg width={fs * 0.7} height={fs * 0.7} viewBox="0 0 24 24" fill="none" stroke={c.heroInk} strokeWidth="4" strokeLinecap="round" strokeLinejoin="round"><path d="M4 12l5 5L20 6" /></svg> : null}
+                    </div>
+                    <span style={{ position: "relative", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+                      {item}
+                      <span style={{ position: "absolute", left: 0, top: "52%", height: Math.max(2, fs * 0.08), width: `${k * 100}%`, background: c.dim }} />
+                    </span>
+                  </div>
+                );
+              })}
+            </div>
+          ) : null}
+          <div style={{ display: "flex", alignItems: "center", gap: fs * 0.6, padding: `${P * 0.03}px ${P * 0.045}px`, background: c.field, borderTop: `1px solid ${c.stroke}`, fontSize: fs * 0.92, color: done ? c.ok : hero, fontWeight: 700 }}>
+            <span style={{ width: fs, textAlign: "center" }}>{done ? "✓" : spin}</span>
+            <span>{done ? "Done" : `${status}...`}</span>
+            <span style={{ marginLeft: "auto", color: c.dim, fontWeight: 400 }}>{clock(seconds)}</span>
+          </div>
+        </div>
+      </div>
+      <div style={{ position: "absolute", inset: 0, pointerEvents: "none", boxShadow: `inset 0 0 0 0 ${rgba(hero, 0)}` }} />
+    </Place>
+  );
+};

package/src/remotion/kit/Text3D.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { FontLoader } from "three/examples/jsm/loaders/FontLoader.js";
+import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";
+import { interBoldTypeface } from "./inter-bold-typeface";
+import { CameraKeysContext } from "./scene3d-context";
+import { degToRad, entranceAt, fitTextSize, nearestVisible, type Entrance3D, type Vec3 } from "./three-math";
+
+// The one bundled typeface, parsed once. It holds Latin letters, digits and common punctuation only.
+let font: ReturnType<FontLoader["parse"]> | undefined;
+export const typeface = () => (font ??= new FontLoader().parse(interBoldTypeface as never));
+
+// The shape of Text3D's geometry for a given size, one place so that measuring and drawing cannot disagree.
+const build = (text: string, size: number, extrude: number): TextGeometry => {
+  const g = new TextGeometry(text, {
+    font: typeface(), size, depth: extrude, curveSegments: 6,
+    bevelEnabled: true, bevelThickness: size * 0.02, bevelSize: size * 0.015, bevelSegments: 2,
+  });
+  g.computeBoundingBox();
+  return g;
+};
+
+// How wide and tall a text is at size 1, measured on the typeface's own glyphs (a line break starts a new line). The geometry scales with size, so
+// this is the width at any size divided by that size.
+const measured = new Map<string, { width: number; height: number }>();
+export function measureText(text: string): { width: number; height: number } {
+  let m = measured.get(text);
+  if (!m) {
+    const g = build(text, 1, 0.25), b = g.boundingBox!;
+    m = { width: b.max.x - b.min.x, height: b.max.y - b.min.y };
+    g.dispose();
+    measured.set(text, m);
+  }
+  return m;
+}
+
+// Extruded text with depth, lit by the scene's lights. Place it inside a Scene3D. Latin text only: the bundled typeface has no Hebrew, Arabic or other
+// scripts, so those stay 2D. Leave `size` out: the word is then sized from its own measured width so that it fills `fit` of the frame's width (default
+// 0.8) at the closest the Scene3D's camera comes to it, which is the widest it ever has to be and whole at every moment; a line break (\n) makes a
+// second line, and the height is held to `fit` of the frame's height too. A `size` you give wins (the height of a capital-ish line in scene units; at z 6
+// the camera sees about 3.1 units across on 9:16 and 10 on 16:9, see Scene3D). `depth` is how far it is extruded (default 0.25 of the size), `rotation`
+// is in degrees, and `enter` is how it arrives: "rise" (up from below), "turn" (a quarter turn in), "fly" (from far away toward the camera) or "none",
+// starting `delay` frames into the scene. Face it at the camera when it must be read: keep its rotation near 0 and the camera in front of it, and hold
+// it at least a second and a half.
+export const Text3D: React.FC<{
+  text: string;
+  size?: number;
+  fit?: number;
+  depth?: number;
+  color?: string;
+  position?: Vec3;
+  rotation?: Vec3;
+  enter?: Entrance3D;
+  delay?: number;
+}> = ({ text, size: given, fit = 0.8, depth, color = "#ffffff", position = [0, 0, 0], rotation = [0, 0, 0], enter = "none", delay = 0 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const size = given ?? fitTextSize(measureText(text), nearestVisible(keys, width / height, position[2]), fit);
+  const extrude = depth ?? size * 0.25;
+  const geometry = React.useMemo(() => {
+    const g = build(text, size, extrude);
+    const b = g.boundingBox!;
+    // Centred on its own middle, so that position places the middle of the word.
+    g.translate(-(b.max.x + b.min.x) / 2, -(b.max.y + b.min.y) / 2, -extrude / 2);
+    return g;
+  }, [text, size, extrude]);
+  React.useEffect(() => () => geometry.dispose(), [geometry]);
+  const e = entranceAt(enter, frame, delay, fps, size);
+  if (e.opacity <= 0) return null;
+  return (
+    <group position={[position[0] + e.offset[0], position[1] + e.offset[1], position[2] + e.offset[2]]} rotation={[degToRad(rotation[0]) + e.rotation[0], degToRad(rotation[1]) + e.rotation[1], degToRad(rotation[2]) + e.rotation[2]]} scale={e.scale}>
+      <mesh geometry={geometry}>
+        <meshStandardMaterial color={color} roughness={0.35} metalness={0.1} transparent={e.opacity < 1} opacity={e.opacity} />
+      </mesh>
+    </group>
+  );
+};

package/src/remotion/kit/TextOnImage.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { createPortal } from "react-dom";
+import { AbsoluteFill, useVideoConfig } from "remotion";
+import { ImageLayersContext, TextInkContext } from "./ImageLayers";
+import { inkFor, placementOf, REGIONS, zoneRect, type ImageLayersRecord, type Rect, type Region } from "./image-layers-math";
+
+// The simple, always-correct way to put words on a picture. It sets its children in the picture's calm zone (the manifest's textZone, from the ImageLayers it sits in or
+// from `layers`; or `zone`, a region name or a rectangle in fractions of the frame), chooses dark or light ink from how light that zone is (a Headline inside takes it),
+// and lays a soft local scrim just behind the words, stronger the busier the zone is, so they read on any picture. When the picture has a subject layer the words go
+// BEHIND it if the subject covers 10 to 60 percent of the text block (the title behind the person), and in front of it when it would hide more than 60 percent;
+// `behindSubject` forces behind or front (a force behind still yields to front when most of the words would be hidden). Put it inside an ImageLayers. `ink` and
+// `scrim` (0 to 1) override the choices.
+export const TextOnImage: React.FC<{
+  layers?: ImageLayersRecord;
+  zone?: Region | Rect;
+  behindSubject?: boolean;
+  ink?: string;
+  scrim?: number;
+  children?: React.ReactNode;
+}> = ({ layers: given, zone, behindSubject, ink, scrim, children }) => {
+  const { width, height } = useVideoConfig();
+  const shared = React.useContext(ImageLayersContext);
+  const layers = given ?? shared?.layers;
+  const region: Region | undefined = typeof zone === "string" ? zone : zone ? undefined : layers?.textZone.region;
+  const rect: Rect = typeof zone === "object" ? zone : zoneRect(region ?? "bottom");
+  const picked = inkFor(layers?.textZone ?? { luminance: 0.2, busy: 0.5 });
+  const colour = ink ?? picked.ink, strength = scrim ?? picked.strength;
+  const place = placementOf(rect, layers?.subject ? layers.subjectBox : undefined, behindSubject);
+  const body = (
+    <>
+      <div style={{ position: "absolute", left: `${(rect.x - rect.w * 0.12) * 100}%`, top: `${(rect.y - rect.h * 0.35) * 100}%`, width: `${rect.w * 1.24 * 100}%`, height: `${rect.h * 1.7 * 100}%`, background: `radial-gradient(ellipse at 50% 50%, rgba(${picked.scrim},${strength}) 0%, rgba(${picked.scrim},${strength * 0.7}) 40%, rgba(${picked.scrim},0) 72%)`, pointerEvents: "none" }} />
+      <TextInkContext.Provider value={colour}>
+        <div style={{ position: "absolute", left: `${rect.x * 100}%`, top: `${rect.y * 100}%`, width: `${rect.w * 100}%`, height: `${rect.h * 100}%`, color: colour, display: "flex", alignItems: "center", justifyContent: "center" }}>{children}</div>
+      </TextInkContext.Provider>
+    </>
+  );
+  void width; void height; void REGIONS;
+  // In front of the subject: the words are drawn into ImageLayers's front layer instead of its middle one.
+  if (layers?.subject && !place.behind && shared?.frontRoot) return createPortal(<AbsoluteFill>{body}</AbsoluteFill>, shared.frontRoot);
+  return <AbsoluteFill>{body}</AbsoluteFill>;
+};

package/src/remotion/kit/Warp3D.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { AdditiveBlending, BufferAttribute, Color, DoubleSide, type BufferGeometry } from "three";
+import { warpSpeed, warpStreaks, warpTravel, type SpeedKey } from "./three-fx-math";
+import type { Vec3 } from "./three-math";
+
+// Speed streaks rushing out of a vanishing point at the middle of the frame, additive and in two colours: a ground for a hyperspace beat, or a 12 to 20 frame burst between
+// scenes. `speed` is a number or keys { frame, speed } joined smoothly (the streaks are longer and quicker the higher it is; 1 is a steady rush); or give `burst` { frame,
+// frames, peak? } for a short rise and fall that is nothing outside it and fades the streaks in and out. `count` streaks (500), `colors` two colours, `seed`.
+// Put it in a Scene3D with the default camera or any camera that looks down the z axis; it is drawn with no depth test, so it sits over anything else in the scene.
+export const Warp3D: React.FC<{
+  speed?: number | SpeedKey[];
+  burst?: { frame: number; frames: number; peak?: number };
+  count?: number;
+  colors?: [string, string];
+  width?: number;
+  seed?: number;
+  position?: Vec3;
+}> = ({ speed = 1, burst, count = 500, colors = ["#7C3AED", "#22D3EE"], width = 0.035, seed = 0, position = [0, 0, 0] }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const streaks = React.useMemo(() => warpStreaks(count, seed), [count, seed]);
+  const n = streaks.length;
+  const geom = React.useRef<BufferGeometry>(null);
+  const index = React.useMemo(() => { const a = new Uint32Array(n * 6); for (let i = 0; i < n; i++) a.set([i * 4, i * 4 + 1, i * 4 + 2, i * 4 + 1, i * 4 + 3, i * 4 + 2], i * 6); return a; }, [n]);
+  const A = React.useMemo(() => new Color(colors[0]), [colors]), B = React.useMemo(() => new Color(colors[1]), [colors]);
+  const v = warpSpeed(frame, speed, burst);
+  const travel = warpTravel(frame, speed, burst);
+  const { pos, col } = React.useMemo(() => {
+    const D = 35, zFar = -30, pos = new Float32Array(n * 12), col = new Float32Array(n * 12), c = new Color();
+    const fade = burst ? Math.min(1, v * 1.4) : 1;
+    streaks.forEach((s, i) => {
+      const z = zFar + ((((s.z * D + travel * 0.35) % D) + D) % D), len = (0.25 + Math.min(6, v) * 1.4) * (0.35 + 0.65 * s.mix), tail = z - len;
+      const x = s.x * 4, y = s.y * 4, r = Math.hypot(x, y) || 1, nx = -y / r, ny = x / r, w = width * (0.5 + s.mix);
+      const verts = [[x + nx * w, y + ny * w, z], [x - nx * w, y - ny * w, z], [x + nx * w, y + ny * w, tail], [x - nx * w, y - ny * w, tail]];
+      c.copy(A).lerp(B, s.mix);
+      const bright = Math.min(1, (z - zFar) / D + 0.15) * fade;
+      verts.forEach((p, k) => { const o = i * 12 + k * 3, head = k < 2 ? 1 : 0; pos[o] = p[0]!; pos[o + 1] = p[1]!; pos[o + 2] = p[2]!; col[o] = c.r * head * bright; col[o + 1] = c.g * head * bright; col[o + 2] = c.b * head * bright; });
+    });
+    return { pos, col };
+  }, [streaks, n, v, travel, burst, A, B, width]);
+  React.useLayoutEffect(() => {
+    const g = geom.current;
+    if (!g) return;
+    g.setAttribute("position", new BufferAttribute(pos, 3));
+    g.setAttribute("color", new BufferAttribute(col, 3));
+    g.setIndex(new BufferAttribute(index, 1));
+    g.computeBoundingSphere();
+  }, [pos, col, index]);
+  void fps;
+  return (
+    <group position={position}>
+      <mesh frustumCulled={false} renderOrder={10}>
+        <bufferGeometry ref={geom} />
+        <meshBasicMaterial vertexColors transparent blending={AdditiveBlending} depthWrite={false} depthTest={false} side={DoubleSide} toneMapped={false} />
+      </mesh>
+    </group>
+  );
+};

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

@@ -0,0 +1,179 @@
+// The arithmetic behind the kit's grounds (BgVideo, BgImage, BgSequence and the animated grounds), with no React in it. Everything is a pure function
+// of the frame, so any frame can be drawn on its own.
+const clamp01 = (n: number) => (n > 0 ? (n < 1 ? n : 1) : 0);
+const mixN = (a: number, b: number, t: number) => a + (b - a) * t;
+
+// --- A video ground that loops with a cross-fade over the join -------------------------------------------------------------------------
+
+export const DEFAULT_CROSSFADE = 12;
+export type VideoLayer = { index: number; start: number; opacity: number };
+
+// Which plays of the clip are on screen at `frame`. A play is the clip from its first frame, started at `start` (a composition frame) and `clipFrames` long
+// (its length at the playback rate). With `loop`, the next play starts `crossfade` frames before the last one ends and fades in over them, so the restart
+// is never a jump; the earlier play stays at full opacity beneath until the new one has covered it. Without it the clip plays once and holds its last frame.
+export function videoLayers(frame: number, o: { clipFrames: number; loop: boolean; crossfade?: number }): VideoLayer[] {
+  const clip = Math.max(1, Math.floor(o.clipFrames));
+  if (!o.loop) return [{ index: 0, start: 0, opacity: 1 }];
+  const fade = Math.max(0, Math.min(o.crossfade ?? DEFAULT_CROSSFADE, Math.floor(clip / 2)));
+  const period = Math.max(1, clip - fade);
+  const f = Math.max(0, frame);
+  const k = Math.floor(f / period);
+  const age = f - k * period;
+  const current: VideoLayer = { index: k, start: k * period, opacity: k > 0 && fade > 0 ? clamp01((age + 1) / (fade + 1)) : 1 };
+  if (k > 0 && age < fade) return [{ index: k - 1, start: (k - 1) * period, opacity: 1 }, current];
+  return [current];
+}
+
+// --- A still ground that always covers the frame ------------------------------------------------------------------------------------
+
+export type Drift = "none" | "left" | "right" | "up" | "down";
+export type PlateView = { scale: number; tx: number; ty: number };
+
+// How a still is placed over time. `progress` is how far through its time on screen it is (0 to 1). The scale grows by `zoom` over that time, and
+// `drift` pans a few percent (`driftAmount` of the frame, each way). The base scale is chosen so that the pan and the blur never show an edge: the
+// picture is wider than the frame by at least twice the largest shift. tx and ty are fractions of the frame's width and height.
+export function plateView(progress: number, o: { zoom?: number; drift?: Drift; driftAmount?: number; blurPx?: number; width?: number } = {}): PlateView {
+  const p = clamp01(progress);
+  const amount = o.drift && o.drift !== "none" ? o.driftAmount ?? 0.04 : 0;
+  const blurMargin = o.blurPx && o.width ? (4 * o.blurPx) / o.width : 0;
+  const base = 1 + 2 * amount + blurMargin;
+  const scale = base * (1 + (o.zoom ?? 0.06) * p);
+  const along = mixN(amount, -amount, p);
+  const [dx, dy] = o.drift === "left" ? [along, 0] : o.drift === "right" ? [-along, 0] : o.drift === "up" ? [0, along] : o.drift === "down" ? [0, -along] : [0, 0];
+  return { scale, tx: dx, ty: dy };
+}
+
+// --- A ground that changes from one picture to the next ---------------------------------------------------------------------------------
+
+export type SequenceItem = { src: string; from: number };
+export type SequenceTransition = "fade" | "blur" | "wipe" | "zoom";
+export type SequenceLayer = { index: number; opacity: number; blur: number; scale: number; wipe?: number; progress: number };
+
+// The items in order, the first starting at frame 0 (it is visible from the first frame whatever its `from`). Two items out of order or on the same frame
+// is a mistake that would put a picture on screen at the wrong time, so it is an explained error.
+export function checkItems(items: readonly SequenceItem[]): void {
+  if (!items.length) throw new Error("BgSequence needs at least one item: give it items with a src and a from frame (bgPerScene(manifest.scenes, srcs) builds them).");
+  for (let i = 1; i < items.length; i++) {
+    if (items[i]!.from === items[i - 1]!.from) throw new Error(`BgSequence items ${i - 1} and ${i} start on the same frame (${items[i]!.from}). Give each its own frame.`);
+    if (items[i]!.from < items[i - 1]!.from) throw new Error(`BgSequence items are out of order: item ${i} starts at frame ${items[i]!.from}, before item ${i - 1} at ${items[i - 1]!.from}. List them by from.`);
+  }
+}
+
+// The window in which the change into item `i` happens: centred on its `from`, or starting at it with align "start".
+function windowOf(items: readonly SequenceItem[], i: number, frames: number, align: "center" | "start"): [number, number] {
+  const from = items[i]!.from;
+  // A window may not reach back past the item before, or the two changes would overlap.
+  const lo = align === "start" ? from : from - frames / 2;
+  const w0 = i > 0 ? Math.max(lo, items[i - 1]!.from) : lo;
+  return [w0, w0 + frames];
+}
+
+// Which items are drawn at `frame`, bottom to top. Outside a change only one is drawn; during it two. The one underneath stays fully opaque, so there is
+// never a gap, and the one on top comes in by the chosen transition. `progress` runs 0 to 1 over the time an item is on screen, for its own slow zoom,
+// which carries on through the change so that nothing freezes or jumps.
+export function sequenceLayers(items: readonly SequenceItem[], frame: number, o: { transition?: SequenceTransition; transitionFrames?: number; align?: "center" | "start" } = {}): SequenceLayer[] {
+  checkItems(items);
+  const frames = Math.max(1, Math.round(o.transitionFrames ?? 18)), align = o.align ?? "center", kind = o.transition ?? "fade";
+  const wins = items.map((_, i) => (i === 0 ? ([-Infinity, -Infinity] as [number, number]) : windowOf(items, i, frames, align)));
+  const progressOf = (i: number): number => {
+    const s = wins[i]![0] === -Infinity ? 0 : wins[i]![0];
+    const e = i + 1 < items.length ? wins[i + 1]![1] : Math.max(s + 1, s + 300);
+    return clamp01((frame - s) / Math.max(1, e - s));
+  };
+  // The item on top: the last whose window has begun.
+  let top = 0;
+  for (let i = 1; i < items.length; i++) if (frame >= wins[i]![0]) top = i;
+  const p = top === 0 ? 1 : clamp01((frame - wins[top]![0]) / frames);
+  if (top === 0 || p >= 1) return [{ index: top, opacity: 1, blur: 0, scale: 1, progress: progressOf(top) }];
+  const peak = Math.sin(Math.PI * p);
+  const under: SequenceLayer = { index: top - 1, opacity: 1, blur: kind === "blur" ? peak : 0, scale: kind === "zoom" ? 1 + 0.1 * p : 1, progress: progressOf(top - 1) };
+  const over: SequenceLayer = {
+    index: top, progress: progressOf(top), opacity: kind === "wipe" ? 1 : p, blur: kind === "blur" ? peak : 0, scale: kind === "zoom" ? 1.08 - 0.08 * p : 1,
+    ...(kind === "wipe" ? { wipe: p } : {}),
+  };
+  return [under, over];
+}
+
+// The items for a ground that changes exactly on scene starts, which are already on the beat. A scene whose src is missing keeps the picture before it.
+export function bgPerScene(scenes: readonly { startFrame: number }[], srcs: readonly (string | undefined)[]): SequenceItem[] {
+  const items: SequenceItem[] = [];
+  scenes.forEach((s, i) => {
+    const src = srcs[i];
+    if (src && src !== items[items.length - 1]?.src) items.push({ src, from: items.length === 0 ? 0 : s.startFrame });
+  });
+  return items;
+}
+
+// --- Grounds drawn in code ----------------------------------------------------------------------------------------------------------------
+
+export type Blob = { x: number; y: number; r: number };
+// Three large colour fields that drift and cross: centres as fractions of the frame, radii as fractions of its longer side. They travel about a third
+// of the frame in two seconds, so the movement is plain within a short shot, and they cross, which is where the structure shows.
+export function auroraBlobs(frame: number, fps: number, speed = 1): Blob[] {
+  const t = (frame / fps) * speed * 0.3 * 2 * Math.PI;
+  return [
+    { x: 0.28 + 0.26 * Math.sin(t), y: 0.26 + 0.18 * Math.cos(t * 0.8), r: 0.5 },
+    { x: 0.74 + 0.24 * Math.cos(t * 0.7 + 1), y: 0.58 + 0.2 * Math.sin(t * 0.9 + 2), r: 0.56 },
+    { x: 0.5 + 0.34 * Math.sin(t * 0.5 + 4), y: 0.86 + 0.1 * Math.cos(t * 0.6), r: 0.46 },
+  ];
+}
+
+// The one dial the animated grounds share: 0 is a faint ground and 1 a strong one, 0.6 by default, which reads on a phone. `strength` is what the
+// grounds multiply their light by, from 0.2 to 1.
+export const DEFAULT_INTENSITY = 0.6;
+export const groundStrength = (intensity = DEFAULT_INTENSITY): number => 0.2 + 0.8 * clamp01(intensity);
+
+// A colour rotated about the colour wheel by `degrees`, keeping its lightness and saturation: the neighbours of a hero colour for fields that differ in hue.
+export function hueShift(hex: string, degrees: number): string {
+  const n = hex.replace("#", ""), f = n.length === 3 ? n.split("").map((c) => c + c).join("") : n;
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(f.slice(i, i + 2), 16) / 255) as [number, number, number];
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2, d = max - min;
+  let h = 0, sat = 0;
+  if (d > 0) {
+    sat = d / (1 - Math.abs(2 * l - 1));
+    h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    h *= 60;
+  }
+  h = (((h + degrees) % 360) + 360) % 360;
+  const c = (1 - Math.abs(2 * l - 1)) * sat, x = c * (1 - Math.abs(((h / 60) % 2) - 1)), m = l - c / 2;
+  const [rr, gg, bb] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  const hexv = (v: number) => Math.round(Math.min(1, Math.max(0, v + m)) * 255).toString(16).padStart(2, "0");
+  return `#${hexv(rr)}${hexv(gg)}${hexv(bb)}`;
+}
+
+// A colour as rgba(), from a hex colour and an alpha from 0 to 1.
+export function withAlpha(hex: string, alpha: number): string {
+  const n = hex.replace("#", ""), f = n.length === 3 ? n.split("").map((c) => c + c).join("") : n;
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(f.slice(i, i + 2), 16));
+  return `rgba(${r}, ${g}, ${b}, ${Math.round(clamp01(alpha) * 1000) / 1000})`;
+}
+
+// A perspective grid receding to a horizon. Horizontal lines get closer toward the horizon (squared spacing) and slide toward the viewer; `offset` is how
+// far through one spacing they have slid (0 to 1, repeating), so the grid is seamless.
+export function gridOffset(frame: number, fps: number, speed = 1): number {
+  const x = (frame / fps) * speed * 0.18;
+  return x - Math.floor(x);
+}
+export function gridRows(offset: number, count: number): number[] {
+  // Depth 0 is the horizon, 1 is the bottom edge. Rows are at depth ((i + offset) / count) ** 2.
+  return Array.from({ length: count }, (_, i) => ((i + offset) / count) ** 2);
+}
+
+// Wide diagonal light beams sweeping across: the angle in degrees of each and how far it has slid sideways, as a fraction of the frame width, and its
+// strength (0.4 to 1) as it brightens and dims. Four beams, a full sweep in about eight seconds.
+export function beamStates(frame: number, fps: number, speed = 1): { angle: number; slide: number; strength: number }[] {
+  const t = (frame / fps) * speed * 0.16 * 2 * Math.PI;
+  return [0, 1, 2, 3].map((i) => ({ angle: 22 + i * 8 + 8 * Math.sin(t + i * 2), slide: -0.2 + i * 0.28 + 0.2 * Math.sin(t * 0.8 + i * 1.3), strength: 0.7 + 0.3 * Math.sin(t * 1.3 + i) }));
+}
+
+// A breathing vignette (0 to 1) and the seed of the film grain, which steps every 3 frames: the same frame always has the same grain.
+export const breath = (frame: number, fps: number, speed = 1) => 0.5 + 0.5 * Math.sin((frame / fps) * speed * 0.35 * 2 * Math.PI);
+export const grainSeed = (frame: number) => Math.floor(Math.max(0, frame) / 3) % 997;
+
+// A colour between two hex colours, as a hex string.
+export function mixHex(a: string, b: string, t: number): string {
+  const parse = (h: string) => { const n = h.replace("#", ""); const f = n.length === 3 ? n.split("").map((c) => c + c).join("") : n; return [0, 2, 4].map((i) => parseInt(f.slice(i, i + 2), 16)); };
+  const [ar, ag, ab] = parse(a) as [number, number, number], [br, bg, bb] = parse(b) as [number, number, number];
+  const hex = (n: number) => Math.round(Math.min(255, Math.max(0, n))).toString(16).padStart(2, "0");
+  return `#${hex(mixN(ar, br, t))}${hex(mixN(ag, bg, t))}${hex(mixN(ab, bb, t))}`;
+}

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

@@ -3,6 +3,8 @@ import type { WordTiming } from "../../pipeline/schema";
 export type CaptionGroup = "none" | "word" | "phrase";
 
 export const MAX_GROUP_WORDS = 6;
+// The size of a group when nothing says otherwise: a few words, never one.
+export const DEFAULT_GROUP_WORDS = 3;
 export const MAX_GROUP_CHARS = 32;
 // A pause between two words at least this long ends a group.
 export const PAUSE_SEC = 0.35;
@@ -23,11 +25,13 @@ 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;
+const fitsIn = (max: number) => (ws: WordTiming[]) => ws.length <= max && 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][] {
+// Index ranges [start, end) into `words`, one per caption. "word": one word each. "phrase": grouped the way the words are spoken, at most `maxWords`
+// (default 6) words and about 32 characters in a group. A group never spans two sentences: it ends at ., ? or !.
+export function captionGroups(words: WordTiming[], group: "word" | "phrase", opts: { maxWords?: number } = {}): [number, number][] {
   if (group === "word") return words.map((_, i) => [i, i + 1]);
+  const fits = fitsIn(Math.max(1, Math.floor(opts.maxWords ?? MAX_GROUP_WORDS)));
   const groups: [number, number][] = [];
   let start = 0;
   const gapAfter = (i: number) => (words[i + 1] ? words[i + 1]!.startSec - words[i]!.endSec : Infinity);

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

@@ -0,0 +1,45 @@
+// What makes the default captions readable on any ground: a dark plate behind the words, white ink, and the spoken word on a chip of the film's
+// accent (a karaoke fill, which has no chip, takes the accent lightened just enough to stay legible on the plate). Pure functions over hex colours.
+
+// The plate behind a group of words: dark, rounded, about 58% opaque.
+export const PLATE_RGB: [number, number, number] = [8, 10, 20];
+export const PLATE_ALPHA = 0.58;
+export const PLATE_COLOR = `rgba(${PLATE_RGB.join(",")},${PLATE_ALPHA})`;
+// The contrast the spoken word must keep against the plate seen over the brightest ground (large bold type needs 3 to 1; the white ink has far more).
+export const SPOKEN_CONTRAST = 3.2;
+
+const parse = (hex: string): [number, number, number] => {
+  const h = hex.replace("#", "");
+  const full = h.length === 3 ? h.split("").map((c) => c + c).join("") : h.slice(0, 6);
+  const n = Number.parseInt(full, 16);
+  return Number.isNaN(n) ? [255, 255, 255] : [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+};
+const lin = (v: number) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+// WCAG relative luminance of an rgb colour, 0 to 1.
+export const wcagLuminance = (rgb: readonly number[]): number => 0.2126 * lin(rgb[0]!) + 0.7152 * lin(rgb[1]!) + 0.0722 * lin(rgb[2]!);
+// WCAG contrast ratio between two luminances.
+export const contrastOf = (a: number, b: number): number => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+// The plate over a ground of colour `ground` (rgb).
+export const plateOver = (ground: readonly number[]): [number, number, number] => PLATE_RGB.map((p, i) => p * PLATE_ALPHA + ground[i]! * (1 - PLATE_ALPHA)) as [number, number, number];
+// The brightest the plate can look: over a white ground.
+export const BRIGHTEST_PLATE_LUMINANCE = wcagLuminance(plateOver([255, 255, 255]));
+
+const hex = (rgb: number[]) => `#${rgb.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0")).join("")}`;
+
+// The accent, mixed toward white until it keeps SPOKEN_CONTRAST against the brightest plate. A light accent is returned as it is.
+export function legibleAccent(accent: string): string {
+  const c = parse(accent);
+  for (let k = 0; k <= 20; k++) {
+    const t = k / 20;
+    const mixed = c.map((v) => v + (255 - v) * t);
+    if (contrastOf(wcagLuminance(mixed), BRIGHTEST_PLATE_LUMINANCE) >= SPOKEN_CONTRAST) return hex(mixed);
+  }
+  return "#ffffff";
+}
+
+// The ink that reads best on a chip of this accent colour: white, or a near-black when the accent is light.
+export function inkOnAccent(accent: string): string {
+  const l = wcagLuminance(parse(accent));
+  return contrastOf(1, l) >= contrastOf(wcagLuminance([20, 20, 28]), l) ? "#ffffff" : "#14141c";
+}