reelkit-cli 0.6.0 → 0.8.0

package/src/remotion/kit/Grounds.tsx

@@ -0,0 +1,177 @@
+import React from "react";
+import { AbsoluteFill, Img, OffthreadVideo, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import { auroraBlobs, beamStates, breath, checkItems, grainSeed, gridOffset, gridRows, groundStrength, hueShift, mixHex, plateView, withAlpha, sequenceLayers, videoLayers, type Drift, type SequenceItem, type SequenceTransition } from "./bg-math";
+import { useMedia } from "./media";
+
+const isVideo = (src: string) => /\.(mp4|mov|webm|m4v)(\?|$)/i.test(src);
+
+// What every media ground shares: a dark layer so type stays readable, and a tint laid over at low opacity so a clip or picture takes the film's accent.
+const Finish: React.FC<{ dim: number; tint?: string }> = ({ dim, tint }) => (
+  <>
+    {tint ? <AbsoluteFill style={{ backgroundColor: tint, opacity: 0.18 }} /> : null}
+    {dim > 0 ? <AbsoluteFill style={{ backgroundColor: `rgba(0,0,0,${Math.min(0.8, Math.max(0, dim))})` }} /> : null}
+  </>
+);
+
+type PlateProps = { src: string; scale: number; tx: number; ty: number; blurPx: number; opacity?: number; wipe?: number; loopVideo?: boolean };
+
+// One picture or clip, covering the frame, moved by the given scale and shift. It is drawn muted, always.
+const Plate: React.FC<PlateProps> = ({ src, scale, tx, ty, blurPx, opacity = 1, wipe }) => {
+  const { width, height } = useVideoConfig();
+  const url = useMedia(src);
+  const mask = wipe === undefined ? undefined : `linear-gradient(90deg, #000 ${wipe * 115 - 15}%, transparent ${wipe * 115}%)`;
+  const style: React.CSSProperties = { width: "100%", height: "100%", objectFit: "cover" };
+  return (
+    <AbsoluteFill style={{ opacity, transform: `translate(${tx * width}px, ${ty * height}px) scale(${scale})`, filter: blurPx > 0 ? `blur(${blurPx}px)` : undefined, WebkitMaskImage: mask, maskImage: mask, overflow: "hidden" }}>
+      {isVideo(src) ? <OffthreadVideo src={url} muted style={style} /> : <Img src={url} style={style} />}
+    </AbsoluteFill>
+  );
+};
+
+// A video as the ground, for the whole film or for one scene. dim (0 to 0.8, default 0.35) darkens it so type stays readable; blur is in pixels; zoom is a
+// slow push as a fraction over `durationInFrames` (default the film's length); tint is a colour laid over at low opacity; playbackRate 0.5 is a calmer ground.
+// The clip is always muted. When loop is on (the default) and `durationSec` is given (manifest.background.durationSec), a film longer than the clip starts it
+// again with a short cross-fade over the join, so the restart is not seen; without durationSec the clip plays once and holds its last frame.
+export const BgVideo: React.FC<{ src: string; dim?: number; blur?: number; zoom?: number; tint?: string; loop?: boolean; playbackRate?: number; durationSec?: number; durationInFrames?: number }> = ({
+  src, dim = 0.35, blur = 0, zoom = 0.04, tint, loop = true, playbackRate = 1, durationSec, durationInFrames,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps, width, durationInFrames: total } = useVideoConfig();
+  const view = plateView(frame / Math.max(1, durationInFrames ?? total), { zoom, blurPx: blur, width });
+  const url = useMedia(src);
+  const layers = videoLayers(frame, { clipFrames: durationSec ? (durationSec * fps) / playbackRate : 1, loop: loop && Boolean(durationSec) });
+  const clipFrames = Math.max(1, Math.floor(durationSec ? (durationSec * fps) / playbackRate : 1));
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      <AbsoluteFill style={{ transform: `scale(${view.scale})`, filter: blur > 0 ? `blur(${blur}px)` : undefined }}>
+        {layers.map((l) => (
+          <Sequence key={l.index} from={l.start} durationInFrames={durationSec && loop ? clipFrames : Infinity} layout="none">
+            <AbsoluteFill style={{ opacity: l.opacity }}>
+              <OffthreadVideo src={url} muted playbackRate={playbackRate} style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+            </AbsoluteFill>
+          </Sequence>
+        ))}
+      </AbsoluteFill>
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// One still picture as the ground. It always covers the frame: the pan and the blur never show an edge. zoom is a slow push over its time on screen
+// (default 0.06), drift a slow pan of a few percent, and fit is "cover".
+export const BgImage: React.FC<{ src: string; dim?: number; blur?: number; tint?: string; zoom?: number; drift?: Drift; fit?: "cover"; durationInFrames?: number }> = ({
+  src, dim = 0.35, blur = 0, tint, zoom = 0.06, drift = "none", durationInFrames,
+}) => {
+  const frame = useCurrentFrame();
+  const { width, durationInFrames: total } = useVideoConfig();
+  const v = plateView(frame / Math.max(1, durationInFrames ?? total), { zoom, drift, blurPx: blur, width });
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      <Plate src={src} scale={v.scale} tx={v.tx} ty={v.ty} blurPx={blur} />
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// Several grounds that change smoothly over the film. items are { src, from } (frames, in order, the first visible from frame 0; a video src is drawn too, played once from the start of the film and held on its last frame).
+// The change is centred on `from` unless align is "start"; `transition` is "fade" (default), "blur" (a cross-fade through a blur peak), "wipe" (a soft-edged wipe)
+// or "zoom" (the old one pushes in while the new one settles from slightly larger), over transitionFrames (default 18). Each item keeps its own slow zoom running
+// through the change. dim, blur, tint, zoom and drift are shared, so the film keeps one look. bgPerScene builds items from the scenes.
+export const BgSequence: React.FC<{ items: SequenceItem[]; transition?: SequenceTransition; transitionFrames?: number; align?: "center" | "start"; dim?: number; blur?: number; tint?: string; zoom?: number; drift?: Drift }> = ({
+  items, transition = "fade", transitionFrames = 18, align = "center", dim = 0.35, blur = 0, tint, zoom = 0.06, drift = "none",
+}) => {
+  const frame = useCurrentFrame();
+  const { width } = useVideoConfig();
+  checkItems(items);
+  const layers = sequenceLayers(items, frame, { transition, transitionFrames, align });
+  const peak = transition === "blur" ? 24 : 0;
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      {layers.map((l) => {
+        const v = plateView(l.progress, { zoom, drift, blurPx: blur + peak, width });
+        return <Plate key={l.index} src={items[l.index]!.src} scale={v.scale * l.scale} tx={v.tx} ty={v.ty} blurPx={blur + l.blur * peak} opacity={l.opacity} wipe={l.wipe} />;
+      })}
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// Three large colour fields on the base colour, in the hero colour and its two neighbours on the colour wheel, drifting and crossing: their edges and
+// where they cross show, and they move plainly within two seconds. Radial gradients and one blend mode: cheap. intensity (0 to 1, default 0.6) is how
+// strongly they light the base; Grade and Vignette on top darken a ground, so raise it (0.8) under them.
+export const BgAurora: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const longer = Math.max(width, height), k = groundStrength(intensity);
+  const colors = [hero, hueShift(mixHex(hero, "#ffffff", 0.12), 42), hueShift(mixHex(hero, bg, 0.1), -46)];
+  const peak = [0.95, 0.8, 0.85];
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg, overflow: "hidden" }}>
+      {auroraBlobs(frame, fps, speed).map((b, i) => (
+        <div key={i} style={{
+          position: "absolute", left: b.x * width - b.r * longer, top: b.y * height - b.r * longer, width: b.r * 2 * longer, height: b.r * 2 * longer, mixBlendMode: "screen",
+          background: `radial-gradient(circle closest-side, ${withAlpha(colors[i]!, peak[i]! * k)} 0%, ${withAlpha(colors[i]!, peak[i]! * k * 0.7)} 45%, ${withAlpha(colors[i]!, peak[i]! * k * 0.22)} 80%, ${withAlpha(colors[i]!, 0)} 100%)`,
+        }} />
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+// A perspective grid receding to a horizon and sliding toward the viewer, with a glow where it meets the sky. A few dozen lines in one SVG. intensity (0 to 1,
+// default 0.6) is how bright the lines and the glow are.
+export const BgGrid: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const horizon = height * 0.42, vx = width / 2, rows = gridRows(gridOffset(frame, fps, speed), 16), cols = 15, k = groundStrength(intensity);
+  const line = mixHex(hero, "#ffffff", 0.25);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse 80% 28% at 50% 42%, ${withAlpha(hero, 0.8 * k)} 0%, ${withAlpha(hero, 0)} 100%)` }} />
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        <defs><linearGradient id="rk-grid-fade" gradientUnits="userSpaceOnUse" x1="0" y1={horizon} x2="0" y2={height}><stop offset="0" stopColor={line} stopOpacity="0" /><stop offset="0.3" stopColor={line} stopOpacity={0.55 * k} /><stop offset="1" stopColor={line} stopOpacity={Math.min(1, 1.1 * k)} /></linearGradient></defs>
+        <g stroke="url(#rk-grid-fade)" strokeWidth={Math.max(1.5, width / 420)} fill="none">
+          {rows.map((d, i) => <line key={`r${i}`} x1={0} x2={width} y1={horizon + (height - horizon) * d} y2={horizon + (height - horizon) * d} />)}
+          {Array.from({ length: cols }, (_, i) => { const x = (i / (cols - 1) - 0.5) * width * 3; return <line key={`c${i}`} x1={vx} y1={horizon} x2={vx + x} y2={height} />; })}
+        </g>
+      </svg>
+    </AbsoluteFill>
+  );
+};
+
+// Four wide diagonal beams of light sweeping across the base colour, brightening and dimming, with a glow where they leave the top. They are soft but plainly
+// there: the strongest is about as bright as the hero colour at half strength. intensity (0 to 1, default 0.6) is how bright; Grade and Vignette on top
+// darken a ground, so raise it (0.8) under them.
+export const BgBeams: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const k = groundStrength(intensity), light = mixHex(hero, "#ffffff", 0.2);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg, overflow: "hidden" }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse 90% 40% at 50% -5%, ${withAlpha(hero, 0.7 * k)} 0%, ${withAlpha(hero, 0)} 100%)` }} />
+      {beamStates(frame, fps, speed).map((b, i) => (
+        <div key={i} style={{
+          position: "absolute", left: (0.3 + b.slide) * width - width * 0.2, top: -height * 0.25, width: width * 0.4, height: height * 1.5, transform: `rotate(${b.angle}deg)`, mixBlendMode: "screen",
+          background: `linear-gradient(90deg, ${withAlpha(light, 0)} 0%, ${withAlpha(light, 0.55 * k * b.strength)} 50%, ${withAlpha(light, 0)} 100%)`,
+        }} />
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+// A still ground with a breathing vignette, a soft glow of the hero colour and film grain. The grain steps every few frames by the frame number, so a
+// frame is always the same. intensity (0 to 1, default 0.6) is how strong the glow and the grain are.
+export const BgGrain: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const b = breath(frame, fps, speed), k = groundStrength(intensity);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse at ${50 + 6 * Math.sin((frame / fps) * speed * 0.5)}% ${38 + 4 * b}%, ${withAlpha(hero, 0.55 * k)} 0%, ${withAlpha(hero, 0)} 62%)` }} />
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse at center, rgba(0,0,0,0) 45%, rgba(0,0,0,${0.28 + 0.16 * b}) 100%)` }} />
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0, opacity: 0.06 + 0.1 * k, mixBlendMode: "overlay" }}>
+        <filter id="rk-grain"><feTurbulence type="fractalNoise" baseFrequency="0.8" numOctaves="2" seed={grainSeed(frame)} stitchTiles="stitch" /><feColorMatrix type="saturate" values="0" /></filter>
+        <rect width="100%" height="100%" filter="url(#rk-grain)" />
+      </svg>
+    </AbsoluteFill>
+  );
+};

package/src/remotion/kit/Headline.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+import { continueRender, delayRender, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { Place } from "./Place";
+import { fonts, springs } from "./theme";
+import { inkOn } from "./three-math";
+import { clamp01, headlineFrames, headlineLines, headlineWords, keywordIndex, outCubic } from "./ui-math";
+import { DEFAULT_HERO } from "./ui-theme";
+import { TextInkContext } from "./ImageLayers";
+
+// A headline set heavy: two to five words that come in one by one, with ONE keyword emphasised. `emphasis` is "color" (the keyword in the hero colour),
+// "highlight" (a block of the hero colour sweeps in behind it) or "underline" (a bar draws on under it). `keyword` must be one of the words (case and
+// punctuation ignored) or it throws and lists the words. The text breaks into the fewest lines of about 12 characters and is sized to fill `width` (a fraction
+// of the frame's width, default 0.86): it is measured after layout, so nothing leaves the frame, and at most `maxSize` (a fraction of the width, default
+// 0.2) is used. `delay` and `per` are frames from the component's own mount (0 and 4 frames a word); headlineFrames(text, { delay, per }) gives each word's
+// frame for sound. `ink` is the text colour (default white, or the ink a TextOnImage chose for its zone), `y` the height of its middle as a fraction of the frame (0.5).
+export const Headline: React.FC<{
+  text: string;
+  keyword?: string;
+  emphasis?: "color" | "highlight" | "underline";
+  hero?: string;
+  ink?: string;
+  font?: string;
+  width?: number;
+  maxSize?: number;
+  delay?: number;
+  per?: number;
+  align?: "center" | "left";
+  y?: number;
+}> = ({ text, keyword, emphasis = "color", hero = DEFAULT_HERO, ink: given, font = fonts.display, width: fraction = 0.86, maxSize = 0.2, delay = 0, per = 4, align = "center", y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const fromText = React.useContext(TextInkContext);
+  const ink = given ?? fromText ?? "#f4f4f5";
+  const { fps, width: W } = useVideoConfig();
+  const words = headlineWords(text);
+  const key = keyword === undefined ? -1 : keywordIndex(text, keyword);
+  const lines = React.useMemo(() => headlineLines(words), [text]);
+  const longest = Math.max(...lines.map((l) => l.map((i) => words[i]!).join(" ").length));
+  const target = W * fraction;
+  const estimate = Math.min(W * maxSize, target / (longest * 0.64));
+  const [fit, setFit] = React.useState(1);
+  const fitRef = React.useRef(1);
+  const refs = React.useRef<(HTMLSpanElement | null)[]>([]);
+  const [hold] = React.useState(() => delayRender("headline fit"));
+  // The estimate is corrected once the real letters are laid out (and again when the fonts have arrived, since a face that is not loaded yet measures
+  // narrower), so a face that is wider or narrower than expected still fills the width and never leaves it. The frame waits for the correction.
+  React.useLayoutEffect(() => {
+    let live = true, same = 0, tries = 0, last = -1;
+    const measure = (): number => {
+      const widest = Math.max(...refs.current.map((r) => r?.offsetWidth ?? 0));
+      if (widest > 0 && live) {
+        const next = Math.max(0.3, Math.min((W * maxSize) / estimate, target / (widest / fitRef.current)));
+        fitRef.current = next;
+        setFit(next);
+      }
+      return widest / fitRef.current;
+    };
+    // The face arrives a moment after the first layout (it is added to the page while this runs), so the width is read again until it has stopped changing.
+    const poll = () => {
+      if (!live) return;
+      const natural = Math.round(measure() * 10) / 10;
+      same = natural === last ? same + 1 : 0;
+      last = natural;
+      tries++;
+      if ((same >= 3 && (typeof document === "undefined" || document.fonts.status === "loaded")) || tries > 60) continueRender(hold); else setTimeout(poll, 40);
+    };
+    poll();
+    return () => { live = false; continueRender(hold); };
+  }, [text, font, W, fraction, maxSize, estimate]);
+  const size = estimate * fit;
+  const ev = headlineFrames(text, { delay, per });
+  return (
+    <Place y={y}>
+      <div style={{ width: target, textAlign: align, fontFamily: font, fontWeight: 800, fontSize: size, lineHeight: 1.04, letterSpacing: "-0.025em", color: ink }}>
+        {lines.map((line, li) => (
+          <div key={li} style={{ display: "flex", justifyContent: align === "center" ? "center" : "flex-start" }}>
+            <span ref={(el) => { refs.current[li] = el; }} style={{ display: "inline-flex", whiteSpace: "nowrap", gap: "0.24em" }}>
+              {line.map((wi) => {
+                const land = ev.words[wi]!;
+                const p = spring({ frame: frame - land + 6, fps, config: springs.snappy });
+                const hot = wi === key;
+                const sweep = outCubic(clamp01((frame - land - 3) / 12));
+                const wordInk = hot && emphasis === "color" ? hero : hot && emphasis === "highlight" ? inkOn(hero) : ink;
+                return (
+                  <span key={wi} style={{ position: "relative", display: "inline-block", opacity: clamp01(p * 1.6), transform: `translateY(${(1 - p) * 0.35}em)`, filter: p < 1 ? `blur(${(1 - p) * size * 0.06}px)` : undefined, color: wordInk }}>
+                    {hot && emphasis === "highlight" ? <span style={{ position: "absolute", left: "-0.1em", right: "-0.1em", top: "0.06em", bottom: "0.0em", background: hero, borderRadius: "0.12em", transformOrigin: "0 50%", transform: `scaleX(${sweep})`, zIndex: -1 }} /> : null}
+                    <span style={{ position: "relative" }}>{words[wi]}</span>
+                    {hot && emphasis === "underline" ? <span style={{ position: "absolute", left: 0, bottom: "-0.02em", height: "0.1em", width: `${sweep * 100}%`, background: hero, borderRadius: "0.1em" }} /> : null}
+                  </span>
+                );
+              })}
+            </span>
+          </div>
+        ))}
+      </div>
+    </Place>
+  );
+};

package/src/remotion/kit/Hero3D.tsx

@@ -0,0 +1,197 @@
+import React from "react";
+import { continueRender, delayRender, useCurrentFrame, useVideoConfig } from "remotion";
+import { useThree } from "@react-three/fiber";
+import { CanvasTexture, DoubleSide, ExtrudeGeometry, Shape, ShapeGeometry, SRGBColorSpace, TextureLoader, type BufferGeometry, type Texture } from "three";
+import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
+import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";
+import { useMedia } from "./media";
+import { CameraKeysContext } from "./scene3d-context";
+import { typeface } from "./Text3D";
+import { poseAt, type PoseKey } from "./three-fx-math";
+import { degToRad, mixHex, nearestVisible, type Vec3 } from "./three-math";
+
+const roundRect = (w: number, h: number, r: number): Shape => {
+  const s = new Shape(), x = -w / 2, y = -h / 2, k = Math.min(r, w / 2, h / 2);
+  s.moveTo(x + k, y); s.lineTo(x + w - k, y); s.quadraticCurveTo(x + w, y, x + w, y + k); s.lineTo(x + w, y + h - k); s.quadraticCurveTo(x + w, y + h, x + w - k, y + h);
+  s.lineTo(x + k, y + h); s.quadraticCurveTo(x, y + h, x, y + h - k); s.lineTo(x, y + k); s.quadraticCurveTo(x, y, x + k, y);
+  return s;
+};
+const uvs = (g: ShapeGeometry, w: number, h: number) => { const p = g.attributes.position!, uv = g.attributes.uv!; for (let i = 0; i < p.count; i++) uv.setXY(i, (p.getX(i) + w / 2) / w, (p.getY(i) + h / 2) / h); return g; };
+
+// A soft dark ellipse for the contact shadow, drawn once.
+const shadowTex = (): CanvasTexture => {
+  const c = document.createElement("canvas");
+  c.width = c.height = 256;
+  const g = c.getContext("2d")!, r = g.createRadialGradient(128, 128, 0, 128, 128, 128);
+  r.addColorStop(0, "rgba(0,0,0,0.75)"); r.addColorStop(0.55, "rgba(0,0,0,0.3)"); r.addColorStop(1, "rgba(0,0,0,0)");
+  g.fillStyle = r; g.fillRect(0, 0, 256, 256);
+  const t = new CanvasTexture(c); t.colorSpace = SRGBColorSpace; return t;
+};
+
+// A screen face when there is no screenshot: a gradient of the hero colour and a few soft bars, so a device is never an empty slab.
+const mockTex = (hero: string, aspect: number): CanvasTexture => {
+  const W = 512, H = Math.round(512 / aspect), c = document.createElement("canvas");
+  c.width = W; c.height = H;
+  const g = c.getContext("2d")!, grad = g.createLinearGradient(0, 0, W, H);
+  grad.addColorStop(0, mixHex(hero, "#ffffff", 0.25)); grad.addColorStop(1, mixHex(hero, "#000000", 0.45));
+  g.fillStyle = grad; g.fillRect(0, 0, W, H);
+  g.fillStyle = "rgba(255,255,255,0.9)"; g.beginPath(); g.roundRect(W * 0.1, H * 0.12, W * 0.45, H * 0.04, 12); g.fill();
+  for (let i = 0; i < 5; i++) { g.fillStyle = `rgba(255,255,255,${0.2 - i * 0.02})`; g.beginPath(); g.roundRect(W * 0.1, H * (0.24 + i * 0.13), W * 0.8, H * 0.1, 18); g.fill(); }
+  const t = new CanvasTexture(c); t.colorSpace = SRGBColorSpace; return t;
+};
+
+export type HeroKind = "device" | "logo" | "box" | "coin";
+
+type Built = { geometry: BufferGeometry; glyph?: BufferGeometry; w: number; h: number; d: number; screen?: { w: number; h: number; z: number } };
+// The body of each kind, centred, in its own units, with its size.
+function build(kind: HeroKind, text: string, aspect: number): Built {
+  if (kind === "device") {
+    const w = 1, h = w / aspect, depth = 0.07, g = new ExtrudeGeometry(roundRect(w, h, 0.09 * w), { depth, bevelEnabled: true, bevelThickness: 0.018, bevelSize: 0.018, bevelSegments: 5, curveSegments: 14 });
+    g.translate(0, 0, -depth / 2);
+    return { geometry: g, w: w + 0.04, h: h + 0.04, d: depth + 0.04, screen: { w: w * 0.92, h: h * 0.94, z: depth / 2 + 0.019 } };
+  }
+  if (kind === "logo") {
+    const g = new TextGeometry(text, { font: typeface(), size: 1, depth: 0.28, curveSegments: 8, bevelEnabled: true, bevelThickness: 0.025, bevelSize: 0.02, bevelSegments: 3 });
+    g.computeBoundingBox();
+    const b = g.boundingBox!;
+    g.translate(-(b.max.x + b.min.x) / 2, -(b.max.y + b.min.y) / 2, -0.14);
+    return { geometry: g, w: b.max.x - b.min.x, h: b.max.y - b.min.y, d: 0.34 };
+  }
+  if (kind === "coin") {
+    // A true disc with a raised rim, and the first letter of `text` standing on its face.
+    const disc = new Shape();
+    disc.absarc(0, 0, 0.5, 0, Math.PI * 2, false);
+    const g = new ExtrudeGeometry(disc, { depth: 0.1, bevelEnabled: true, bevelThickness: 0.04, bevelSize: 0.03, bevelSegments: 8, curveSegments: 64 });
+    g.translate(0, 0, -0.05);
+    const glyph = new TextGeometry(text.slice(0, 1) || "R", { font: typeface(), size: 0.5, depth: 0.04, curveSegments: 8, bevelEnabled: true, bevelThickness: 0.008, bevelSize: 0.008, bevelSegments: 2 });
+    glyph.computeBoundingBox();
+    const b = glyph.boundingBox!;
+    glyph.translate(-(b.max.x + b.min.x) / 2, -(b.max.y + b.min.y) / 2, 0.095);
+    return { geometry: g, w: 1.06, h: 1.06, d: 0.2, glyph };
+  }
+  return { geometry: new RoundedBoxGeometry(1, 1, 1, 6, 0.12), w: 1, h: 1, d: 1 };
+}
+
+// The screenshot as a texture, loaded once; the frame waits for it (and for its size, which sets the screen's shape) so it is never drawn empty.
+function useScreenshot(url: string): { texture: Texture | null; aspect: number | undefined } {
+  const [state, setState] = React.useState<{ texture: Texture | null; aspect: number | undefined; url: string }>({ texture: null, aspect: undefined, url: "" });
+  const hold = React.useRef<number | undefined>(undefined);
+  const release = () => { if (hold.current !== undefined) { continueRender(hold.current); hold.current = undefined; } };
+  React.useLayoutEffect(() => {
+    if (!url) { setState({ texture: null, aspect: undefined, url: "" }); return; }
+    if (hold.current === undefined) hold.current = delayRender(`screenshot ${url.slice(0, 40)}`);
+    let live = true;
+    new TextureLoader().load(url, (t) => { t.colorSpace = SRGBColorSpace; const img = t.image as { width: number; height: number }; if (live) setState({ texture: t, aspect: img.width / Math.max(1, img.height), url }); else release(); }, undefined, () => release());
+    return () => { live = false; };
+  }, [url]);
+  // The frame is released only after the texture has been drawn into the scene: two animation frames after it arrived.
+  // While rendering, the canvas draws only when the frame changes, so a texture that arrives later has to be drawn by asking for a frame.
+  const advance = useThree((t) => t.advance);
+  React.useEffect(() => {
+    if (state.texture && state.url === url) { advance(performance.now()); release(); }
+  }, [state, url, advance]);
+  React.useEffect(() => release, []);
+  return { texture: state.texture, aspect: state.aspect };
+}
+
+const Picture: React.FC<{ texture: Texture; w: number; h: number; opacity?: number }> = ({ texture, w, h, opacity = 1 }) => {
+  const g = React.useMemo(() => uvs(new ShapeGeometry(roundRect(w, h, 0.05), 12), w, h), [w, h]);
+  return <mesh geometry={g}><meshBasicMaterial map={texture} toneMapped={false} transparent={opacity < 1} opacity={opacity} /></mesh>;
+};
+
+// A studio-lit hero: one object, lit like a product shot. `kind` is "device" (a rounded slab with a screen that shows `src`, a screenshot; without it a designed
+// screen), "logo" (`text`, a short word or a single letter, extruded in the kit's typeface), "box" or "coin". Physical material with a clearcoat in `hero`, a key light
+// and two coloured rim lights (`rim1`, `rim2`, by default the hero colour turned toward blue and toward pink). `floor` is "soft" (a contact shadow, default), "mirror"
+// (a flipped, faded copy below) or "none". `spin` is how many degrees a second it turns about the vertical (12 for a logo, box or coin; a device sways by that many
+// degrees instead) and `hover` how much it bobs, 0 to 1 (0.5). It fits the frame by default (`fit`, 0.7, at the closest the camera comes). `poses` are keys {
+// frame, rotation (degrees), position, scale} that re-pose it, the same timing as Camera: one hero carried across scenes. `aspect` is a device's width over height
+// (the screenshot's own when `src` is given, else 0.5).
+export const Hero3D: React.FC<{
+  kind?: HeroKind;
+  src?: string;
+  text?: string;
+  hero?: string;
+  rim1?: string;
+  rim2?: string;
+  floor?: "soft" | "mirror" | "none";
+  spin?: number;
+  hover?: number;
+  fit?: number;
+  aspect?: number;
+  poses?: PoseKey[];
+  lights?: boolean;
+  position?: Vec3;
+}> = ({ kind = "box", src, text = "R", hero = "#7C3AED", rim1, rim2, floor = "soft", spin, hover = 0.5, fit = 0.7, aspect, poses, lights = true, position = [0, 0, 0] }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const url = useMedia(src ?? "");
+  const shot = useScreenshot(src ? url : "");
+  const natural = shot.aspect;
+  const ratio = aspect ?? natural ?? 0.5;
+  const built = React.useMemo(() => build(kind, text.slice(0, 10), ratio), [kind, text, ratio]);
+  React.useEffect(() => () => built.geometry.dispose(), [built]);
+  const view = nearestVisible(keys, width / height, position[2]);
+  // Fit with room for the turn: a thing that spins is as wide as its width and its depth.
+  const reach = Math.max(built.w, kind === "device" ? built.w : built.d * 0.6 + built.w * 0.6);
+  const base = Math.min((fit * view.width) / reach, (fit * view.height) / built.h);
+  const pose = poseAt(poses, frame, fps);
+  const t = frame / fps;
+  const turn = spin ?? (kind === "device" ? 8 : 12);
+  const yaw = kind === "device" ? Math.sin(t * 0.9) * turn : t * turn;
+  const bob = Math.sin(t * 1.7) * 0.035 * hover * base * built.h;
+  const r1 = rim1 ?? mixHex(hero, "#2a6bff", 0.55), r2 = rim2 ?? mixHex(hero, "#ff3aa8", 0.55);
+  const shadow = React.useMemo(shadowTex, []);
+  const mock = React.useMemo(() => (kind === "device" && !src ? mockTex(hero, ratio) : undefined), [kind, src, hero, ratio]);
+  const metal = kind === "coin" ? 0.85 : kind === "logo" ? 0.35 : 0.2;
+  const body = (opacity: number) => (
+    <group>
+      <mesh geometry={built.geometry}>
+        <meshPhysicalMaterial color={kind === "device" ? mixHex(hero, "#101018", 0.8) : hero} roughness={kind === "coin" ? 0.28 : 0.34} metalness={metal} clearcoat={1} clearcoatRoughness={0.12} transparent={opacity < 1} opacity={opacity} />
+      </mesh>
+      {built.glyph ? (
+        <mesh geometry={built.glyph}>
+          <meshPhysicalMaterial color={mixHex(hero, "#ffffff", 0.45)} roughness={0.25} metalness={0.9} clearcoat={1} clearcoatRoughness={0.1} transparent={opacity < 1} opacity={opacity} />
+        </mesh>
+      ) : null}
+      {kind === "device" && built.screen ? (
+        <group position={[0, 0, built.screen.z]}>
+          {src ? (shot.texture ? <Picture texture={shot.texture} w={built.screen.w} h={built.screen.h} opacity={opacity} /> : null) : mock ? <mesh geometry={uvs(new ShapeGeometry(roundRect(built.screen.w, built.screen.h, 0.05), 12), built.screen.w, built.screen.h)}><meshBasicMaterial map={mock} toneMapped={false} transparent={opacity < 1} opacity={opacity} /></mesh> : null}
+          {/* The sheen: a pale band that crosses the glass once, early, and stays inside it. */}
+          <mesh position={[(Math.min(1, Math.max(0, (frame - 10) / 40)) - 0.5) * built.screen.w * 0.9, 0, 0.002]} scale={[built.screen.w * 0.16, built.screen.h * 0.98, 1]}>
+            <planeGeometry args={[1, 1]} />
+            <meshBasicMaterial color="#ffffff" transparent opacity={0.14 * opacity * (frame < 10 || frame > 50 ? 0 : Math.sin(Math.PI * ((frame - 10) / 40)))} depthWrite={false} side={DoubleSide} />
+          </mesh>
+        </group>
+      ) : null}
+    </group>
+  );
+  const floorY = -(built.h / 2) * base - 0.06 * base;
+  return (
+    <group position={[position[0] + pose.position[0], position[1] + pose.position[1] + bob, position[2] + pose.position[2]]} scale={pose.scale}>
+      {lights ? (
+        <>
+          <directionalLight position={[3, 5, 6]} intensity={2.2} />
+          <pointLight position={[-3.5, 1, -3]} color={r1} intensity={55} distance={14} />
+          <pointLight position={[3.5, 1.5, -3]} color={r2} intensity={55} distance={14} />
+        </>
+      ) : null}
+      <group rotation={[degToRad(pose.rotation[0]), degToRad(pose.rotation[1] + yaw), degToRad(pose.rotation[2])]} scale={base}>{body(1)}</group>
+      {floor === "soft" ? (
+        <mesh position={[0, floorY, 0]} rotation={[-Math.PI / 2, 0, 0]} scale={[base * built.w * 1.8, base * Math.max(built.d, built.w * 0.5) * 1.6, 1]}>
+          <planeGeometry args={[1, 1]} />
+          <meshBasicMaterial map={shadow} transparent depthWrite={false} toneMapped={false} />
+        </mesh>
+      ) : null}
+      {floor === "mirror" ? (
+        <group position={[0, floorY * 2 - 0.0, 0]} scale={[1, -1, 1]}>
+          <group rotation={[degToRad(pose.rotation[0]), degToRad(pose.rotation[1] + yaw), degToRad(pose.rotation[2])]} scale={base}>{body(0.2)}</group>
+        </group>
+      ) : null}
+    </group>
+  );
+};
+
+// A tilted screen in 3D carrying a screenshot (`src`) or a designed mock, with a bezel, a shadow and a sheen: the interface carried across scenes. It is Hero3D kind="device"
+// with no spin (a gentle sway of 5 degrees), so give it `poses` to re-pose the one screen at each scene. Same props as Hero3D otherwise.
+export const Screen3D: React.FC<Omit<React.ComponentProps<typeof Hero3D>, "kind" | "text">> = (props) => <Hero3D kind="device" spin={5} {...props} />;

package/src/remotion/kit/HudOverlay.tsx

@@ -0,0 +1,52 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { font as loadFont } from "./theme";
+import { rgba } from "./ui-theme";
+import { timecode } from "./ui-math";
+
+// A thin layer of instrument decoration that sits over a scene: corner brackets, two to four small monospace labels in the corners (your own words: a
+// version, a place, a status; they fill top left, top right, bottom left, bottom right in that order), a running timecode from the frame (it takes the next
+// free corner; `timecode={false}` for none) and faint scan lines with a slow band. Labels are never smaller than 0.022 of the frame's width (24 px at 1080
+// wide). `ink` is the colour of everything (default white), `hero` the small recording dot. Cheap: no images, no filters.
+export const HudOverlay: React.FC<{
+  labels?: string[];
+  timecode?: boolean;
+  scanlines?: boolean;
+  hero?: string;
+  ink?: string;
+  font?: string;
+  inset?: number;
+}> = ({ labels = [], timecode: showCode = true, scanlines = true, hero = "#ff4d4d", ink = "#ffffff", font, inset = 0.05 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W, height: H } = useVideoConfig();
+  const mono = font ?? loadFont("jetbrainsMono");
+  const m = W * inset, arm = W * 0.07, t = Math.max(3, W * 0.0035);
+  const items = labels.slice(0, 4);
+  if (showCode && items.length < 4) items.push(timecode(frame, fps));
+  const fs = Math.max(W * 0.024, 24);
+  const corner = (i: number): React.CSSProperties => [
+    { left: m, top: m }, { right: m, top: m, textAlign: "right" as const }, { left: m, bottom: m }, { right: m, bottom: m, textAlign: "right" as const },
+  ][i]!;
+  const bracket = (i: number): React.CSSProperties => {
+    const left = i % 2 === 0, top = i < 2;
+    return { position: "absolute", [left ? "left" : "right"]: m * 0.45, [top ? "top" : "bottom"]: m * 0.45, width: arm, height: arm, [left ? "borderLeft" : "borderRight"]: `${t}px solid ${rgba(ink, 0.85)}`, [top ? "borderTop" : "borderBottom"]: `${t}px solid ${rgba(ink, 0.85)}` };
+  };
+  const band = ((frame * 5) % (H * 1.4)) - H * 0.2;
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none", fontFamily: mono, color: ink }}>
+      {scanlines ? (
+        <>
+          <AbsoluteFill style={{ backgroundImage: `repeating-linear-gradient(0deg, ${rgba(ink, 0.045)} 0px, ${rgba(ink, 0.045)} 2px, transparent 2px, transparent 5px)` }} />
+          <div style={{ position: "absolute", left: 0, right: 0, top: band, height: H * 0.12, background: `linear-gradient(180deg, transparent, ${rgba(ink, 0.05)}, transparent)` }} />
+        </>
+      ) : null}
+      {[0, 1, 2, 3].map((i) => <div key={i} style={bracket(i)} />)}
+      {items.map((label, i) => (
+        <div key={i} style={{ position: "absolute", ...corner(i), margin: i < 2 ? `${W * 0.012}px ${W * 0.03}px` : `${W * 0.012}px ${W * 0.03}px`, fontSize: fs, fontWeight: 700, letterSpacing: "0.08em", textTransform: "uppercase", opacity: 0.88, display: "flex", alignItems: "center", gap: fs * 0.5, flexDirection: i % 2 ? "row-reverse" : "row" }}>
+          {i === 0 ? <span style={{ width: fs * 0.55, height: fs * 0.55, borderRadius: 999, background: hero, opacity: Math.floor(frame / 15) % 2 ? 0.25 : 1 }} /> : null}
+          <span style={{ fontVariantNumeric: "tabular-nums" }}>{label}</span>
+        </div>
+      ))}
+    </AbsoluteFill>
+  );
+};

package/src/remotion/kit/ImageLayers.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { useMedia } from "./media";
+import { layerMoves, type ImageLayersRecord } from "./image-layers-math";
+
+// What ImageLayers shares with the TextOnImage inside it: the picture's layers, and the element the words go into when they must sit in front of the subject.
+export const ImageLayersContext = React.createContext<{ layers?: ImageLayersRecord; frontRoot: HTMLElement | null } | undefined>(undefined);
+// The ink a TextOnImage chose for its zone, which a Headline inside it takes unless it is given one.
+export const TextInkContext = React.createContext<string | undefined>(undefined);
+
+const fill = (scale: number, tx: number, ty: number, w: number, h: number): React.CSSProperties => ({ transform: `translate(${tx * w}px, ${ty * h}px) scale(${scale})` });
+
+// A picture in layers, with the words as a layer OF the picture. It draws the back picture, then `children` (the middle layer: your words), then the subject cut out
+// of the same picture, then `front`, so a headline can pass BEHIND the subject. Pass `layers` (the manifest scene's imageLayers, from `reelkit assets layers`) or
+// `back` and `subject` yourself; without a subject it is one flat picture with the words over it, and nothing fails. Depth comes from the frame: the back drifts and
+// grows slowly, the subject moves more and the other way (`depth`, 0 to 1, default 0.4; 0 moves them together), and the words between them at their own rate.
+// `focus` softly blurs the other layer ("subject" blurs the back, "back" blurs the subject). Every layer covers the frame at every frame, so no edge is shown.
+// Put a TextOnImage in it for words that sit where the picture is calm.
+export const ImageLayers: React.FC<{
+  layers?: ImageLayersRecord;
+  back?: string;
+  subject?: string;
+  depth?: number;
+  focus?: "subject" | "back";
+  front?: React.ReactNode;
+  children?: React.ReactNode;
+}> = ({ layers, back, subject, depth = 0.4, focus, front, children }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const backSrc = useMedia(back ?? layers?.back ?? ""), subjectSrc = useMedia(subject ?? layers?.subject ?? "");
+  const hasSubject = Boolean(subject ?? layers?.subject);
+  const m = layerMoves(frame, fps, depth);
+  const blur = Math.round(width * 0.006 * 10) / 10;
+  const [frontRoot, setFrontRoot] = React.useState<HTMLElement | null>(null);
+  const img: React.CSSProperties = { width: "100%", height: "100%", objectFit: "cover", display: "block" };
+  const ctx = React.useMemo(() => ({ layers: layers ?? (back ? { back, subject, textZone: { region: "bottom" as const, luminance: 0.3, busy: 0.5 } } : undefined), frontRoot }), [layers, back, subject, frontRoot]);
+  return (
+    <ImageLayersContext.Provider value={ctx}>
+      <AbsoluteFill style={{ overflow: "hidden" }}>
+        {backSrc ? <AbsoluteFill style={{ ...fill(m.back.scale, m.back.tx, m.back.ty, width, height), filter: focus === "subject" ? `blur(${blur}px)` : undefined }}><img src={backSrc} style={img} /></AbsoluteFill> : null}
+        <AbsoluteFill style={{ ...fill(m.text.scale, m.text.tx, m.text.ty, width, height) }}>{children}</AbsoluteFill>
+        {hasSubject && subjectSrc ? <AbsoluteFill style={{ ...fill(m.subject.scale, m.subject.tx, m.subject.ty, width, height), filter: focus === "back" ? `blur(${blur}px)` : undefined }}><img src={subjectSrc} style={img} /></AbsoluteFill> : null}
+        <AbsoluteFill ref={setFrontRoot as never} />
+        {front ? <AbsoluteFill>{front}</AbsoluteFill> : null}
+      </AbsoluteFill>
+    </ImageLayersContext.Provider>
+  );
+};

package/src/remotion/kit/Music.tsx

@@ -1,11 +1,11 @@
 import React from "react";
 import { Audio, useVideoConfig } from "remotion";
-import { musicVolume, speechSpans, type SpeechScene } from "./music-math";
+import { DEFAULT_DUCK_TO, DEFAULT_MUSIC_VOLUME, musicVolume, speechSpans, type MusicDip, type SpeechScene } from "./music-math";
 import { useGain, useManifest, useMedia } from "./media";
 
 // The video's music track. Place it once, outside the scenes. It sits at `duckTo` while the voiceover is heard and comes up to `volume`
-// in the gaps, loops when the video is longer than the track, and fades out over the last second. `scenes` defaults to the manifest's.
-export const Music: React.FC<{ src: string; volume?: number; duckTo?: number; scenes?: SpeechScene[] }> = ({ src, volume = 0.5, duckTo = 0.12, scenes }) => {
+// in real pauses (a gap of 1.2 s or more: it rises over 0.4 s and is back down 0.25 s before the next word), drops to a dip's volume inside each of `dips` (absolute frames: a rest before the big moment), loops when the video is longer than the track, and fades out over the last second. `scenes` defaults to the manifest's.
+export const Music: React.FC<{ src: string; volume?: number; duckTo?: number; scenes?: SpeechScene[]; dips?: MusicDip[] }> = ({ src, volume = DEFAULT_MUSIC_VOLUME, duckTo = DEFAULT_DUCK_TO, scenes, dips }) => {
   const { fps, durationInFrames } = useVideoConfig();
   const manifest = useManifest();
   const gain = useGain(src);
@@ -13,7 +13,7 @@ export const Music: React.FC<{ src: string; volume?: number; duckTo?: number; sc
   return (
     <Audio
       src={useMedia(src)} loop loopVolumeCurveBehavior="extend"
-      volume={(f) => musicVolume(f, { fps, totalFrames: durationInFrames, volume, duckTo, spans, gain })}
+      volume={(f) => musicVolume(f, { fps, totalFrames: durationInFrames, volume, duckTo, spans, gain, dips })}
     />
   );
 };