@framefields/node-compositor 0.0.0-stage → 2.0.3

package/src/shared/audio-reactive.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "vitest";
+import { compileTimeline } from "./compiler.js";
+import type { CompositorNodeConfig } from "./config.js";
+import { processCompositor } from "./processor.js";
+
+describe("Audio-Reactive Motion Graphics Engine Pipeline", () => {
+	it("connects signal streams to Compositor and drives beat-synchronized motion", () => {
+		// Mock dynamic signal streams (beat spikes at frame 12 and 24, continuous bass ramp)
+		const beatSamples = new Array(48).fill(0.0);
+		beatSamples[12] = 1.0; // Beat hit 1
+		beatSamples[24] = 1.0; // Beat hit 2
+
+		const bassSamples = new Array(48).fill(0.0).map((_, i) => i / 48);
+
+		const signalsByHandle = new Map<string, number[]>([
+			["audio_beat_handle", beatSamples],
+			["audio_bass_handle", bassSamples],
+		]);
+
+		const compositorConfig: CompositorNodeConfig = {
+			width: 1920,
+			height: 1080,
+			volume: 1,
+			fps: 24,
+			mode: "Video",
+			layout: [
+				{
+					id: "bouncing-logo-star",
+					kind: "shape",
+					shapeType: "star",
+					starPoints: 5,
+					starInnerRadiusRatio: 0.5,
+					width: 300,
+					height: 300,
+					x: 810,
+					y: 390,
+					position: "absolute",
+					strokeWidth: 4,
+					strokeColor: "#38bdf8",
+					animation: {
+						tracks: [
+							{
+								id: "t-beat-scale",
+								prop: "scale",
+								source: {
+									type: "signal",
+									inputHandleId: "audio_beat_handle",
+									multiplier: 0.6,
+									offset: 1.0,
+									smoothingWindowFrames: 0,
+								},
+								keyframes: [],
+							},
+							{
+								id: "t-bass-trim",
+								prop: "trimEnd",
+								source: {
+									type: "signal",
+									inputHandleId: "audio_bass_handle",
+									multiplier: 0.8,
+									offset: 0.2,
+									smoothingWindowFrames: 0,
+								},
+								keyframes: [],
+							},
+							{
+								id: "t-procedural-wiggle",
+								prop: "rotation",
+								source: {
+									type: "wiggle",
+									frequency: 2.0,
+									amplitude: 15.0,
+									octaves: 2,
+									seed: 777,
+								},
+								keyframes: [],
+							},
+						],
+					},
+				},
+				{
+					id: "staggered-bars-row",
+					kind: "flex",
+					dir: "row",
+					gap: 20,
+					staggerFrames: 4,
+					staggerDirection: "forward",
+					children: [
+						{
+							id: "bar-1",
+							kind: "shape",
+							width: 40,
+							height: 200,
+							startFrame: 0,
+							durationFrames: 24,
+							animation: {
+								tracks: [
+									{
+										id: "t-bar1-fade",
+										prop: "opacity",
+										keyframes: [
+											{ id: "k1", frame: 0, value: 0 },
+											{ id: "k2", frame: 12, value: 1 },
+										],
+									},
+								],
+							},
+						},
+						{
+							id: "bar-2",
+							kind: "shape",
+							width: 40,
+							height: 200,
+							startFrame: 0,
+							durationFrames: 24,
+							animation: {
+								tracks: [
+									{
+										id: "t-bar2-fade",
+										prop: "opacity",
+										keyframes: [
+											{ id: "k3", frame: 0, value: 0 },
+											{ id: "k4", frame: 12, value: 1 },
+										],
+									},
+								],
+							},
+						},
+						{
+							id: "bar-3",
+							kind: "shape",
+							width: 40,
+							height: 200,
+							startFrame: 0,
+							durationFrames: 24,
+							animation: {
+								tracks: [
+									{
+										id: "t-bar3-fade",
+										prop: "opacity",
+										keyframes: [
+											{ id: "k5", frame: 0, value: 0 },
+											{ id: "k6", frame: 12, value: 1 },
+										],
+									},
+								],
+							},
+						},
+					],
+				},
+			],
+		};
+
+		// 1. Process compositor into VirtualMediaData tree
+		const vm = processCompositor(
+			compositorConfig,
+			new Map(),
+			true,
+			signalsByHandle,
+		);
+
+		// Verify signals attached to operation
+		const operation = vm.operation as Record<string, unknown>;
+		expect(operation.signals).toBeDefined();
+		const signals = operation.signals as Record<string, unknown>;
+		expect(signals.audio_beat_handle).toBe(beatSamples);
+
+		// 2. Compile into timeline
+		const { tl, targetsById } = compileTimeline(
+			"audio-reactive-session",
+			vm,
+			{ fps: 24, durationSec: 2 },
+		);
+
+		const logoStub = targetsById["bouncing-logo-star"];
+		expect(logoStub).toBeDefined();
+
+		// Check baseline at frame 0 (t = 0 sec):
+		// Beat signal = 0.0 -> scale = 0.0 * 0.6 + 1.0 = 1.0
+		tl.seek(0);
+		expect(logoStub.scale).toBeCloseTo(1.0, 3);
+		// Bass signal = 0.0 -> trimEnd = 0.0 * 0.8 + 0.2 = 0.2
+		expect(logoStub.trimEnd).toBeCloseTo(0.2, 3);
+		// Rotation wiggles within amplitude [-15, 15]
+		expect(Math.abs(logoStub.rotation as number)).toBeLessThanOrEqual(15);
+
+		// Check beat hit at frame 12 (t = 12/24 = 0.5 sec):
+		// Beat signal = 1.0 -> scale = 1.0 * 0.6 + 1.0 = 1.6!
+		tl.seek(12 / 24);
+		expect(logoStub.scale).toBeCloseTo(1.6, 3);
+
+		// Check post-beat settling at frame 14:
+		// Beat signal = 0.0 -> scale back to 1.0
+		tl.seek(14 / 24);
+		expect(logoStub.scale).toBeCloseTo(1.0, 3);
+
+		// Check second beat hit at frame 24 (t = 1.0 sec):
+		tl.seek(24 / 24);
+		expect(logoStub.scale).toBeCloseTo(1.6, 3);
+
+		// Check container staggering:
+		// bar-1: startFrame = 0
+		// bar-2: startFrame = 4 (stagger offset 1 * 4)
+		// bar-3: startFrame = 8 (stagger offset 2 * 4)
+		const bar1 = targetsById["bar-1"];
+		const bar2 = targetsById["bar-2"];
+		const bar3 = targetsById["bar-3"];
+
+		// At frame 0:
+		tl.seek(0);
+		expect(bar1.opacity).toBe(0);
+
+		// At frame 4 (bar-1 is halfway faded 0.33, bar-2 is just starting):
+		tl.seek(4 / 24);
+		expect(bar1.opacity).toBeGreaterThan(0);
+		expect(bar2.opacity).toBe(0);
+		expect(bar3.opacity).toBe(0);
+
+		// At frame 8 (bar-3 is just starting):
+		tl.seek(8 / 24);
+		expect(bar2.opacity).toBeGreaterThan(0);
+		expect(bar3.opacity).toBe(0);
+	});
+});

package/src/shared/bezier-solver.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+	buildSpatialSplineSegments,
+	catmullRomToBezier,
+	sampleBezierCurve,
+	sampleCubicBezierSegment,
+	solveBezierDerivative,
+	solveCubicBezier,
+} from "./bezier-solver.js";
+
+describe("bezier-solver", () => {
+	it("evaluates linear cubic bezier curve correctly", () => {
+		expect(solveCubicBezier(0, 0, 1, 1, 0)).toBe(0);
+		expect(solveCubicBezier(0, 0, 1, 1, 0.5)).toBeCloseTo(0.5, 3);
+		expect(solveCubicBezier(0, 0, 1, 1, 1)).toBe(1);
+	});
+
+	it("evaluates standard ease-in and ease-out curves correctly", () => {
+		// Ease-in: slow start, steep finish (e.g. 0.42, 0, 1, 1)
+		const easeInMid = solveCubicBezier(0.42, 0, 1, 1, 0.5);
+		expect(easeInMid).toBeLessThan(0.5);
+
+		// Ease-out: fast start, slow finish (e.g. 0, 0, 0.58, 1)
+		const easeOutMid = solveCubicBezier(0, 0, 0.58, 1, 0.5);
+		expect(easeOutMid).toBeGreaterThan(0.5);
+	});
+
+	it("calculates derivative (speed) accurately", () => {
+		// For linear, speed should be constant ~1.0
+		const linearSpeed = solveBezierDerivative(0, 0, 1, 1, 0.5);
+		expect(linearSpeed).toBeCloseTo(1.0, 2);
+
+		// Ease-out has higher initial speed and lower final speed
+		const easeOutStartSpeed = solveBezierDerivative(0.1, 0.8, 0.2, 1.0, 0.1);
+		const easeOutEndSpeed = solveBezierDerivative(0.1, 0.8, 0.2, 1.0, 0.9);
+		expect(easeOutStartSpeed).toBeGreaterThan(easeOutEndSpeed);
+	});
+
+	it("samples bezier curve points across 0..1 range", () => {
+		const samples = sampleBezierCurve(0.25, 0.1, 0.25, 1.0, 10);
+		expect(samples).toHaveLength(11);
+		expect(samples[0].t).toBe(0);
+		expect(samples[0].value).toBe(0);
+		expect(samples[10].t).toBe(1);
+		expect(samples[10].value).toBe(1);
+	});
+
+	it("converts Catmull-Rom to Cubic Bezier control points", () => {
+		const p0 = { x: 0, y: 0 };
+		const p1 = { x: 100, y: 0 };
+		const p2 = { x: 200, y: 100 };
+		const p3 = { x: 300, y: 100 };
+
+		const { c1, c2 } = catmullRomToBezier(p0, p1, p2, p3);
+		expect(c1.x).toBeCloseTo(100 + 200 / 6, 2);
+		expect(c1.y).toBeCloseTo(100 / 6, 2);
+		expect(c2.x).toBeCloseTo(200 - 200 / 6, 2);
+	});
+
+	it("builds spatial spline segments with custom or Catmull-Rom tangents", () => {
+		const points = [
+			{ frame: 0, x: 0, y: 0, spatialTangentOut: { x: 50, y: -20 } },
+			{ frame: 30, x: 200, y: 100, spatialTangentIn: { x: -30, y: 10 } },
+			{ frame: 60, x: 400, y: 100 },
+		];
+
+		const segments = buildSpatialSplineSegments(points);
+		expect(segments).toHaveLength(2);
+
+		// Segment 0 uses authored tangents
+		expect(segments[0].c1).toEqual({ x: 50, y: -20 });
+		expect(segments[0].c2).toEqual({ x: 170, y: 110 });
+
+		// Segment 1 uses Catmull-Rom tangent computation
+		expect(segments[1].p0).toEqual({ x: 200, y: 100 });
+		expect(segments[1].p1).toEqual({ x: 400, y: 100 });
+	});
+
+	it("samples cubic bezier segment points smoothly", () => {
+		const p0 = { x: 0, y: 0 };
+		const c1 = { x: 50, y: 100 };
+		const c2 = { x: 150, y: 100 };
+		const p1 = { x: 200, y: 0 };
+
+		const sampled = sampleCubicBezierSegment(p0, c1, c2, p1, 10);
+		expect(sampled).toHaveLength(11);
+		expect(sampled[0]).toEqual(p0);
+		expect(sampled[10]).toEqual(p1);
+		// Midpoint should have positive y due to control points
+		expect(sampled[5].y).toBeGreaterThan(50);
+	});
+});

package/src/shared/bezier-solver.ts

@@ -0,0 +1,257 @@
+/**
+ * Cubic Bezier and Speed Curve Solver for Motion Graphics
+ * Provides analytical/Newton-Raphson solvers for unit easing curves and 2D spatial trajectory splines.
+ */
+
+export interface Point2D {
+	x: number;
+	y: number;
+}
+
+export interface SpatialKeyframePoint {
+	frame: number;
+	x: number;
+	y: number;
+	spatialTangentIn?: Point2D;
+	spatialTangentOut?: Point2D;
+}
+
+export interface SplineSegment {
+	p0: Point2D;
+	c1: Point2D;
+	c2: Point2D;
+	p1: Point2D;
+	startFrame: number;
+	endFrame: number;
+}
+
+/**
+ * Solves a cubic bezier curve defined by control points (x1, y1) and (x2, y2)
+ * for a given progress parameter t in [0, 1].
+ */
+export function solveCubicBezier(
+	x1: number,
+	y1: number,
+	x2: number,
+	y2: number,
+	t: number,
+): number {
+	if (t <= 0) return 0;
+	if (t >= 1) return 1;
+
+	// Check for linear edge case
+	if (x1 === y1 && x2 === y2) return t;
+
+	// Find u such that x(u) = t
+	// x(u) = 3*(1-u)^2 * u * x1 + 3*(1-u) * u^2 * x2 + u^3
+	// dx/du = 3*(1-u)^2 * x1 + 6*(1-u)*u * (x2 - x1) + 3*u^2 * (1 - x2)
+	let u = t; // initial guess
+	for (let i = 0; i < 8; i++) {
+		const oneMinusU = 1 - u;
+		const oneMinusU2 = oneMinusU * oneMinusU;
+		const u2 = u * u;
+
+		const currentX =
+			3 * oneMinusU2 * u * x1 + 3 * oneMinusU * u2 * x2 + u2 * u;
+		const diff = currentX - t;
+		if (Math.abs(diff) < 1e-6) break;
+
+		const dx =
+			3 * oneMinusU2 * x1 +
+			6 * oneMinusU * u * (x2 - x1) +
+			3 * u2 * (1 - x2);
+
+		if (Math.abs(dx) < 1e-6) break;
+		u -= diff / dx;
+		u = Math.max(0, Math.min(1, u));
+	}
+
+	// Bisection fallback if Newton didn't converge within bounds
+	const oneMinusU = 1 - u;
+	const checkX =
+		3 * oneMinusU * oneMinusU * u * x1 +
+		3 * oneMinusU * u * u * x2 +
+		u * u * u;
+
+	if (Math.abs(checkX - t) > 1e-3) {
+		let low = 0;
+		let high = 1;
+		u = t;
+		for (let i = 0; i < 16; i++) {
+			const mid = (low + high) * 0.5;
+			const oMid = 1 - mid;
+			const xMid =
+				3 * oMid * oMid * mid * x1 +
+				3 * oMid * mid * mid * x2 +
+				mid * mid * mid;
+			if (Math.abs(xMid - t) < 1e-5) {
+				u = mid;
+				break;
+			}
+			if (xMid < t) low = mid;
+			else high = mid;
+			u = mid;
+		}
+	}
+
+	// Evaluate y(u)
+	const oU = 1 - u;
+	return (
+		3 * oU * oU * u * y1 +
+		3 * oU * u * u * y2 +
+		u * u * u
+	);
+}
+
+/**
+ * Calculates the instantaneous speed (derivative |dy/dt|) at parameter t in [0, 1].
+ */
+export function solveBezierDerivative(
+	x1: number,
+	y1: number,
+	x2: number,
+	y2: number,
+	t: number,
+): number {
+	const clampedT = Math.max(0, Math.min(1, t));
+	const eps = 1e-4;
+	const t0 = Math.max(0, clampedT - eps);
+	const t1 = Math.min(1, clampedT + eps);
+	const dt = t1 - t0;
+	if (dt <= 0) return 0;
+
+	const y0 = solveCubicBezier(x1, y1, x2, y2, t0);
+	const y1Val = solveCubicBezier(x1, y1, x2, y2, t1);
+	return Math.abs((y1Val - y0) / dt);
+}
+
+/**
+ * Generates an array of samples along the cubic bezier curve for visualization.
+ */
+export function sampleBezierCurve(
+	x1: number,
+	y1: number,
+	x2: number,
+	y2: number,
+	steps = 60,
+): Array<{ t: number; value: number; speed: number }> {
+	const samples: Array<{ t: number; value: number; speed: number }> = [];
+	for (let i = 0; i <= steps; i++) {
+		const t = i / steps;
+		const value = solveCubicBezier(x1, y1, x2, y2, t);
+		const speed = solveBezierDerivative(x1, y1, x2, y2, t);
+		samples.push({ t, value, speed });
+	}
+	return samples;
+}
+
+/**
+ * Converts Catmull-Rom four-point configuration to cubic Bezier control points.
+ */
+export function catmullRomToBezier(
+	p0: Point2D,
+	p1: Point2D,
+	p2: Point2D,
+	p3: Point2D,
+): { c1: Point2D; c2: Point2D } {
+	return {
+		c1: {
+			x: p1.x + (p2.x - p0.x) / 6,
+			y: p1.y + (p2.y - p0.y) / 6,
+		},
+		c2: {
+			x: p2.x - (p3.x - p1.x) / 6,
+			y: p2.y - (p3.y - p1.y) / 6,
+		},
+	};
+}
+
+/**
+ * Builds smooth Bezier spline segments between an ordered array of spatial keyframes.
+ * Respects custom spatial tangents if authored; otherwise uses smooth Catmull-Rom.
+ */
+export function buildSpatialSplineSegments(
+	points: SpatialKeyframePoint[],
+): SplineSegment[] {
+	if (points.length < 2) return [];
+
+	const segments: SplineSegment[] = [];
+
+	for (let i = 0; i < points.length - 1; i++) {
+		const curr = points[i];
+		const next = points[i + 1];
+
+		let c1: Point2D;
+		let c2: Point2D;
+
+		if (curr.spatialTangentOut) {
+			c1 = {
+				x: curr.x + curr.spatialTangentOut.x,
+				y: curr.y + curr.spatialTangentOut.y,
+			};
+		} else {
+			// Natural Catmull-Rom tangent
+			const prev = i > 0 ? points[i - 1] : curr;
+			const pNextNext = i + 2 < points.length ? points[i + 2] : next;
+			const cr = catmullRomToBezier(prev, curr, next, pNextNext);
+			c1 = cr.c1;
+		}
+
+		if (next.spatialTangentIn) {
+			c2 = {
+				x: next.x + next.spatialTangentIn.x,
+				y: next.y + next.spatialTangentIn.y,
+			};
+		} else {
+			const prev = i > 0 ? points[i - 1] : curr;
+			const pNextNext = i + 2 < points.length ? points[i + 2] : next;
+			const cr = catmullRomToBezier(prev, curr, next, pNextNext);
+			c2 = cr.c2;
+		}
+
+		segments.push({
+			p0: { x: curr.x, y: curr.y },
+			c1,
+			c2,
+			p1: { x: next.x, y: next.y },
+			startFrame: curr.frame,
+			endFrame: next.frame,
+		});
+	}
+
+	return segments;
+}
+
+/**
+ * Samples points along a cubic bezier segment between p0 and p1 with control points c1, c2.
+ */
+export function sampleCubicBezierSegment(
+	p0: Point2D,
+	c1: Point2D,
+	c2: Point2D,
+	p1: Point2D,
+	steps = 20,
+): Point2D[] {
+	const pts: Point2D[] = [];
+	for (let i = 0; i <= steps; i++) {
+		const u = i / steps;
+		const oU = 1 - u;
+		const oU2 = oU * oU;
+		const oU3 = oU2 * oU;
+		const u2 = u * u;
+		const u3 = u2 * u;
+
+		const x =
+			oU3 * p0.x +
+			3 * oU2 * u * c1.x +
+			3 * oU * u2 * c2.x +
+			u3 * p1.x;
+		const y =
+			oU3 * p0.y +
+			3 * oU2 * u * c1.y +
+			3 * oU * u2 * c2.y +
+			u3 * p1.y;
+		pts.push({ x, y });
+	}
+	return pts;
+}