agentvfx 0.0.0-stage → 0.3.5

package/skills/agentvfx/schemas/fx-score.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentvfx/fx-score.schema.json",
+  "title": "agentvfx FX score",
+  "description": "What the model writes to render one 3-5 s clip. Enforced by engine/core/validate.mjs (vfx.mjs validate), which also checks template ids, presets, parameter ranges and bindings against the library.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "template", "durationSec", "seed"],
+  "$defs": {
+    "layer": {
+      "oneOf": [
+        { "type": "string", "description": "template id" },
+        {
+          "type": "object", "additionalProperties": false, "required": ["template"],
+          "properties": { "template": { "type": "string" }, "preset": { "type": "string" }, "params": { "type": "object" } }
+        }
+      ]
+    },
+    "hex": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+  },
+  "properties": {
+    "version": { "const": 1 },
+    "template": { "type": "string", "description": "base layer template id (vfx.mjs list)" },
+    "preset": { "type": "string" },
+    "params": { "type": "object", "description": "input name -> value; overrides the preset" },
+    "stack": { "type": "array", "maxItems": 2, "items": { "$ref": "#/$defs/layer" }, "description": "layers drawn on top of the base, each fed the previous layer as inputImage" },
+    "input": {
+      "type": "object", "additionalProperties": false,
+      "properties": { "video": { "type": "string" }, "audio": { "type": "string" }, "startSec": { "type": "number", "minimum": 0 } }
+    },
+    "durationSec": { "type": "number", "minimum": 3, "maximum": 5 },
+    "fps": { "enum": [24, 25, 30, 50, 60], "description": "default: the template's X_AGENTVFX.fps, else 30" },
+    "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+    "bindings": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["param", "feature", "gain", "offset"],
+        "properties": {
+          "param": { "type": "string" },
+          "feature": { "type": "string", "description": "rms, peak, rmsDb, bass, mid, treb, bass_att, mid_att, treb_att, flux, onset, beat, beatPhase, bpm, corr, width, balance, or bands.0..bands.31" },
+          "gain": { "type": "number" }, "offset": { "type": "number" },
+          "attackMs": { "type": "number", "minimum": 0 }, "releaseMs": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "hits": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["template", "durationFrames"],
+        "description": "exactly one of t (seconds), onset (onset index), beat (beat index)",
+        "properties": {
+          "t": { "type": "number", "minimum": 0 }, "onset": { "type": "integer", "minimum": 0 }, "beat": { "type": "integer", "minimum": 0 },
+          "template": { "type": "string" }, "preset": { "type": "string" }, "params": { "type": "object" },
+          "durationFrames": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "cuts": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["layers"],
+        "description": "hard cut: exactly one of t (seconds) or beat (beat index); the layers replace the base stack from that frame",
+        "properties": {
+          "t": { "type": "number", "minimum": 0 }, "beat": { "type": "integer", "minimum": 0 },
+          "layers": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/$defs/layer" } }
+        }
+      }
+    },
+    "palette": {
+      "oneOf": [
+        { "enum": ["brutal-acid", "brutal-red", "mono", "rainbow", "thermal", "paper-grey", "acid-data", "hazard-orange", "flesh-pink", "lilac-terminal", "blood-red", "clinic-mint"] },
+        { "type": "array", "minItems": 2, "maxItems": 8, "items": { "$ref": "#/$defs/hex" } }
+      ]
+    },
+    "safety": {
+      "type": "object", "additionalProperties": false,
+      "description": "default { mode: stage }: full intensity, flash audit written as a report and SAFETY.txt. broadcast-safe enforces limits; safeVariant adds film.safe.mp4 next to the full-intensity film.mp4.",
+      "properties": { "mode": { "enum": ["stage", "broadcast-safe"] }, "safeVariant": { "type": "boolean" } }
+    },
+    "out": { "type": "string", "description": "output folder name" },
+    "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "text item key -> string, overriding the template's default text" },
+    "textStyle": {
+      "type": "object",
+      "description": "text item key -> look override merged over the template's text item (see references/template-format.md, Text layer)",
+      "additionalProperties": {
+        "type": "object", "additionalProperties": false,
+        "properties": {
+          "font": { "enum": ["display", "tall", "grotesk", "mono", "serif"] },
+          "size": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+          "x": { "type": "number", "minimum": -0.5, "maximum": 1.5 }, "y": { "type": "number", "minimum": -0.5, "maximum": 1.5 },
+          "tracking": { "type": "number", "minimum": -0.2, "maximum": 2 },
+          "align": { "enum": ["left", "center", "right"] },
+          "weight": { "type": "number", "minimum": 100, "maximum": 900 }
+        }
+      }
+    }
+  }
+}

package/skills/agentvfx/scripts/export-web.mjs

@@ -0,0 +1,157 @@
+// agentvfx (Apache-2.0, see LICENSE). Bundle selected templates and the live runtime into a folder a page
+// can open with no network and no build. The GLSL prelude is imported here and inlined verbatim.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PALETTES, hexToRgb } from "../engine/core/palettes.mjs";
+import { resolveParams } from "../engine/core/templates.mjs";
+import { loadLibrary } from "../engine/core/templates.mjs";
+import { templatePasses } from "../engine/node/render.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const runtimePath = path.join(here, "../runtime/agentvfx.js");
+const preludePath = path.join(here, "../engine/web/prelude.mjs");
+const licensePath = path.join(here, "../LICENSE");
+const noticePath = path.join(here, "../NOTICE");
+// The licence notice is added after stripUrls runs, so it survives; it names the repository without a scheme because the
+// bundle must hold no fetchable URL. LICENSE and NOTICE, with their URLs, are written beside it.
+const LICENSE_NOTICE = [
+  "agentvfx is licensed under the Apache License 2.0; see LICENSE and NOTICE in this folder. Keep them with these files.",
+  "Copyright 2026 Woojin Go (github.com/wjgoarxiv/agentvfx)",
+];
+const flashPaths = ["../engine/core/flash-constants.mjs", "../engine/core/flash.mjs"].map((p) => path.join(here, p));
+
+function parseArgs(argv) {
+  const ids = [];
+  let out = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--out") out = argv[++i];
+    else ids.push(argv[i]);
+  }
+  return { ids, out };
+}
+
+function stripUrls(source) {
+  return source.split("\n").filter((line) => !/https?:\/\//u.test(line)).join("\n");
+}
+
+// Shader credits cite their sources as links inside comments. The bundle keeps each credit and drops only the
+// scheme, so the folder still holds no fetchable URL.
+function delink(source) {
+  return source.replace(/https?:\/\//gu, "");
+}
+
+function bundleRuntime() {
+  const prelude = stripUrls(readFileSync(preludePath, "utf8"));
+  const runtime = readFileSync(runtimePath, "utf8")
+    .split("\n")
+    .filter((line) => !line.startsWith("import "))
+    .join("\n");
+  const glue = `const PALETTES = Object.freeze(${JSON.stringify(PALETTES)});\n${hexToRgb.toString()}\n${resolveParams.toString()}\n`;
+  // The live flash guard runs the audit's own detector, inlined module by module without its import/export syntax.
+  const flash = flashPaths.map((p) => readFileSync(p, "utf8").split("\n")
+    .filter((line) => !line.startsWith("import ") && !line.startsWith("export {"))
+    .map((line) => line.replace(/^export /u, ""))
+    .join("\n")).join("\n");
+  return `${LICENSE_NOTICE.map((line) => `// ${line}`).join("\n")}\n${prelude}\n${glue}\n${flash}\n${runtime}`;
+}
+
+function bundleTemplates(lib, ids) {
+  const out = {};
+  for (const id of ids) {
+    const tpl = lib.get(id);
+    const fx = structuredClone(tpl.fx);
+    if (fx.X_AGENTVFX) delete fx.X_AGENTVFX.credits;
+    out[id] = {
+      fx,
+      passes: templatePasses(tpl).map((pass) => ({
+        target: pass.target,
+        persistent: pass.persistent,
+        file: pass.file,
+        src: delink(readFileSync(path.join(tpl.dir, pass.file), "utf8")),
+      })),
+    };
+  }
+  return `export default ${JSON.stringify(out)};\n`;
+}
+
+function demoHtml(ids) {
+  const hero = ids[0];
+  const hit = ids.includes("test-strobe") ? "test-strobe" : ids[0];
+  const head = ids.includes("sacred") ? "sacred" : ids[0];
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<!-- ${LICENSE_NOTICE.join(" ")} -->
+<title>agentvfx</title>
+<style>
+  html, body { margin: 0; background: #000; color: #fff; font: 16px sans-serif; }
+  #hero { position: fixed; inset: 0; width: 100%; height: 100%; display: block; pointer-events: none; }
+  #head { position: fixed; left: 24px; top: 24px; width: min(70vw, 640px); height: 96px; pointer-events: none; }
+  #hit, label { position: fixed; z-index: 2; background: #111; color: #fff; border: 1px solid #fff; padding: 8px 14px; font: 16px sans-serif; }
+  #hit { left: 24px; bottom: 24px; }
+  label { right: 24px; bottom: 24px; }
+  audio { position: fixed; left: 24px; bottom: 72px; width: min(70vw, 360px); }
+</style>
+</head>
+<body>
+<canvas id="hero"></canvas>
+<canvas id="head"></canvas>
+<button id="hit" type="button">Hit</button>
+<audio id="player" controls></audio>
+<label>Audio <input id="file" type="file" accept="audio/*"></label>
+<script type="module">
+import { AgentVfx } from "./agentvfx.js";
+import templates from "./templates.js";
+const hero = document.getElementById("hero");
+const head = document.getElementById("head");
+const fx = await AgentVfx.mount(hero, { templates, template: ${JSON.stringify(hero)} });
+const label = AgentVfx.textSource({ text: "AGENTVFX", font: "700 64px sans-serif", color: "#ffffff", background: "#000000", width: 960, height: 180 });
+await AgentVfx.mount(head, { templates, template: ${JSON.stringify(head)}, source: label });
+const fire = () => fx.trigger(${JSON.stringify(hit)}, { preset: "hold", durationMs: 2000 });
+document.getElementById("hit").addEventListener("pointerenter", fire);
+document.getElementById("hit").addEventListener("click", fire);
+document.getElementById("file").addEventListener("change", (event) => {
+  const file = event.target.files && event.target.files[0];
+  if (!file) return;
+  const player = document.getElementById("player");
+  player.src = URL.createObjectURL(file);
+  player.play();
+  fx.audio(player);
+});
+window.__hit = fire;
+window.__litReady = true;
+</script>
+</body>
+</html>
+`;
+}
+
+const { ids, out } = parseArgs(process.argv.slice(2));
+if (!out || ids.length === 0) {
+  console.error("usage: node scripts/export-web.mjs <templateId...> --out <dir>");
+  process.exit(1);
+}
+const lib = loadLibrary({ includeTest: true });
+const missing = ids.filter((id) => !lib.has(id));
+if (missing.length) {
+  for (const id of missing) console.error(`unknown template id ${id}`);
+  process.exit(1);
+}
+mkdirSync(out, { recursive: true });
+const files = {
+  "agentvfx.js": bundleRuntime(),
+  "templates.js": bundleTemplates(lib, ids),
+  "demo.html": demoHtml(ids),
+};
+for (const [name, body] of Object.entries(files)) {
+  if (/https?:\/\//u.test(body)) {
+    console.error(`${name} still contains an external URL`);
+    process.exit(1);
+  }
+  writeFileSync(path.join(out, name), body);
+}
+// The licence and notice carry URLs by design, so they are copied verbatim after the no-URL check above.
+writeFileSync(path.join(out, "LICENSE"), readFileSync(licensePath));
+writeFileSync(path.join(out, "NOTICE"), readFileSync(noticePath));

package/skills/agentvfx/scripts/loop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Turn a rendered clip into a silent seamless loop: play forward, then backward (2N-2 frames, no held frame at either turn),
+// optionally write a small looping WebP preview, and flash-audit the loop played twice so the wrap point is checked too.
+// node loop.mjs <in.mp4> <out.mp4> [--preview out.webp|out.gif] [--audit out.json] [--crf 23] [--maxrate 3500] [--hold 0]
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createFlashAuditor } from "../engine/core/flash.mjs";
+import { encodePreview, findFfmpeg, findImg2webp, previewRungs, probeVideo } from "../engine/node/encode.mjs";
+
+function ffmpegOrThrow() {
+  const ffmpeg = findFfmpeg();
+  if (!ffmpeg) throw new Error("BLOCKED_NO_FFMPEG_FOR_VIDEO: ffmpeg not found (set FFMPEG_PATH or install ffmpeg)");
+  return ffmpeg;
+}
+
+function run(ffmpeg, args) {
+  const r = spawnSync(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", ...args], { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffmpeg failed: ${r.stderr}`);
+}
+
+/** Write the forward+backward loop of `src` to `out` with no audio stream. Returns { frames, fps }. */
+export function pingpong(src, out, { crf = 23, maxrateKbps = 3500, hold = 0 } = {}) {
+  if (!Number.isInteger(hold) || hold < 0) throw new Error(`pingpong: hold must be a whole number of frames >= 0, got ${hold}`);
+  if (path.resolve(src) === path.resolve(out)) throw new Error("pingpong: output must differ from input");
+  const ffmpeg = ffmpegOrThrow();
+  const info = probeVideo(src);
+  if (!info?.frames || info.frames < 3) throw new Error(`pingpong: cannot read frames of ${src}`);
+  const n = info.frames;
+  mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+  // hold > 0 freezes each turn for `hold` extra frames, which spreads the doubled-back transitions across a wider window.
+  const pad = hold > 0 ? `,tpad=stop_mode=clone:stop=${hold}` : "";
+  run(ffmpeg, ["-i", src, "-filter_complex",
+    `[0:v]split[a][b];[a]setpts=PTS-STARTPTS${pad}[f];[b]reverse,trim=start_frame=1:end_frame=${n - 1},setpts=PTS-STARTPTS${pad}[r];[f][r]concat=n=2:v=1:a=0[v]`,
+    "-map", "[v]", "-an", "-c:v", "libx264", "-preset", "slow", "-crf", String(crf),
+    "-maxrate", `${maxrateKbps}k`, "-bufsize", `${maxrateKbps * 2}k`, "-pix_fmt", "yuv420p", "-movflags", "+faststart", out]);
+  return { frames: 2 * n - 2 + 2 * hold, fps: info.fps };
+}
+
+/** Small looping animated preview (README use): WebP through the engine's preview ladder (ffmpeg libwebp_anim, img2webp), GIF as the last rung. */
+export function preview(src, out, { width = 400, fps = 12 } = {}) {
+  const ffmpeg = ffmpegOrThrow();
+  mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-preview-"));
+  try {
+    run(ffmpeg, ["-i", src, "-vf", `fps=${fps},scale=${width}:-2:flags=lanczos`, "-an", "-start_number", "0", path.join(dir, "%05d.png")]);
+    const rungs = previewRungs(ffmpeg).filter((r) => (out.endsWith(".gif") ? r === "gif" : r !== "gif"));
+    if (!rungs.length) throw new Error(`preview: no encoder for ${path.extname(out)} (install img2webp, or ffmpeg with libwebp)`);
+    const r = encodePreview({ encoder: rungs[0], ffmpeg, img2webp: findImg2webp(), dir, fps, out });
+    if (r.code !== 0) throw new Error(`preview (${rungs[0]}) failed: ${r.stderr}`);
+    return rungs[0];
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Decode a whole (small) clip to RGBA frames. Meant for tests and short clips. */
+export function readFrames(file) {
+  const ffmpeg = ffmpegOrThrow();
+  const { width, height } = probeVideo(file);
+  const r = spawnSync(ffmpeg, ["-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "-"], { maxBuffer: 1 << 30 });
+  if (r.status !== 0) throw new Error(`readFrames: ${r.stderr}`);
+  const size = width * height * 4;
+  const frames = [];
+  for (let o = 0; o + size <= r.stdout.length; o += size) frames.push({ width, height, data: r.stdout.subarray(o, o + size) });
+  return frames;
+}
+
+/** Flash-audit the clip played `plays` times back to back (streams frames; never holds the clip in memory). */
+export function auditLoop(file, { plays = 2 } = {}) {
+  const ffmpeg = ffmpegOrThrow();
+  const info = probeVideo(file);
+  if (!info) throw new Error(`auditLoop: cannot probe ${file}`);
+  const { width, height, fps } = info;
+  const auditor = createFlashAuditor({ fps, width, height });
+  const size = width * height * 4;
+  return new Promise((resolve, reject) => {
+    const p = spawn(ffmpeg, ["-v", "error", "-stream_loop", String(plays - 1), "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "-"]);
+    let pending = Buffer.alloc(0);
+    let err = "";
+    p.stderr.on("data", (d) => { err += d; });
+    let failed = null;
+    p.stdout.on("data", (chunk) => {
+      if (failed) return;
+      try {
+        pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+        while (pending.length >= size) {
+          auditor.push({ width, height, data: pending.subarray(0, size) });
+          pending = pending.subarray(size);
+        }
+      } catch (e) {
+        failed = e;
+        p.kill();
+      }
+    });
+    p.on("error", reject);
+    p.on("close", (code) => {
+      if (failed) return reject(failed);
+      if (code !== 0) return reject(new Error(`auditLoop: ffmpeg exit ${code} ${err}`));
+      const report = auditor.finish();
+      resolve({ pass: !report.exceeds, plays, ...report });
+    });
+  });
+}
+
+async function main(argv) {
+  const [src, out, ...rest] = argv;
+  if (!src || !out) {
+    console.error("usage: loop.mjs <in.mp4> <out.mp4> [--preview out.webp|out.gif] [--audit out.json] [--crf 23] [--maxrate 3500] [--hold 0]");
+    return 2;
+  }
+  const opt = {};
+  for (let i = 0; i < rest.length; i += 2) opt[rest[i].replace(/^--/, "")] = rest[i + 1];
+  const res = pingpong(src, out, { crf: Number(opt.crf ?? 23), maxrateKbps: Number(opt.maxrate ?? 3500), hold: Number(opt.hold ?? 0) });
+  if (opt.preview) preview(out, opt.preview);
+  const audit = await auditLoop(out);
+  if (opt.audit) {
+    mkdirSync(path.dirname(path.resolve(opt.audit)), { recursive: true });
+    writeFileSync(opt.audit, `${JSON.stringify(audit, null, 2)}\n`);
+  }
+  console.log(JSON.stringify({ out, frames: res.frames, fps: res.fps, flashPass: audit.pass, worstWindow: audit.worstWindow, redFlashes: audit.redFlashes }));
+  return audit.pass ? 0 : 3;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.message); process.exit(1); });
+}

package/skills/agentvfx/scripts/make-beat.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// agentvfx (Apache-2.0, see LICENSE). Generates the original 10 s, 132 BPM demo drum loop (test-media/beat-132.mp3).
+// Everything is synthesised here from sines and seeded noise: a kick on every beat, a snare on
+// beats 2 and 4, closed hats on the 8ths, starting a quarter beat in, over a faint noise bed so the
+// waveform never goes flat between hits. Nothing is sampled or downloaded.
+// usage: node scripts/make-beat.mjs [out.mp3]
+import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findFfmpeg } from "../engine/node/encode.mjs";
+
+const SR = 48000;
+const BPM = 132;
+const SECONDS = 10;
+const BEAT = (60 / BPM) * SR;
+const N = SR * SECONDS;
+const LEAD_BEATS = 0.26;
+const AIR = 0.06;
+const TAU = Math.PI * 2;
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Stereo float mix. L and R draw their own noise so the hats and snare are not mono. */
+export function renderBeat() {
+  const rand = mulberry32(132);
+  const L = new Float32Array(N);
+  const R = new Float32Array(N);
+  const add = (start, len, fn) => {
+    for (let i = 0; i < len && start + i < N; i++) {
+      const [l, r] = fn(i / SR, i);
+      L[start + i] += l;
+      R[start + i] += r;
+    }
+  };
+  const noise = () => rand() * 2 - 1;
+
+  const kick = (start) => {
+    let phase = 0;
+    add(start, Math.floor(0.25 * SR), (t) => {
+      phase += (TAU * (45 + 110 * Math.exp(-t * 28))) / SR;
+      const body = Math.sin(phase) * Math.exp(-t * 18) * 0.95;
+      const click = Math.exp(-t * 250) * 0.5 * noise();
+      return [body + click, body + click];
+    });
+  };
+  const snare = (start) => {
+    add(start, Math.floor(0.25 * SR), (t) => {
+      const tone = Math.sin(TAU * 190 * t) * Math.exp(-t * 28) * 0.25;
+      const env = Math.exp(-t * 17) * 0.22;
+      return [tone + noise() * env, tone + noise() * env];
+    });
+  };
+  const hat = (start, accent) => {
+    let pl = 0;
+    let pr = 0;
+    add(start, Math.floor(0.06 * SR), (t) => {
+      const nl = noise();
+      const nr = noise();
+      const env = Math.exp(-t * 90) * (accent ? 0.07 : 0.04);
+      const out = [(nl - pl) * env, (nr - pr) * env];
+      pl = nl;
+      pr = nr;
+      return out;
+    });
+  };
+
+  for (let b = 0; (b + LEAD_BEATS) * BEAT < N; b++) {
+    const at = Math.round((b + LEAD_BEATS) * BEAT);
+    kick(at);
+    if (b % 4 === 1 || b % 4 === 3) snare(at);
+    hat(at, false);
+    hat(Math.round((b + LEAD_BEATS + 0.5) * BEAT), true);
+  }
+  let lo = 0;
+  let ro = 0;
+  for (let i = 0; i < N; i++) {
+    lo += (noise() - lo) * 0.35;
+    ro += (noise() - ro) * 0.35;
+    L[i] += lo * AIR;
+    R[i] += ro * AIR;
+  }
+  return [L, R];
+}
+
+/** 16-bit stereo WAV bytes, soft-limited so the loudest hit sits near -1 dBFS. */
+export function toWav([L, R]) {
+  const data = Buffer.alloc(N * 4);
+  for (let i = 0; i < N; i++) {
+    data.writeInt16LE(Math.round(Math.tanh(L[i] * 1.1) * 0.89 * 32767), i * 4);
+    data.writeInt16LE(Math.round(Math.tanh(R[i] * 1.1) * 0.89 * 32767), i * 4 + 2);
+  }
+  const head = Buffer.alloc(44);
+  head.write("RIFF", 0);
+  head.writeUInt32LE(36 + data.length, 4);
+  head.write("WAVEfmt ", 8);
+  head.writeUInt32LE(16, 16);
+  head.writeUInt16LE(1, 20);
+  head.writeUInt16LE(2, 22);
+  head.writeUInt32LE(SR, 24);
+  head.writeUInt32LE(SR * 4, 28);
+  head.writeUInt16LE(4, 32);
+  head.writeUInt16LE(16, 34);
+  head.write("data", 36);
+  head.writeUInt32LE(data.length, 40);
+  return Buffer.concat([head, data]);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const out = path.resolve(process.argv[2] ?? path.join(root, "test-media", "beat-132.mp3"));
+  const ffmpeg = findFfmpeg();
+  if (!ffmpeg) {
+    console.error("make-beat: ffmpeg not found (set FFMPEG_PATH or put it on PATH)");
+    process.exit(1);
+  }
+  mkdirSync(path.dirname(out), { recursive: true });
+  const r = spawnSync(ffmpeg, ["-v", "error", "-y", "-f", "wav", "-i", "pipe:0", "-map_metadata", "-1", "-fflags", "+bitexact", "-flags:a", "+bitexact", "-c:a", "libmp3lame", "-b:a", "192k", out], { input: toWav(renderBeat()), encoding: "utf8", maxBuffer: 1 << 26 });
+  if (r.status !== 0) {
+    console.error(`make-beat: ffmpeg failed: ${r.stderr}`);
+    process.exit(1);
+  }
+  console.log(`wrote ${out} (${SECONDS} s, ${BPM} BPM)`);
+}

package/skills/agentvfx/scripts/plate.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Render a procedural Blender "plate" (background footage for agentvfx templates) and encode it to H.264 film.mp4.
+// node plate.mjs --scene terminalcore --shot wall --out gallery/plates/terminalcore-wall --width 640 --height 360 --seconds 4 --fps 30 --samples 48
+// Extra: --quality preview|final (final: 256 samples, accurate denoise, camera motion blur), --frame N (single test still, no video),
+//        --exposure EV, --bloom X, --key X, --haze X, --keep-frames, --no-post
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findFfmpeg, which } from "../engine/node/encode.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const FLAGS = new Set(["keep-frames", "no-post"]);
+
+function parseArgs(argv) {
+  const o = {};
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i].replace(/^--/, "");
+    if (FLAGS.has(k)) o[k] = true;
+    else o[k] = argv[++i];
+  }
+  return o;
+}
+
+function findBlender(env = process.env) {
+  const mac = "/Applications/Blender.app/Contents/MacOS/Blender";
+  const found = [env.BLENDER_PATH, which("blender", env), mac].find((p) => p && existsSync(p));
+  if (!found) throw new Error("BLOCKED_NO_BLENDER: set BLENDER_PATH or install Blender 5.x");
+  return found;
+}
+
+const o = parseArgs(process.argv.slice(2));
+const scene = o.scene ?? "terminalcore";
+const shot = o.shot ?? "wall";
+const out = path.resolve(o.out ?? `gallery/plates/${scene}-${shot}`);
+const width = Number(o.width ?? 640);
+const height = Number(o.height ?? 360);
+const seconds = Number(o.seconds ?? 4);
+const fps = Number(o.fps ?? 30);
+const quality = o.quality ?? "preview";
+if (!["preview", "final"].includes(quality)) throw new Error(`--quality must be preview or final, got "${quality}"`);
+const samples = Number(o.samples ?? (quality === "final" ? 256 : 40));
+const script = path.join(here, "..", "plates", scene, "scene.py");
+if (!existsSync(script)) throw new Error(`unknown plate scene "${scene}" (no ${script})`);
+
+mkdirSync(out, { recursive: true });
+const frames = path.join(out, "frames");
+rmSync(frames, { recursive: true, force: true });
+const args = ["-b", "--factory-startup", "--python-exit-code", "1", "--python", script, "--", "--shot", shot, "--out", out, "--width", width, "--height", height, "--seconds", seconds, "--fps", fps, "--samples", samples, "--quality", quality];
+for (const k of ["frame", "exposure", "bloom", "key", "haze"]) if (o[k] !== undefined) args.push(`--${k}`, o[k]);
+
+const t0 = Date.now();
+const bl = spawnSync(findBlender(), args.map(String), { encoding: "utf8", maxBuffer: 1 << 29 });
+const renderSec = (Date.now() - t0) / 1000;
+const log = (bl.stdout ?? "") + (bl.stderr ?? "");
+writeFileSync(path.join(out, "blender.log"), log);
+if (bl.status !== 0 || log.includes("Traceback")) {
+  console.error(log.split("\n").slice(-40).join("\n"));
+  process.exit(bl.status || 1);
+}
+
+for (const line of log.split("\n")) if (line.startsWith("TIMING")) console.log(line);
+if (o.frame) {
+  console.log(`still ${path.join(out, `still_${String(o.frame).padStart(3, "0")}.png`)}  ${renderSec.toFixed(1)}s`);
+  process.exit(0);
+}
+
+const ffmpeg = findFfmpeg();
+if (!ffmpeg) throw new Error("BLOCKED_NO_FFMPEG: set FFMPEG_PATH or install ffmpeg");
+const pngs = readdirSync(frames).filter((f) => f.endsWith(".png")).sort();
+const grade = shot === "gallery" ? "vignette=PI/7,noise=alls=3:allf=t" : "vignette=PI/5.5,noise=alls=7:allf=t";
+const post = o["no-post"] ? "format=yuv420p" : `${grade},format=yuv420p`;
+const enc = spawnSync(ffmpeg, ["-v", "error", "-y", "-framerate", String(fps), "-start_number", "1", "-i", path.join(frames, "f_%04d.png"), "-vf", post, "-c:v", "libx264", "-crf", quality === "final" ? "14" : "17", "-preset", "slow", "-movflags", "+faststart", path.join(out, "film.mp4")], { encoding: "utf8" });
+if (enc.status !== 0) {
+  console.error(enc.stderr);
+  process.exit(enc.status ?? 1);
+}
+for (const [label, idx] of [["first", 0], ["mid", Math.floor(pngs.length / 2)], ["last", pngs.length - 1]]) copyFileSync(path.join(frames, pngs[idx]), path.join(out, `still_${label}.png`));
+if (!o["keep-frames"]) rmSync(frames, { recursive: true, force: true });
+const report = { scene, shot, quality, width, height, fps, seconds, samples, frames: pngs.length, renderSeconds: renderSec, secondsPerFrame: renderSec / pngs.length };
+writeFileSync(path.join(out, "plate.json"), JSON.stringify(report, null, 2));
+console.log(JSON.stringify(report));