Skip to content

Code-first video & image, rendered natively on WebGPU.

Let LayerAnimation.signal take a signal object

okanasl985e6be7bda2
diff --git a/.changeset/inline-signal-tracks.md b/.changeset/inline-signal-tracks.md
new file mode 100644
index 00000000..6aa948d5
--- /dev/null
+++ b/.changeset/inline-signal-tracks.md
@@ -0,0 +1,6 @@
+---
+"gitframes": patch
+"@gitframes/compositions": patch
+---
+
+`LayerAnimation.signal()` and `.colorSignal()` now accept a signal object (`Signal.fromArray`, `Signal.builder`, …) as well as a name registered with `comp.addSignal`. Before, passing the object produced a meaningless handle id and the track silently did nothing (or picked up an unrelated signal). The object is carried on its track and registered with the program under a generated `inline_signal_N` id, so specs stay plain JSON. Values that are neither a signal nor a name now throw.
diff --git a/packages/compositions/src/program/animation.ts b/packages/compositions/src/program/animation.ts
index d263b0df..acdc9b56 100644
--- a/packages/compositions/src/program/animation.ts
+++ b/packages/compositions/src/program/animation.ts
@@ -1,3 +1,4 @@
+import { attachInlineSignal, resolveSignalArg } from "./inline-signals.js";
import type {
AnimatableProp,
AnimationTrack,
@@ -233,30 +234,6 @@ function parseEase(ease?: string | EaseRef): EaseRef | undefined {
return undefined;
}
-function extractSignalHandleId(signalOrHandleId: unknown): string {
- if (typeof signalOrHandleId === "string") return signalOrHandleId;
- if (
- signalOrHandleId &&
- typeof signalOrHandleId === "object" &&
- "inputHandleId" in signalOrHandleId &&
- typeof (signalOrHandleId as { inputHandleId: unknown }).inputHandleId ===
- "string"
- ) {
- return (signalOrHandleId as { inputHandleId: string }).inputHandleId;
- }
- if (
- signalOrHandleId &&
- typeof signalOrHandleId === "object" &&
- "gpuBinding" in signalOrHandleId &&
- (signalOrHandleId as { gpuBinding?: { nodeId?: string } }).gpuBinding
- ?.nodeId
- ) {
- return (signalOrHandleId as { gpuBinding: { nodeId: string } }).gpuBinding
- .nodeId;
- }
- return String(signalOrHandleId);
-}
-
/**
* Fluent builder and runtime representation for layer animations.
* Supports chainable keyframes, reactive signal binding, Perlin wiggles, and springs.
@@ -790,13 +767,18 @@ export class LayerAnimation implements LayerAnimationSpec {
/**
* Binds an animatable property to a reactive continuous Signal (e.g. LFO, speech energy, audio pitch).
+ *
+ * `signalOrHandleId` is either a signal object (`Signal.fromArray`,
+ * `Signal.builder`, an audio channel …) — carried on the track and
+ * registered with the program automatically — or the name of a signal
+ * registered with `comp.addSignal(name, signal)`.
*/
public signal(
prop: AnimatableProp,
signalOrHandleId: unknown,
options: SignalTrackOptions = {},
): this {
- const handleId = extractSignalHandleId(signalOrHandleId);
+ const { handleId, inline } = resolveSignalArg(signalOrHandleId);
const id = `${prop}_sig_${handleId}_${this.tracks.length}`;
const source: TrackSource = {
@@ -811,6 +793,7 @@ export class LayerAnimation implements LayerAnimationSpec {
debounceFrames: options.debounceFrames ?? 2,
channel: options.channel ?? "primary",
};
+ if (inline) attachInlineSignal(source, inline);
this.tracks.push({
id,
@@ -822,14 +805,15 @@ export class LayerAnimation implements LayerAnimationSpec {
}
/**
- * Modulates color interpolation based on an active signal.
+ * Modulates color interpolation based on an active signal (object or
+ * registered name, as in {@link LayerAnimation.signal}).
*/
public colorSignal(
prop: AnimatableProp,
signalOrHandleId: unknown,
options: ColorSignalOptions,
): this {
- const handleId = extractSignalHandleId(signalOrHandleId);
+ const { handleId, inline } = resolveSignalArg(signalOrHandleId);
const id = `${prop}_colorSig_${handleId}_${this.tracks.length}`;
const source: TrackSource = {
@@ -844,6 +828,7 @@ export class LayerAnimation implements LayerAnimationSpec {
colorThreshold: options.threshold,
channel: "primary",
};
+ if (inline) attachInlineSignal(source, inline);
this.tracks.push({
id,
diff --git a/packages/compositions/src/program/inline-signals.ts b/packages/compositions/src/program/inline-signals.ts
new file mode 100644
index 00000000..7ab49da3
--- /dev/null
+++ b/packages/compositions/src/program/inline-signals.ts
@@ -0,0 +1,121 @@
+/**
+ * Inline signal objects on animation tracks.
+ *
+ * `LayerAnimation.signal(prop, Signal.fromArray(...))` binds a track to a
+ * signal object instead of a name registered with `comp.addSignal`. The spec
+ * stays plain data: the track's `inputHandleId` gets a generated name and the
+ * object rides on the source under a non-enumerable symbol (invisible to JSON,
+ * zod and hashing). `compositorToProgram` walks the layout and folds those
+ * objects into the program's `signals` map under their generated names, so
+ * every evaluator (which only looks signals up by name) sees them.
+ */
+
+const INLINE_SIGNAL = Symbol.for("gitframes.inlineSignal");
+
+const handleIds = new WeakMap<object, string>();
+let nextHandle = 0;
+
+/**
+ * The generated handle id for a signal object. The same object always gets
+ * the same id, so reusing one signal across tracks registers it once.
+ */
+function inlineSignalHandleId(signal: object): string {
+ let id = handleIds.get(signal);
+ if (id === undefined) {
+ id = `inline_signal_${nextHandle++}`;
+ handleIds.set(signal, id);
+ }
+ return id;
+}
+
+/**
+ * Resolves the `signalOrHandleId` argument of `LayerAnimation.signal` /
+ * `colorSignal` to a handle id, plus the signal object to carry inline (when
+ * it is not a registered name).
+ */
+export function resolveSignalArg(signalOrHandleId: unknown): {
+ handleId: string;
+ inline?: object;
+} {
+ if (typeof signalOrHandleId === "string") {
+ return { handleId: signalOrHandleId };
+ }
+ if (
+ signalOrHandleId === null ||
+ (typeof signalOrHandleId !== "object" &&
+ typeof signalOrHandleId !== "function")
+ ) {
+ throw new TypeError(
+ `LayerAnimation.signal: expected a signal object or a signal name, got ${String(signalOrHandleId)}. ` +
+ `Pass a signal (Signal.fromArray / Signal.builder / an audio channel …) or register it with comp.addSignal(name, signal) and pass the name.`,
+ );
+ }
+ const obj = signalOrHandleId as {
+ inputHandleId?: unknown;
+ gpuBinding?: { nodeId?: unknown };
+ get?: unknown;
+ };
+ // Graph source descriptors (audio extractors …) are resolved by their own
+ // handle at render time.
+ if (typeof obj.inputHandleId === "string") {
+ return { handleId: obj.inputHandleId };
+ }
+ // GPU-bound signals keep their node id as the handle; their CPU `get()`
+ // still rides inline, so the track animates even when nothing registers
+ // that node id (an explicit registration under the same id wins).
+ if (typeof obj.gpuBinding?.nodeId === "string") {
+ return typeof obj.get === "function"
+ ? { handleId: obj.gpuBinding.nodeId, inline: signalOrHandleId }
+ : { handleId: obj.gpuBinding.nodeId };
+ }
+ return {
+ handleId: inlineSignalHandleId(signalOrHandleId),
+ inline: signalOrHandleId,
+ };
+}
+
+/** Attaches an inline signal object to a track source without making it enumerable. */
+export function attachInlineSignal(source: object, signal: object): void {
+ Object.defineProperty(source, INLINE_SIGNAL, {
+ value: signal,
+ enumerable: false,
+ configurable: true,
+ writable: true,
+ });
+}
+
+/** The inline signal object carried by a track source, if any. */
+export function getInlineSignal(source: unknown): object | undefined {
+ if (!source || typeof source !== "object") return undefined;
+ return (source as { [INLINE_SIGNAL]?: object })[INLINE_SIGNAL];
+}
+
+/**
+ * Collects every inline signal object under `nodes` (animation tracks of each
+ * node, recursing into `children`) keyed by its generated handle id.
+ */
+export function collectInlineSignals(
+ nodes: readonly unknown[],
+ out: Record<string, unknown> = {},
+): Record<string, unknown> {
+ for (const node of nodes) {
+ if (!node || typeof node !== "object") continue;
+ const { animation, children } = node as {
+ animation?: { tracks?: unknown };
+ children?: unknown;
+ };
+ const tracks = animation?.tracks;
+ if (Array.isArray(tracks)) {
+ for (const track of tracks) {
+ const source = (track as { source?: { inputHandleId?: unknown } })
+ ?.source;
+ const signal = getInlineSignal(source);
+ if (signal && typeof source?.inputHandleId === "string") {
+ out[source.inputHandleId] = signal;
+ }
+ }
+ }
+ if (Array.isArray(children)) collectInlineSignals(children, out);
+ }
+ return out;
+}
diff --git a/packages/compositions/src/program/to-virtual-media.ts b/packages/compositions/src/program/to-virtual-media.ts
index de358868..c399c78d 100644
--- a/packages/compositions/src/program/to-virtual-media.ts
+++ b/packages/compositions/src/program/to-virtual-media.ts
@@ -17,6 +17,7 @@ import {
getActiveMediaMetadata,
type VirtualMediaData,
} from "@gitframes/core";
+import { collectInlineSignals } from "./inline-signals.js";
import type { CompositorProgramConfig, LayoutNode } from "./schema.js";
import { computeStaggerDelay } from "./stagger.js";
@@ -288,7 +289,12 @@ export function compositorToProgram(
// is NOT read by the renderer — do not treat it as the source of
// truth (the config is).
layout: config.layout,
- signals: signals ?? (config as any).signals ?? {},
+ // Signal objects passed straight to `LayerAnimation.signal` ride on
+ // their tracks; fold them in under their generated handle ids.
+ signals: {
+ ...collectInlineSignals(config.layout),
+ ...(signals ?? (config as any).signals ?? {}),
+ },
...(((config as any).onRequestFrame ||
(options as any).onRequestFrame) && {
onRequestFrame:
diff --git a/packages/gitframes/src/signal-tracks.test.ts b/packages/gitframes/src/signal-tracks.test.ts
new file mode 100644
index 00000000..71cf9024
--- /dev/null
+++ b/packages/gitframes/src/signal-tracks.test.ts
@@ -0,0 +1,146 @@
+/**
+ * LayerAnimation.signal accepts a signal object or the name of one registered
+ * with comp.addSignal — both must drive the property frame by frame.
+ */
+import { Canvas, loadImage } from "skia-canvas";
+import { describe, expect, it } from "vitest";
+import { Composition, Layer, LayerAnimation, Signal } from "./index.js";
+
+const FPS = 30;
+// Opacity 0 on even frames, 1 on odd ones.
+const GATE = Array.from({ length: 30 }, (_, f) => f % 2);
+
+async function pixel(png: Buffer, x: number, y: number) {
+ const img = await loadImage(png);
+ const canvas = new Canvas(img.width, img.height);
+ const ctx = canvas.getContext("2d");
+ ctx.drawImage(img, 0, 0);
+ return Array.from(ctx.getImageData(x, y, 1, 1).data.slice(0, 3));
+}
+
+function comp() {
+ return new Composition({
+ width: 200,
+ height: 200,
+ fps: FPS,
+ durationFrames: 30,
+ backgroundColor: "#000000",
+ });
+}
+
+function square(id: string, x: number, anim: LayerAnimation) {
+ return Layer.box({
+ id,
+ position: "absolute",
+ x,
+ y: 0,
+ width: 100,
+ height: 200,
+ background: "#ffffff",
+ }).animate(anim);
+}
+
+async function brightness(c: Composition, frame: number, x = 50) {
+ return (await pixel(await c.renderFrame({ frame }), x, 100))[0];
+}
+
+describe("signal tracks", () => {
+ it("animates from a signal object (Signal.fromArray)", async () => {
+ const c = comp();
+ c.add(
+ square(
+ "a",
+ 0,
+ LayerAnimation.create().signal("opacity", Signal.fromArray(GATE, FPS)),
+ ),
+ );
+ expect(await brightness(c, 4)).toBe(0);
+ expect(await brightness(c, 5)).toBe(255);
+ });
+
+ it("animates from a signal object (Signal.builder custom fn)", async () => {
+ const c = comp();
+ const sig = Signal.builder({
+ type: "custom",
+ fn: (ctx) => (ctx.frame >= 10 ? 1 : 0),
+ });
+ c.add(square("a", 0, LayerAnimation.create().signal("opacity", sig)));
+ expect(await brightness(c, 3)).toBe(0);
+ expect(await brightness(c, 12)).toBe(255);
+ });
+
+ it("animates from a registered signal name", async () => {
+ const c = comp();
+ c.addSignal("gate", Signal.fromArray(GATE, FPS));
+ c.add(square("a", 0, LayerAnimation.create().signal("opacity", "gate")));
+ expect(await brightness(c, 4)).toBe(0);
+ expect(await brightness(c, 5)).toBe(255);
+ });
+
+ it("keeps each inline signal on its own track, alongside named ones", async () => {
+ const c = comp();
+ c.addSignal("gate", Signal.fromArray(GATE, FPS));
+ const inverted = Signal.fromArray(
+ GATE.map((v) => 1 - v),
+ FPS,
+ );
+ c.add(
+ square("named", 0, LayerAnimation.create().signal("opacity", "gate")),
+ // A nested child: inline signals are collected through containers.
+ Layer.box({
+ id: "wrap",
+ position: "absolute",
+ x: 100,
+ y: 0,
+ width: 100,
+ height: 200,
+ children: [
+ square(
+ "inline",
+ 0,
+ LayerAnimation.create().signal("opacity", inverted),
+ ),
+ ],
+ }),
+ );
+ expect(await brightness(c, 4, 50)).toBe(0);
+ expect(await brightness(c, 4, 150)).toBe(255);
+ expect(await brightness(c, 5, 50)).toBe(255);
+ expect(await brightness(c, 5, 150)).toBe(0);
+ });
+
+ it("keeps the spec plain data and registers inline signals with the program", () => {
+ const sig = Signal.fromArray(GATE, FPS);
+ const anim = LayerAnimation.create()
+ .signal("opacity", sig)
+ .signal("scale", sig, { offset: 1 });
+ const [a, b] = anim.tracks.map(
+ (t) => (t.source as { inputHandleId: string }).inputHandleId,
+ );
+ // Same object → same handle, and the spec serialises without the object.
+ expect(a).toBe(b);
+ expect(a).toMatch(/^inline_signal_\d+$/);
+ expect(JSON.parse(JSON.stringify(anim.toSpec()))).toEqual(anim.toSpec());
+
+ const c = comp();
+ c.add(square("a", 0, anim));
+ const vm = c.toVirtualMedia() as {
+ operation: { op: string; signals?: Record<string, unknown> };
+ children?: unknown[];
+ };
+ const find = (n: typeof vm): typeof vm | undefined =>
+ n.operation.op === "Compositor"
+ ? n
+ : (n.children as (typeof vm)[] | undefined)?.map(find).find(Boolean);
+ expect(find(vm)?.operation.signals?.[a]).toBe(sig);
+ });
+
+ it("rejects values that are neither a signal nor a name", () => {
+ expect(() => LayerAnimation.create().signal("opacity", 0.5)).toThrow(
+ /addSignal/,
+ );
+ expect(() => LayerAnimation.create().signal("opacity", undefined)).toThrow(
+ /addSignal/,
+ );
+ });
+});
diff --git a/plugins/gitframes/skills/gitframes-compose/SKILL.md b/plugins/gitframes/skills/gitframes-compose/SKILL.md
index 71fc38ae..36c78e6a 100644
--- a/plugins/gitframes/skills/gitframes-compose/SKILL.md
+++ b/plugins/gitframes/skills/gitframes-compose/SKILL.md
@@ -211,11 +211,23 @@ const floatAnim = LayerAnimation.create()
const springAnim = LayerAnimation.create()
.spring("scale", { damping: 14, stiffness: 190, mass: 1 });
-// Audio reactivity via Signal
+// Audio reactivity: pass the signal object straight in…
+const kick = Signal.fromArray(kickEnvelope, fps); // or Signal.builder({ type: "custom", fn })
const beatAnim = LayerAnimation.create()
- .signal("scale", "drum_stem_signal", { multiplier: 0.12, offset: 1.0, smoothing: 2 });
+ .signal("scale", kick, { multiplier: 0.12, offset: 1.0, smoothing: 2 });
+
+// …or register it once by name and bind the name (handy when many layers share it)
+comp.addSignal("drum_stem_signal", kick);
+const beatAnim2 = LayerAnimation.create()
+ .signal("opacity", "drum_stem_signal", { multiplier: 0.5, offset: 0.5 });
```
+`.signal()` / `.colorSignal()` drive the prop with `value × multiplier + offset` every frame. A signal
+object is carried on its track and registered with the program automatically (under a generated
+`inline_signal_N` id, so the spec stays plain JSON); a string is looked up in `comp.addSignal` names.
+Anything else (a number, `undefined`) throws. Signals are sampled at the **composition** frame
+(`ctx.frame`), not the layer's local frame.
+
---
## Critical Authoring Rules & Gotchas