@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/templates/default/openvidstudio-stem/src/paths.ts

@@ -0,0 +1,148 @@
+// Spark behaviours. A path is a pure function of local time, in frames since the Spark appeared,
+// returning where the Spark is in the composition's pixels. Every helper here returns one (split
+// returns n), so they compose, and none keeps state between frames or draws a random number.
+
+import { E } from "@openvidstudio/core";
+
+export interface Point {
+  x: number;
+  y: number;
+}
+export type Path = (t: number) => Point;
+export interface Keyframe extends Point {
+  /** Local frame the Spark is at this point. */
+  frame: number;
+  easing?: (t: number) => number;
+}
+
+const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
+const lerp = (a: number, b: number, k: number) => a + (b - a) * k;
+const mix = (a: Point, b: Point, k: number): Point => ({ x: lerp(a.x, b.x, k), y: lerp(a.y, b.y, k) });
+
+/** Keyframes as a path: eased between neighbours, held at the first and last. */
+export function keyframePath(keys: Keyframe[]): Path {
+  if (keys.length === 0) throw new Error("A Spark path needs at least one keyframe.");
+  const sorted = [...keys].sort((a, b) => a.frame - b.frame);
+  return (t) => {
+    if (t <= sorted[0].frame) return { x: sorted[0].x, y: sorted[0].y };
+    for (let i = 1; i < sorted.length; i++) {
+      const a = sorted[i - 1];
+      const b = sorted[i];
+      if (t <= b.frame) {
+        const k = b.frame === a.frame ? 1 : (t - a.frame) / (b.frame - a.frame);
+        return mix(a, b, (b.easing ?? E.sine)(clamp01(k)));
+      }
+    }
+    const last = sorted[sorted.length - 1];
+    return { x: last.x, y: last.y };
+  };
+}
+
+/** A path from either form a Spark accepts. */
+export function resolvePath(path: Path | Keyframe[]): Path {
+  return typeof path === "function" ? path : keyframePath(path);
+}
+
+/** A curve through points, walked at constant speed (by arc length) so the Spark does not bunch at corners. */
+export function polyline(points: Point[]): (u: number) => Point {
+  if (points.length === 0) throw new Error("polyline needs at least one point.");
+  const lengths = [0];
+  for (let i = 1; i < points.length; i++) lengths.push(lengths[i - 1] + Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y));
+  const total = lengths[lengths.length - 1];
+  return (u) => {
+    if (total === 0) return points[0];
+    const d = clamp01(u) * total;
+    let i = 1;
+    while (i < points.length - 1 && lengths[i] < d) i++;
+    const span = lengths[i] - lengths[i - 1];
+    return mix(points[i - 1], points[i], span === 0 ? 1 : (d - lengths[i - 1]) / span);
+  };
+}
+
+/**
+ * Draws a curve: the Spark leaves its start at frame 0 and reaches the end of the curve at
+ * `duration`. `curve` is a function of progress 0..1 or a list of points; `ease` shapes the pace.
+ */
+export function trace(curve: ((u: number) => Point) | Point[], opts: { duration: number; ease?: (t: number) => number }): Path {
+  const c = typeof curve === "function" ? curve : polyline(curve);
+  const ease = opts.ease ?? E.sine;
+  return (t) => c(ease(clamp01(t / opts.duration)));
+}
+
+/**
+ * Carries a value along a function: x runs from `from` to `to` over `duration` and the Spark sits
+ * at y = fn(x). `map` turns that graph point into the composition's pixels (an Axes' world-to-screen
+ * mapping); without one the point is used as pixels.
+ */
+export function carry(
+  fn: (x: number) => number,
+  from: number,
+  to: number,
+  opts: { duration: number; map?: (x: number, y: number) => Point; ease?: (t: number) => number },
+): Path {
+  const ease = opts.ease ?? E.sine;
+  const map = opts.map ?? ((x: number, y: number) => ({ x, y }));
+  return (t) => {
+    const x = lerp(from, to, ease(clamp01(t / opts.duration)));
+    return map(x, fn(x));
+  };
+}
+
+/** Circles a target: `period` frames per turn, starting at `startAngle` (radians, 0 is to the right). */
+export function orbit(target: Point, radius: number, opts: { period: number; startAngle?: number; clockwise?: boolean } = { period: 90 }): Path {
+  const dir = opts.clockwise === false ? -1 : 1;
+  return (t) => {
+    const a = (opts.startAngle ?? 0) + dir * (2 * Math.PI * t) / opts.period;
+    return { x: target.x + radius * Math.cos(a), y: target.y + radius * Math.sin(a) };
+  };
+}
+
+/**
+ * Splits into n Sparks: all n travel the parent path until `at`, then fan out evenly round a
+ * circle of `spread` px, `duration` frames to get there. For probability: one Spark becomes
+ * the outcomes. Returns one path per Spark.
+ */
+export function split(parent: Path, n: number, opts: { at: number; spread: number; duration?: number; startAngle?: number }): Path[] {
+  const duration = opts.duration ?? 30;
+  return Array.from({ length: n }, (_, i) => {
+    const angle = (opts.startAngle ?? -Math.PI / 2) + (2 * Math.PI * i) / n;
+    return (t: number) => {
+      const origin = parent(Math.min(t, opts.at));
+      if (t <= opts.at) return origin;
+      const k = E.cinematic(clamp01((t - opts.at) / duration));
+      return { x: origin.x + Math.cos(angle) * opts.spread * k, y: origin.y + Math.sin(angle) * opts.spread * k };
+    };
+  });
+}
+
+/**
+ * Falls under gravity: starts at (x, y) with velocity (vx, vy) in px per frame, `g` px per frame
+ * squared downwards. With `floorY` it stops there. This is the projectile, so a physics lesson
+ * can fall the Spark with the numbers it is teaching.
+ */
+export function fall(g: number, start: Point & { vx?: number; vy?: number }, opts: { floorY?: number } = {}): Path {
+  const vx = start.vx ?? 0;
+  const vy = start.vy ?? 0;
+  return (t) => {
+    const y = start.y + vy * t + 0.5 * g * t * t;
+    return { x: start.x + vx * t, y: opts.floorY === undefined ? y : Math.min(y, opts.floorY) };
+  };
+}
+
+/**
+ * Walks a pointer through places, one hop at a time: `hop` frames to move, `hold` frames resting
+ * on each, so a viewer can read where it is. Pointers on an array, nodes of a graph.
+ */
+export function walk(points: Point[], opts: { hop: number; hold?: number; ease?: (t: number) => number }): Path {
+  if (points.length === 0) throw new Error("walk needs at least one point.");
+  const hold = opts.hold ?? 0;
+  const ease = opts.ease ?? E.cinematic;
+  const step = opts.hop + hold;
+  return (t) => {
+    if (t <= 0) return points[0];
+    const i = Math.min(points.length - 1, Math.floor(t / step));
+    if (i >= points.length - 1) return points[points.length - 1];
+    const within = t - i * step;
+    return mix(points[i], points[i + 1], ease(clamp01(within / opts.hop)));
+  };
+}

package/templates/default/output/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!README.md

package/templates/default/output/README.md

@@ -0,0 +1,9 @@
+# output/
+
+Everything `render_video`, `contact_sheet`, and `qc_extract_frames` produce lands
+here: the rendered `<videoName>.mp4`, `contact-sheet.jpg`, and the `qc/<videoName>/`
+frame stills used for visual QC.
+
+This folder is gitignored (see `.gitignore` here) since renders are build output,
+not source. Pick the finished video up from `output/<videoName>.mp4`, or point an
+upload step at that path.

package/templates/default/package.json

@@ -3,22 +3,27 @@
   "version": "0.1.0",
   "description": "An openvidstudio video project, scaffolded from templates/default.",
   "private": true,
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "@openvidstudio/core": "file:./openvidstudio-core",
-    "@remotion/cli": "4.0.490",
-    "@remotion/google-fonts": "^4.0.490",
-    "@remotion/shapes": "^4.0.490",
-    "@remotion/tailwind-v4": "4.0.490",
-    "@remotion/transitions": "^4.0.490",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "remotion": "4.0.490",
-    "tailwindcss": "4.0.0"
+    "@openvidstudio/stem": "file:./openvidstudio-stem",
+    "@remotion/cli": "4.0.534",
+    "@remotion/google-fonts": "4.0.534",
+    "@remotion/motion-blur": "4.0.534",
+    "@remotion/shapes": "4.0.534",
+    "@remotion/tailwind-v4": "4.0.534",
+    "@remotion/transitions": "4.0.534",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "remotion": "4.0.534",
+    "tailwindcss": "4.3.3"
   },
   "devDependencies": {
-    "@types/react": "19.2.7",
-    "@types/web": "0.0.166",
-    "typescript": "5.9.3"
+    "@types/react": "19.3.0",
+    "@types/web": "0.0.358",
+    "typescript": "7.0.2"
   },
   "scripts": {
     "dev": "remotion studio",
@@ -26,6 +31,7 @@
     "upgrade": "remotion upgrade"
   },
   "sideEffects": [
-    "*.css"
+    "*.css",
+    "./src/brand.ts"
   ]
 }

package/templates/default/public/imported_audios/README.md

@@ -0,0 +1,14 @@
+# public/imported_audios/
+
+Drop any sound effect or music file here that you want a scene to use. Reference
+it from a scene with `staticFile("imported_audios/<filename>")`.
+
+This is separate from `public/sfx/`, which is the synthesized pack `@openvidstudio/core`
+ships (clicks, keystrokes, a bell, a whoosh, a music bed). Nothing in `sfx/` carries
+third-party rights; anything you put here does, so credit the source in the video
+description if its licence asks for it.
+
+`plan_sound_effects` also writes here: it saves anything it fetches automatically
+(via the `freesound` provider) into this folder, and for anything you have to
+download by hand it writes the exact filename to save into `DOWNLOAD-THESE.md`
+alongside this README.

package/templates/default/public/sfx/CREDITS.md

@@ -0,0 +1,49 @@
+# Credits for public/sfx/
+
+A rendered video carries no attribution duty from anything here and no content ID.
+Four different sources, so all four are recorded.
+
+## Synthesized in this repo
+
+`bell.wav`, `blip.wav`, `success.wav`, `whoosh.wav` and `music-bed.mp3`
+come from `scripts/gen-sfx.sh` (ffmpeg, sine and anoisesrc). No sampled or
+licensed material went into any of them.
+
+## Mixkit
+
+`click.wav` is "Fast double click on mouse" (Mixkit sound effect 275,
+https://mixkit.co/free-sound-effects/click/), supplied by the project owner on 2026-10-19 to
+replace a 30 ms synthesized tick. Trimmed to the two clicks (the first lands on the cue frame),
+mixed to mono, 48 kHz 16-bit PCM like the rest of the pack, and raised 1.5 dB so its peak is
+-1.5 dBFS. Licence: the Mixkit Sound Effects Free License, https://mixkit.co/license/#sfxFree.
+Using it in a rendered video needs no attribution. The licence text could not be read when
+this file was added, so confirm its terms on redistribution before republishing this pack as
+a sound library on its own (a fork that only ships the video tool is a different thing).
+Replace it with a synthesized or CC0 click and `click.wav` stops being the only licensed file here.
+
+## Copyright-free recording
+
+`typing-effect.mp3` is a recording of typing, committed as-is. It replaced the four
+synthesized key sounds, which sounded like a metronome one sample per character.
+
+## CC0, from Kenney
+
+| File | Original |
+|---|---|
+| `bong.wav` | Kenney Interface Sounds, `interface/bong_001.ogg` |
+| `click_soft.wav` | Kenney Interface Sounds, `interface/click_001.ogg` |
+| `drop.wav` | Kenney Interface Sounds, `interface/drop_001.ogg` |
+
+Source: https://kenney.nl. Kenney's asset packs are released under CC0 1.0 (public
+domain): https://creativecommons.org/publicdomain/zero/1.0/. Commercial use is allowed
+and attribution is not required; this file exists so the provenance is on record, not
+because the licence asks for it.
+
+Converted from Vorbis .ogg to 48 kHz mono 16-bit PCM .wav to match the rest of the pack.
+CC0 permits the format change.
+
+## Adding your own
+
+Anything you bring in from elsewhere goes in `public/imported_audios/`, not here, so it
+stays obvious which sounds carry terms. `plan_sound_effects` enforces that split and
+writes an `ATTRIBUTION.md` next to whatever it fetches.

package/templates/default/scripts/visual-regression.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Renders this project's video and diffs it against the last accepted render.
+ *
+ * Meant for CI, but it is an ordinary script: run it locally with `node
+ * scripts/visual-regression.mjs <videoName>` and it does the same thing.
+ *
+ * Draft mode by default. A full-quality render on every merge is minutes of CI time for a
+ * check whose job is to notice that a panel changed colour, and draft is half resolution,
+ * which the comparison downscales anyway. Incremental is on for the same reason: after the
+ * first run, only the beats that actually changed are re-rendered.
+ *
+ * The baseline lives in .openvidstudio/visual-baseline/<videoName>/ and is meant to be
+ * committed. That is the whole mechanism: the diff is against what the repository last
+ * agreed the product looked like, and accepting a change is a commit like any other.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runRenderVideo, runVisualRegression } from "@openvidstudio/mcp-server";
+
+const videoName = process.argv[2];
+if (!videoName) {
+  console.error("usage: node scripts/visual-regression.mjs <videoName>");
+  process.exit(2);
+}
+
+const projectRoot = process.cwd();
+const accept = process.argv.includes("--accept");
+const outPath = path.join("output", `${videoName}-ci.mp4`);
+
+const render = await runRenderVideo({
+  projectRoot,
+  videoName,
+  outPath,
+  draft: true,
+  incremental: true,
+  // CI has no brand to extract from and no product running; the look is whatever the
+  // project already committed.
+  skipBrandLock: true,
+});
+
+if (!render.success) {
+  console.error(render.stderr || render.stdout);
+  process.exit(1);
+}
+console.log(
+  `rendered ${render.renderedBeats?.length ?? "?"} beat(s), reused ${render.reusedBeats?.length ?? 0}, ` +
+    `${render.framesRendered ?? "?"} of ${render.totalFrames ?? "?"} frames in ${render.elapsedSeconds}s`,
+);
+
+const result = await runVisualRegression({
+  projectRoot,
+  videoName,
+  videoPath: outPath,
+  baselineDir: path.join(".openvidstudio", "visual-baseline", videoName),
+  updateBaseline: accept,
+});
+
+console.log(result.markdown);
+
+// Written to a file as well as stdout: the workflow posts this verbatim as a PR comment,
+// and passing multi-line markdown through a step output is a quoting problem nobody needs.
+fs.mkdirSync("output", { recursive: true });
+fs.writeFileSync(path.join("output", "visual-regression.md"), result.markdown + "\n", "utf8");
+
+// A drifted beat is a finding, not a build break: most of the time the change is intended
+// and the right response is to look at the diff and accept it. The workflow reports, the
+// human decides.
+process.exit(0);

package/templates/default/src/PreflightBenchmark.tsx

@@ -0,0 +1,49 @@
+// A fixed, representative composition preflight's render benchmark times: real camera
+// motion (CinematicScene's grain/vignette/grade plus a push-in/drift keyframe pair) over a
+// real DOM-rendered panel (ChecklistPanel), the same shape as a normal scaffolded scene.
+// Registered once by init_project into src/videos/.registry.json under videoName
+// "__preflight__", which stitch_composition's registry filter (by real videoName) never
+// touches, so this survives every re-stitch of every real video in the project.
+//
+// Never hand-edit this file's registration out of Root.tsx: stitch_composition
+// regenerates Root.tsx from the registry on every call, so an edit there is lost on the
+// next stitch of any video. Change the registry entry (see initProject.ts) instead.
+
+import React from "react";
+import { CinematicScene, Layer, ChecklistPanel, E } from "@openvidstudio/core";
+
+export const PreflightBenchmark: React.FC = () => {
+  return (
+    <CinematicScene
+      camera={[
+        { frame: 0, x: 960, y: 540, scale: 1.04, rotZ: -0.4 },
+        { frame: 150, x: 960, y: 548, scale: 1.18, rotZ: 0.4, easing: E.drift },
+      ]}
+    >
+      <Layer depth={0}>
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: "0 180px",
+          }}
+        >
+          <ChecklistPanel
+            title="Preflight benchmark"
+            width={860}
+            fontSize={27}
+            items={[
+              { label: "Camera motion", flipAt: 20 },
+              { label: "Grain and vignette", flipAt: 50 },
+              { label: "DOM text reveal", flipAt: 80 },
+              { label: "A real frame, timed", flipAt: 110 },
+            ]}
+          />
+        </div>
+      </Layer>
+    </CinematicScene>
+  );
+};