fix(core): make the volume lane audible in preview

The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.

The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.

The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.

Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.

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

Author: vanceingalls

.fallowrc.jsonc

@@ -655,6 +655,11 @@
       // optional fields, but the line-shift fingerprint re-flags the inherited
       // complexity.
       "packages/studio/src/utils/sourcePatcher.ts",
+      // runtime/media.ts: refreshRuntimeMediaCache pre-dates this work and is
+      // untouched by it — this stack only adds a volume-lane branch to
+      // syncRuntimeMedia's author-volume resolution, but touching the file makes
+      // fallow report the inherited function.
+      "packages/core/src/runtime/media.ts",
       // timeline.ts: collectRuntimeTimelinePayload (CRITICAL) pre-dates this PR;
       // only an import line changed here (slideshow/sceneId → slideshow/index),
       // but the line-shift fingerprint makes fallow re-flag inherited complexity.

packages/core/src/runtime/audioAutomationVolume.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { elementVolumeLaneGain } from "./audioAutomationVolume.js";
+
+const el = (automation?: string) => ({
+  getAttribute: (name: string) =>
+    name === "data-automation" && automation !== undefined ? automation : null,
+});
+
+const duck = JSON.stringify({
+  version: 1,
+  lanes: [
+    {
+      target: "volume",
+      points: [
+        { t: 0, v: 0.55 },
+        { t: 1.4, v: 0.55 },
+        { t: 1.5, v: 0.15 },
+        { t: 9.5, v: 0.15 },
+        { t: 11, v: 0.55 },
+      ],
+    },
+  ],
+});
+
+describe("elementVolumeLaneGain", () => {
+  it("returns the lane's gain at a clip-local time", () => {
+    expect(elementVolumeLaneGain(el(duck), 0)).toBeCloseTo(0.55, 6);
+    expect(elementVolumeLaneGain(el(duck), 1.4)).toBeCloseTo(0.55, 6);
+    expect(elementVolumeLaneGain(el(duck), 5)).toBeCloseTo(0.15, 6);
+    expect(elementVolumeLaneGain(el(duck), 11)).toBeCloseTo(0.55, 6);
+    // Holds past the last point rather than falling to zero.
+    expect(elementVolumeLaneGain(el(duck), 20)).toBeCloseTo(0.55, 6);
+  });
+
+  it("ramps between points", () => {
+    const mid = elementVolumeLaneGain(el(duck), 1.45) ?? 0;
+    expect(mid).toBeLessThan(0.55);
+    expect(mid).toBeGreaterThan(0.15);
+  });
+
+  it("returns null with no automation, so the caller keeps its own rules", () => {
+    expect(elementVolumeLaneGain(el(), 1)).toBeNull();
+    expect(elementVolumeLaneGain(el(""), 1)).toBeNull();
+  });
+
+  it("returns null for an element that carries only FX lanes", () => {
+    const fxOnly = JSON.stringify({
+      version: 1,
+      lanes: [{ target: "fx.n1.frequency", points: [{ t: 0, v: 400 }] }],
+    });
+    expect(elementVolumeLaneGain(el(fxOnly), 0)).toBeNull();
+  });
+
+  it("plays flat rather than silent when the attribute is unreadable", () => {
+    expect(elementVolumeLaneGain(el("{not json"), 0)).toBeNull();
+  });
+
+  it("tolerates an object with no getAttribute at all", () => {
+    expect(elementVolumeLaneGain({}, 0)).toBeNull();
+  });
+
+  it("does not reparse the same attribute on every call", () => {
+    // The runtime asks once per tick per track; parsing there would run the JSON
+    // parser 60 times a second for a value that only changes on an edit.
+    let reads = 0;
+    const counting = {
+      getAttribute: (name: string) => {
+        if (name !== "data-automation") return null;
+        reads += 1;
+        return duck;
+      },
+    };
+    for (let i = 0; i < 50; i += 1) elementVolumeLaneGain(counting, i / 10);
+    expect(reads).toBe(50);
+    // Same object identity back each time proves the parse was cached.
+    const a = elementVolumeLaneGain(el(duck), 1);
+    const b = elementVolumeLaneGain(el(duck), 1);
+    expect(a).toBe(b);
+  });
+});

packages/core/src/runtime/audioAutomationVolume.ts

@@ -0,0 +1,57 @@
+/**
+ * The volume lane's gain for an element at a moment in its clip.
+ *
+ * Volume is not scheduled onto the gain AudioParam the way FX parameters are.
+ * The runtime rewrites that gain every tick from `data-volume` and the GSAP
+ * seeked value, which would erase a scheduled envelope within a frame — so the
+ * lane feeds the same per-tick path the probed `volumeKeyframes` already use,
+ * and the render still bakes it into the samples.
+ */
+
+import {
+  HF_AUDIO_AUTOMATION_ATTR,
+  parseAutomation,
+  sampleAutomationLane,
+  VOLUME_TARGET,
+  type HfAutomationLane,
+} from "../audioAutomation.js";
+
+/**
+ * Parsed lanes by the attribute text they came from. Reparsing on every tick
+ * would run the JSON parser 60 times a second per track for a value that only
+ * changes when the author edits it.
+ */
+const cache = new Map<string, HfAutomationLane | null>();
+const CACHE_LIMIT = 64;
+
+function laneFromAttr(raw: string): HfAutomationLane | null {
+  const hit = cache.get(raw);
+  if (hit !== undefined) return hit;
+  let lane: HfAutomationLane | null = null;
+  try {
+    lane = parseAutomation(raw).lanes.find((l) => l.target === VOLUME_TARGET) ?? null;
+  } catch {
+    // Unreadable automation plays the track flat rather than silencing it.
+    lane = null;
+  }
+  if (cache.size > CACHE_LIMIT) cache.clear();
+  cache.set(raw, lane);
+  return lane;
+}
+
+/**
+ * Gain the lane asks for at `relTime` clip-local seconds, or null when the
+ * element has no volume lane and the caller should fall back to its own rules.
+ */
+export function elementVolumeLaneGain(
+  el: { getAttribute?(name: string): string | null },
+  relTime: number,
+): number | null {
+  const raw =
+    (typeof el.getAttribute === "function" ? el.getAttribute(HF_AUDIO_AUTOMATION_ATTR) : null) ??
+    "";
+  if (!raw) return null;
+  const lane = laneFromAttr(raw);
+  if (!lane || lane.points.length === 0) return null;
+  return sampleAutomationLane(lane, relTime);
+}

packages/core/src/runtime/media.test.ts

@@ -307,6 +307,87 @@ describe("syncRuntimeMedia", () => {
     document.body.innerHTML = "";
   });
 
+  describe("volume automation lane", () => {
+    const DUCK = JSON.stringify({
+      version: 1,
+      lanes: [
+        {
+          target: "volume",
+          points: [
+            { t: 0, v: 0.8 },
+            { t: 2, v: 0.8 },
+            { t: 3, v: 0.1 },
+            { t: 8, v: 0.1 },
+          ],
+        },
+      ],
+    });
+
+    /**
+     * The runtime rewrites the transport's gain every tick. Before the lane fed
+     * this path it was scheduled onto the AudioParam instead and erased within a
+     * frame, so the envelope was inaudible in preview while being correct in the
+     * render.
+     */
+    function volumesAt(times: number[], automation?: string, volume = 0.55) {
+      const clip = createMockClip({ start: 0, end: 10, volume });
+      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+      if (automation) clip.el.setAttribute("data-automation", automation);
+      const seen: number[] = [];
+      for (const t of times) {
+        syncRuntimeMedia({
+          clips: [clip],
+          timeSeconds: t,
+          playing: true,
+          playbackRate: 1,
+          onElementVolume: (_el, v) => seen.push(v),
+        });
+      }
+      return seen;
+    }
+
+    it("drives the transport gain from the lane, not from data-volume", () => {
+      const [held, ducked] = volumesAt([1, 5], DUCK);
+      expect(held).toBeCloseTo(0.8, 5);
+      expect(ducked).toBeCloseTo(0.1, 5);
+    });
+
+    it("ramps between points across ticks", () => {
+      const [a, b, c] = volumesAt([2, 2.5, 3], DUCK);
+      expect(a).toBeCloseTo(0.8, 5);
+      expect(b).toBeGreaterThan(0.1);
+      expect(b).toBeLessThan(0.8);
+      expect(c).toBeCloseTo(0.1, 5);
+    });
+
+    it("falls back to data-volume when there is no lane", () => {
+      const [only] = volumesAt([5], undefined, 0.55);
+      expect(only).toBeCloseTo(0.55, 5);
+    });
+
+    it("supersedes keyframes probed from the timeline", () => {
+      // Both present: the lane is the explicit one, and `lint` warns about it.
+      const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
+      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+      clip.el.setAttribute("data-automation", DUCK);
+      clip.volumeKeyframes = [
+        { time: 0, volume: 1 },
+        { time: 10, volume: 1 },
+      ];
+      let seen = -1;
+      syncRuntimeMedia({
+        clips: [clip],
+        timeSeconds: 5,
+        playing: true,
+        playbackRate: 1,
+        onElementVolume: (_el, v) => {
+          seen = v;
+        },
+      });
+      expect(seen).toBeCloseTo(0.1, 5);
+    });
+  });
+
   it("plays active clip when playing and buffered", () => {
     const clip = createMockClip({ start: 0, end: 10 });
     Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });

packages/core/src/runtime/media.ts

@@ -1,5 +1,6 @@
 import { swallow } from "./diagnostics";
 import { interpolateVolumeGain, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
+import { elementVolumeLaneGain } from "./audioAutomationVolume.js";
 import { normalizePlaybackRate } from "./playbackRate.js";
 
 export function readElementPlaybackRate(el: Element): number {
@@ -270,7 +271,13 @@ export function syncRuntimeMedia(params: {
       const currentElementVolume = clampVolume(el.volume);
 
       let authorVolume: number;
-      if (clip.volumeKeyframes && clip.volumeKeyframes.length > 0) {
+      // An explicit volume lane owns the fader. It is checked before the probed
+      // keyframes because the two would otherwise fight, and it is the one the
+      // author drew — `lint` warns when a track carries both.
+      const laneGain = elementVolumeLaneGain(el, relTime);
+      if (laneGain !== null) {
+        authorVolume = clampVolume(laneGain);
+      } else if (clip.volumeKeyframes && clip.volumeKeyframes.length > 0) {
         // Keyframes probed from the GSAP timeline — same source as the renderer.
         // Use the interpolated envelope value directly; no need to track GSAP changes.
         authorVolume = clampVolume(interpolateVolumeGain(clip.volumeKeyframes, relTime));

packages/core/src/runtime/webAudioTransport.ts

@@ -1,10 +1,5 @@
-import { attachElementFxChain, readElementAutomation } from "./audioFx.js";
-import {
-  scheduleParamLane,
-  volumeLane,
-  type AutomationTiming,
-} from "../audio/audioFxAutomation.js";
-import { VOLUME_RANGE } from "../audioAutomation.js";
+import { attachElementFxChain } from "./audioFx.js";
+import type { AutomationTiming } from "../audio/audioFxAutomation.js";
 import { swallow } from "./diagnostics";
 import { getDebugSurface } from "./globals.js";
 
@@ -63,20 +58,6 @@ function startBoundedSource(
   return true;
 }
 
-/**
- * The volume lane rides the fader, after the effects — where a DAW puts it,
- * and the order the render bakes it in.
- */
-function scheduleVolumeLane(
-  el: HTMLMediaElement,
-  gainNode: GainNode,
-  timing: AutomationTiming,
-): void {
-  const lane = volumeLane(readElementAutomation(el));
-  if (!lane) return;
-  scheduleParamLane([{ param: gainNode.gain }], lane, VOLUME_RANGE.scale, timing);
-}
-
 export type ScheduledSource = {
   el: HTMLMediaElement;
   sourceNode: AudioBufferSourceNode;
@@ -219,8 +200,6 @@ export class WebAudioTransport {
       const fx = attachElementFxChain(this._ctx, el, sourceNode, gainNode, timing);
       gainNode.connect(this._masterGain);
 
-      scheduleVolumeLane(el, gainNode, timing);
-
       this._rate = safeRate;
       this._rateAnchorCtx = scheduledAt;
       this._rateAnchorComp = compositionTime;