reelkit-cli 0.5.0 → 0.8.0

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

@@ -42,7 +42,7 @@ const springOf = (o: Timing): SpringConfig => ({ stiffness: o.stiffness ?? sprin
 // 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 } {
+export 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++) {
@@ -55,7 +55,7 @@ function locate<K extends { frame: number }>(sorted: K[], frame: number, fps: nu
   return { from, to: from, p: 0 };
 }
 
-const mix = (a: number, b: number, p: number) => a + (b - a) * p;
+export 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 };
@@ -111,3 +111,37 @@ export function cameraTransform(c: CameraView, w: number, h: number): { origin:
     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})`,
   };
 }
+
+// A punch: a quick push of 8 to 15 percent onto a point, for emphasis on a word or a click. It rises over `frames` frames with a small overshoot,
+// holds for `hold` frames and eases back over `release`. The zoom is about the point itself, so the point stays where it is on screen.
+export type Punch = { frame: number; x: number; y: number; amount?: number; frames?: number; hold?: number; release?: number };
+
+// 0 before the punch, 1 at its full push, with a little over 1 on the way in (an ease-out-back with a small constant).
+export function punchEnvelope(p: Punch, frame: number): number {
+  const rise = Math.max(1, p.frames ?? 5), hold = Math.max(0, p.hold ?? 6), release = Math.max(1, p.release ?? 8);
+  const t = frame - p.frame;
+  if (t <= 0) return 0;
+  if (t < rise) { const u = t / rise - 1, c = 1.1; return 1 + (c + 1) * u ** 3 + c * u ** 2; }
+  if (t <= rise + hold) return 1;
+  const u = (t - rise - hold) / release;
+  return u >= 1 ? 0 : 1 - (3 * u * u - 2 * u * u * u);
+}
+
+// The camera with every punch applied. A punch of strength `e` scales the view by 1 + amount * e about its point.
+export function applyPunches(view: CameraView, punches: readonly Punch[], frame: number): CameraView {
+  let { x, y, zoom } = view;
+  for (const p of punches) {
+    const e = punchEnvelope(p, frame);
+    if (e === 0) continue;
+    const m = 1 + Math.min(0.5, Math.max(0, p.amount ?? 0.1)) * e;
+    // Zooming by m with the point P kept still on screen moves the centre to P - (P - C) / m.
+    x = p.x - (p.x - x) / m; y = p.y - (p.y - y) / m; zoom *= m;
+  }
+  return { ...view, x, y, zoom };
+}
+
+// The camera key that pushes in until an element fills the frame: the element's box, as fractions of the frame (x and y its centre), so that
+// its longer side just reaches the frame's edge. Put it in `keys`, then the next key pulls out or on to the next element.
+export function zoomTo(frame: number, box: { x: number; y: number; width: number; height: number }): CameraKey {
+  return { frame, x: box.x, y: box.y, zoom: Math.max(1, Math.min(1 / Math.max(1e-3, box.width), 1 / Math.max(1e-3, box.height))) };
+}

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

@@ -1,31 +1,43 @@
 import type { WordTiming } from "../../pipeline/schema";
 
+// The music is already down this long before a word starts, and stays down this long after it ends.
 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;
+// The music falls over this long before a word (it is down 0.25 s before the word starts) and rises over this long after a pause.
+export const DUCK_FALL_SEC = 0.25;
+export const DUCK_RISE_SEC = 0.4;
+// Only a gap of at least this long between words lets the music come up; a shorter one keeps it steady so it does not pump. With sentences 0.3 s
+// apart the music holds under a whole narrated passage and lifts in real pauses only: before the first word and after the last.
+export const DUCK_GAP_SEC = 1.2;
+// What the music sits at under a voice, and the level it comes up to, as `volume` multipliers: the voice is 1.
+export const DEFAULT_DUCK_TO = 0.18;
+export const DEFAULT_MUSIC_VOLUME = 0.5;
 export const FADE_OUT_SEC = 1;
+// A dip eases in and out over this many frames just outside its range, so the track never jumps.
+export const DIP_RAMP_FRAMES = 6;
+
+export type MusicDip = { from: number; to: number; volume: number };
 
 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.
+// DUCK_GAP_SEC (less than 1.2 s) apart 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);
+    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 {
+// How far down the music is at `t` seconds, 0 (not at all) to 1 (fully): full inside a stretch, falling over DUCK_FALL_SEC just before its start and
+// rising over DUCK_RISE_SEC just after its end.
+export 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);
+    const edge = Math.min((t - a) / DUCK_FALL_SEC + 1, (b - t) / DUCK_RISE_SEC + 1);
     amount = Math.max(amount, Math.max(0, Math.min(1, edge)));
   }
   return amount;
@@ -33,10 +45,15 @@ function duckAmount(spans: [number, number][], t: number): number {
 
 // 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 {
+export function musicVolume(frame: number, o: { fps: number; totalFrames: number; volume: number; duckTo: number; spans: [number, number][]; gain?: number; dips?: MusicDip[] }): 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;
+  let base = o.volume + (Math.min(o.duckTo, o.volume) - o.volume) * duck;
+  // A dip is a rest that the author asked for: inside it the track is held at the dip's volume, with a short ramp at each edge.
+  for (const d of o.dips ?? []) {
+    const near = Math.max(0, Math.min(1, Math.min(frame - d.from, d.to - frame) / DIP_RAMP_FRAMES + 1));
+    if (near > 0) base = Math.min(base, base + (d.volume - base) * near);
+  }
   const fade = Math.max(0, Math.min(1, (o.totalFrames - frame) / (FADE_OUT_SEC * o.fps)));
   return base * fade * (o.gain ?? 1);
 }

package/src/remotion/kit/quiet-three.ts

@@ -0,0 +1,11 @@
+// three.js 0.186 prints a deprecation notice for THREE.Clock from inside @react-three/fiber, once per canvas, to the browser console. Renders forward
+// every console line, so that one notice would fill the output of render, preview and check. This drops that exact warning and nothing else.
+const NOTICE = "THREE.Clock: This module has been deprecated";
+const GUARD = "__reelkitQuietThree";
+const g = globalThis as unknown as Record<string, unknown>;
+if (typeof console !== "undefined" && !g[GUARD]) {
+  g[GUARD] = true;
+  const warn = console.warn.bind(console);
+  console.warn = (...args: unknown[]) => { if (typeof args[0] === "string" && args[0].startsWith(NOTICE)) return; warn(...args); };
+}
+export {};

package/src/remotion/kit/sample-text.ts

@@ -0,0 +1,55 @@
+import { typeface } from "./Text3D";
+import { centred, MAX_PIECES, MAX_POINTS } from "./three-fx-math";
+import { hash01 } from "./seeded";
+import type { Vec3 } from "./three-math";
+
+type Poly = { x: number; y: number }[];
+// The outline of every glyph of a word in the kit's typeface, outlines and holes together: a point is inside a letter when it is inside an odd number of them.
+function outlines(text: string): { polys: Poly[]; box: { x0: number; y0: number; x1: number; y1: number } } {
+  const polys: Poly[] = [];
+  for (const shape of typeface().generateShapes(text, 1)) {
+    polys.push(shape.getPoints(10));
+    for (const hole of shape.holes) polys.push(hole.getPoints(10));
+  }
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const poly of polys) for (const p of poly) { x0 = Math.min(x0, p.x); x1 = Math.max(x1, p.x); y0 = Math.min(y0, p.y); y1 = Math.max(y1, p.y); }
+  return { polys, box: { x0, y0, x1, y1 } };
+}
+function inside(polys: Poly[], x: number, y: number): boolean {
+  let hit = false;
+  for (const poly of polys) for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const a = poly[i]!, b = poly[j]!;
+    if ((a.y > y) !== (b.y > y) && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) hit = !hit;
+  }
+  return hit;
+}
+
+// The slots of a short word, as blocks: cells of a grid that fall inside the letters, about `count` of them (never over 4000), centred, the word's width 1.
+export function textSlots(text: string, count: number): Vec3[] {
+  const { polys, box } = outlines(text);
+  if (!polys.length) return [[0, 0, 0]];
+  const w = box.x1 - box.x0, h = box.y1 - box.y0, want = Math.max(8, Math.min(MAX_PIECES, Math.round(count)));
+  // The share of the box the letters fill, estimated on a coarse sample, gives the cell size at which about `want` cells land inside.
+  let hits = 0;
+  const probe = 40;
+  for (let a = 0; a < probe; a++) for (let b = 0; b < probe; b++) if (inside(polys, box.x0 + ((a + 0.5) / probe) * w, box.y0 + ((b + 0.5) / probe) * h)) hits++;
+  const fill = Math.max(0.05, hits / (probe * probe)), cell = Math.sqrt((w * h * fill) / want);
+  const out: Vec3[] = [];
+  for (let y = box.y0 + cell / 2; y < box.y1; y += cell) for (let x = box.x0 + cell / 2; x < box.x1; x += cell) if (inside(polys, x, y)) out.push([x, y, 0]);
+  const stride = Math.max(1, Math.ceil(out.length / MAX_PIECES));
+  return centred(stride > 1 ? out.filter((_, i) => i % stride === 0) : out);
+}
+
+// `count` seeded points inside the letters of a word, as a flat array, centred, the width 1, a little thickness in z.
+export function textPoints(text: string, count: number, seed = 0): Float32Array {
+  const { polys, box } = outlines(text), n = Math.max(1, Math.min(MAX_POINTS, Math.round(count))), w = box.x1 - box.x0, h = box.y1 - box.y0;
+  const pts: Vec3[] = [];
+  for (let i = 0, k = 0; pts.length < n && k < n * 60; k++) {
+    const x = box.x0 + hash01(k, seed + 51) * w, y = box.y0 + hash01(k, seed + 52) * h;
+    if (inside(polys, x, y)) { pts.push([x, y, (hash01(i++, seed + 53) - 0.5) * 0.12 * w]); }
+  }
+  while (pts.length < n) pts.push(pts[pts.length % Math.max(1, pts.length)] ?? [0, 0, 0]);
+  const c = centred(pts), out = new Float32Array(n * 3);
+  c.forEach((p, i) => { out[i * 3] = p[0]; out[i * 3 + 1] = p[1]; out[i * 3 + 2] = p[2]; });
+  return out;
+}

package/src/remotion/kit/scene3d-context.ts

@@ -0,0 +1,5 @@
+import { createContext } from "react";
+import type { Camera3DKey } from "./three-math";
+
+// The camera path of the Scene3D a 3D component sits in, so that Text3D and Orbit3D can size themselves to the closest the camera comes.
+export const CameraKeysContext = createContext<readonly Camera3DKey[] | undefined>(undefined);

package/src/remotion/kit/seeded.ts

@@ -0,0 +1,13 @@
+// Seeded randomness for everything the kit draws or places: the same seed always gives the same numbers, so a frame can be drawn on its own. Never Math.random.
+export function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+// One number in [0, 1) from two integers (an index and a seed), with no state.
+export const hash01 = (i: number, seed = 0): number => mulberry32((Math.imul(i | 0, 2654435761) ^ Math.imul(seed | 0, 40503) ^ 0x9e3779b9) >>> 0)();

package/src/remotion/kit/sound-cues.ts

@@ -0,0 +1,89 @@
+// The pure parts of SoundCues: nothing here needs React or Remotion, so it can be tested and used in a composition's own timing code.
+import { travel } from "./motion-math";
+import { PEAKS_ON_BOUNDARY, transitionSpan, type TransitionKind } from "./transition-math";
+import { punchEnvelope, type Punch } from "./motion-math";
+import { springs } from "./theme";
+
+// One sound to play: `at` is an absolute frame of the video, `sound` a key into the sounds map, `volume` is this cue's own level.
+export type SoundCue = { at: number; sound: string; volume?: number };
+
+// A cue on every `every`th beat of the beats that fall from `from` to `to` (both included, in frames), starting with the first of them.
+// `every` below 1 or not a whole number is treated as 1 so that a slip never silently drops all the cues.
+export function cuesOnBeats(
+  beatFrames: number[],
+  opts: { from: number; to: number; every: number; sound: string; volume?: number },
+): SoundCue[] {
+  const every = Number.isFinite(opts.every) && opts.every >= 1 ? Math.floor(opts.every) : 1;
+  return beatFrames
+    .filter((b) => b >= opts.from && b <= opts.to)
+    .filter((_, i) => i % every === 0)
+    .map((b) => ({ at: b, sound: opts.sound, ...(opts.volume !== undefined ? { volume: opts.volume } : {}) }));
+}
+
+// The frame at which a sound `leadFrames` long must start so that it ENDS on `frame`: a riser or a whoosh into a cut or a reveal.
+// Never before the first frame of the video.
+export const cueBefore = (frame: number, leadFrames: number): number => Math.max(0, Math.round(frame - leadFrames));
+
+// Where the eye sees a scene end. A SceneFrame transition is complete exactly on the boundary (the next scene's start), but the picture changes most
+// in the middle of it, which is half the exit's frames before the boundary (4 frames for the default 8, 3 for `transitionFrames={6}`, 3 for "rgb-whip", whose default is 6); a "cut" has no
+// such span, and neither do "color-push", "flash", "ring" and "flip", which are fullest on the boundary itself. A hit placed on the boundary lands after the change, which is why it reads as late. `exit` and `transitionFrames` are SceneFrame's own.
+export function changeFrame(scene: { startFrame: number; durationFrames: number; exit?: TransitionKind; transitionFrames?: number }): number {
+  const boundary = scene.startFrame + scene.durationFrames;
+  // A cut, and the transitions that are fullest on the frame the next scene starts (a colour field covering the frame, a flash, a closed ring, an inverted frame), peak on the boundary.
+  if (scene.exit && PEAKS_ON_BOUNDARY.includes(scene.exit)) return boundary;
+  const frames = Math.min(transitionSpan(scene.exit, scene.transitionFrames), Math.floor(scene.durationFrames / 2));
+  return Math.max(scene.startFrame, Math.round(boundary - frames / 2));
+}
+
+// A cue for each scene change, where the eye sees it: an impact on the change's visual peak (changeFrame) and a whoosh that ENDS on that same frame.
+// `scenes` are the manifest's scenes, each with its SceneFrame `exit` and `transitionFrames` if it has them, in order; the last scene has no change after
+// it. `whoosh.frames` is the whoosh's length in frames (from the search line, seconds times 30). Leave out whichever of `impact` and `whoosh` you do not want.
+// `skip` lists scene indices whose change gets no cue (a quiet one). Cues come out in order of frame.
+export function cuesOnChanges(
+  scenes: { startFrame: number; durationFrames: number; exit?: TransitionKind; transitionFrames?: number }[],
+  opts: { impact?: { sound: string; volume?: number }; whoosh?: { sound: string; volume?: number; frames: number }; skip?: number[] },
+): SoundCue[] {
+  const cues: SoundCue[] = [];
+  scenes.slice(0, -1).forEach((scene, i) => {
+    if (opts.skip?.includes(i)) return;
+    const at = changeFrame(scene);
+    if (opts.whoosh) cues.push({ at: cueBefore(at, opts.whoosh.frames), sound: opts.whoosh.sound, ...(opts.whoosh.volume !== undefined ? { volume: opts.whoosh.volume } : {}) });
+    if (opts.impact) cues.push({ at, sound: opts.impact.sound, ...(opts.impact.volume !== undefined ? { volume: opts.impact.volume } : {}) });
+  });
+  return cues.sort((a, b) => a.at - b.at);
+}
+
+// Where the eye sees a camera move or a punch: the frame the picture changes fastest. A Camera key at `frame` is reached by a spring that starts
+// `lead` frames earlier (12 unless set), so the fastest frame is about 9 frames before the key's own frame, not on it; a punch (`{ punch: true }`)
+// rises over its first `frames` frames (5) and is fastest right after its frame. Place a hit there. `frame` is in the clock the Camera counts (inside a
+// SceneFrame that is the scene's own frame: add the scene's startFrame for an absolute cue).
+export function cueOnCamera(frame: number, o: { punch?: boolean; punchFrames?: number; lead?: number; stiffness?: number; damping?: number; fps?: number } = {}): number {
+  if (o.punch) {
+    const p: Punch = { frame, x: 0.5, y: 0.5, frames: o.punchFrames };
+    let best = 1, top = -1;
+    for (let k = 1; k <= (o.punchFrames ?? 5); k++) { const v = punchEnvelope(p, frame + k) - punchEnvelope(p, frame + k - 1); if (v > top) { top = v; best = k; } }
+    return frame + best;
+  }
+  const lead = Math.max(1, o.lead ?? 12), config = { stiffness: o.stiffness ?? springs.smooth.stiffness, damping: o.damping ?? springs.smooth.damping };
+  let best = 1, top = -1;
+  for (let k = 1; k <= lead; k++) { const v = travel(k / lead, o.fps ?? 30, config, lead) - travel((k - 1) / lead, o.fps ?? 30, config, lead); if (v > top) { top = v; best = k; } }
+  return frame - lead + best;
+}
+
+// What SoundCues plays: for each cue its start frame, its file and its final volume (cue volume times master times the file's levelling gain).
+// A cue whose sound is not in `sounds` is a mistake in the composition and is reported with the names that exist.
+export function resolveCues(args: {
+  cues: SoundCue[];
+  sounds: Record<string, string>;
+  volume?: number;
+  urls?: Record<string, string>;
+  gainFor: (src: string) => number;
+}): { from: number; src: string; volume: number }[] {
+  const master = args.volume ?? 1;
+  return args.cues.map((c) => {
+    const src = args.sounds[c.sound];
+    if (src === undefined) throw new Error(`SoundCues: a cue uses the sound "${c.sound}", which is not in sounds. The sounds are: ${Object.keys(args.sounds).join(", ") || "none"}.`);
+    const file = args.urls?.[src] ?? src;
+    return { from: Math.max(0, Math.round(c.at)), src: file, volume: (c.volume ?? 0.35) * master * args.gainFor(src) };
+  });
+}

package/src/remotion/kit/sound-kinds.ts

@@ -0,0 +1,122 @@
+// Sound for interface events: turns the frames a component reports (promptFrames, lineFrames, clickFrames, settleFrame, ...) into SoundCues with a sensible
+// sound role, level and density for the kind of event. Pure and deterministic: the same events always give the same cues. A cue's `sound` is a ROLE (like
+// "type-tick"); the film's `sounds` map says which pulled file plays each role.
+import { hash01 } from "./seeded";
+import type { SoundCue } from "./sound-cues";
+
+export const CUE_KINDS = ["type", "click", "snap", "pop", "count", "stream", "assemble", "resolve"] as const;
+export type CueKind = (typeof CUE_KINDS)[number];
+
+// `volume` is [without a narrator, under a narrator]: films with no voice use 0.35 to 0.6 for the main hits and less for small ticks; under a voice nothing is over 0.3.
+export type CueRole = { search: string; seconds: number; volume: [number, number] };
+export const CUE_TABLE: Record<CueKind, { about: string; per10s: string; roles: Record<string, CueRole> }> = {
+  type: {
+    about: "typed text: sparse key ticks, one every 2 to 3 characters, at most 12 a second, a little different in level each, and a thock on the return at the end",
+    per10s: "1 to 3 runs of 6 to 12 ticks",
+    roles: {
+      "type-tick": { search: "mouse click", seconds: 0.2, volume: [0.2, 0.1] },
+      "type-return": { search: "glass tap", seconds: 0.5, volume: [0.4, 0.2] },
+    },
+  },
+  click: { about: "a cursor click or a button press", per10s: "1 to 3", roles: { click: { search: "mouse click", seconds: 0.2, volume: [0.4, 0.22] } } },
+  snap: { about: "a card or a panel settling", per10s: "2 to 5", roles: { snap: { search: "soft impact", seconds: 0.7, volume: [0.45, 0.25] } } },
+  pop: { about: "a badge, a chip, a bubble appearing", per10s: "3 to 6", roles: { pop: { search: "bubble pop", seconds: 0.5, volume: [0.4, 0.22] } } },
+  count: {
+    about: "a number counting: a train of ticks that speeds up, ending on a settle chime on settleFrame",
+    per10s: "0 to 2 trains",
+    roles: { "count-tick": { search: "counter ticks", seconds: 0.1, volume: [0.2, 0.1] }, "count-settle": { search: "success chime", seconds: 1, volume: [0.45, 0.25] } },
+  },
+  stream: { about: "terminal lines or streamed text: one soft tick per line, at most 6 a second", per10s: "5 to 15", roles: { stream: { search: "glass tap", seconds: 0.5, volume: [0.18, 0.1] } } },
+  assemble: {
+    about: "pieces building up: a rising run of small hits that gets louder, ending on a lock hit",
+    per10s: "0 to 1",
+    roles: { "assemble-run": { search: "counter ticks", seconds: 0.1, volume: [0.25, 0.12] }, "assemble-lock": { search: "soft impact", seconds: 0.7, volume: [0.55, 0.3] } },
+  },
+  resolve: {
+    about: "the logo or the end card: a riser that ends on a chime, with a clear second of nothing before the riser",
+    per10s: "1 per film, at the end",
+    roles: { "resolve-riser": { search: "whoosh buildup", seconds: 1.2, volume: [0.35, 0.2] }, "resolve-chime": { search: "sparkle shimmer", seconds: 1.5, volume: [0.55, 0.3] } },
+  },
+};
+
+// The seconds a key tick may be spaced by at the closest: at most this many a second.
+const MAX_TICKS_PER_SECOND = 12;
+const MAX_STREAM_PER_SECOND = 6;
+
+export type CueOptions = {
+  // The scene's startFrame (or any frame to add) when the events are in a scene's own clock; 0 for absolute frames.
+  offset?: number;
+  fps?: number;
+  // Under a narrator: the quieter levels.
+  voice?: boolean;
+  // A master level multiplied into every cue (default 1).
+  volume?: number;
+  seed?: number;
+  // "resolve" only: how long the riser is in frames (default 36: it ends on the chime).
+  riserFrames?: number;
+};
+
+const level = (kind: CueKind, role: string, o: CueOptions) => CUE_TABLE[kind].roles[role]!.volume[o.voice ? 1 : 0] * (o.volume ?? 1);
+const r3 = (n: number) => Math.round(n * 1000) / 1000;
+
+// Never two cues for one role on the same frame: the later is dropped. Frames are rounded, never below 0, and the cues come out in order.
+function unique(cues: SoundCue[]): SoundCue[] {
+  const seen = new Set<string>();
+  return cues.filter((c) => { const k = `${c.sound}@${c.at}`; if (seen.has(k)) return false; seen.add(k); return true; }).sort((a, b) => a.at - b.at);
+}
+
+// Drops events closer than `gap` frames to the one kept before.
+const spaced = (frames: number[], gap: number): number[] => { const out: number[] = []; for (const f of frames) if (!out.length || f - out[out.length - 1]! >= gap) out.push(f); return out; };
+
+// The cues for one kind of event. `events` are frames in the component's clock (add `offset` to make them absolute):
+//   "type": the frame of every typed character (promptFrames(...).type); ticks on every 2nd or 3rd, a return thock one frame after the last character is typed
+//   "click" | "snap" | "pop": the frames of the events (clickFrames, panelSettleFrame, chapterFrames(...).badges)
+//   "count": [startFrame, settleFrame] (rollStart and settleFrame of CounterRoll): a speeding tick train, then the chime ON settleFrame
+//   "stream": the frame of every line (terminalFrames(...).lines): one soft tick per line, at most 6 a second
+//   "assemble": [startFrame, lockFrame] (assembleProgress start and the frame the last piece lands): a rising run, then the lock ON lockFrame
+//   "resolve": [frame] the frame the logo lands: the riser ends on it and the chime is ON it (use clearBefore to keep the second before the riser silent)
+export function cuesFor(events: readonly number[], kind: CueKind, o: CueOptions = {}): SoundCue[] {
+  if (!CUE_KINDS.includes(kind)) throw new Error(`cuesFor: unknown kind "${kind}". The kinds are: ${CUE_KINDS.join(", ")}.`);
+  const fps = o.fps ?? 30, off = o.offset ?? 0, seed = o.seed ?? 0;
+  const at = (f: number) => Math.max(0, Math.round(f + off));
+  const cue = (f: number, sound: string, volume: number): SoundCue => ({ at: at(f), sound, volume: r3(volume) });
+  const f = [...events].filter(Number.isFinite).sort((a, b) => a - b);
+  if (!f.length) return [];
+  switch (kind) {
+    case "type": {
+      // Every 2nd character, every 3rd if that would be over 12 a second, more if it is still too fast (the typing itself is faster than any key could be).
+      const span = Math.max(1, (f[f.length - 1]! - f[0]!) / fps), per = f.length / span;
+      let every = 2;
+      while (per / every > MAX_TICKS_PER_SECOND) every++;
+      const ticks = f.filter((_, i) => i % every === 0).map((fr, i) => cue(fr, "type-tick", level("type", "type-tick", o) * (0.8 + 0.4 * hash01(i, seed))));
+      return unique([...ticks, cue(f[f.length - 1]! + 1, "type-return", level("type", "type-return", o))]);
+    }
+    case "click": return unique(spaced(f, 3).map((fr) => cue(fr, "click", level("click", "click", o))));
+    case "snap": return unique(spaced(f, 3).map((fr) => cue(fr, "snap", level("snap", "snap", o))));
+    case "pop": return unique(spaced(f, 3).map((fr, i) => cue(fr, "pop", level("pop", "pop", o) * (0.9 + 0.2 * hash01(i, seed)))));
+    case "stream": return unique(spaced(f, Math.ceil(fps / MAX_STREAM_PER_SECOND)).map((fr) => cue(fr, "stream", level("stream", "stream", o))));
+    case "count": case "assemble": {
+      const role = kind === "count" ? ["count-tick", "count-settle"] : ["assemble-run", "assemble-lock"];
+      const start = f[0]!, end = f.length > 1 ? f[f.length - 1]! : f[0]! + fps;
+      const len = Math.max(1, end - start);
+      // The ticks bunch up toward the end (the roll eases out, the build gathers speed): positions (i/n)^0.6 of the way, no closer than the cap allows.
+      const n = Math.min(Math.floor((len / fps) * MAX_TICKS_PER_SECOND), 24);
+      const gap = Math.ceil(fps / MAX_TICKS_PER_SECOND);
+      const frames = spaced(Array.from({ length: n }, (_, i) => Math.round(start + len * ((i + 0.5) / n) ** (kind === "count" ? 0.6 : 1.4))), gap).filter((fr) => end - fr >= gap);
+      const base = level(kind, role[0]!, o);
+      const run = frames.map((fr, i) => cue(fr, role[0]!, kind === "assemble" ? base * (0.5 + 1.0 * (i / Math.max(1, frames.length - 1))) : base * (0.85 + 0.3 * hash01(i, seed))));
+      return unique([...run, cue(end, role[1]!, level(kind, role[1]!, o))]);
+    }
+    case "resolve": {
+      const end = f[0]!, rise = o.riserFrames ?? 36;
+      return unique([cue(Math.max(0, end - rise), "resolve-riser", level("resolve", "resolve-riser", o)), cue(end, "resolve-chime", level("resolve", "resolve-chime", o))]);
+    }
+  }
+}
+
+// Keeps the second of nothing before a resolve: removes every cue that starts in the `seconds` (default 1) before the riser does, and the riser's own span is kept.
+// `frame` is the frame the logo lands (the chime); cues of the resolve itself are never removed.
+export function clearBefore(cues: readonly SoundCue[], frame: number, o: { seconds?: number; fps?: number; riserFrames?: number } = {}): SoundCue[] {
+  const fps = o.fps ?? 30, riserStart = frame - (o.riserFrames ?? 36), from = riserStart - (o.seconds ?? 1) * fps;
+  return cues.filter((c) => c.sound.startsWith("resolve-") || c.at < from || c.at >= frame);
+}

package/src/remotion/kit/theme.ts

@@ -3,6 +3,7 @@ import { loadFont as loadDisplay } from "@remotion/google-fonts/Sora";
 import { loadFont as loadArchivoBlack } from "@remotion/google-fonts/ArchivoBlack";
 import { loadFont as loadBebasNeue } from "@remotion/google-fonts/BebasNeue";
 import { loadFont as loadGreatVibes } from "@remotion/google-fonts/GreatVibes";
+import { loadFont as loadJetBrainsMono } from "@remotion/google-fonts/JetBrainsMono";
 import { loadFont as loadKanit } from "@remotion/google-fonts/Kanit";
 import { loadFont as loadModak } from "@remotion/google-fonts/Modak";
 import { loadFont as loadMontserrat } from "@remotion/google-fonts/Montserrat";
@@ -77,6 +78,7 @@ const loaders = {
   // Genre faces for film-style titles (original designs, not imitations of any film's logo):
   cinzel: () => loadCinzel("normal", { weights: ["700", "900"], ...latin }), // Roman inscription capitals: epic, historical
   playfairDisplay: () => loadPlayfairDisplay("normal", { weights: ["700", "900"], ...latin }), // high-contrast serif: elegant, editorial
+  jetbrainsMono: () => loadJetBrainsMono("normal", { weights: ["400", "700"], ...latin }), // monospace: terminals, code, small labels
   orbitron: () => loadOrbitron("normal", { weights: ["700", "900"], ...latin }), // geometric sci-fi
   rye: () => loadRye("normal", { weights: ["400"], ...latin }), // western poster
   creepster: () => loadCreepster("normal", { weights: ["400"], ...latin }), // horror