@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/templates/default/openvidstudio-core/src/handheld.tsx

@@ -0,0 +1,116 @@
+// Handheld sway and impact shake: small, deterministic camera motion on top of a move.
+// A locked-off camera on a screenshot reads as a slideshow; a few pixels of drift reads as a person
+// holding the camera. Both effects are pure functions of the frame (never Math.random, which would
+// differ per render process and flicker), so the same frame is the same everywhere.
+
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+export interface ShakeOffset {
+  /** Horizontal and vertical offset in px. */
+  x: number;
+  y: number;
+  /** Roll in degrees. */
+  rot: number;
+}
+
+/** Roll, in degrees, that goes with each px of sway or shake. Small: a camera rolls far less than it shifts. */
+export const HANDHELD_ROLL_PER_PX = 0.03;
+export const SHAKE_ROLL_PER_PX = 0.04;
+/** Peak shake in px at 1080p, and the time constant (in frames) the hit dies away with. */
+export const DEFAULT_SHAKE_AMPLITUDE = 12;
+export const DEFAULT_SHAKE_DECAY = 8;
+
+const TAU = Math.PI * 2;
+
+/** A stable pseudo-random phase in [0, 2pi) for a seed and an axis. */
+const phase = (seed: number, axis: number): number => {
+  const x = Math.sin(seed * 127.1 + axis * 311.7) * 43758.5453;
+  return (x - Math.floor(x)) * TAU;
+};
+
+/**
+ * Handheld sway at a frame. Each axis is two sines at unrelated frequencies (0.11 and 0.28 rad per
+ * frame, about 0.5 Hz and 1.3 Hz at 30 fps), so the path never visibly repeats and the axes do not
+ * move in lockstep. `amount` is the largest offset in px, `seed` picks a different path.
+ */
+export const handheldOffset = (frame: number, amount: number, seed = 1): ShakeOffset => {
+  const axis = (k: number, slow: number, fast: number) =>
+    0.62 * Math.sin(frame * slow + phase(seed, k)) + 0.38 * Math.sin(frame * fast + phase(seed, k + 1));
+  return {
+    x: amount * axis(0, 0.113, 0.277),
+    y: amount * axis(2, 0.137, 0.331),
+    rot: amount * HANDHELD_ROLL_PER_PX * axis(4, 0.091, 0.223),
+  };
+};
+
+/**
+ * 1 where sway runs freely, 0 inside any `holds` window ([from, to] inclusive, in frames), and a
+ * smooth ramp over `ramp` frames on either side. A hold is the moment the camera is "set down":
+ * a cursor click, a text block the viewer has to read.
+ */
+export const holdWeight = (frame: number, holds: [number, number][] = [], ramp = 6): number => {
+  let weight = 1;
+  for (const [from, to] of holds) {
+    if (frame >= from && frame <= to) return 0;
+    const distance = frame < from ? from - frame : frame - to;
+    const t = Math.min(1, distance / ramp);
+    weight = Math.min(weight, t * t * (3 - 2 * t));
+  }
+  return weight;
+};
+
+/**
+ * Handheld sway for the current frame, scaled for the composition height (`amount` is px at 1080p)
+ * and eased to exactly zero inside the `holds` windows.
+ */
+export const useHandheld = (
+  amount: number,
+  options: { holds?: [number, number][]; seed?: number; ramp?: number } = {},
+): ShakeOffset => {
+  const frame = useCurrentFrame();
+  const { height } = useVideoConfig();
+  const weight = holdWeight(frame, options.holds, options.ramp);
+  const k = height / 1080;
+  const o = handheldOffset(frame, amount, options.seed ?? 1);
+  return { x: o.x * weight * k, y: o.y * weight * k, rot: o.rot * weight };
+};
+
+/**
+ * Shake from impacts at the given frames. Before an impact it contributes exactly nothing; on the
+ * impact frame it is at full `amplitude` (px); after that it rings at about 9 Hz while a decaying
+ * envelope (time constant `decay` frames) takes it below 5% of the amplitude by 3 x decay.
+ * Each impact kicks in its own direction, taken from its frame number.
+ */
+export const impactShake = (
+  frame: number,
+  impactFrames: number[],
+  options: { amplitude?: number; decay?: number } = {},
+): ShakeOffset => {
+  const amplitude = options.amplitude ?? DEFAULT_SHAKE_AMPLITUDE;
+  const decay = Math.max(1, options.decay ?? DEFAULT_SHAKE_DECAY);
+  let x = 0;
+  let y = 0;
+  let rot = 0;
+  for (const hit of impactFrames) {
+    const age = frame - hit;
+    if (age < 0) continue;
+    const swing = amplitude * Math.exp(-age / decay) * Math.cos(age * 1.9);
+    const dir = phase(hit, 7);
+    x += swing * Math.cos(dir);
+    y += swing * Math.sin(dir);
+    rot += swing * SHAKE_ROLL_PER_PX * (Math.sin(dir) >= 0 ? 1 : -1);
+  }
+  return { x, y, rot };
+};
+
+/** Impact shake for the current frame, scaled for the composition height. */
+export const useImpactShake = (
+  impactFrames: number[],
+  options: { amplitude?: number; decay?: number } = {},
+): ShakeOffset => {
+  const frame = useCurrentFrame();
+  const { height } = useVideoConfig();
+  const s = impactShake(frame, impactFrames, options);
+  const k = height / 1080;
+  return { x: s.x * k, y: s.y * k, rot: s.rot };
+};

package/templates/default/openvidstudio-core/src/index.ts

@@ -2,23 +2,54 @@
 // scenes in the openvidstudio house style: camera rig, motion helpers, SFX,
 // look pass, design tokens, and the shared scene/UI components.
 
+// Local, offline Inter/JetBrains Mono loading (A2): every scene imports from this
+// index, so importing it here means every render gets bundled fonts with zero
+// network access, instead of the @remotion/google-fonts loaders that used to be
+// scattered across TerminalReplay/RepoCta/ChecklistPanel.
+import "./localFonts";
+
 // Camera + layers
-export { CameraRig, Layer, useCamera } from "./camera";
-export type { CamKeyframe } from "./camera";
+export { CameraRig, Layer, useCamera, resolveCamera, projectToScreen, Z_STEP } from "./camera";
+export type { CamKeyframe, CameraInfo } from "./camera";
+
+// Directed shot: a flat capture turned into a push-in with tilt, depth of field and a cursor (C4)
+export { DirectedShot, directedKeyframes } from "./DirectedShot";
+export type { DirectedShotProps, DirectedKeyframeOptions, CaptureRect } from "./DirectedShot";
+
+// Cinematic shots (camera half): the shot vocabulary
+export { resolveShot, SHOT_NAMES } from "./shots";
+export type { ShotName, ShotOptions, ResolvedShot } from "./shots";
+
+// Cinematic shots (camera half): layered shots and motion blur
+export { LayeredShot } from "./LayeredShot";
+export type { LayeredShotProps, LayerManifest, ShotLayer } from "./LayeredShot";
+export { MotionBlur } from "./motionBlur";
+export type { MotionBlurOptions } from "./motionBlur";
+
+// Cinematic shots (camera half): handheld sway and impact shake
+export { handheldOffset, holdWeight, useHandheld, impactShake, useImpactShake } from "./handheld";
+export type { ShakeOffset } from "./handheld";
+
+// Music-first timing: the score's grid as scene-local frames (C3)
+export { MusicClockProvider, useMusicClock, createMusicClock } from "./musicClock";
+export { NarrationWordsProvider, useNarrationWords, createNarrationWords } from "./narrationWords";
+export type { NarrationWord, NarrationWords, WordAt } from "./narrationWords";
+export type { MusicCues, MusicClock } from "./musicClock";
 
 // Motion helpers
 export { E, SPRING, tween, pop, jitter, staggerDelay } from "./motion";
 
 // SFX
 export {
-  KeySound,
   TypingSfx,
   Click,
   Whoosh,
   Blip,
   SuccessChime,
   Bell,
-  EnterKey,
+  SoftClick,
+  Bong,
+  Drop,
   MusicBed,
 } from "./sfx";
 
@@ -26,7 +57,18 @@ export {
 export { FilmGrain, Vignette, ColorGrade, LookPass } from "./look";
 
 // Design tokens
-export { color, font, glow, panelShadow, radius } from "./tokens";
+export {
+  color, font, glow, panelShadow, radius,
+  applyBrand, brandAssets, monoStack, uiStack,
+} from "./tokens";
+export type { Brand } from "./tokens";
+
+// Design system as code (C2)
+export {
+  defineDesignSystem, contrastRatio,
+  DEFAULT_TYPE_SCALE, DEFAULT_GRID, DEFAULT_MOTION, DEFAULT_TEXTURE, DEFAULT_TRANSITIONS,
+} from "./designSystem";
+export type { DesignSystem, TypeScale, LayoutGrid, MotionPersonality, CameraEnergy, Motif, Texture } from "./designSystem";
 
 // Scene wrapper
 export { CinematicScene } from "./CinematicScene";
@@ -35,7 +77,8 @@ export { CinematicScene } from "./CinematicScene";
 export { BrowserFrame } from "./DeviceFrame";
 
 // Kinetic typography
-export { TitleSlam, Caption } from "./KineticText";
+export { TitleSlam, Caption, captionLayout } from "./KineticText";
+export type { CaptionPosition, CaptionRect } from "./KineticText";
 
 // Terminal replay
 export {
@@ -53,8 +96,27 @@ export { ChecklistPanel } from "./ChecklistPanel";
 export type { ChecklistItem } from "./ChecklistPanel";
 
 // Cursor actor
-export { CursorActor } from "./CursorActor";
+export { CursorActor, cursorPositionAt } from "./CursorActor";
 export type { CursorKeyframe } from "./CursorActor";
 
 // Repo CTA scene
 export { RepoCta } from "./RepoCta";
+
+// Kinetic text primitives (C4)
+export { Words, useTyped, Caret } from "./kinetic";
+
+// Pixel-grid family: dot-matrix text, logo assembler, wipe transition (C4)
+export { DotText, PixelLogo, PixelWipe } from "./pixel";
+export type { PixelShape } from "./pixel";
+
+// Backgrounds and transition primitives (C4)
+export { Atmosphere, DotGrid, Flash, Black, Letterbox } from "./atmosphere";
+
+// UI chrome: windows, JSON viewer, tool chips, badges, glass panel, chapter HUD (C4)
+export { Window, JsonView, Check, Cross, ToolChip, Pill, Glass, ChapterHud } from "./panels";
+export type { Chapter } from "./panels";
+
+// Transition overlays drawn over a hard cut by stitch_composition, so a beat's `transition`
+// field changes the picture without moving any beat boundary
+export { TransitionOverlay, TRANSITION_TYPES, transitionEnvelope } from "./TransitionOverlay";
+export type { TransitionType } from "./TransitionOverlay";

package/templates/default/openvidstudio-core/src/kinetic.tsx

@@ -0,0 +1,152 @@
+// Kinetic text primitives: masked per-word reveals and a typing effect. Ported from
+// reference/launch-video's lib/type.tsx (the openvidstudio launch video's own scene
+// library) and generalized: no hardcoded video palette, and the word stagger can come
+// from a video's own DesignSystem instead of a fixed constant.
+
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import type { DesignSystem } from "./designSystem";
+import { E, tween } from "./motion";
+import { color, uiStack } from "./tokens";
+
+/**
+ * Per-word masked text reveal. Never a plain opacity fade (STYLE.md): each word clips in
+ * from below on its own stagger delay, and -- if `out` is set -- clips back out the same
+ * way. `accent` recolors (and glows) individual words by index, for a line that needs one
+ * word to land harder than the rest.
+ */
+export const Words: React.FC<{
+  text: string;
+  /** frame the first word starts revealing */
+  at: number;
+  /** frame the exit starts. Omit to leave the line on screen. */
+  out?: number;
+  size?: number;
+  weight?: number;
+  color?: string;
+  /** word index -> accent color for just that word */
+  accent?: Record<number, string>;
+  /**
+   * Frames between word starts. Explicit `stagger` always wins. Otherwise, when `design`
+   * is passed, this reads `design.motion.staggerMs` and converts it to frames at the
+   * composition's own fps, so a video's motion personality (DEFAULT_MOTION.staggerMs is
+   * 60ms) drives every `Words` call instead of a value copied by hand into each one.
+   * With neither, falls back to a plain 3 frame stagger.
+   */
+  stagger?: number;
+  design?: DesignSystem;
+  align?: "left" | "center" | "right";
+  font?: string;
+  tracking?: string;
+  lineHeight?: number;
+  maxWidth?: number;
+  glow?: string;
+  italic?: boolean;
+  style?: React.CSSProperties;
+}> = ({
+  text,
+  at,
+  out,
+  size = 72,
+  weight = 800,
+  color: textColor = color.textPrimary,
+  accent = {},
+  stagger,
+  design,
+  align = "left",
+  font,
+  tracking = "-0.035em",
+  lineHeight = 1.08,
+  maxWidth,
+  glow,
+  italic,
+  style,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const effectiveStagger =
+    stagger ?? (design ? Math.max(1, Math.round((design.motion.staggerMs / 1000) * fps)) : 3);
+  const effectiveFont = font ?? uiStack();
+  if (frame < at) return null;
+  if (out !== undefined && frame > out + 14) return null;
+  const words = text.split(" ");
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        justifyContent: align === "center" ? "center" : align === "right" ? "flex-end" : "flex-start",
+        columnGap: size * 0.26,
+        rowGap: size * 0.02,
+        fontFamily: effectiveFont,
+        fontWeight: weight,
+        fontSize: size,
+        letterSpacing: tracking,
+        lineHeight,
+        color: textColor,
+        maxWidth,
+        fontStyle: italic ? "italic" : undefined,
+        ...style,
+      }}
+    >
+      {words.map((w, i) => {
+        const d = at + i * effectiveStagger;
+        const p = tween(frame, [d, d + 11], [0, 1], E.snap);
+        const o = out !== undefined ? tween(frame, [out + i * 1.5, out + i * 1.5 + 9], [0, 1], E.whip) : 0;
+        const c = accent[i] ?? textColor;
+        return (
+          <span key={i} style={{ display: "inline-block", overflow: "hidden", paddingBottom: size * 0.12, marginBottom: -size * 0.12 }}>
+            <span
+              style={{
+                display: "inline-block",
+                transform: `translateY(${(1 - p) * 105 - o * 105}%)`,
+                color: c,
+                textShadow: glow || accent[i] ? `0 0 ${size * 0.35}px ${(accent[i] ?? glow) + "55"}` : undefined,
+              }}
+            >
+              {w}
+            </span>
+          </span>
+        );
+      })}
+    </div>
+  );
+};
+
+/**
+ * Typewriter hook: returns the visible slice of `text` at the current frame plus the
+ * per-character reveal frames, so a caller can drive `TypingSfx` (from ./sfx) off the same
+ * numbers the visible text uses, keeping sound and motion frame-exact.
+ */
+export const useTyped = (text: string, at: number, cps = 22) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const fpc = fps / cps;
+  const charFrames = Array.from({ length: text.length }, (_, i) =>
+    Math.round(at + i * fpc + (Math.sin(i * 12.9898) * 0.5 + 0.5) * fpc * 0.5),
+  );
+  const n = charFrames.filter((f) => f <= frame).length;
+  return { visible: text.slice(0, n), done: n >= text.length, charFrames, end: charFrames[charFrames.length - 1] ?? at };
+};
+
+/** Blinking text caret, sized to a line height. Pair with `useTyped` for a typed line. */
+export const Caret: React.FC<{ h?: number; color?: string; blink?: boolean }> = ({
+  h = 40,
+  color: caretColor = color.textPrimary,
+  blink = true,
+}) => {
+  const frame = useCurrentFrame();
+  const on = !blink || Math.floor(frame / 9) % 2 === 0;
+  return (
+    <span
+      style={{
+        display: "inline-block",
+        width: h * 0.5,
+        height: h,
+        background: on ? caretColor : "transparent",
+        verticalAlign: "text-bottom",
+        marginLeft: 4,
+      }}
+    />
+  );
+};

package/templates/default/openvidstudio-core/src/localFonts.ts

@@ -0,0 +1,67 @@
+// Local, offline font loading (A2). @remotion/google-fonts' loaders fetch
+// fonts.gstatic.com at module load time; every scaffolded scene imports from this
+// package's index, so a render with no network access crashes before it ever gets to
+// a frame. This module instead loads bundled woff2 files (Inter + JetBrains Mono,
+// sourced from the @fontsource/inter and @fontsource/jetbrains-mono npm packages, see
+// packages/core/scripts/gen-fonts.sh) from the scaffolded project's own public/fonts/
+// via `FontFace`, gated on Remotion's delayRender/continueRender so a render always
+// waits for the real glyphs instead of racing them.
+//
+// Import once, for its side effect, from index.ts. Every other module that used to
+// call `loadFont(...)` from @remotion/google-fonts now just references the family by
+// name ("Inter, system-ui, sans-serif" / "JetBrains Mono, ui-monospace, monospace").
+
+import { continueRender, delayRender, staticFile } from "remotion";
+
+type LocalFontFile = {
+  family: string;
+  weight: string;
+  file: string;
+};
+
+const FILES: LocalFontFile[] = [
+  { family: "Inter", weight: "400", file: "fonts/inter-latin-400-normal.woff2" },
+  { family: "Inter", weight: "500", file: "fonts/inter-latin-500-normal.woff2" },
+  { family: "Inter", weight: "700", file: "fonts/inter-latin-700-normal.woff2" },
+  { family: "Inter", weight: "800", file: "fonts/inter-latin-800-normal.woff2" },
+  { family: "Inter", weight: "900", file: "fonts/inter-latin-900-normal.woff2" },
+  { family: "JetBrains Mono", weight: "400", file: "fonts/jetbrains-mono-latin-400-normal.woff2" },
+  { family: "JetBrains Mono", weight: "700", file: "fonts/jetbrains-mono-latin-700-normal.woff2" },
+];
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ovsLocalFontsLoaded: boolean | undefined;
+}
+
+// Module-scope side effect, same as the loadFont() calls this replaces: run once per
+// document, gate the render on it. Guarded so importing this module from more than
+// one scene (every scene does, via index.ts) only issues the FontFace loads once.
+if (typeof document !== "undefined" && !globalThis.__ovsLocalFontsLoaded) {
+  globalThis.__ovsLocalFontsLoaded = true;
+  const handle = delayRender("@openvidstudio/core: loading local Inter + JetBrains Mono fonts");
+
+  Promise.all(
+    FILES.map((f) =>
+      new FontFace(f.family, `url(${staticFile(f.file)}) format("woff2")`, {
+        weight: f.weight,
+        style: "normal",
+      }).load(),
+    ),
+  )
+    .then((faces) => {
+      // TS's DOM lib doesn't declare add()/delete() on FontFaceSet even though every
+      // real implementation supports them (it's Set-like per spec); narrow cast only
+      // for this call.
+      const fonts = document.fonts as unknown as { add: (font: FontFace) => void };
+      faces.forEach((face) => fonts.add(face));
+      continueRender(handle);
+    })
+    .catch((err) => {
+      // Never let a font-loading failure hang the render forever: log and continue,
+      // same fallback behavior offline @remotion/google-fonts had (fallback glyphs)
+      // rather than a stuck delayRender.
+      console.error("@openvidstudio/core: local font load failed", err);
+      continueRender(handle);
+    });
+}

package/templates/default/openvidstudio-core/src/motion.ts

@@ -11,6 +11,12 @@ export const E = {
   drift: Easing.bezier(0.4, 0.0, 0.6, 1.0),
   // snappy UI reaction (button press, blip reveal)
   snap: Easing.bezier(0.2, 0.9, 0.25, 1.0),
+  // symmetric ease in and out along a sine: a calm, even move with no hard push at either end
+  sine: (t: number): number => (t <= 0 ? 0 : t >= 1 ? 1 : -(Math.cos(Math.PI * t) - 1) / 2),
+  // symmetric ease in and out along an exponential: nearly still at both ends, fast through the
+  // middle. Exact 0 and 1 at the ends (Remotion's Easing.exp is not), so a tween lands on its target.
+  expo: (t: number): number =>
+    t <= 0 ? 0 : t >= 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2,
 } as const;
 
 export const SPRING = {

package/templates/default/openvidstudio-core/src/motionBlur.tsx

@@ -0,0 +1,35 @@
+// Motion blur for a move, applied only while the move is happening.
+// Remotion's CameraMotionBlur renders its children several times at sub-frame offsets and blends
+// them, which is exactly what a real shutter does and costs `samples` times the render work. A
+// shot is still for most of its length, so blurring all of it would pay that cost and soften a
+// frame that has nothing to smear. MotionBlur switches the wrapper on only inside a frame window.
+
+import React from "react";
+import { useCurrentFrame } from "remotion";
+import { CameraMotionBlur } from "@remotion/motion-blur";
+
+export interface MotionBlurOptions {
+  /** Shutter angle in degrees (0 to 360). 180 is the film default; larger smears more. */
+  shutterAngle?: number;
+  /** How many sub-frame renders are blended. More is smoother and slower. Default 8. */
+  samples?: number;
+}
+
+export const MotionBlur: React.FC<
+  MotionBlurOptions & {
+    /** First frame (local to the scene) of the blur window. Default 0. */
+    from?: number;
+    /** Last frame of the blur window, inclusive. Default: never ends. */
+    to?: number;
+    children: React.ReactNode;
+  }
+> = ({ from = 0, to = Number.POSITIVE_INFINITY, shutterAngle = 180, samples = 8, children }) => {
+  const frame = useCurrentFrame();
+  // Outside the window the children render as they would without this component, byte for byte.
+  if (frame < from || frame > to) return <>{children}</>;
+  return (
+    <CameraMotionBlur shutterAngle={shutterAngle} samples={samples}>
+      {children}
+    </CameraMotionBlur>
+  );
+};

package/templates/default/openvidstudio-core/src/musicClock.tsx

@@ -0,0 +1,171 @@
+// Music-first timing (C3). A scene that cuts, pulses or lands text "on the music" needs the
+// music's grid in frames, local to the scene. compose_score writes that grid to a cues file
+// that is exact by construction (every hit is placed at an exact sample), and stitch_composition
+// hands it to the composition through MusicClockProvider. A scene then asks for it by beat id:
+//
+//   const clock = useMusicClock("reveal");
+//   const hit = clock.at(8);                 // first downbeat of bar 8, as a scene-local frame
+//   const glow = clock.beatPulse();          // 1 on every beat, decaying to 0 before the next
+//   if (clock.onDownbeat()) { ... }          // true on the frame a bar starts
+//
+// Bars are counted from 0 at the start of the track, in 4/4 (what compose_score writes).
+// The bed is mounted at composition frame 0, so bar 0 beat 0 is composition frame 0.
+
+import React, { createContext, useContext, useMemo } from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+/** The fields of compose_score's cues file the clock reads. Everything but bpm is optional. */
+export interface MusicCues {
+  bpm: number;
+  /** Beats per bar. compose_score writes 4/4 only, so this defaults to 4. */
+  beatsPerBar?: number;
+  /** Seconds from the start of the file to the first downbeat. 0 for compose_score's tracks. */
+  offsetSeconds?: number;
+  /** Section map, in bars. */
+  sections?: { label: string; startBar: number; durationBars: number }[];
+  /** Impact points the score was composed around. */
+  impacts?: { label: string; atBar: number; atBeat?: number }[];
+}
+
+export interface MusicClock {
+  /** False when no cues were provided: the clock then runs on a 120 bpm grid so a scene still renders. */
+  available: boolean;
+  bpm: number;
+  beatsPerBar: number;
+  fps: number;
+  /** Frames from the start of the composition to the start of this scene. */
+  sceneStartFrame: number;
+  framesPerBeat: number;
+  framesPerBar: number;
+  /**
+   * The scene-local frame of `bar` and `beat` (both 0-based; `beat` may be fractional, so
+   * at(8, 2.5) is the "and" of beat 3 in bar 8). Rounded to the nearest frame. Negative when
+   * that moment is before the scene starts, which is how a scene knows a hit already passed.
+   */
+  at: (bar: number, beat?: number) => number;
+  /** The bar a scene-local frame falls in, and the beat within it (0-based, fractional). */
+  position: (frame: number) => { bar: number; beat: number };
+  /** The scene-local frame of the impact point with this label, or null if the score has none. */
+  impact: (label: string) => number | null;
+  /** The section of the track a scene-local frame falls in, or null when cues carry no sections. */
+  sectionAt: (frame: number) => string | null;
+  /**
+   * 1 on a beat, decaying to 0 by the next one. `decay` is the fraction of a beat the pulse
+   * lasts (default 0.6), `strongOnly` pulses on downbeats only. Uses the current frame.
+   */
+  beatPulse: (opts?: { decay?: number; strongOnly?: boolean }) => number;
+  /** True on the frame a bar starts. Uses the current frame. */
+  onDownbeat: () => boolean;
+  /** True on the frame a beat starts. Uses the current frame. */
+  onBeat: () => boolean;
+}
+
+/**
+ * The pure core of the clock, with the current frame passed in rather than read from Remotion,
+ * so it can be tested without rendering and reused by anything that already has a frame.
+ */
+export function createMusicClock(opts: {
+  cues: MusicCues | null | undefined;
+  fps: number;
+  sceneStartFrame?: number;
+  /** The scene-local frame the pulse/downbeat helpers answer for. */
+  frame?: number;
+}): MusicClock {
+  const { cues, fps } = opts;
+  const sceneStartFrame = opts.sceneStartFrame ?? 0;
+  const frame = opts.frame ?? 0;
+  const available = !!cues && Number.isFinite(cues.bpm) && cues.bpm > 0;
+  const bpm = available ? cues!.bpm : 120;
+  const beatsPerBar = available && cues!.beatsPerBar ? cues!.beatsPerBar : 4;
+  const framesPerBeat = (60 / bpm) * fps;
+  const framesPerBar = framesPerBeat * beatsPerBar;
+
+  // A track found rather than composed may have its first downbeat a little after the start of
+  // the file; the grid is then shifted by that much. compose_score's own tracks start on beat 0.
+  const offsetFrames = available && cues!.offsetSeconds ? cues!.offsetSeconds * fps : 0;
+  const absolute = (bar: number, beat = 0) => (bar * beatsPerBar + beat) * framesPerBeat + offsetFrames;
+  const at = (bar: number, beat = 0) => Math.round(absolute(bar, beat)) - sceneStartFrame;
+
+  const position = (localFrame: number) => {
+    const beatsIn = (localFrame + sceneStartFrame - offsetFrames) / framesPerBeat;
+    const bar = Math.floor(beatsIn / beatsPerBar + 1e-9);
+    return { bar, beat: beatsIn - bar * beatsPerBar };
+  };
+
+  // Frames are integers and beats are not. A beat lands on the frame at() gives for it (its exact
+  // position rounded to the nearest frame), so the pulse helpers use the same rounding and a
+  // scene that cuts on at(8) and pulses on onDownbeat() agrees about which frame that is.
+  const framesSinceBeat = () => {
+    const abs = frame + sceneStartFrame - offsetFrames;
+    // The latest beat whose rounded frame is at or before this one.
+    const beatIndex = Math.ceil((abs + 0.5) / framesPerBeat - 1e-9) - 1;
+    return { since: Math.round(abs - Math.round(beatIndex * framesPerBeat)), beatIndex };
+  };
+
+  return {
+    available,
+    bpm,
+    beatsPerBar,
+    fps,
+    sceneStartFrame,
+    framesPerBeat,
+    framesPerBar,
+    at,
+    position,
+    impact: (label) => {
+      const hit = cues?.impacts?.find((i) => i.label === label);
+      return hit ? at(hit.atBar, hit.atBeat ?? 0) : null;
+    },
+    sectionAt: (localFrame) => {
+      const sections = cues?.sections;
+      if (!sections?.length) return null;
+      const { bar } = position(localFrame);
+      const hit = sections.find((s) => bar >= s.startBar && bar < s.startBar + s.durationBars);
+      return hit ? hit.label : null;
+    },
+    beatPulse: ({ decay = 0.6, strongOnly = false } = {}) => {
+      const { since, beatIndex } = framesSinceBeat();
+      if (strongOnly && beatIndex % beatsPerBar !== 0) return 0;
+      const span = Math.max(1, (strongOnly ? framesPerBar : framesPerBeat) * decay);
+      const t = since / span;
+      return t >= 1 || t < 0 ? 0 : Math.pow(1 - t, 2);
+    },
+    onBeat: () => framesSinceBeat().since === 0,
+    onDownbeat: () => {
+      const { since, beatIndex } = framesSinceBeat();
+      return since === 0 && beatIndex % beatsPerBar === 0;
+    },
+  };
+}
+
+interface ProviderValue {
+  cues: MusicCues | null;
+  /** beat id -> the composition frame the beat's Sequence starts at */
+  beatStarts: Record<string, number>;
+}
+
+const MusicClockContext = createContext<ProviderValue>({ cues: null, beatStarts: {} });
+
+/**
+ * Mounted once by the generated composition. `beatStarts` maps each beat id to the composition
+ * frame its Sequence begins on, which is what turns the track's grid into scene-local frames.
+ */
+export const MusicClockProvider: React.FC<{
+  cues: MusicCues | null;
+  beatStarts: Record<string, number>;
+  children: React.ReactNode;
+}> = ({ cues, beatStarts, children }) => {
+  const value = useMemo(() => ({ cues, beatStarts }), [cues, beatStarts]);
+  return <MusicClockContext.Provider value={value}>{children}</MusicClockContext.Provider>;
+};
+
+/**
+ * The music clock for the scene of beat `beatId`. Must be called from inside that beat's scene,
+ * because the pulse and downbeat helpers read the scene's current frame.
+ */
+export function useMusicClock(beatId: string): MusicClock {
+  const { cues, beatStarts } = useContext(MusicClockContext);
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  return createMusicClock({ cues, fps, sceneStartFrame: beatStarts[beatId] ?? 0, frame });
+}