agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/engine/core/mark.mjs

@@ -0,0 +1,28 @@
+// agentvfx (agentvfx licence, see LICENSE). Local replacement for the plugin's lib/mark.mjs: the generator
+// tag and the credit line that ffmpeg writes into every MP4, plus an optional comment (the stage-mode flashing notice).
+// Attribution is a licence condition for published output, so the credit also goes to CREDIT.txt next to the film.
+export const GENERATOR = "agentvfx";
+export const CREDIT_TEXT = "Made with agentvfx by Woojin Go - https://github.com/wjgoarxiv/agentvfx";
+export const CREDIT_SHORT = "VFX: agentvfx (github.com/wjgoarxiv/agentvfx)";
+
+export function creditText() {
+  return `${CREDIT_TEXT}
+
+Publishing this film? The agentvfx licence requires a credit. The film carries a small on-screen credit; keep it
+in the frame. If you switched it off ("credit": { "overlay": false }), put the line above where viewers can find
+it: the description, caption or credits. Where space is short: ${CREDIT_SHORT}
+When you hand the film to someone who will publish it, pass the credit on with it.
+Licence: the agentvfx licence (Additional Terms plus the PolyForm Noncommercial License 1.0.0). Individuals may use
+their own output commercially; companies, client work, paid services and AI training are not covered.
+See LICENSE in https://github.com/wjgoarxiv/agentvfx.
+`;
+}
+
+export function ffmpegMetadataArgs({ comment = null } = {}) {
+  const args = ["-metadata", `encoder_tool=${GENERATOR}`, "-metadata", `description=${CREDIT_TEXT}`];
+  if (comment) args.push("-metadata", `comment=${comment}`);
+  return args;
+}
+
+// The on-screen credit burned into a corner of every render unless the score sets "credit": { "overlay": false }.
+export const CREDIT_OVERLAY = "made with agentvfx";

package/skills/agentvfx/engine/core/palettes.mjs

@@ -0,0 +1,36 @@
+// agentvfx (agentvfx licence, see LICENSE). Shared palettes, usable by any template that declares a `palette` input.
+// Each palette is a list of sRGB hex stops; templates sample it as a ramp (index 0..1) or as a cyclic
+// ramp. Brutal palettes are black, white and one acid accent, in the spirit of festival HUD
+// colour grammar; the names are neutral and no existing colour system is copied.
+
+export const PALETTES = Object.freeze({
+  "brutal-acid": ["#000000", "#ffffff", "#c8ff00"],
+  "brutal-red": ["#000000", "#ffffff", "#ff2a00"],
+  mono: ["#000000", "#ffffff"],
+  rainbow: ["#ff0040", "#ff8000", "#ffee00", "#30ff40", "#00e5ff", "#2040ff", "#b000ff", "#ff00c8"],
+  thermal: ["#0010ff", "#6a00ff", "#ff00d0", "#ff0030", "#ff7a00", "#ffee00", "#00ffe0"],
+  "paper-grey": ["#d9d9d6", "#0a0a0a", "#ff2a6d"],
+  "acid-data": ["#000000", "#b6ff00", "#1f4dff"],
+  "hazard-orange": ["#141414", "#8c8c88", "#ff5a00"],
+  "flesh-pink": ["#ffffff", "#ff3c8e", "#111111"],
+  "lilac-terminal": ["#0b0613", "#b69cff", "#ff6ad5"],
+  "blood-red": ["#000000", "#d10000", "#ffffff"],
+  "clinic-mint": ["#f2f4f1", "#7fe3c1", "#b8a4ff"],
+});
+
+export const PALETTE_NAMES = Object.freeze(Object.keys(PALETTES));
+
+/** "#rrggbb" -> [r, g, b] in 0..1 (sRGB). */
+export function hexToRgb(hex) {
+  const m = /^#([0-9a-f]{6})$/iu.exec(hex);
+  if (!m) throw new Error(`not a #rrggbb colour: ${hex}`);
+  const n = parseInt(m[1], 16);
+  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
+}
+
+/** A palette name or a custom list of 2-8 hex stops -> list of [r, g, b]. */
+export function resolvePalette(value) {
+  const stops = typeof value === "string" ? PALETTES[value] : value;
+  if (!Array.isArray(stops)) throw new Error(`unknown palette: ${value}`);
+  return stops.map(hexToRgb);
+}

package/skills/agentvfx/engine/core/schedule.mjs

@@ -0,0 +1,85 @@
+// agentvfx (agentvfx licence, see LICENSE). The score compositor's timeline: for each frame, which layers are active
+// (base stack, cuts, hits), their parameter values (preset, params, audio bindings) and their local
+// time. Pure and deterministic; the page only draws what this returns.
+import { resolveParams } from "./templates.mjs";
+
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+
+/** Resolve a `t` / `beat` / `onset` reference to a frame index. */
+export function resolveFrame(ref, { fps, features }, path) {
+  if (ref.t !== undefined) return Math.round(ref.t * fps);
+  const kind = ref.beat !== undefined ? "beat" : "onset";
+  const list = kind === "beat" ? features?.meta?.beats : features?.meta?.onsets;
+  if (!list) throw Object.assign(new Error(`${path}.${kind}: needs an audio source (input.audio or a video with sound)`), { path: `${path}.${kind}` });
+  const idx = ref[kind];
+  if (idx >= list.length) throw Object.assign(new Error(`${path}.${kind}: index ${idx} but the track has ${list.length} ${kind}s`), { path: `${path}.${kind}` });
+  return list[idx];
+}
+
+const layerRef = (l) => (typeof l === "string" ? { template: l } : l);
+
+/** Feature value for a binding ("bands.12" or a scalar name) on one frame of features. */
+function featureValue(frame, feature) {
+  if (!frame) return 0;
+  if (feature.startsWith("bands.")) return Number(frame.bands?.[Number(feature.slice(6))] ?? 0);
+  return Number(frame[feature] ?? 0);
+}
+
+/**
+ * Build the per-frame plan. Returns { frameCount, frames: [{ layers: [{key, template, params, t}] }],
+ * templatesUsed: Set, events: [frame...] } where events are the frames of hits and cuts (for strips).
+ */
+export function buildSchedule(score, lib, { features = null } = {}) {
+  const fps = score.fps;
+  const frameCount = Math.round(score.durationSec * fps);
+  const ctx = { fps, features };
+  const used = new Set();
+  const resolve = (ref) => {
+    const tpl = lib.get(ref.template);
+    used.add(ref.template);
+    const text = tpl.fx.X_AGENTVFX.text;
+    const labels = text ? Object.fromEntries(text.map((t) => [t.key, score.labels?.[t.key] ?? t.default])) : null;
+    const styled = text && score.textStyle ? text.filter((t) => score.textStyle[t.key]) : [];
+    const textStyle = styled.length ? Object.fromEntries(styled.map((t) => [t.key, score.textStyle[t.key]])) : null;
+    return { template: ref.template, params: resolveParams(tpl.fx, ref), inputs: tpl.fx.INPUTS ?? [], labels, textStyle };
+  };
+  const initial = [{ template: score.template, preset: score.preset, params: score.params }, ...(score.stack ?? []).map(layerRef)].map(resolve);
+  const cuts = (score.cuts ?? []).map((c, i) => ({ frame: resolveFrame(c, ctx, `cuts[${i}]`), index: i, layers: c.layers.map(layerRef).map(resolve) }))
+    .sort((a, b) => a.frame - b.frame || a.index - b.index);
+  const hits = (score.hits ?? []).map((h, i) => ({ start: resolveFrame(h, ctx, `hits[${i}]`), index: i, duration: h.durationFrames, layer: resolve({ template: h.template, preset: h.preset, params: h.params }) }));
+
+  const bindings = (score.bindings ?? []).map((b) => ({ ...b, state: 0 }));
+  const frames = [];
+  for (let f = 0; f < frameCount; f++) {
+    let base = { id: "b", layers: initial };
+    for (const c of cuts) if (c.frame <= f) base = { id: `c${c.index}`, layers: c.layers };
+    const featureFrame = features?.frames?.[f] ?? null;
+    const bound = {};
+    for (const b of bindings) {
+      const raw = featureValue(featureFrame, b.feature);
+      const ms = raw > b.state ? b.attackMs : b.releaseMs;
+      const k = isNum(ms) && ms > 0 ? Math.exp(-1000 / (fps * ms)) : 0;
+      b.state = k * b.state + (1 - k) * raw;
+      bound[b.param] = b.offset + b.gain * b.state;
+    }
+    const applyBindings = (layer) => {
+      if (layer.template !== score.template || !bindings.length) return layer.params;
+      const params = { ...layer.params };
+      for (const input of layer.inputs) {
+        if (bound[input.NAME] === undefined) continue;
+        let v = bound[input.NAME];
+        if (isNum(input.MIN)) v = Math.max(input.MIN, v);
+        if (isNum(input.MAX)) v = Math.min(input.MAX, v);
+        params[input.NAME] = input.TYPE === "long" ? Math.round(v) : input.TYPE === "bool" ? v > 0.5 : v;
+      }
+      return params;
+    };
+    const layers = base.layers.map((l, i) => ({ key: `${base.id}:${i}`, template: l.template, params: applyBindings(l), t: f / fps, ...(l.labels ? { labels: l.labels } : {}), ...(l.textStyle ? { textStyle: l.textStyle } : {}) }));
+    for (const h of hits) {
+      if (f >= h.start && f < h.start + h.duration) layers.push({ key: `h${h.index}`, template: h.layer.template, params: h.layer.params, t: (f - h.start) / fps, ...(h.layer.labels ? { labels: h.layer.labels } : {}), ...(h.layer.textStyle ? { textStyle: h.layer.textStyle } : {}) });
+    }
+    frames.push({ layers });
+  }
+  const events = [...new Set([...cuts.map((c) => c.frame), ...hits.map((h) => h.start)])].filter((f) => f >= 0 && f < frameCount).sort((a, b) => a - b);
+  return { frameCount, fps, frames, templatesUsed: used, events };
+}

package/skills/agentvfx/engine/core/templates.mjs

@@ -0,0 +1,43 @@
+// agentvfx (agentvfx licence, see LICENSE). The template library: every templates/<family>/<id>/fx.json, keyed by
+// X_AGENTVFX.id. Test templates live under templates/_test/ and are loaded only on request.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const TEMPLATES_ROOT = fileURLToPath(new URL("../../templates/", import.meta.url));
+
+/** Map id -> { id, dir, rel, family, fx, passes: [file...] }. Throws on a duplicate id or unreadable JSON. */
+export function loadLibrary({ root = TEMPLATES_ROOT, includeTest = false } = {}) {
+  const lib = new Map();
+  if (!existsSync(root)) return lib;
+  for (const family of readdirSync(root).sort()) {
+    const fdir = path.join(root, family);
+    if (!statSync(fdir).isDirectory()) continue;
+    if (family === "_test" && !includeTest) continue;
+    if (family.startsWith(".") || (family.startsWith("_") && family !== "_test")) continue;
+    for (const name of readdirSync(fdir).sort()) {
+      const dir = path.join(fdir, name);
+      const file = path.join(dir, "fx.json");
+      if (!statSync(dir).isDirectory() || !existsSync(file)) continue;
+      let fx;
+      try {
+        fx = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        throw new Error(`${path.relative(root, file)}: invalid JSON (${error.message})`);
+      }
+      const id = fx?.X_AGENTVFX?.id ?? name;
+      if (lib.has(id)) throw new Error(`duplicate template id ${id} (${path.relative(root, lib.get(id).dir)} and ${path.relative(root, dir)})`);
+      const passes = readdirSync(dir).filter((f) => /^(main|pass\d+)\.frag$/u.test(f)).sort();
+      lib.set(id, { id, dir, rel: path.relative(root, dir).split(path.sep).join("/"), family, fx, passes });
+    }
+  }
+  return lib;
+}
+
+/** Defaults from INPUTS, then the named preset, then explicit params. */
+export function resolveParams(fx, { preset = null, params = {} } = {}) {
+  const out = {};
+  for (const input of fx.INPUTS ?? []) if (input.DEFAULT !== undefined) out[input.NAME] = input.DEFAULT;
+  if (preset) Object.assign(out, fx.X_AGENTVFX.presets[preset]);
+  return Object.assign(out, params);
+}

package/skills/agentvfx/engine/core/util.mjs

@@ -0,0 +1,167 @@
+// Pure math, easing and seeded-randomness helpers shared by the page engine and the Node side.
+// Adapted from mexicat/pdoom-video app/src/engine/util.ts (MIT, see ../NOTICE). Every function is a
+// deterministic function of its arguments: nothing here may read a clock or an unseeded RNG
+// (MO-A-23), because the determinism gate hashes frames rendered by two separate processes.
+
+export const clamp = (x, a = 0, b = 1) => (x < a ? a : x > b ? b : x);
+export const lerp = (a, b, t) => a + (b - a) * t;
+export const invLerp = (a, b, x) => (a === b ? 0 : (x - a) / (b - a));
+export const remap = (x, a, b, c, d, clamped = true) => {
+  const t = invLerp(a, b, x);
+  return lerp(c, d, clamped ? clamp(t) : t);
+};
+export const smoothstep = (a, b, x) => {
+  const t = clamp((x - a) / (b - a));
+  return t * t * (3 - 2 * t);
+};
+export const fract = (x) => x - Math.floor(x);
+export const mod = (x, m) => ((x % m) + m) % m;
+export const TAU = Math.PI * 2;
+
+// Cubic bezier easing, solved by a fixed 40-step bisection so the value never depends on a
+// convergence tolerance.
+function bezier(x1, y1, x2, y2) {
+  const coord = (t, a, b) => 3 * a * t * (1 - t) ** 2 + 3 * b * t * t * (1 - t) + t ** 3;
+  return (x) => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 40; i++) {
+      const mid = (lo + hi) / 2;
+      if (coord(mid, x1, x2) < x) lo = mid;
+      else hi = mid;
+    }
+    return coord((lo + hi) / 2, y1, y2);
+  };
+}
+
+// The named easing set (MO-A-08). Scenes pick from these names; ad hoc curves are not allowed.
+export const ease = Object.freeze({
+  linear: (t) => t,
+  outQuad: (t) => 1 - (1 - t) * (1 - t),
+  inOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2),
+  outCubic: (t) => 1 - (1 - t) ** 3,
+  inOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+  outExpo: (t) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t)),
+  // Film tokens from the preset bibles (MO-B-01..03).
+  slam: bezier(0.16, 1, 0.3, 1),
+  drift: bezier(0.37, 0, 0.63, 1),
+  surgePunch: bezier(0.16, 1, 0.3, 1),
+});
+
+/** Eased progress of x through [a, b], clamped. */
+export const prog = (x, a, b, fn = ease.linear) => fn(clamp((x - a) / (b - a)));
+
+/**
+ * Piecewise interpolation through keyframes `[[time, value, easeName], ...]`; the ease on key i
+ * shapes the segment that ends at key i. Only names from `ease` are accepted.
+ */
+export function keys(t, ks) {
+  if (ks.length === 0) return 0;
+  if (t <= ks[0][0]) return ks[0][1];
+  for (let i = 1; i < ks.length; i++) {
+    const [time, value, name = "inOutCubic"] = ks[i];
+    if (t <= time) {
+      const [pt, pv] = ks[i - 1];
+      const fn = ease[name];
+      if (!fn) throw new Error(`unknown ease: ${name}`);
+      return lerp(pv, value, fn((t - pt) / (time - pt)));
+    }
+  }
+  return ks[ks.length - 1][1];
+}
+
+/** Damped spring response to a step at time 0 (the rare deliberate overshoot, MO-A-08). */
+export const springStep = (t, freq = 4, damping = 0.35) => {
+  if (t <= 0) return 0;
+  const w = TAU * freq;
+  return 1 - Math.exp(-damping * w * t) * Math.cos(w * Math.sqrt(1 - damping * damping) * t);
+};
+
+/** Exponential decay after an event at t0 (1 at t0, half-life hl). */
+export const pulse = (t, t0, hl = 0.12) => (t < t0 ? 0 : 0.5 ** ((t - t0) / hl));
+
+// ---- seeded randomness (MO-SH-01, MO-A-23) ----
+
+/** FNV-1a 32-bit over the UTF-8 bytes of `text`; offset basis 0x811c9dc5, prime 0x01000193. */
+export function fnv1a32(text) {
+  let hash = 0x811c9dc5;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+/** MO-SH-01: the one seed formula for every pass in every product. */
+export const passSeed = (runSeed, sceneId, shotIndex, pass) => fnv1a32(`${runSeed}:${sceneId}:${shotIndex}:${pass}`);
+
+/** mulberry32 PRNG in unsigned 32-bit arithmetic. Returns a function yielding [0, 1). */
+export 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;
+  };
+}
+
+/** Stateless hash of numbers to [0, 1). */
+export function hash(...xs) {
+  let h = 2166136261 >>> 0;
+  for (const x of xs) {
+    h ^= Math.floor(x * 1000003) | 0;
+    h = Math.imul(h, 16777619);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0x5bd1e995);
+    h ^= h >>> 15;
+  }
+  return (h >>> 0) / 4294967296;
+}
+
+const quintic = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+export function noise1(x, seed = 0) {
+  const i = Math.floor(x);
+  return lerp(hash(i, seed) * 2 - 1, hash(i + 1, seed) * 2 - 1, quintic(x - i));
+}
+
+// ---- colour ----
+
+export const srgbToLinear = (s) => (s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4);
+export const linearToSrgb = (l) => (l <= 0.0031308 ? 12.92 * l : 1.055 * l ** (1 / 2.4) - 0.055);
+
+export function hexToRgb(hex) {
+  const n = Number.parseInt(hex.replace("#", ""), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+export const hexToLinear = (hex) => hexToRgb(hex).map((v) => srgbToLinear(v / 255));
+
+/** WCAG relative luminance of an sRGB hex colour. */
+export function relativeLuminance(hex) {
+  const [r, g, b] = hexToLinear(hex);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export const contrastRatio = (la, lb) => (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+
+/** HSL hue (degrees) and saturation (0..1) of 0..255 sRGB values. */
+export function hsl(r, g, b) {
+  const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h;
+  if (max === rn) h = ((gn - bn) / d) % 6;
+  else if (max === gn) h = (bn - rn) / d + 2;
+  else h = (rn - gn) / d + 4;
+  return { h: mod(h * 60, 360), s, l };
+}
+export const hueDistance = (a, b) => {
+  const d = Math.abs(mod(a, 360) - mod(b, 360));
+  return Math.min(d, 360 - d);
+};