reframe-video 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Kiyeon Jeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Bundled assets: CC0 sound samples in assets/sfx/ retain their original
+provenance — see assets/sfx/LICENSE.md.

package/README.md

@@ -0,0 +1,77 @@
+# reframe
+
+**Declarative motion graphics that AI can write, humans can tweak — and the
+human's edits survive an AI regeneration.**
+
+A scene is a single self-contained `.ts` file (plain-data IR, no React, no
+project scaffold). Renders are deterministic: same input, byte-identical
+frames. Human edits live in a non-destructive overlay JSON addressed by stable
+node ids / state names / timeline labels — regenerate the scene with an AI and
+the overlay reapplies; anything broken is reported loudly, never silently lost.
+
+```bash
+brew install ffmpeg                  # system dep (or apt install ffmpeg)
+npx playwright install chromium      # one-time browser download
+npx reframe-video new hello          # scaffold hello.ts in this directory
+npx reframe-video render hello.ts    # → out/hello.mp4
+```
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `reframe render <scene.ts> [--overlay edits.json] [-o out.mp4]` | deterministic mp4 |
+| `reframe batch <scene.ts> <data.json\|csv>` | one mp4 per data row (row keys are overlay addresses) |
+| `reframe preview` | scrub/play/edit UI for scenes in the current directory; edits export as overlay JSON |
+| `reframe new <name>` | scaffold a documented starter scene |
+| `reframe motion <mp4>` | calibrated motion profile of a rendered clip |
+| `reframe guide [--regen]` | the scene-authoring guide / regeneration contract — **feed this to your AI** |
+
+(Installed as both `reframe` and `reframe-video`; with npx use `npx reframe-video <cmd>`.)
+
+## Writing a scene
+
+```ts
+import { scene, text, seq, to, wait } from "@reframe/core"; // or "reframe-video"
+
+export default scene({
+  id: "hello",
+  size: { width: 1920, height: 1080 },
+  fps: 30,
+  background: "#101014",
+  nodes: [
+    text({ id: "title", x: 960, y: 540, anchor: "center",
+      content: "Hello", fontFamily: "Inter", fontSize: 120, fontWeight: 800, fill: "#FFF" }),
+  ],
+  states: {
+    hidden: { title: { opacity: 0, y: 580 } },
+    shown:  { title: { opacity: 1, y: 540 } },
+  },
+  initial: "hidden",
+  timeline: seq(
+    to("shown", { duration: 0.6, ease: "easeOutCubic", label: "enter" }),
+    wait(2, "hold"),
+  ),
+});
+```
+
+The renderer resolves `@reframe/core` itself — a scene file needs no
+package.json next to it. For editor IntelliSense, `npm i -D reframe-video`
+and import from `"reframe-video"` (same API, both specifiers work).
+
+Audio is label-anchored (`audio: { cues: [{ at: "enter", sfx: "whoosh" }] }`)
+so sound design follows retiming and regeneration. Full syntax:
+`npx reframe-video guide`.
+
+## Why this instead of generating Remotion/HTML?
+
+One-shot generation quality is a wash (we measured it). The difference is the
+second turn: reframe's output is an addressable document, so "tweak just the
+timing", "redesign it but keep my edits", and "render 50 personalized
+versions" are operations, not re-prompt-and-hope. Receipts, benchmarks, and
+the full story: https://github.com/kiyeonjeon21/reframe
+
+## Requirements
+
+Node ≥ 20, ffmpeg on PATH, Playwright chromium (one-time
+`npx playwright install chromium`). macOS/Linux.

package/assets/sfx/LICENSE.md

@@ -0,0 +1,12 @@
+# Vendored sound effects — all CC0 1.0 (public domain)
+
+Verified against each asset page's license field on 2026-06-11.
+
+| files | source | author | license |
+|---|---|---|---|
+| keypress-001/004/007/010/014.wav | [Keyboard Soundpack #1](https://opengameart.org/content/keyboard-soundpack-1-typing-and-single-keystrokes) (Cherry KC 1000 recordings) | unicaegames | CC0 |
+| click_002/003/004.ogg, confirmation_001.ogg | [Interface Sounds](https://opengameart.org/content/interface-sounds) | Kenney (kenney.nl) | CC0 |
+
+CC0 requires no attribution; this file records provenance anyway.
+Files placed here named after a procedural SFX (e.g. `whoosh.wav`) override
+the synthesizer for that name.

package/dist/analyze.js

@@ -0,0 +1,344 @@
+// ../../benchmark/harness/motion/analyze.ts
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+
+// ../../benchmark/harness/motion/blockflow.ts
+var DEFAULT_OPTIONS = {
+  scale: 4,
+  // 480x270 analysis of 1920x1080
+  blockSize: 16,
+  searchRadius: 12,
+  changedThreshold: 2,
+  blockActivityThreshold: 1.5,
+  movingThreshold: 0.3
+};
+function blockSad(prev, next, width, bx, by, dx, dy, size) {
+  let sad = 0;
+  for (let y = 0; y < size; y++) {
+    let nextRow = (by + y) * width + bx;
+    let prevRow = (by + y + dy) * width + bx + dx;
+    for (let x = 0; x < size; x++) {
+      sad += Math.abs(next[nextRow + x] - prev[prevRow + x]);
+    }
+  }
+  return sad;
+}
+function parabola(left, best, right) {
+  const denom = left - 2 * best + right;
+  if (denom <= 0) return 0;
+  return Math.max(-0.5, Math.min(0.5, (left - right) / (2 * denom)));
+}
+function analyzePair(prev, next, opts) {
+  const { width, height, scale, blockSize, searchRadius: R, changedThreshold } = opts;
+  let diffSum = 0;
+  let changed = 0;
+  const n = width * height;
+  for (let i = 0; i < n; i++) {
+    const d = Math.abs(next[i] - prev[i]);
+    diffSum += d;
+    if (d > changedThreshold) changed++;
+  }
+  const diffMean = diffSum / n;
+  const changedFraction = changed / n;
+  const speeds = [];
+  let movingCount = 0;
+  let saturatedCount = 0;
+  let residualSum = 0;
+  let zeroSadSum = 0;
+  let bestSadSum = 0;
+  let activeBlocks = 0;
+  const pxPerBlock = blockSize * blockSize;
+  for (let by = R; by + blockSize + R <= height; by += blockSize) {
+    for (let bx = R; bx + blockSize + R <= width; bx += blockSize) {
+      const zeroSad = blockSad(prev, next, width, bx, by, 0, 0, blockSize);
+      if (zeroSad / pxPerBlock < opts.blockActivityThreshold) continue;
+      activeBlocks++;
+      const PENALTY = 2;
+      let best = zeroSad;
+      let bestScore = zeroSad;
+      let bestDx = 0;
+      let bestDy = 0;
+      for (let dy = -R; dy <= R; dy++) {
+        for (let dx = -R; dx <= R; dx++) {
+          if (dx === 0 && dy === 0) continue;
+          const sad = blockSad(prev, next, width, bx, by, dx, dy, blockSize);
+          const score = sad + PENALTY * (Math.abs(dx) + Math.abs(dy));
+          if (score < bestScore) {
+            bestScore = score;
+            best = sad;
+            bestDx = dx;
+            bestDy = dy;
+          }
+        }
+      }
+      let fx = bestDx;
+      let fy = bestDy;
+      if (Math.abs(bestDx) < R) {
+        fx += parabola(
+          blockSad(prev, next, width, bx, by, bestDx - 1, bestDy, blockSize),
+          best,
+          blockSad(prev, next, width, bx, by, bestDx + 1, bestDy, blockSize)
+        );
+      }
+      if (Math.abs(bestDy) < R) {
+        fy += parabola(
+          blockSad(prev, next, width, bx, by, bestDx, bestDy - 1, blockSize),
+          best,
+          blockSad(prev, next, width, bx, by, bestDx, bestDy + 1, blockSize)
+        );
+      }
+      const speed = Math.hypot(fx, fy);
+      residualSum += best / pxPerBlock;
+      zeroSadSum += zeroSad;
+      bestSadSum += best;
+      if (Math.abs(bestDx) >= R || Math.abs(bestDy) >= R) saturatedCount++;
+      if ((bestDx !== 0 || bestDy !== 0) && speed > opts.movingThreshold && best < 0.6 * zeroSad) {
+        movingCount++;
+        speeds.push(speed * scale);
+      }
+    }
+  }
+  speeds.sort((a, b) => a - b);
+  const matchResidual = activeBlocks > 0 ? residualSum / activeBlocks : 0;
+  return {
+    blockSpeedMean: speeds.length ? speeds.reduce((a, b) => a + b, 0) / speeds.length : 0,
+    blockSpeedP95: speeds.length ? speeds[Math.min(speeds.length - 1, Math.floor(speeds.length * 0.95))] : 0,
+    movingFraction: activeBlocks > 0 ? movingCount / activeBlocks : 0,
+    diffMean,
+    changedFraction,
+    matchResidual,
+    nonGeometricRatio: zeroSadSum > 0 ? Math.min(1, bestSadSum / zeroSadSum) : 0,
+    saturatedFraction: activeBlocks > 0 ? saturatedCount / activeBlocks : 0,
+    activeBlocks
+  };
+}
+
+// ../../benchmark/harness/motion/frames.ts
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+async function resolveSource(path) {
+  const s = await stat(path);
+  if (s.isDirectory()) return { kind: "png", input: join(path, "%05d.png") };
+  return { kind: "mp4", input: path };
+}
+async function* frameStream(source, opts) {
+  const frameBytes = opts.width * opts.height;
+  const args = [
+    "-loglevel",
+    "error",
+    ...source.kind === "png" ? ["-framerate", "30"] : [],
+    "-i",
+    source.input,
+    "-f",
+    "rawvideo",
+    "-pix_fmt",
+    "gray",
+    "-s",
+    `${opts.width}x${opts.height}`,
+    "-"
+  ];
+  const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+  let stderr = "";
+  proc.stderr.on("data", (d) => stderr += d.toString());
+  let pending = Buffer.alloc(0);
+  for await (const chunk of proc.stdout) {
+    pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+    while (pending.length >= frameBytes) {
+      yield new Uint8Array(pending.subarray(0, frameBytes));
+      pending = pending.subarray(frameBytes);
+    }
+  }
+  const code = await new Promise((res) => proc.on("close", (c) => res(c ?? 1)));
+  if (code !== 0) throw new Error(`ffmpeg exited ${code}: ${stderr.slice(-1e3)}`);
+  if (pending.length !== 0) throw new Error(`trailing partial frame (${pending.length} bytes)`);
+}
+
+// ../../benchmark/harness/motion/analyze.ts
+var ANALYSIS_WIDTH = 480;
+var ANALYSIS_HEIGHT = 270;
+var mean = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+function rollingMedian(xs, i, w) {
+  const half = Math.floor(w / 2);
+  const window = [];
+  for (let j = Math.max(0, i - half); j <= Math.min(xs.length - 1, i + half); j++) {
+    if (j !== i) window.push(xs[j]);
+  }
+  window.sort((a, b) => a - b);
+  return window.length ? window[Math.floor(window.length / 2)] : 0;
+}
+function spearman(xs, ys) {
+  const n = xs.length;
+  if (n < 4) return null;
+  const rank = (vs) => {
+    const sorted = vs.map((v, i) => [v, i]).sort((a, b) => a[0] - b[0]);
+    const ranks = new Array(n);
+    sorted.forEach(([, originalIndex], r) => ranks[originalIndex] = r);
+    return ranks;
+  };
+  const rx = rank(xs);
+  const ry = rank(ys);
+  const mx = mean(rx);
+  const my = mean(ry);
+  let cov = 0;
+  let vx = 0;
+  let vy = 0;
+  for (let i = 0; i < n; i++) {
+    cov += (rx[i] - mx) * (ry[i] - my);
+    vx += (rx[i] - mx) ** 2;
+    vy += (ry[i] - my) ** 2;
+  }
+  return vx > 0 && vy > 0 ? cov / Math.sqrt(vx * vy) : null;
+}
+function dominantPeriodicity(xs, fps) {
+  const n = xs.length;
+  if (n < 24) return null;
+  const m = mean(xs);
+  const centered = xs.map((x) => x - m);
+  const var0 = mean(centered.map((x) => x * x));
+  if (var0 < 1e-6) return null;
+  const maxLag = Math.floor(n / 2);
+  const corr = [];
+  for (let lag = 0; lag <= maxLag; lag++) {
+    let c = 0;
+    for (let i = 0; i + lag < n; i++) c += centered[i] * centered[i + lag];
+    corr.push(c / ((n - lag) * var0));
+  }
+  let bestLag = 0;
+  let bestCorr = 0;
+  for (let lag = 4; lag < maxLag; lag++) {
+    const isLocalMax = corr[lag] > corr[lag - 1] && corr[lag] >= corr[lag + 1];
+    if (isLocalMax && corr[lag] > bestCorr) {
+      bestCorr = corr[lag];
+      bestLag = lag;
+    }
+  }
+  return bestCorr > 0.3 && bestLag > 0 ? fps / bestLag : null;
+}
+function classifyEasing(speeds, nonGeometricRatios, saturatedFractions) {
+  const reliable = speeds.length >= 6 && mean(nonGeometricRatios) < 0.5 && saturatedFractions.filter((s) => s > 0.3).length / saturatedFractions.length < 0.2 && mean(speeds) > 0.5;
+  if (!reliable) {
+    return { class: "unreliable", thirdsRatio: null, spearman: null, reliable: false };
+  }
+  const third = Math.max(1, Math.floor(speeds.length / 3));
+  const first = mean(speeds.slice(0, third));
+  const last = mean(speeds.slice(-third));
+  const R = last > 0.01 ? first / last : Infinity;
+  const rho = spearman(
+    speeds.map((_, i) => i),
+    speeds
+  );
+  let cls = "other";
+  if (R > 1.8 && rho !== null && rho < -0.5) cls = "decelerating";
+  else if (R < 0.55 && rho !== null && rho > 0.5) cls = "accelerating";
+  else if (R >= 0.7 && R <= 1.4 && rho !== null && Math.abs(rho) < 0.4) cls = "linear";
+  return { class: cls, thirdsRatio: Number.isFinite(R) ? R : null, spearman: rho, reliable: true };
+}
+async function analyzeMotion(inputPath, opts = {}) {
+  const fps = opts.fps ?? 30;
+  const blockOpts = {
+    ...DEFAULT_OPTIONS,
+    width: ANALYSIS_WIDTH,
+    height: ANALYSIS_HEIGHT,
+    ...opts.changedThreshold !== void 0 && { changedThreshold: opts.changedThreshold }
+  };
+  const source = await resolveSource(resolve(inputPath));
+  const keys = [
+    "blockSpeedMean",
+    "blockSpeedP95",
+    "movingFraction",
+    "diffMean",
+    "changedFraction",
+    "matchResidual",
+    "nonGeometricRatio",
+    "saturatedFraction",
+    "activeBlocks"
+  ];
+  const series = Object.fromEntries([...keys.map((k) => [k, []]), ["t", []]]);
+  let prev = null;
+  let pair = 0;
+  for await (const frame of frameStream(source, blockOpts)) {
+    if (prev) {
+      const stats = analyzePair(prev, frame, blockOpts);
+      for (const k of keys) series[k].push(stats[k]);
+      series.t.push((pair + 0.5) / fps);
+      pair++;
+    }
+    prev = frame;
+  }
+  const d = series.diffMean;
+  const staticFlags = series.changedFraction.map((c) => c < 5e-3);
+  let longestRun = 0;
+  let run = 0;
+  for (const isStatic of staticFlags) {
+    run = isStatic ? run + 1 : 0;
+    longestRun = Math.max(longestRun, run);
+  }
+  const spikes = [];
+  for (let i = 0; i < d.length; i++) {
+    const med = rollingMedian(d, i, 9);
+    const neighbors = Math.max(i > 0 ? d[i - 1] : 0, i + 1 < d.length ? d[i + 1] : 0);
+    if (d[i] > Math.max(4 * med, 1) && series.changedFraction[i] > 0.01 && neighbors < d[i] / 2) {
+      spikes.push({ pair: i, t: series.t[i], ratio: med > 0 ? d[i] / med : Infinity });
+    }
+  }
+  const segments = (opts.segments ?? []).map((seg) => {
+    const idx = series.t.map((t, i) => t >= seg.t0 && t <= seg.t1 ? i : -1).filter((i) => i >= 0);
+    return {
+      ...seg,
+      easing: classifyEasing(
+        idx.map((i) => series.blockSpeedMean[i]),
+        idx.map((i) => series.nonGeometricRatio[i]),
+        idx.map((i) => series.saturatedFraction[i])
+      )
+    };
+  });
+  return {
+    params: { ...blockOpts, analysisWidth: ANALYSIS_WIDTH, analysisHeight: ANALYSIS_HEIGHT, source: source.kind },
+    fps,
+    framePairs: series.t.length,
+    series,
+    summary: {
+      meanSpeed: mean(series.blockSpeedMean.filter((s) => s > 0)),
+      peakSpeed: Math.max(0, ...series.blockSpeedP95),
+      meanDiff: mean(d),
+      staticFraction: staticFlags.filter(Boolean).length / Math.max(1, staticFlags.length),
+      longestStaticRunSec: longestRun / fps,
+      allStatic: staticFlags.every(Boolean),
+      spikes,
+      saturatedPairs: series.saturatedFraction.map((s, i) => s > 0.3 ? i : -1).filter((i) => i >= 0),
+      diffPeriodicityHz: dominantPeriodicity(d, fps)
+    },
+    segments
+  };
+}
+async function main() {
+  const [input, ...rest] = process.argv.slice(2);
+  if (!input) {
+    console.error("usage: tsx analyze.ts <mp4|framesDir> [-o out.json] [--fps N] [--segments seg.json] [--changed-threshold N]");
+    process.exit(2);
+  }
+  let out = null;
+  const opts = {};
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "-o") out = rest[++i];
+    else if (rest[i] === "--fps") opts.fps = Number(rest[++i]);
+    else if (rest[i] === "--segments") opts.segments = JSON.parse(readFileSync(rest[++i], "utf8"));
+    else if (rest[i] === "--changed-threshold") opts.changedThreshold = Number(rest[++i]);
+  }
+  const profile = await analyzeMotion(input, opts);
+  const json = JSON.stringify(profile, null, 1);
+  if (out) await writeFile(out, json);
+  else console.log(json);
+}
+if (/analyze\.(ts|js)$/.test(process.argv[1] ?? "")) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+export {
+  analyzeMotion,
+  classifyEasing
+};