feat(engine): bake automation envelopes into the render

The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.

Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.

A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/core/stubs/audio-fx-runtime-entry.ts

@@ -7,15 +7,17 @@
  * ends share a single implementation rather than two that have to be kept in
  * agreement.
  *
- * Exposes `window.__HF_AUDIO_FX.render(pcm, sampleRate, chain)`, which returns
- * the processed samples.
+ * Exposes `window.__HF_AUDIO_FX.render(pcm, sampleRate, chain, automation)`,
+ * which returns the processed samples.
  */
 
 import {
   buildFxChain,
   chainNeedsWorklets,
   ensureAudioFxWorklets,
 } from "../src/audio/audioFxGraph.js";
+import { scheduleChainAutomation } from "../src/audio/audioFxAutomation.js";
+import { parseAutomation, resolveAutomation } from "../src/audioAutomation.js";
 import { parseAudioFxChain, type HfAudioFxChain } from "../src/audioFx.js";
 
 declare global {
@@ -25,6 +27,7 @@ declare global {
         planes: Float32Array[],
         sampleRate: number,
         chainJson: string,
+        automationJson?: string,
       ): Promise<Float32Array[]>;
     };
   }
@@ -42,6 +45,7 @@ declare global {
  * mix, so how far a tail may run past a clip's end is a product decision rather
  * than something to pick here.
  */
+
 /** The clip's audio as an AudioBuffer, a plane per channel. */
 function toBuffer(
   ctx: OfflineAudioContext,
@@ -71,6 +75,7 @@ async function render(
   planes: Float32Array[],
   sampleRate: number,
   chainJson: string,
+  automationJson?: string,
 ): Promise<Float32Array[]> {
   const chain: HfAudioFxChain = parseAudioFxChain(chainJson);
   const channels = Math.max(1, planes.length);
@@ -83,6 +88,19 @@ async function render(
   source.buffer = toBuffer(ctx, planes, channels, frames, sampleRate);
 
   const fx = buildFxChain(ctx, chain);
+
+  // The input WAV is the clip's own audio from its first sample, so clip-local
+  // time is offline time — the envelope needs no offset here. Same scheduler as
+  // preview, which is what makes the two agree.
+  if (automationJson) {
+    const automation = resolveAutomation(parseAutomation(automationJson), chain);
+    scheduleChainAutomation(automation, chain, fx.nodes, {
+      scheduledAt: 0,
+      elapsed: 0,
+      rate: 1,
+    });
+  }
+
   source.connect(fx.input);
   fx.output.connect(ctx.destination);
   source.start();

packages/engine/src/services/audioAutomationRender.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { parseAudioElements, volumeLaneKeyframes } from "./audioMixer.js";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const lanes = (points: HfAutomationLane["points"], target = "volume") => ({
+  lanes: [{ target, points }],
+});
+
+describe("volumeLaneKeyframes", () => {
+  it("keeps a straight fade at two keyframes, in composition time", () => {
+    const out = volumeLaneKeyframes(
+      lanes([
+        { t: 0, v: 1 },
+        { t: 2, v: 0 },
+      ]),
+      5,
+      2,
+    );
+    expect(out).toEqual([
+      { time: 5, volume: 1 },
+      { time: 7, volume: 0 },
+    ]);
+  });
+
+  it("holds the first value before the envelope starts", () => {
+    const out = volumeLaneKeyframes(
+      lanes([
+        { t: 1, v: 0.3 },
+        { t: 2, v: 1 },
+      ]),
+      0,
+      2,
+    );
+    // Not `data-volume` at t=0 — the lane's own first value.
+    expect(out?.[0]).toEqual({ time: 0, volume: 0.3 });
+  });
+
+  it("holds the last value out to the clip end", () => {
+    const out = volumeLaneKeyframes(
+      lanes([
+        { t: 0, v: 1 },
+        { t: 1, v: 0.5 },
+      ]),
+      0,
+      4,
+    );
+    expect(out?.at(-1)).toEqual({ time: 4, volume: 0.5 });
+  });
+
+  it("samples a bent segment, which the linear baker would straighten", () => {
+    const straight = volumeLaneKeyframes(
+      lanes([
+        { t: 0, v: 0 },
+        { t: 2, v: 1 },
+      ]),
+      0,
+      2,
+    );
+    const bent = volumeLaneKeyframes(
+      lanes([
+        { t: 0, v: 0, curve: 1 },
+        { t: 2, v: 1 },
+      ]),
+      0,
+      2,
+    );
+    expect(straight?.length).toBe(2);
+    expect(bent?.length ?? 0).toBeGreaterThan(30);
+    // Same endpoints, different path between them.
+    expect(bent?.[0]).toEqual({ time: 0, volume: 0 });
+    expect(bent?.at(-1)).toEqual({ time: 2, volume: 1 });
+    const mid = bent?.find((k) => Math.abs(k.time - 1) < 0.02);
+    expect(mid?.volume ?? 1).toBeLessThan(0.4);
+  });
+
+  it("has nothing to bake for a track whose only lane is an FX one", () => {
+    expect(volumeLaneKeyframes(lanes([{ t: 0, v: 200 }], "fx.n1.frequency"), 0, 2)).toBeNull();
+  });
+});
+
+describe("parseAudioElements", () => {
+  it("carries the automation attribute through to the mixer", () => {
+    const automation = '{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1}]}]}';
+    const html = `<!DOCTYPE html><html><body>
+      <div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
+        <audio id="bgm" src="a.wav" data-start="0" data-duration="10" data-automation='${automation}'></audio>
+      </div></body></html>`;
+    const [el] = parseAudioElements(html);
+    expect(el?.automation).toBe(automation);
+  });
+
+  it("leaves automation unset when the element has none", () => {
+    const html = `<!DOCTYPE html><html><body>
+      <div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
+        <audio id="bgm" src="a.wav" data-start="0" data-duration="10"></audio>
+      </div></body></html>`;
+    expect(parseAudioElements(html)[0]?.automation).toBeUndefined();
+  });
+});

packages/engine/src/services/audioFxRender.test.ts

@@ -56,6 +56,15 @@ function tone(path: string, seconds = 0.3, freq = 440): void {
   writeWav(path, s, SR);
 }
 
+/** RMS of one slice, for comparing how loud a moment is against another. */
+const sliceRms = (s: Float32Array, from: number, to: number): number => {
+  const a = Math.max(0, Math.floor(from * SR));
+  const b = Math.min(s.length, Math.floor(to * SR));
+  let sum = 0;
+  for (let i = a; i < b; i++) sum += (s[i] ?? 0) * (s[i] ?? 0);
+  return Math.sqrt(sum / Math.max(1, b - a));
+};
+
 const rms = (s: Float32Array): number =>
   Math.sqrt(s.reduce((a, x) => a + x * x, 0) / Math.max(1, s.length));
 const db = (x: number): number => 20 * Math.log10(x + 1e-30);
@@ -221,6 +230,45 @@ describe.skipIf(!HAS_BROWSER)("browser render", () => {
     expect(db(rms(readWav(outPath).samples))).toBeLessThan(db(rms(readWav(input).samples)) - 3);
   }, 180_000);
 
+  it("sweeps a filter across the clip when a lane automates it", async () => {
+    // A 2 kHz tone under a lowpass whose cutoff rises from below it to well
+    // above: the start should be attenuated and the end should not. This is
+    // the whole point of the render path — the envelope has to be *scheduled*
+    // offline, not merely parsed.
+    const input = join(dir, "sweep-in.wav");
+    tone(input, 1.5, 2000);
+    const outPath = join(dir, "sweep-out.wav");
+    await applyAudioFxChain(
+      input,
+      {
+        version: 1,
+        nodes: [{ type: "lowpass", id: "n1", enabled: true, params: { frequency: 300, q: 0.707 } }],
+      },
+      outPath,
+      {
+        trackId: "t",
+        automation: {
+          version: 1,
+          lanes: [
+            {
+              target: "fx.n1.frequency",
+              points: [
+                { t: 0, v: 300 },
+                { t: 1.5, v: 16000 },
+              ],
+            },
+          ],
+        },
+      },
+    );
+    const after = readWav(outPath).samples;
+    const head = db(sliceRms(after, 0.05, 0.25));
+    const tail = db(sliceRms(after, 1.2, 1.45));
+    // Opening the filter past the tone has to leave it far louder than when
+    // the cutoff sat an octave and a half below it.
+    expect(tail).toBeGreaterThan(head + 15);
+  }, 180_000);
+
   it("renders a multi-effect chain including reverb", async () => {
     const input = join(dir, "in.wav");
     tone(input);

packages/engine/src/services/audioFxRender.ts

@@ -18,6 +18,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { getAudioFxRuntimeScript } from "@hyperframes/core/audio-fx-runtime";
 import { enabledAudioFxNodes, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { serializeAutomation, type HfAutomation } from "@hyperframes/core/audio-automation";
 import { acquireBrowser } from "./browserManager.js";
 
 export class AudioFxRenderError extends Error {
@@ -184,7 +185,7 @@ export async function applyAudioFxChain(
   inputWav: string,
   chain: HfAudioFxChain,
   outputWav: string,
-  options: { trackId: string; signal?: AbortSignal },
+  options: { trackId: string; signal?: AbortSignal; automation?: HfAutomation },
 ): Promise<string> {
   if (enabledAudioFxNodes(chain).length === 0) return inputWav;
   if (!existsSync(inputWav)) {
@@ -216,7 +217,12 @@ export async function applyAudioFxChain(
       await page.addScriptTag({ content: getAudioFxRuntimeScript() });
 
       const rendered = (await page.evaluate(
-        async ([channelB64, rate, chainJson]: [string[], number, string]) => {
+        async ([channelB64, rate, chainJson, automationJson]: [
+          string[],
+          number,
+          string,
+          string,
+        ]) => {
           const decode = (b64: string): Float32Array => {
             const bin = atob(b64);
             const bytes = new Uint8Array(bin.length);
@@ -226,12 +232,22 @@ export async function applyAudioFxChain(
           const api = (
             window as unknown as {
               __HF_AUDIO_FX?: {
-                render(p: Float32Array[], r: number, c: string): Promise<Float32Array[]>;
+                render(
+                  p: Float32Array[],
+                  r: number,
+                  c: string,
+                  a?: string,
+                ): Promise<Float32Array[]>;
               };
             }
           ).__HF_AUDIO_FX;
           if (!api) throw new Error("audio FX runtime failed to load");
-          const out = await api.render(channelB64.map(decode), rate, chainJson);
+          const out = await api.render(
+            channelB64.map(decode),
+            rate,
+            chainJson,
+            automationJson || undefined,
+          );
           const encode = (plane: Float32Array): string => {
             const u8 = new Uint8Array(plane.buffer, plane.byteOffset, plane.length * 4);
             let s = "";
@@ -249,7 +265,8 @@ export async function applyAudioFxChain(
           ),
           sampleRate,
           JSON.stringify(chain),
-        ] as [string[], number, string],
+          options.automation ? serializeAutomation(options.automation) : "",
+        ] as [string[], number, string, string],
       )) as string[];
 
       // byteOffset and byteLength matter: Node pools small allocations, so a
@@ -278,4 +295,4 @@ export async function applyAudioFxChain(
   }
 }
 
-export type { HfAudioFxChain };
+export type { HfAudioFxChain, HfAutomation };