@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/templates/default/.windsurf/skills/remotion-upgrade/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: remotion-upgrade
+description: Upgrade Remotion, and related packages
+version: 4.0.521
+---
+
+# Upgrade Remotion
+
+1. Inspect the project manifests and lockfile to identify the package manager and workspaces. Preserve unrelated changes.
+2. Determine whether `@remotion/cli` is locally available. If it is, run:
+
+   ```bash
+   npx remotion upgrade
+   ```
+
+   This also updates project-local Remotion skills. Skip the manual upgrade below.
+
+3. If `@remotion/cli` is not available, upgrade manually:
+   - Get the latest stable Remotion version with `npm view remotion version`.
+   - Find every installed `remotion` and `@remotion/*` dependency across the project and upgrade them all to that exact version. Preserve their dependency sections and the project's workspace or catalog conventions.
+   - Read the current [Mediabunny compatibility page](https://www.remotion.dev/docs/mediabunny/version) and determine the Mediabunny version compatible with the target Remotion version. Upgrade every installed `mediabunny` and `@mediabunny/*` package to the documented compatible version.
+   - Run the project's package manager to update its lockfile.
+4. If `@remotion/cli` is not available, update the installed Remotion skills:
+
+   ```bash
+   npx skills update remotion-best-practices remotion-captions remotion-create remotion-docs remotion-interactivity remotion-maps remotion-markup remotion-multimedia remotion-render remotion-saas remotion-studio remotion-upgrade --yes
+   ```
+
+5. Review the manifest and lockfile diff. Ensure all Remotion packages use one version and all installed Mediabunny packages use the compatible version. If the CLI is available, run `npx remotion versions` as an additional check.
+
+The [Remotion releases](https://github.com/remotion-dev/remotion/releases) contain the changelog and may be useful for summarizing relevant changes after the upgrade.

package/templates/default/.windsurf/skills/remotion-upgrade/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: '/remotion-upgrade'
+  short_description: 'Upgrade Remotion and related dependencies'
+  icon_small: './assets/remotion-icon.png'
+  icon_large: './assets/remotion-icon.png'
+  brand_color: '#0B84F3'
+  default_prompt: '$remotion-upgrade: Upgrade my project.'

package/templates/default/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md: this project's video pipeline
+
+This project was scaffolded with openvidstudio: a Remotion + Playwright
+video-generation add-on driven via MCP tools. If you're an AI coding agent
+about to build a video for this project, read `./docs/PLANNING.md` first.
+That's step 0, before you touch `beats.json` or write a single scene. This
+file is a short pointer for agents that look for `AGENTS.md` specifically;
+`CLAUDE.md` in this same directory covers the identical ground in more
+detail and is kept in sync with this file by hand.
+
+## The order
+
+```
+preflight -> plan_production -> extract_brand -> write_brief -> plan_beats -> [write VO]
+  -> validate_beats -> APPROVAL GATE -> write_beats_file -> captures -> [compose_score]
+  -> scenes -> render_stills -> validate_scenes -> stitch_composition -> render_video
+  -> finalize_video -> qc_extract_frames
+```
+
+`./docs/CREATIVE.md` is the craft: read it before writing a brief at peak or mid level.
+`./docs/TOOLS.md` lists every tool. Review with `render_stills` (`perBeat: "review"`) before
+any full render, at every level: it returns a contact grid and numeric findings.
+
+## Before you write a scene: read the brief first
+
+Read `src/videos/<name>/brief.json` before writing a single scene. It names
+the creative level this video is being made at:
+
+- **peak and mid: author scenes.** Compose from `@openvidstudio/core`'s
+  primitive library against the video's own `src/videos/<name>/design.ts`.
+  `scaffold_scene` with `mode: "starter"` gives a scene file wired to that
+  design system with no layout imposed; `mode: "blank"` registers the beat
+  and leaves the file to you. The structure and pacing are your creative
+  decisions, not a template's.
+- **literal, or a tight time budget: `scaffold_scene` with `mode:
+  "template"` (the default).** A scene that renders immediately, using
+  that beat's own copy and duration. This is a shortcut, not the default
+  way to build a scene at every level.
+
+Every scene still has to pass `./docs/STYLE.md`'s hard rules (no linear
+easing, `CinematicScene` always, motion never stops, no em dashes) and
+claim-obligates-visual (`./docs/SCRIPT.md`). Then run `validate_scenes`:
+a static read of the scene source for camera-scale cropping, a camera
+that never moves, missing capture assets, a settle-sidecar timeout,
+leftover TODOs, a beat with no narration file. A static read can still
+miss a real-render-only problem, so render a still and look whenever a
+scene's framing is in doubt.
+
+## Docs
+
+`./docs/PLANNING.md`, `PIPELINE.md`, `STYLE.md`, `CAPTURE.md`, `SCRIPT.md`,
+`OVERVIEW.md`, `HIGGSFIELD.md`, `API.md`, `NARRATION.md`. `init_project`
+copies these in and never overwrites a file you've already edited.
+
+## Rules that fail QC
+
+- **No linear easing, ever.** Use `@openvidstudio/core`'s eased/spring
+  presets.
+- **Every scene wrapped in `CinematicScene`.**
+- **Motion never stops.** A frozen frame fails.
+- **No em dashes**, on screen or in VO, anywhere.

package/templates/default/CLAUDE.md

@@ -26,6 +26,11 @@ clobber local edits here). If a doc listed below is missing, re-run
   this instead of opening the library source.
 - `./docs/NARRATION.md`: voice, music and sound effects, and why generated
   voiceover usually sounds synthetic.
+- `./docs/CREATIVE.md`: how to make the video good: the story, the hook, a
+  motif from the brand, on-screen copy, pacing to music, camera, and the
+  review rubric. Read it before writing a brief at peak or mid level.
+- `./docs/TOOLS.md`: every MCP tool with a one-line purpose, generated from
+  the server's own registry.
 
 ## Rules a scene-writing agent must never violate
 
@@ -42,16 +47,52 @@ silently broken while writing a scene:
   frozen frame is a QC fail.
 - **No em dashes**, on screen or in VO, anywhere.
 
-## Before you hand-write a scene
+## Before you write a scene: read the brief first
 
-`scaffold_scene` emits a scene that renders, using that beat's own copy and
-duration. Start from it and edit the content rather than composing a scene
-from primitives: it already has correct camera keyframes, a safe content
-width, and the right shape for the beat's capture method.
+Read `src/videos/<name>/brief.json` (and `brief.md`) before writing a single
+scene. It names the creative level this video is being made at, and that
+decides how you get to a scene file:
 
-Then run `validate_scenes`. The commonest mistake in this pipeline is
-invisible: content laid out at full stage width gets cropped once the camera
-pushes in, and the render does not warn.
+- **peak and mid: author scenes.** Compose from `@openvidstudio/core`'s
+  primitive library (`Words`, `PixelLogo`, `DotText`, `ChapterHud`,
+  `Window`, and the rest -- see `./docs/API.md`) against the video's
+  own `src/videos/<name>/design.ts` (its `DesignSystem`: palette roles,
+  type scale, motif, motion personality). `scaffold_scene` with `mode:
+  "starter"` gives you a scene file already wired to that design system
+  and the beat's real facts, with no layout imposed, as a faster starting
+  point than a blank file; `mode: "blank"` registers the beat for
+  `stitch_composition` without writing anything, if you'd rather start
+  from nothing. Either way, the structure, pacing and composition are
+  your creative decisions, not a template's.
+- **literal, or a tight time budget: `scaffold_scene` with `mode:
+  "template"` (the default)** is the fast path: a scene that renders
+  immediately, using that beat's own copy and duration, with correct
+  camera keyframes and a safe content width already handled. Start from
+  it and edit the content. This is a shortcut for when the brief calls
+  for exactly what's specified and nothing more, not the default way to
+  build a scene at every level.
+
+Whichever path, every scene still has to pass `STYLE.md`'s hard rules (no
+linear easing, `CinematicScene` always, motion never stops, no em dashes)
+and claim-obligates-visual (`SCRIPT.md`).
+
+Review before any full render, at every level. `render_stills` with
+`perBeat: "review"` writes five frames per beat and one labelled contact
+grid, and returns numeric findings (cropping, text size, reading time,
+contrast, em dashes, safe area, HUD overlap, dead frames) so an agent that
+cannot view images can still review. Look, fix, and render again with the
+next `round`, until the rubric in `CREATIVE.md` passes. Numbers shown on
+screen come from `facts.json` or a capture, never from memory.
+
+Then run `validate_scenes`. It reads the scene source statically: camera
+scale against the content widths declared in the file, a camera that
+never moves, missing capture assets, a settle-sidecar timeout, leftover
+TODOs, a beat with no narration file. The commonest mistake in this
+pipeline is invisible otherwise: content laid out at full stage width
+gets cropped once the camera pushes in, and a plain render does not
+warn. A static read can still miss a real-render-only problem (the
+validator's own source says so plainly); render a still and look
+whenever a scene's framing is at all in doubt.
 
 ## Components
 

package/templates/default/openvidstudio-core/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@openvidstudio/core",
-  "version": "0.1.0",
-  "description": "Camera rig, motion, SFX, look pass, and scene components shared by every openvidstudio video project.",
+  "version": "1.3.1",
+  "description": "Camera rig, shot moves, transitions, motion, sound, look pass and scene components shared by every openvidstudio video project.",
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
   "type": "commonjs",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -11,19 +14,20 @@
     "scripts",
     "public"
   ],
-  "dependencies": {
-    "@remotion/google-fonts": "^4.0.490"
-  },
   "peerDependencies": {
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "remotion": "4.0.490"
+    "@remotion/motion-blur": "4.0.534",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "remotion": "4.0.534"
   },
   "devDependencies": {
-    "@types/react": "19.2.7",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "remotion": "4.0.490",
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
+    "@remotion/motion-blur": "4.0.534",
+    "@types/react": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "remotion": "4.0.534",
     "typescript": "5.9.3"
   },
   "scripts": {

package/templates/default/openvidstudio-core/scripts/gen-fonts.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Copy bundled woff2 files for offline rendering (A2) into templates/default/public/fonts/.
+# Source: the @fontsource/inter and @fontsource/jetbrains-mono npm packages (license-clean,
+# SIL OFL), not hand-downloaded from fonts.gstatic.com. Re-run after bumping either package
+# in packages/core/package.json's devDependencies, or if templates/default/public/fonts/ is
+# ever wiped. Requires both packages already installed (pnpm install at repo root).
+set -e
+cd "$(dirname "$0")/.."
+
+INTER="node_modules/@fontsource/inter/files"
+MONO="node_modules/@fontsource/jetbrains-mono/files"
+OUT="../../templates/default/public/fonts"
+
+if [ ! -d "$INTER" ] || [ ! -d "$MONO" ]; then
+  echo "error: @fontsource/inter or @fontsource/jetbrains-mono not installed under packages/core/node_modules." >&2
+  echo "Run: pnpm add -D @fontsource/inter @fontsource/jetbrains-mono --filter @openvidstudio/core" >&2
+  exit 1
+fi
+
+mkdir -p "$OUT"
+
+for w in 400 500 700 800 900; do
+  cp "$INTER/inter-latin-$w-normal.woff2" "$OUT/"
+done
+
+for w in 400 700; do
+  cp "$MONO/jetbrains-mono-latin-$w-normal.woff2" "$OUT/"
+done
+
+echo "fonts generated:"
+ls "$OUT"

package/templates/default/openvidstudio-core/scripts/gen-sfx.sh

@@ -1,25 +1,12 @@
 #!/bin/bash
 # Generate synthesized UI SFX into public/sfx/ (no licensing, fully reproducible).
 # Swap any file for a real recorded pack later, sfx.tsx API stays identical.
+# typing-effect.mp3 and click.wav are not generated here: they are recordings committed as-is.
 set -e
 cd "$(dirname "$0")/.."
 mkdir -p public/sfx
 
-# Mechanical key thocks: filtered brown-noise bursts, 3 pitch variations
-ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.06:c=brown:a=0.9" \
-  -af "highpass=f=180,lowpass=f=2400,afade=t=in:d=0.004,afade=t=out:st=0.025:d=0.035,volume=3.2" \
-  public/sfx/key_a.wav
-ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.055:c=brown:a=0.9:seed=7" \
-  -af "highpass=f=200,lowpass=f=1900,afade=t=in:d=0.004,afade=t=out:st=0.022:d=0.033,volume=3.4" \
-  public/sfx/key_b.wav
-ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.065:c=brown:a=0.9:seed=23" \
-  -af "highpass=f=160,lowpass=f=2900,afade=t=in:d=0.004,afade=t=out:st=0.028:d=0.037,volume=3.0" \
-  public/sfx/key_c.wav
-
-# Click: sharp short tick
-ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.03:c=white:a=0.8" \
-  -af "highpass=f=1400,lowpass=f=6500,afade=t=in:d=0.002,afade=t=out:st=0.01:d=0.02,volume=2.2" \
-  public/sfx/click.wav
+# Click: not generated. click.wav is a recorded double click (Mixkit), committed as-is; see public/sfx/CREDITS.md.
 
 # Whoosh: bandpassed pink noise swell
 ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.55:c=pink:a=0.8" \
@@ -49,11 +36,6 @@ ffmpeg -v error -y \
   -filter_complex "[0]volume=1.0[a];[1]volume=0.45[b];[2]volume=0.22[c];[a][b][c]amix=inputs=3:normalize=0,afade=t=in:d=0.004,afade=t=out:st=0.12:d=1.45,volume=1.2" \
   public/sfx/bell.wav
 
-# Enter key: deeper, heavier thock than a letter key
-ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.085:c=brown:a=0.95:seed=41" \
-  -af "highpass=f=110,lowpass=f=1500,afade=t=in:d=0.004,afade=t=out:st=0.03:d=0.05,volume=3.6" \
-  public/sfx/key_enter.wav
-
 # Music bed: slow ambient pad, two detuned sines under a filtered noise wash.
 # Synthesized rather than licensed, so a generated video carries no third-party
 # audio rights. 60s, loop it for longer videos.

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

@@ -2,15 +2,12 @@
 
 import React from "react";
 import { useCurrentFrame, useVideoConfig } from "remotion";
-import { loadFont as loadInter } from "@remotion/google-fonts/Inter";
+import "./localFonts";
 import { pop, SPRING } from "./motion";
 import { Blip } from "./sfx";
 import { color, panelShadow, radius } from "./tokens";
 
-const { fontFamily: uiFamily } = loadInter("normal", {
-  weights: ["500", "700"],
-  subsets: ["latin"],
-});
+const uiFamily = "Inter, system-ui, sans-serif";
 
 export type ChecklistItem = {
   label: string;

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

@@ -2,13 +2,18 @@
 // Content renders on an oversized stage; camera keyframes drive the shot.
 
 import React from "react";
-import { AbsoluteFill } from "remotion";
+import { AbsoluteFill, useVideoConfig } from "remotion";
 import { CameraRig, CamKeyframe } from "./camera";
 import { LookPass } from "./look";
 import { color } from "./tokens";
 
 export const CinematicScene: React.FC<{
   camera: CamKeyframe[];
+  /**
+   * Stage size in px. Defaults to the composition size, so camera coordinates are in frame px
+   * (centre 960,540 in 1920x1080, 540,960 in a 1080x1920 reel) rather than in a fixed 1920x1080
+   * space that a 9:16 frame would show only a slice of.
+   */
   stageWidth?: number;
   stageHeight?: number;
   /** dark (default) or light stage */
@@ -20,14 +25,15 @@ export const CinematicScene: React.FC<{
   children: React.ReactNode;
 }> = ({
   camera,
-  stageWidth = 1920,
-  stageHeight = 1080,
+  stageWidth,
+  stageHeight,
   variant = "dark",
   grain = 0.05,
   vignette = 0.32,
   overlay,
   children,
 }) => {
+  const video = useVideoConfig();
   const bg =
     variant === "dark"
       ? `radial-gradient(ellipse 90% 80% at 50% 40%, ${color.bg1} 0%, ${color.bg0} 100%)`
@@ -36,13 +42,15 @@ export const CinematicScene: React.FC<{
     <AbsoluteFill style={{ background: bg }}>
       <CameraRig
         keyframes={camera}
-        stageWidth={stageWidth}
-        stageHeight={stageHeight}
+        stageWidth={stageWidth ?? video.width}
+        stageHeight={stageHeight ?? video.height}
       >
         {children}
       </CameraRig>
       {overlay ? (
-        <div style={{ position: "absolute", inset: 0 }}>{overlay}</div>
+        <div data-ovs-overlay="" style={{ position: "absolute", inset: 0 }}>
+          {overlay}
+        </div>
       ) : null}
       <LookPass
         grain={grain}

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

@@ -1,5 +1,5 @@
 // Cursor as an actor (STYLE.md rule 4): oversized macOS cursor gliding between keyframes
-// with cinematic easing, click = press-scale + expanding ring + click SFX.
+// with cinematic easing along a slight arc, click = press-scale + expanding ring + click SFX.
 
 import React from "react";
 import { useCurrentFrame } from "remotion";
@@ -9,6 +9,56 @@ import { color } from "./tokens";
 
 export type CursorKeyframe = { frame: number; x: number; y: number };
 
+/** How far a segment bows sideways at its widest, as a fraction of the segment's length. */
+const ARC = 0.06;
+/** How far past the target the cursor swings before settling, as a fraction of the segment's length. */
+const OVERSHOOT = 0.025;
+
+/**
+ * Cursor position at an arbitrary frame, by the same clamp-and-interpolate rule the actor
+ * itself renders with. Pulled out so a click ring can ask "where was the cursor AT FRAME c"
+ * once, and freeze that answer, instead of the actor's per-frame render reading whatever the
+ * live position happens to be on the frame the ring is drawn.
+ *
+ * A hand does not move in a straight line. Each segment bows to one side (by up to 6% of its
+ * length, alternating sides from one segment to the next so a run of moves does not lean one way),
+ * and the cursor swings a little past the target before it settles, which reads as a person
+ * aiming. The progress along the segment is still E.cinematic, and the position on a keyframe's
+ * own frame is exactly that keyframe.
+ */
+function positionAt(sorted: CursorKeyframe[], frame: number): { x: number; y: number } {
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  if (frame <= first.frame) return { x: first.x, y: first.y };
+  if (frame >= last.frame) return { x: last.x, y: last.y };
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i].frame >= frame) {
+      const a = sorted[i - 1];
+      const b = sorted[i];
+      const progress = tween(frame, [a.frame, b.frame], [0, 1], E.cinematic);
+      const t = (frame - a.frame) / (b.frame - a.frame);
+      const dx = b.x - a.x;
+      const dy = b.y - a.y;
+      const length = Math.hypot(dx, dy);
+      if (length < 1e-6) return { x: b.x, y: b.y };
+      const side = i % 2 === 1 ? 1 : -1;
+      const bow = ARC * length * Math.sin(Math.PI * progress) * side;
+      // The overshoot rides the last 45% of the segment's time and is zero again on arrival.
+      const overshoot = t > 0.55 ? OVERSHOOT * length * Math.sin((Math.PI * (t - 0.55)) / 0.45) : 0;
+      const along = progress * length + overshoot;
+      return {
+        x: a.x + (dx / length) * along + (-dy / length) * bow,
+        y: a.y + (dy / length) * along + (dx / length) * bow,
+      };
+    }
+  }
+  return { x: last.x, y: last.y };
+}
+
+/** The cursor's position at `frame` along `path`, exactly as CursorActor draws it. */
+export const cursorPositionAt = (path: CursorKeyframe[], frame: number): { x: number; y: number } =>
+  positionAt([...path].sort((a, b) => a.frame - b.frame), frame);
+
 export const CursorActor: React.FC<{
   path: CursorKeyframe[];
   /** frames at which a click happens (ring + press + sfx) */
@@ -20,17 +70,7 @@ export const CursorActor: React.FC<{
   const sorted = [...path].sort((a, b) => a.frame - b.frame);
   if (frame < sorted[0].frame) return null;
 
-  let x = sorted[sorted.length - 1].x;
-  let y = sorted[sorted.length - 1].y;
-  for (let i = 1; i < sorted.length; i++) {
-    if (sorted[i].frame >= frame) {
-      const a = sorted[i - 1];
-      const b = sorted[i];
-      x = tween(frame, [a.frame, b.frame], [a.x, b.x], E.cinematic);
-      y = tween(frame, [a.frame, b.frame], [a.y, b.y], E.cinematic);
-      break;
-    }
-  }
+  const { x, y } = positionAt(sorted, frame);
 
   // press scale near a click
   const press = clicks.reduce((acc, c) => {
@@ -42,17 +82,21 @@ export const CursorActor: React.FC<{
 
   return (
     <>
-      {/* click rings */}
+      {/* click rings: anchored at the cursor's position AT ITS OWN CLICK FRAME, computed
+          once per click and frozen there. Reading live x/y here instead would let a ring
+          still fading out on a later frame visibly slide off the target the cursor has
+          since moved on from. */}
       {clicks.map((c, i) => {
         if (frame < c || frame > c + 22) return null;
+        const anchor = positionAt(sorted, c);
         const p = tween(frame, [c, c + 22], [0, 1], E.snap);
         return (
           <div
             key={i}
             style={{
               position: "absolute",
-              left: x - 60 * p,
-              top: y - 60 * p,
+              left: anchor.x - 60 * p,
+              top: anchor.y - 60 * p,
               width: 120 * p,
               height: 120 * p,
               borderRadius: "50%",