From d302bc0f44e491657b5d77b8e1007f24aec96128 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 17 Aug 2026 14:19:31 -0400
Subject: [PATCH 1/4] fix(audio): carry authoring gain above unity into preview
 and render
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`HTMLMediaElement.volume` is spec-clamped to [0,1], so both timeline probes
lost a clip's authored gain the moment it also carried a fade: the probe
seeded the element at the clamped value and every sample read back at or
below 0 dB, and the mixer prefers probed keyframes over the static volume.
Both probes now shadow the accessor for their own duration and forward the
clamped value to the native setter, so the authored gain survives while
nothing outside the probe ever sees an illegal volume.

Measured on one 6 s composition, first 4 s: unity -32.8 LUFS, boosted -27.0,
boosted-with-fade -32.8 before and -27.0 after — +5.8 dB, exactly the gain
the clip was authored at.

Collapse the other owners of the same decision, each of which kept preview
and render disagreeing on their own: the Web Audio master gain had two
writers, so unmuting discarded the user's volume; the user's volume was
applied twice, once per clip and once on the master; and the control bridge
wrote `el.volume` for clips the transport already owned, which the next tick
read back as the clip's author gain. `<video data-has-audio>` is never
scheduled as a buffer source, so it now routes through a media-element gain
node — but only while the audio context is running, since routing into a
suspended graph would silence audio the native path is playing.
---
 packages/core/package-subpaths.json           |   6 +
 packages/core/package.json                    |  10 ++
 packages/core/src/audioGain.test.ts           |  61 ++++++++++
 packages/core/src/audioGain.ts                | 104 ++++++++++++++++
 packages/core/src/runtime/init.ts             |  32 +++--
 packages/core/src/runtime/media.test.ts       |  45 +++++--
 packages/core/src/runtime/media.ts            |  44 ++++---
 .../src/runtime/mediaVolumeEnvelope.test.ts   |  57 +++++++++
 .../core/src/runtime/mediaVolumeEnvelope.ts   |  52 ++++----
 .../src/runtime/webAudioTransport.test.ts     |  73 +++++++++++
 .../core/src/runtime/webAudioTransport.ts     | 115 +++++++++++++++---
 .../engine/src/services/audioMixer.test.ts    |  29 +++++
 packages/engine/src/services/audioMixer.ts    |   4 +-
 packages/parsers/src/types.ts                 |   2 +-
 .../producer/src/services/htmlCompiler.ts     | 101 ++++++++++-----
 15 files changed, 630 insertions(+), 105 deletions(-)
 create mode 100644 packages/core/src/audioGain.test.ts
 create mode 100644 packages/core/src/audioGain.ts

diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index 1485e4f022..ef217b46f8 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -158,6 +158,12 @@
       "types": "./dist/audioAutomation.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./audio-gain": {
+      "source": "./src/audioGain.ts",
+      "runtime": "./dist/audioGain.js",
+      "types": "./dist/audioGain.d.ts",
+      "environments": ["browser", "bun", "node"]
+    },
     "./color-grading": {
       "source": "./src/colorGrading.ts",
       "runtime": "./dist/colorGrading.js",
diff --git a/packages/core/package.json b/packages/core/package.json
index 41077e31d1..c830528b9c 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -172,6 +172,12 @@
       "import": "./src/audioAutomation.ts",
       "types": "./src/audioAutomation.ts"
     },
+    "./audio-gain": {
+      "bun": "./src/audioGain.ts",
+      "node": "./dist/audioGain.js",
+      "import": "./src/audioGain.ts",
+      "types": "./src/audioGain.ts"
+    },
     "./color-grading": {
       "bun": "./src/colorGrading.ts",
       "node": "./dist/colorGrading.js",
@@ -478,6 +484,10 @@
         "import": "./dist/audioAutomation.js",
         "types": "./dist/audioAutomation.d.ts"
       },
+      "./audio-gain": {
+        "import": "./dist/audioGain.js",
+        "types": "./dist/audioGain.d.ts"
+      },
       "./color-grading": {
         "import": "./dist/colorGrading.js",
         "types": "./dist/colorGrading.d.ts"
diff --git a/packages/core/src/audioGain.test.ts b/packages/core/src/audioGain.test.ts
new file mode 100644
index 0000000000..029c7b6c66
--- /dev/null
+++ b/packages/core/src/audioGain.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  AUDIO_GAIN_FADER_MAX,
+  formatAudioGain,
+  AUDIO_GAIN_FADER_MIN,
+  MAX_AUDIO_GAIN,
+  audioGainToFaderPosition,
+  audioGainToText,
+  audioFaderPositionToGain,
+} from "./audioGain";
+
+describe("audio gain fader", () => {
+  it("puts unity gain at the physical midpoint", () => {
+    expect(audioGainToFaderPosition(1)).toBe(0);
+    expect(audioFaderPositionToGain(0)).toBe(1);
+  });
+
+  it("provides +12 dB of boost above unity", () => {
+    expect(audioFaderPositionToGain(AUDIO_GAIN_FADER_MAX)).toBeCloseTo(MAX_AUDIO_GAIN, 6);
+    expect(audioGainToText(MAX_AUDIO_GAIN)).toBe("+12.0 dB");
+  });
+
+  it("preserves a true silence endpoint below unity", () => {
+    expect(audioFaderPositionToGain(AUDIO_GAIN_FADER_MIN)).toBe(0);
+    expect(audioGainToText(0)).toBe("-∞ dB");
+  });
+
+  it("pins sub-floor gain to the fader's silence endpoint", () => {
+    expect(audioGainToFaderPosition(0.00001)).toBe(AUDIO_GAIN_FADER_MIN);
+  });
+
+  it("round-trips representative attenuation and boost values", () => {
+    for (const gain of [0.1, 0.5, 1, 2, MAX_AUDIO_GAIN]) {
+      expect(audioFaderPositionToGain(audioGainToFaderPosition(gain))).toBeCloseTo(gain, 6);
+    }
+  });
+
+  describe("formatAudioGain", () => {
+    it("never collapses an audible fader stop onto silence", () => {
+      for (let position = AUDIO_GAIN_FADER_MIN + 1; position <= AUDIO_GAIN_FADER_MAX; position++) {
+        const serialized = formatAudioGain(audioFaderPositionToGain(position));
+        expect(Number(serialized)).toBeGreaterThan(0);
+      }
+      // Only the very bottom of the travel is a real mute.
+      expect(formatAudioGain(audioFaderPositionToGain(AUDIO_GAIN_FADER_MIN))).toBe("0");
+    });
+
+    it("puts the knob back where the user let go of it", () => {
+      for (let position = AUDIO_GAIN_FADER_MIN; position <= AUDIO_GAIN_FADER_MAX; position++) {
+        const written = Number(formatAudioGain(audioFaderPositionToGain(position)));
+        expect(Math.round(audioGainToFaderPosition(written))).toBe(position);
+      }
+    });
+
+    it("keeps a serialized gain short and inside the ceiling", () => {
+      expect(formatAudioGain(1)).toBe("1");
+      expect(formatAudioGain(0.5)).toBe("0.5");
+      expect(formatAudioGain(99)).toBe(formatAudioGain(MAX_AUDIO_GAIN));
+    });
+  });
+});
diff --git a/packages/core/src/audioGain.ts b/packages/core/src/audioGain.ts
new file mode 100644
index 0000000000..cb19e7d30a
--- /dev/null
+++ b/packages/core/src/audioGain.ts
@@ -0,0 +1,104 @@
+/**
+ * Authoring gain for a media clip.
+ *
+ * HTMLMediaElement.volume is limited to 0..1, but HyperFrames' Web Audio
+ * preview and FFmpeg render paths both support gain above unity. Keep the
+ * shared ceiling here so Studio, preview, and render cannot drift.
+ */
+export const MAX_AUDIO_GAIN_DB = 12;
+export const MAX_AUDIO_GAIN = 10 ** (MAX_AUDIO_GAIN_DB / 20);
+
+/** Studio fader coordinates. Unity is deliberately the physical midpoint. */
+export const AUDIO_GAIN_FADER_MIN = -100;
+export const AUDIO_GAIN_FADER_MAX = 100;
+
+const MIN_AUDIO_GAIN_DB = -60;
+
+export function clampAudioGain(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.max(0, Math.min(MAX_AUDIO_GAIN, value));
+}
+
+export function clampNativeMediaVolume(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.max(0, Math.min(1, value));
+}
+
+/**
+ * Serialize an authored gain for `data-volume`.
+ *
+ * The fader travels in dB, so its stops are irrational (position -70 is
+ * 10 ** (-42/20)). Rounding to two decimals — what the generic numeric
+ * attribute formatter does — collapses the whole bottom of the fader onto
+ * `"0"` (a hard mute) and makes the knob jump on release everywhere below
+ * unity. Six decimals round-trip every integer fader stop back to itself.
+ */
+export function formatAudioGain(gain: number): string {
+  return clampAudioGain(gain)
+    .toFixed(6)
+    .replace(/\.?0+$/, "");
+}
+
+/**
+ * Run `probe` with `el.volume` shadowed by an accessor that keeps the authored
+ * value instead of the spec's [0,1] clamp.
+ *
+ * `HTMLMediaElement.volume` cannot hold gain above unity, so a clip authored
+ * at `data-volume="1.95"` reads back as 1 the moment the probe seeds it — and
+ * a GSAP tween started from that seed fades from 0 dB rather than from the
+ * authored boost. Both the FFmpeg mixer and the Web Audio transport carry gain
+ * up to MAX_AUDIO_GAIN, so the clamp is a probe artefact, not a real ceiling.
+ * The native setter still receives the clamped value, so nothing outside the
+ * probe observes an out-of-range volume, and the shadow is removed afterwards.
+ */
+export function withUnclampedVolume<T>(el: HTMLMediaElement, probe: () => T): T {
+  const descriptor = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
+  const nativeGet = descriptor?.get;
+  const nativeSet = descriptor?.set;
+  if (!nativeGet || !nativeSet) return probe();
+
+  let authored = Number(nativeGet.call(el));
+  Object.defineProperty(el, "volume", {
+    configurable: true,
+    get: () => authored,
+    set: (value: number) => {
+      authored = Number(value);
+      nativeSet.call(el, clampNativeMediaVolume(authored));
+    },
+  });
+  try {
+    return probe();
+  } finally {
+    delete (el as unknown as Record<"volume", unknown>).volume;
+    nativeSet.call(el, clampNativeMediaVolume(authored));
+  }
+}
+
+export function audioFaderPositionToGain(position: number): number {
+  const safe = Math.max(AUDIO_GAIN_FADER_MIN, Math.min(AUDIO_GAIN_FADER_MAX, position));
+  if (safe === AUDIO_GAIN_FADER_MIN) return 0;
+  const db =
+    safe < 0
+      ? (safe / Math.abs(AUDIO_GAIN_FADER_MIN)) * Math.abs(MIN_AUDIO_GAIN_DB)
+      : (safe / AUDIO_GAIN_FADER_MAX) * MAX_AUDIO_GAIN_DB;
+  return 10 ** (db / 20);
+}
+
+export function audioGainToFaderPosition(gain: number): number {
+  const safe = clampAudioGain(gain);
+  if (safe === 0) return AUDIO_GAIN_FADER_MIN;
+  const db = 20 * Math.log10(safe);
+  const position =
+    db < 0
+      ? (db / Math.abs(MIN_AUDIO_GAIN_DB)) * Math.abs(AUDIO_GAIN_FADER_MIN)
+      : (db / MAX_AUDIO_GAIN_DB) * AUDIO_GAIN_FADER_MAX;
+  return Math.max(AUDIO_GAIN_FADER_MIN, Math.min(AUDIO_GAIN_FADER_MAX, position));
+}
+
+export function audioGainToText(gain: number): string {
+  const safe = clampAudioGain(gain);
+  if (safe === 0) return "-∞ dB";
+  const db = 20 * Math.log10(safe);
+  const rounded = Math.abs(db) < 0.05 ? 0 : db;
+  return (rounded > 0 ? "+" : "") + rounded.toFixed(1) + " dB";
+}
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index cd8bd8b2ea..abca294397 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -28,6 +28,7 @@ import {
 } from "./media";
 import { handleErrorForProxy, handleMetadataForProxy, maybeProxyProactively } from "./mediaProxy";
 import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
+import { clampAudioGain, clampNativeMediaVolume } from "../audioGain.js";
 import { createPickerModule } from "./picker";
 import { createRuntimePlayer, type RuntimePlayerTransport } from "./player";
 import { createRuntimeState } from "./state";
@@ -1978,11 +1979,17 @@ export function initSandboxRuntimeModular(): void {
     }
   };
 
+  // Which media elements `syncRuntimeMedia` drives. It owns their volume every
+  // tick, so any other writer (the bridge's master-volume handler) must skip
+  // them or the two fight and the transport reads the loser back as the clip's
+  // author gain.
+  const isTransportOwnedMedia = (element: Element): boolean =>
+    element.hasAttribute("data-start") ||
+    Boolean(resolveMediaCompositionContext(element).compositionRoot);
+
   const syncMediaForCurrentState = () => {
     const cache = refreshRuntimeMediaCache({
-      shouldIncludeElement: (element) =>
-        element.hasAttribute("data-start") ||
-        Boolean(resolveMediaCompositionContext(element).compositionRoot),
+      shouldIncludeElement: isTransportOwnedMedia,
       resolveStartSeconds: (element) => {
         return resolveAbsoluteMediaStartSeconds(element);
       },
@@ -2039,7 +2046,7 @@ export function initSandboxRuntimeModular(): void {
         userMuted: state.bridgeMuted,
         userVolume: state.bridgeVolume,
         forceSync,
-        onElementVolume: (el, volume) => webAudio.setElementVolume(el, volume),
+        applyElementGain: (el, authorGain) => webAudio.applyElementGain(el, authorGain),
         isWebAudioOwned: (el) => webAudio.ownsElement(el),
         onAutoplayBlocked: () => {
           if (state.mediaAutoplayBlockedPosted) return;
@@ -3036,7 +3043,9 @@ export function initSandboxRuntimeModular(): void {
       const mediaStart =
         Number.parseFloat(rawEl.dataset.playbackStart ?? rawEl.dataset.mediaStart ?? "0") || 0;
       const volumeAttr = Number.parseFloat(rawEl.dataset.volume ?? "");
-      const vol = Number.isFinite(volumeAttr) ? volumeAttr : 1;
+      // Author gain only. The user's master volume rides the transport's master
+      // gain; folding it in here too applied it twice.
+      const vol = clampAudioGain(Number.isFinite(volumeAttr) ? volumeAttr : 1);
       const durationAttr = Number.parseFloat(rawEl.dataset.duration ?? "");
       let clipDuration =
         Number.isFinite(durationAttr) && durationAttr > 0 ? durationAttr : Number.POSITIVE_INFINITY;
@@ -3061,7 +3070,7 @@ export function initSandboxRuntimeModular(): void {
           compStart,
           mediaStart,
           clock.now(),
-          vol * state.bridgeVolume,
+          vol,
           gen,
           state.playbackRate,
           clipDuration,
@@ -3141,13 +3150,20 @@ export function initSandboxRuntimeModular(): void {
     onSetVolume: (volume) => {
       state.bridgeVolume = volume;
       webAudio.setVolume(volume);
+      // Only untimed media is set directly. `syncRuntimeMedia` already folds
+      // `state.bridgeVolume` into every clip it owns; writing those here too
+      // made the next tick see a changed `el.volume`, latch the clamped product
+      // as the clip's author gain, and drop a boosted clip by up to 12 dB on
+      // every master-fader move.
       const mediaEls = document.querySelectorAll("video, audio");
       for (const el of mediaEls) {
-        if (!(el instanceof HTMLMediaElement)) continue;
+        if (!(el instanceof HTMLMediaElement) || isTransportOwnedMedia(el)) continue;
         const parsed = parseFloat(el.dataset.volume ?? "");
         const clipVolume = Number.isFinite(parsed) ? parsed : 1;
-        el.volume = clipVolume * volume;
+        el.volume = clampNativeMediaVolume(clampAudioGain(clipVolume) * volume);
       }
+      state.mediaForceSyncNextTick = true;
+      syncMediaForCurrentState();
     },
     onSetMediaOutputMuted: (muted) => {
       state.mediaOutputMuted = muted;
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index bf697161b8..90e7952b96 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -340,7 +340,10 @@ describe("syncRuntimeMedia", () => {
           timeSeconds: t,
           playing: true,
           playbackRate: 1,
-          onElementVolume: (_el, v) => seen.push(v),
+          applyElementGain: (_el, v) => {
+            seen.push(v);
+            return false;
+          },
         });
       }
       return seen;
@@ -365,6 +368,28 @@ describe("syncRuntimeMedia", () => {
       expect(only).toBeCloseTo(0.55, 5);
     });
 
+    it("sends boosted author gain to Web Audio while keeping the native element legal", () => {
+      const clip = createMockClip({ start: 0, end: 10, volume: 3.98 });
+      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+      let transportGain = -1;
+
+      syncRuntimeMedia({
+        clips: [clip],
+        timeSeconds: 1,
+        playing: true,
+        playbackRate: 1,
+        applyElementGain: (_el, gain) => {
+          transportGain = gain;
+          // The transport reports that it now carries the gain, which is what
+          // keeps the native element at unity instead of the clamped product.
+          return true;
+        },
+      });
+
+      expect(transportGain).toBeCloseTo(3.98, 5);
+      expect(clip.el.volume).toBe(1);
+    });
+
     /**
      * The render bakes the lane at CLIP-LOCAL time: prepareAudioTrack already
      * cut the wav with `-ss mediaStart`, so its t=0 is the clip's start, and
@@ -383,8 +408,9 @@ describe("syncRuntimeMedia", () => {
           timeSeconds: t,
           playing: true,
           playbackRate: 1,
-          onElementVolume: (_el, v) => {
+          applyElementGain: (_el, v) => {
             seen = v;
+            return false;
           },
         });
         return seen;
@@ -411,8 +437,9 @@ describe("syncRuntimeMedia", () => {
         timeSeconds: 5,
         playing: true,
         playbackRate: 1,
-        onElementVolume: (_el, v) => {
+        applyElementGain: (_el, v) => {
           seen = v;
+          return false;
         },
       });
       expect(seen).toBeCloseTo(0.1, 5);
@@ -694,15 +721,15 @@ describe("syncRuntimeMedia", () => {
     expect(clip.el.volume).toBe(0.5);
   });
 
-  it("reports the effective element volume to external audio transports", () => {
+  it("reports the clip's author gain to external audio transports", () => {
     const clip = createMockClip({ start: 0, end: 10, volume: 0 });
-    const onElementVolume = vi.fn();
+    const applyElementGain = vi.fn().mockReturnValue(false);
     syncRuntimeMedia({
       clips: [clip],
       timeSeconds: 0,
       playing: false,
       playbackRate: 1,
-      onElementVolume,
+      applyElementGain,
     });
     clip.el.volume = 0.75;
     syncRuntimeMedia({
@@ -711,11 +738,13 @@ describe("syncRuntimeMedia", () => {
       playing: false,
       playbackRate: 1,
       userVolume: 0.5,
-      onElementVolume,
+      applyElementGain,
     });
 
+    // The transport applies the user's volume once, on its master gain, so it
+    // is told the author gain alone. The native element still needs the product.
     expect(clip.el.volume).toBeCloseTo(0.375);
-    expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 0.375);
+    expect(applyElementGain).toHaveBeenLastCalledWith(clip.el, 0.75);
   });
 
   describe("per-element mute (Web Audio ownership)", () => {
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index 40ae5ec176..68aa99d29b 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -2,6 +2,7 @@ import { swallow } from "./diagnostics";
 import { interpolateVolumeGain, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
 import { elementVolumeLaneGain } from "./audioAutomationVolume.js";
 import { normalizePlaybackRate } from "./playbackRate.js";
+import { clampAudioGain, clampNativeMediaVolume } from "../audioGain.js";
 
 export function readElementPlaybackRate(el: Element): number {
   const authored = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
@@ -162,11 +163,6 @@ function isUnplayable(el: HTMLMediaElement): boolean {
 
 const lastRuntimeAppliedVolume = new WeakMap<HTMLMediaElement, number>();
 
-function clampVolume(volume: number): number {
-  if (!Number.isFinite(volume)) return 1;
-  return Math.max(0, Math.min(1, volume));
-}
-
 /**
  * Drop every per-source sync baseline tracked for `el` — offset drift
  * samples, the seek-past-buffered-range retry latch, and the last
@@ -213,6 +209,8 @@ export function syncRuntimeMedia(params: {
   /**
    * User's volume preference (0–1, set via `onSetVolume`). Multiplied with the
    * per-clip author volume so `data-volume="0.5"` at user volume 0.8 yields 0.4.
+   * Only for the native HTMLMedia path — the Web Audio transport applies it
+   * once on its own master gain (see `applyElementGain`).
    */
   userVolume?: number;
   /**
@@ -221,7 +219,18 @@ export function syncRuntimeMedia(params: {
    * outbound message; further invocations are suppressed by the caller.
    */
   onAutoplayBlocked?: () => void;
-  onElementVolume?: (el: HTMLMediaElement, volume: number) => void;
+  /**
+   * Hand the clip's AUTHOR gain to the Web Audio transport. The user's master
+   * volume is NOT folded in here — the transport applies that once, on its
+   * master gain, so a boosted clip is not attenuated twice.
+   *
+   * Returns true when the transport now carries the full gain in its graph, in
+   * which case `el.volume` must stay at unity or the gain is applied twice
+   * (the element feeds the graph). Returns false when the element is still
+   * played by the native HTMLMedia path, which needs the product written to
+   * `el.volume` — spec-clamped, so above-unity gain is unreachable there.
+   */
+  applyElementGain?: (el: HTMLMediaElement, authorGain: number) => boolean;
   /** Is THIS element owned by the Web Audio transport? Owned → mute it (transport
    *  plays it); not owned → leave audible (HTMLMedia fallback). Per-element, not a
    *  global flag, so a not-yet-claimed track isn't muted by other tracks. */
@@ -265,10 +274,10 @@ export function syncRuntimeMedia(params: {
           relTime = clip.mediaStart + ((relTime - clip.mediaStart) % loopLength);
         }
       }
-      const userVol = clampVolume(params.userVolume ?? 1);
-      const fallbackAuthorVolume = clampVolume(clip.volume ?? 1);
+      const userVol = clampNativeMediaVolume(params.userVolume ?? 1);
+      const fallbackAuthorVolume = clampAudioGain(clip.volume ?? 1);
       const previousRuntimeVolume = lastRuntimeAppliedVolume.get(el);
-      const currentElementVolume = clampVolume(el.volume);
+      const currentElementVolume = clampNativeMediaVolume(el.volume);
 
       let authorVolume: number;
       // An explicit volume lane owns the fader. It is checked before the probed
@@ -284,7 +293,7 @@ export function syncRuntimeMedia(params: {
       // there is one time base, and this is it.
       const laneGain = elementVolumeLaneGain(el, params.timeSeconds - clip.start);
       if (laneGain !== null) {
-        authorVolume = clampVolume(laneGain);
+        authorVolume = clampAudioGain(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.
@@ -294,13 +303,13 @@ export function syncRuntimeMedia(params: {
         // and the playback rate — so it only coincides with the envelope's time base
         // for an untrimmed clip playing at 1x from t=0.
         const elapsedInClip = params.timeSeconds - clip.start;
-        authorVolume = clampVolume(interpolateVolumeGain(clip.volumeKeyframes, elapsedInClip));
+        authorVolume = clampAudioGain(interpolateVolumeGain(clip.volumeKeyframes, elapsedInClip));
       } else if (previousRuntimeVolume === undefined) {
         // First tick this clip is active. The transport has already seeked GSAP
         // to the current time (seekTimelineAndAdapters runs before syncRuntimeMedia),
         // so el.volume reflects the animated value — trust it rather than falling
         // back to data-volume, which would clobber the GSAP-seeked position.
-        authorVolume = currentElementVolume;
+        authorVolume = fallbackAuthorVolume > 1 ? fallbackAuthorVolume : currentElementVolume;
       } else if (Math.abs(currentElementVolume - previousRuntimeVolume) > 0.0001) {
         // GSAP (or user code) changed el.volume between ticks — track it.
         authorVolume = currentElementVolume;
@@ -309,10 +318,13 @@ export function syncRuntimeMedia(params: {
         authorVolume = fallbackAuthorVolume;
       }
 
-      const effectiveVolume = clampVolume(authorVolume * userVol);
-      el.volume = effectiveVolume;
-      lastRuntimeAppliedVolume.set(el, effectiveVolume);
-      params.onElementVolume?.(el, effectiveVolume);
+      const authorGain = clampAudioGain(authorVolume);
+      const graphCarriesGain = params.applyElementGain?.(el, authorGain) === true;
+      const nativeVolume = graphCarriesGain
+        ? 1
+        : clampNativeMediaVolume(clampAudioGain(authorGain * userVol));
+      el.volume = nativeVolume;
+      lastRuntimeAppliedVolume.set(el, nativeVolume);
       // Mute only when force-muted or the transport owns this element; an unclaimed
       // track stays audible via the HTMLMedia fallback.
       if (forceMuteAll || params.isWebAudioOwned?.(el)) el.muted = true;
diff --git a/packages/core/src/runtime/mediaVolumeEnvelope.test.ts b/packages/core/src/runtime/mediaVolumeEnvelope.test.ts
index 0132ca8eb3..a1a56d5729 100644
--- a/packages/core/src/runtime/mediaVolumeEnvelope.test.ts
+++ b/packages/core/src/runtime/mediaVolumeEnvelope.test.ts
@@ -26,6 +26,63 @@ describe("probeElementVolumeKeyframes", () => {
     expect(keyframes).toContainEqual({ time: 1.1, volume: 0.2 });
   });
 
+  it("keeps a fade that starts from an above-unity authored gain", () => {
+    const audio = document.createElement("audio");
+    audio.dataset.start = "0";
+    audio.dataset.duration = "2";
+    audio.dataset.volume = "1.949845"; // +5.8 dB
+
+    // A GSAP tween reads the seeded value as its FROM. Through the spec's
+    // [0,1] clamp on `HTMLMediaElement.volume` that read back as 1, so the
+    // whole authored boost was thrown away by the mere presence of a fade.
+    const keyframes = probeElementVolumeKeyframes(
+      audio,
+      (time) => {
+        audio.volume = 1.949845 * Math.max(0, 1 - time / 2);
+      },
+      2,
+      10,
+    );
+
+    expect(keyframes?.[0]?.volume).toBeCloseTo(1.949845, 5);
+    expect(audio.volume).toBeLessThanOrEqual(1);
+  });
+
+  it("carries an above-unity tween target through to the envelope", () => {
+    const audio = document.createElement("audio");
+    audio.dataset.start = "0";
+    audio.dataset.duration = "1";
+    audio.dataset.volume = "1";
+
+    const keyframes = probeElementVolumeKeyframes(
+      audio,
+      (time) => {
+        audio.volume = 1 + time;
+      },
+      1,
+      10,
+    );
+
+    expect(keyframes?.at(-1)?.volume).toBeCloseTo(2, 5);
+  });
+
+  it("restores the native accessor once the probe is done", () => {
+    const audio = document.createElement("audio");
+    audio.dataset.start = "0";
+    audio.dataset.duration = "1";
+    audio.dataset.volume = "2";
+
+    probeElementVolumeKeyframes(audio, () => {}, 1, 10);
+
+    // The own accessor is gone and the spec setter is back in charge: it
+    // rejects an out-of-range volume rather than silently taking it.
+    expect(Object.getOwnPropertyDescriptor(audio, "volume")).toBeUndefined();
+    expect(audio.volume).toBe(1);
+    expect(() => {
+      audio.volume = 5;
+    }).toThrow();
+  });
+
   it("samples a short transition at a clip end between frame intervals", () => {
     const audio = document.createElement("audio");
     audio.dataset.start = "0";
diff --git a/packages/core/src/runtime/mediaVolumeEnvelope.ts b/packages/core/src/runtime/mediaVolumeEnvelope.ts
index b12349ed4e..e3405b3692 100644
--- a/packages/core/src/runtime/mediaVolumeEnvelope.ts
+++ b/packages/core/src/runtime/mediaVolumeEnvelope.ts
@@ -1,4 +1,5 @@
 import type { RuntimeTimelineLike } from "./types";
+import { clampAudioGain, withUnclampedVolume } from "../audioGain.js";
 
 /**
  * Shared volume-automation utilities used by both the renderer (offline PCM
@@ -16,8 +17,9 @@ export interface VolumeKeyframe {
 
 /**
  * Normalise raw keyframes to track-relative seconds: subtract `trackStart`,
- * clamp to [0,1], sort, de-duplicate, and prepend a `baseVolume` anchor at
- * t=0 when the first keyframe starts after the clip's begin.
+ * clamp to the authoring gain range, sort, de-duplicate, and prepend a
+ * `baseVolume` anchor at t=0 when the first keyframe starts after the clip's
+ * begin.
  *
  * Returns an empty array when all keyframes are invalid — the caller should
  * treat an empty envelope as "no automation, use static volume."
@@ -31,7 +33,7 @@ export function normaliseEnvelope(
     .filter((k) => Number.isFinite(k.time) && Number.isFinite(k.volume))
     .map((k) => ({
       time: Math.max(0, k.time - trackStart),
-      volume: Math.max(0, Math.min(1, k.volume)),
+      volume: clampAudioGain(k.volume),
     }))
     .sort((a, b) => a.time - b.time);
 
@@ -47,7 +49,7 @@ export function normaliseEnvelope(
 
   if (deduped.length === 0) return deduped;
   if (deduped[0]!.time > 0) {
-    deduped.unshift({ time: 0, volume: Math.max(0, Math.min(1, baseVolume)) });
+    deduped.unshift({ time: 0, volume: clampAudioGain(baseVolume) });
   }
   return deduped;
 }
@@ -114,8 +116,7 @@ function resolveVolumeProbeWindow(
     end = endAttr;
   }
   const staticAttr = parseFiniteDatasetNumber(el.dataset.volume) ?? 1;
-  const staticVolume = Math.max(0, Math.min(1, staticAttr));
-  return { start, end, staticVolume };
+  return { start, end, staticVolume: clampAudioGain(staticAttr) };
 }
 
 /**
@@ -136,29 +137,32 @@ export function probeElementVolumeKeyframes(
 ): VolumeKeyframe[] | null {
   const { start, end, staticVolume } = resolveVolumeProbeWindow(el, compositionDuration);
 
-  // Reset to data-volume so GSAP captures the correct FROM value.
-  el.volume = staticVolume;
-
   const step = 1 / Math.min(60, Math.max(1, sampleFps));
   const sampleStart = Math.max(0, start);
   const sampleEnd = Math.min(compositionDuration, end);
 
-  const keyframes: VolumeKeyframe[] = [];
-  let previousSample: VolumeKeyframe | undefined;
-  for (let t = sampleStart; t <= sampleEnd + 1e-6; t = Math.min(sampleEnd, t + step)) {
-    seekTimeline(t);
-    const raw = Number(el.volume);
-    if (Number.isFinite(raw)) {
-      const volume = Math.max(0, Math.min(1, raw));
-      const sample = {
-        time: Number(t.toFixed(6)),
-        volume: Number(volume.toFixed(6)),
-      };
-      recordVolumeSample(keyframes, previousSample, sample, t === sampleEnd);
-      previousSample = sample;
+  const keyframes: VolumeKeyframe[] = withUnclampedVolume(el, () => {
+    // Reset to data-volume so GSAP captures the correct FROM value. Above
+    // unity that only survives because the shadow accessor is installed.
+    el.volume = staticVolume;
+
+    const samples: VolumeKeyframe[] = [];
+    let previousSample: VolumeKeyframe | undefined;
+    for (let t = sampleStart; t <= sampleEnd + 1e-6; t = Math.min(sampleEnd, t + step)) {
+      seekTimeline(t);
+      const raw = Number(el.volume);
+      if (Number.isFinite(raw)) {
+        const sample = {
+          time: Number(t.toFixed(6)),
+          volume: Number(clampAudioGain(raw).toFixed(6)),
+        };
+        recordVolumeSample(samples, previousSample, sample, t === sampleEnd);
+        previousSample = sample;
+      }
+      if (t === sampleEnd) break;
     }
-    if (t === sampleEnd) break;
-  }
+    return samples;
+  });
 
   const hasAutomation = keyframes.some((kf) => Math.abs(kf.volume - staticVolume) > 0.0001);
   return hasAutomation ? keyframes : null;
diff --git a/packages/core/src/runtime/webAudioTransport.test.ts b/packages/core/src/runtime/webAudioTransport.test.ts
index 35f935bc5a..44d052ea09 100644
--- a/packages/core/src/runtime/webAudioTransport.test.ts
+++ b/packages/core/src/runtime/webAudioTransport.test.ts
@@ -49,6 +49,70 @@ function setupTransport(currentTime = 100) {
 const mockBuffer = {} as AudioBuffer;
 const mockEl = { muted: false } as HTMLMediaElement;
 
+describe("WebAudioTransport gain routing", () => {
+  const elementSourceCtx = (state: AudioContextState) => {
+    const gainNode = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
+    const sourceNode = { connect: vi.fn() };
+    const ctx = {
+      state,
+      createMediaElementSource: vi.fn(() => sourceNode),
+      createGain: vi.fn(() => gainNode),
+      destination: {},
+    };
+    const transport = new WebAudioTransport();
+    (transport as unknown as { _ctx: unknown })._ctx = ctx;
+    (transport as unknown as { _masterGain: unknown })._masterGain = {
+      gain: { value: 1 },
+      connect: vi.fn(),
+    };
+    return { transport, ctx, gainNode };
+  };
+
+  it("routes an above-unity element through the graph the native volume cannot reach", () => {
+    // `<video data-has-audio>` is never scheduled as a buffer source, so without
+    // this it plays at the spec's 1.0 ceiling in preview while the render mixer
+    // applies the full authored gain — the delivered file louder than what was
+    // signed off on.
+    const { transport, ctx, gainNode } = elementSourceCtx("running");
+    const el = { muted: false } as HTMLMediaElement;
+
+    expect(transport.applyElementGain(el, 3.98)).toBe(true);
+    expect(ctx.createMediaElementSource).toHaveBeenCalledWith(el);
+    expect(gainNode.gain.value).toBeCloseTo(3.98, 5);
+
+    // One source per element is all the spec allows, so the node is reused.
+    expect(transport.applyElementGain(el, 2)).toBe(true);
+    expect(ctx.createMediaElementSource).toHaveBeenCalledOnce();
+    expect(gainNode.gain.value).toBeCloseTo(2, 5);
+  });
+
+  it("leaves an element that fits in el.volume on the native path", () => {
+    const { transport, ctx } = elementSourceCtx("running");
+    expect(transport.applyElementGain({ muted: false } as HTMLMediaElement, 0.5)).toBe(false);
+    expect(ctx.createMediaElementSource).not.toHaveBeenCalled();
+  });
+
+  it("does not route into a suspended graph, which would silence live audio", () => {
+    const { transport, ctx } = elementSourceCtx("suspended");
+    expect(transport.applyElementGain({ muted: false } as HTMLMediaElement, 3.98)).toBe(false);
+    expect(ctx.createMediaElementSource).not.toHaveBeenCalled();
+  });
+
+  it("applies mute and user volume to one master formula, not two writers", () => {
+    const transport = new WebAudioTransport();
+    const master = { gain: { value: 1 }, connect: vi.fn() };
+    (transport as unknown as { _masterGain: unknown })._masterGain = master;
+
+    transport.setVolume(0.4);
+    expect(master.gain.value).toBeCloseTo(0.4, 5);
+    transport.setMuted(true);
+    expect(master.gain.value).toBe(0);
+    // Unmuting used to reset the node to 1 and discard the user's volume.
+    transport.setMuted(false);
+    expect(master.gain.value).toBeCloseTo(0.4, 5);
+  });
+});
+
 describe("WebAudioTransport", () => {
   it("tracks play generation for async race prevention", () => {
     const transport = new WebAudioTransport();
@@ -166,6 +230,15 @@ describe("WebAudioTransport", () => {
   });
 
   describe("schedulePlayback timing", () => {
+    it("keeps author boost above unity on the per-element gain node", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+
+      await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, 0, 1, gen);
+      transport.applyElementGain(mockEl, 3.98);
+
+      expect(mock.gainNode.gain.value).toBeCloseTo(3.98, 5);
+    });
+
     it("starts in-progress clips immediately with correct buffer offset", async () => {
       const { transport, mock, gen } = setupTransport(100);
 
diff --git a/packages/core/src/runtime/webAudioTransport.ts b/packages/core/src/runtime/webAudioTransport.ts
index e2e2dc66ed..0aa0d71777 100644
--- a/packages/core/src/runtime/webAudioTransport.ts
+++ b/packages/core/src/runtime/webAudioTransport.ts
@@ -7,6 +7,7 @@ import {
 import { VOLUME_RANGE } from "../audioAutomation.js";
 import { swallow } from "./diagnostics";
 import { getDebugSurface } from "./globals.js";
+import { clampAudioGain } from "../audioGain.js";
 
 function normalizeRate(rate: number): number {
   if (!Number.isFinite(rate) || rate <= 0) return 1;
@@ -99,6 +100,16 @@ export class WebAudioTransport {
   private _failedSrcs = new Set<string>();
   private _activeSources: ScheduledSource[] = [];
   private _masterGain: GainNode | null = null;
+  // Elements the native decoder still plays, routed through the graph so their
+  // gain can exceed the 1.0 ceiling `HTMLMediaElement.volume` imposes. Built
+  // lazily and kept for the context's life: `createMediaElementSource` can only
+  // be called once per element.
+  private _elementGains = new Map<HTMLMediaElement, GainNode>();
+  // The master gain has exactly one formula. Mute and user volume are two
+  // inputs to it, not two writers of it — a plain `setMuted(false)` used to
+  // reset the node to 1 and silently discard the user's volume.
+  private _userVolume = 1;
+  private _muted = false;
   // Composition-time reference frame: at AudioContext time `_rateAnchorCtx`,
   // composition time was `_rateAnchorComp`, and time has been advancing at
   // `_rate` composition-seconds per wallclock-second since.
@@ -113,6 +124,7 @@ export class WebAudioTransport {
       this._ctx = new AudioContext();
       this._masterGain = this._ctx.createGain();
       this._masterGain.connect(this._ctx.destination);
+      this.applyMasterGain();
       return true;
     } catch {
       return false;
@@ -206,7 +218,7 @@ export class WebAudioTransport {
       sourceNode.playbackRate.value = safeRate;
 
       const gainNode = this._ctx.createGain();
-      gainNode.gain.value = volume;
+      gainNode.gain.value = clampAudioGain(volume);
 
       const elapsed = compositionTime - compositionStart;
       const scheduledAt = this._ctx.currentTime;
@@ -346,30 +358,97 @@ export class WebAudioTransport {
     this._paused = true;
   }
 
+  private applyMasterGain(): void {
+    if (!this._masterGain) return;
+    this._masterGain.gain.value = this._muted ? 0 : Math.max(0, Math.min(1, this._userVolume));
+  }
+
   setVolume(volume: number): void {
-    if (this._masterGain) {
-      this._masterGain.gain.value = Math.max(0, Math.min(1, volume));
-    }
+    this._userVolume = Number.isFinite(volume) ? volume : 1;
+    this.applyMasterGain();
+  }
+
+  /**
+   * Apply a clip's AUTHOR gain — the user's master volume is applied once, by
+   * `applyMasterGain`, and must not be folded in by the caller.
+   *
+   * Returns true when the graph now carries the whole gain, which tells the
+   * caller to leave `el.volume` at unity. A scheduled buffer source replaces
+   * the element's audio outright (the element is muted), so it reports false;
+   * only the media-element route feeds the graph FROM `el.volume` and so needs
+   * that unity.
+   */
+  applyElementGain(el: HTMLMediaElement, authorGain: number): boolean {
+    const safeGain = clampAudioGain(authorGain);
+    if (this.applyScheduledSourceGain(el, safeGain)) return false;
+    return this.applyMediaElementGain(el, safeGain);
   }
 
-  setElementVolume(el: HTMLMediaElement, volume: number): void {
-    const safeVolume = Math.max(0, Math.min(1, volume));
+  /** The decoded-buffer route. Returns whether this element has one at all. */
+  private applyScheduledSourceGain(el: HTMLMediaElement, gain: number): boolean {
+    let scheduled = false;
     for (const source of this._activeSources) {
       if (source.el !== el) continue;
-      try {
-        source.gainNode.gain.value = safeVolume;
-      } catch (err) {
-        swallow("webAudioTransport.setElementVolume", err);
-      }
+      scheduled = true;
+      this.setGain(source.gainNode, gain);
     }
+    return scheduled;
   }
 
-  setMuted(muted: boolean): void {
-    if (this._masterGain) {
-      this._masterGain.gain.value = muted ? 0 : 1;
+  /** The native-playback route. Returns whether the graph now carries the gain. */
+  private applyMediaElementGain(el: HTMLMediaElement, gain: number): boolean {
+    const existing = this._elementGains.get(el);
+    // Nothing to fix while the gain fits in `el.volume`; leave untouched
+    // elements on the plain native path they have always used.
+    if (!existing && gain <= 1) return false;
+    const gainNode = existing ?? this.attachMediaElementGain(el);
+    return gainNode ? this.setGain(gainNode, gain) : false;
+  }
+
+  private setGain(gainNode: GainNode, gain: number): boolean {
+    try {
+      gainNode.gain.value = gain;
+      return true;
+    } catch (err) {
+      swallow("webAudioTransport.applyElementGain", err);
+      return false;
     }
   }
 
+  /**
+   * Route a natively-played element through the graph so its gain can exceed
+   * unity. Used for `<video data-has-audio>`, which the buffer-source path does
+   * not schedule: without this the render mixer would apply an authored boost
+   * the preview could not, and the delivered file would be louder than what the
+   * author signed off on.
+   */
+  private attachMediaElementGain(el: HTMLMediaElement): GainNode | null {
+    if (!this._ctx || !this._masterGain) return null;
+    // Only while the context is actually running. Routing an element into a
+    // suspended graph (no user gesture yet) would silence audio that the native
+    // path is playing right now, and the routing cannot be undone — one call
+    // per element is all the spec allows.
+    if (this._ctx.state !== "running") return null;
+    try {
+      const source = this._ctx.createMediaElementSource(el);
+      const gainNode = this._ctx.createGain();
+      source.connect(gainNode);
+      gainNode.connect(this._masterGain);
+      this._elementGains.set(el, gainNode);
+      return gainNode;
+    } catch (err) {
+      // Already sourced elsewhere, or a tainted cross-origin source. The
+      // element keeps playing natively at its clamped volume.
+      swallow("webAudioTransport.attachMediaElementGain", err);
+      return null;
+    }
+  }
+
+  setMuted(muted: boolean): void {
+    this._muted = muted;
+    this.applyMasterGain();
+  }
+
   isActive(): boolean {
     return this._activeSources.length > 0 && !this._paused;
   }
@@ -382,6 +461,14 @@ export class WebAudioTransport {
 
   destroy(): void {
     this.stopAll();
+    for (const gainNode of this._elementGains.values()) {
+      try {
+        gainNode.disconnect();
+      } catch {
+        // Already torn down.
+      }
+    }
+    this._elementGains.clear();
     this._bufferCache.clear();
     this._failedSrcs.clear();
     if (this._ctx) {
diff --git a/packages/engine/src/services/audioMixer.test.ts b/packages/engine/src/services/audioMixer.test.ts
index cac9b10ae8..891658b723 100644
--- a/packages/engine/src/services/audioMixer.test.ts
+++ b/packages/engine/src/services/audioMixer.test.ts
@@ -257,6 +257,35 @@ describe("processCompositionAudio", () => {
     expect(filter).not.toContain("weights=");
   });
 
+  it("preserves authored clip gain above unity for quiet-source boosting", async () => {
+    const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
+    const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
+    tempDirs.push(baseDir, workDir);
+    writeFileSync(join(baseDir, "quiet.wav"), "stub");
+
+    const result = await processCompositionAudio(
+      [
+        {
+          id: "quiet",
+          src: "quiet.wav",
+          start: 0,
+          end: 2,
+          mediaStart: 0,
+          layer: 0,
+          volume: 3.98,
+          type: "audio",
+        },
+      ],
+      baseDir,
+      workDir,
+      join(baseDir, "out.m4a"),
+      2,
+    );
+
+    expect(result.success).toBe(true);
+    expect(capturedFilterScripts[1]).toContain("volume=3.98");
+  });
+
   it("lets an FX tail run past the clip, still bounded by the composition", async () => {
     // A reverb is still decaying when the clip's own audio stops. Trimming at
     // the clip boundary is what cut every tail short in the render.
diff --git a/packages/engine/src/services/audioMixer.ts b/packages/engine/src/services/audioMixer.ts
index e71d26587b..d3f146c560 100644
--- a/packages/engine/src/services/audioMixer.ts
+++ b/packages/engine/src/services/audioMixer.ts
@@ -41,6 +41,7 @@ import {
 import { chainTailSeconds } from "@hyperframes/core/audio-fx-tail";
 import { applyAudioFxChain, AudioFxRenderError } from "./audioFxRender.js";
 import type { AudioVolumeKeyframe } from "./audioMixer.types.js";
+import { clampAudioGain } from "@hyperframes/core/audio-gain";
 
 export type { AudioElement, MixResult } from "./audioMixer.types.js";
 
@@ -60,8 +61,7 @@ export type { AudioElement, MixResult } from "./audioMixer.types.js";
 export const MIXED_AUDIO_FILENAME = "audio.m4a";
 
 function clampVolume(volume: number): number {
-  if (!Number.isFinite(volume)) return 1;
-  return Math.max(0, Math.min(1, volume));
+  return clampAudioGain(volume);
 }
 
 function formatFilterNumber(value: number): string {
diff --git a/packages/parsers/src/types.ts b/packages/parsers/src/types.ts
index 4820ba34fd..f402726c2b 100644
--- a/packages/parsers/src/types.ts
+++ b/packages/parsers/src/types.ts
@@ -160,7 +160,7 @@ export interface TimelineMediaElement extends TimelineElementBase {
   isAroll?: boolean;
   sourceWidth?: number;
   sourceHeight?: number;
-  volume?: number; // 0-1 (0% to 100%), default 1.0
+  volume?: number; // linear gain; 0 is silent, 1 is 0 dB, values above 1 boost
   hasAudio?: boolean; // For videos - indicates if video has audio track
 }
 
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index ff8fe7a0b0..164c546b71 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -24,6 +24,7 @@ import {
   type ResolvedDuration,
   type UnresolvedElement,
 } from "@hyperframes/core";
+import { MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
 import {
   assignBundledRuntimeCompositionIds,
   type BundledHostCompositionIdentity,
@@ -2203,8 +2204,41 @@ export async function discoverAudioVolumeAutomationFromTimeline(
 
   const sampleStep = 1 / Math.min(60, Math.max(1, sampleFps));
   return page.evaluate(
-    ({ ids, duration, step }) => {
+    ({ ids, duration, step, maxGain }) => {
       const results: { id: string; keyframes: { time: number; volume: number }[] }[] = [];
+      const clampGain = (value: number) =>
+        Number.isFinite(value) ? Math.max(0, Math.min(maxGain, value)) : 1;
+      // `HTMLMediaElement.volume` is spec-clamped to [0,1], so a clip authored
+      // above unity — or a GSAP tween seeded from one — reads back as 0 dB and
+      // the whole authored boost is lost from the mix. Shadow the accessor for
+      // the probe so the authored value survives; the native setter still gets
+      // the clamped value. Mirrors `withUnclampedVolume` in
+      // packages/core/src/audioGain.ts, which the preview probe uses; this copy
+      // exists only because the probe body is serialized into the page.
+      const volumeDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLMediaElement.prototype,
+        "volume",
+      );
+      const nativeVolumeGet = volumeDescriptor?.get;
+      const nativeVolumeSet = volumeDescriptor?.set;
+      const withUnclampedVolume = <T>(el: HTMLMediaElement, probe: () => T): T => {
+        if (!nativeVolumeGet || !nativeVolumeSet) return probe();
+        let authored = Number(nativeVolumeGet.call(el));
+        Object.defineProperty(el, "volume", {
+          configurable: true,
+          get: () => authored,
+          set: (value: number) => {
+            authored = Number(value);
+            nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
+          },
+        });
+        try {
+          return probe();
+        } finally {
+          delete (el as unknown as Record<"volume", unknown>).volume;
+          nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
+        }
+      };
       const timelines = (window as unknown as { __timelines?: Record<string, unknown> })
         .__timelines;
       if (!timelines) return results;
@@ -2246,42 +2280,45 @@ export async function discoverAudioVolumeAutomationFromTimeline(
         const sampleStart = Math.max(0, start);
         const sampleEnd = Math.min(duration, end);
         const initialVolumeAttr = Number.parseFloat(el.dataset.volume ?? "");
-        if (Number.isFinite(initialVolumeAttr)) {
-          el.volume = Math.max(0, Math.min(1, initialVolumeAttr));
-        }
 
-        const keyframes: { time: number; volume: number }[] = [];
-        let previousSample: { time: number; volume: number } | undefined;
-        for (let t = sampleStart; t <= sampleEnd + 0.000001; t = Math.min(sampleEnd, t + step)) {
-          seekTl(t);
-          const rawVolume = Number(el.volume);
-          if (!Number.isFinite(rawVolume)) {
-            if (t === sampleEnd) break;
-            continue;
+        const keyframes = withUnclampedVolume(el, () => {
+          if (Number.isFinite(initialVolumeAttr)) {
+            el.volume = clampGain(initialVolumeAttr);
           }
-          const volume = Math.max(0, Math.min(1, rawVolume));
-          const sample = {
-            time: Number(t.toFixed(6)),
-            volume: Number(volume.toFixed(6)),
-          };
-          const last = keyframes.at(-1);
-          if (!last || Math.abs(last.volume - volume) > 0.0001) {
-            // Retain the preceding real sample when compression omitted a flat
-            // run. Continuous ramps already have that sample as their last
-            // keyframe, so their interpolation remains unchanged.
-            if (last && previousSample && previousSample.time > last.time) {
-              keyframes.push(previousSample);
+          const samples: { time: number; volume: number }[] = [];
+          let previousSample: { time: number; volume: number } | undefined;
+          for (let t = sampleStart; t <= sampleEnd + 0.000001; t = Math.min(sampleEnd, t + step)) {
+            seekTl(t);
+            const rawVolume = Number(el.volume);
+            if (!Number.isFinite(rawVolume)) {
+              if (t === sampleEnd) break;
+              continue;
+            }
+            const volume = clampGain(rawVolume);
+            const sample = {
+              time: Number(t.toFixed(6)),
+              volume: Number(volume.toFixed(6)),
+            };
+            const last = samples.at(-1);
+            if (!last || Math.abs(last.volume - volume) > 0.0001) {
+              // Retain the preceding real sample when compression omitted a flat
+              // run. Continuous ramps already have that sample as their last
+              // keyframe, so their interpolation remains unchanged.
+              if (last && previousSample && previousSample.time > last.time) {
+                samples.push(previousSample);
+              }
+              samples.push(sample);
+            } else if (t === sampleEnd && sample.time > last.time) {
+              samples.push(sample);
             }
-            keyframes.push(sample);
-          } else if (t === sampleEnd && sample.time > last.time) {
-            keyframes.push(sample);
+            previousSample = sample;
+            if (t === sampleEnd) break;
           }
-          previousSample = sample;
-          if (t === sampleEnd) break;
-        }
+          return samples;
+        });
 
         const staticAttr = Number.parseFloat(el.dataset.volume ?? "");
-        const staticVolume = Number.isFinite(staticAttr) ? Math.max(0, Math.min(1, staticAttr)) : 1;
+        const staticVolume = Number.isFinite(staticAttr) ? clampGain(staticAttr) : 1;
         const hasAutomation = keyframes.some(
           (keyframe) => Math.abs(keyframe.volume - staticVolume) > 0.0001,
         );
@@ -2293,7 +2330,7 @@ export async function discoverAudioVolumeAutomationFromTimeline(
       seekTl(0);
       return results;
     },
-    { ids: audioIds, duration: compositionDuration, step: sampleStep },
+    { ids: audioIds, duration: compositionDuration, step: sampleStep, maxGain: MAX_AUDIO_GAIN },
   );
 }
 

From adfddff16e30418f0c749f4b6fc932a23fa93d22 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 17 Aug 2026 16:55:28 -0400
Subject: [PATCH 2/4] fix(audio): let the volume probe run where there is no
 DOM

The unclamped-volume shim reached for `HTMLMediaElement.prototype` before
checking that a DOM exists. The renderer's probe body is serialized into the
page in production but executed directly by tests that stand in for a Page,
so under the bun lane it threw `ReferenceError: HTMLMediaElement is not
defined` instead of falling back. Both copies now degrade to the clamped path
when the constructor is absent, which is the only correct answer off-browser.
---
 packages/core/src/audioGain.ts                 |  8 +++++++-
 packages/producer/src/services/htmlCompiler.ts | 11 +++++++----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/audioGain.ts b/packages/core/src/audioGain.ts
index cb19e7d30a..542890ca54 100644
--- a/packages/core/src/audioGain.ts
+++ b/packages/core/src/audioGain.ts
@@ -52,7 +52,13 @@ export function formatAudioGain(gain: number): string {
  * probe observes an out-of-range volume, and the shadow is removed afterwards.
  */
 export function withUnclampedVolume<T>(el: HTMLMediaElement, probe: () => T): T {
-  const descriptor = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
+  // Guarded for non-DOM runtimes: the probe that calls this is also reachable
+  // from tests and tools that run outside a browser, where the clamped path is
+  // the right (and only) answer.
+  const descriptor =
+    typeof HTMLMediaElement === "undefined"
+      ? undefined
+      : Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
   const nativeGet = descriptor?.get;
   const nativeSet = descriptor?.set;
   if (!nativeGet || !nativeSet) return probe();
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 164c546b71..a08b55b91d 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -2215,10 +2215,13 @@ export async function discoverAudioVolumeAutomationFromTimeline(
       // the clamped value. Mirrors `withUnclampedVolume` in
       // packages/core/src/audioGain.ts, which the preview probe uses; this copy
       // exists only because the probe body is serialized into the page.
-      const volumeDescriptor = Object.getOwnPropertyDescriptor(
-        HTMLMediaElement.prototype,
-        "volume",
-      );
+      // Guarded because this body is also executed directly by tests that
+      // stand in for a Page, where there is no DOM and no HTMLMediaElement.
+      // Without the descriptor the probe simply keeps the clamped path.
+      const volumeDescriptor =
+        typeof HTMLMediaElement === "undefined"
+          ? undefined
+          : Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
       const nativeVolumeGet = volumeDescriptor?.get;
       const nativeVolumeSet = volumeDescriptor?.set;
       const withUnclampedVolume = <T>(el: HTMLMediaElement, probe: () => T): T => {

From 907362b89a1f7a3248270867491663e6151664a9 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 17 Aug 2026 16:57:16 -0400
Subject: [PATCH 3/4] test(engine): give the mixer level cases the ffmpeg
 timeout its siblings use
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both cases spawn ffmpeg twice — once to build the source, once to mix — under
vitest's 5 s default, which the Windows runner routinely outruns. Every other
ffmpeg-driven suite in this package already declares 180 s.
---
 packages/engine/src/services/audioMixer.level.test.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/engine/src/services/audioMixer.level.test.ts b/packages/engine/src/services/audioMixer.level.test.ts
index 2ad7f5a5c4..38911ab2ef 100644
--- a/packages/engine/src/services/audioMixer.level.test.ts
+++ b/packages/engine/src/services/audioMixer.level.test.ts
@@ -107,7 +107,9 @@ describe.skipIf(!HAS_FFMPEG)("processCompositionAudio levels", () => {
 
     expect(result.success).toBe(true);
     expect(meanVolumeDb(outputPath) - meanVolumeDb(sourcePath)).toBeGreaterThan(-0.3);
-  });
+    // Two ffmpeg spawns per case, which routinely outruns the 5 s default on a
+    // Windows runner. Matches the timeout the other ffmpeg-driven engine suites use.
+  }, 180_000);
 
   it("places a delayed track on its authored start, not one AAC frame later", async () => {
     // The mix is AAC-encoded, and AAC encoders emit ~1024 priming samples. A
@@ -160,5 +162,5 @@ describe.skipIf(!HAS_FFMPEG)("processCompositionAudio levels", () => {
 
     expect(result.success).toBe(true);
     expect(firstAudibleSeconds(outputPath)).toBeCloseTo(2, 2);
-  });
+  }, 180_000);
 });

From 6a5267abbe082eea25adb2d5a231b64d6d5532ff Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 18 Aug 2026 01:18:50 -0400
Subject: [PATCH 4/4] fix(studio): hold the percent volume slider on a clip
 authored above unity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up on the gain work.

The percent slider tops out at 100%, and a boosted clip renders `value={195}`
on it. Committing from that control writes `next / 100` with `next <= 100`, so
one touch silently caps the clip and drops up to 12 dB — which only became
audible damage once this stack made above-unity gain actually render. Both
panels now hold the control above unity, the way the flat panel already holds
it while an automation lane owns the level. A hold, not a fix: the dB fader
that can represent these levels replaces the control outright.

Pin the render-side ceiling too. The existing case feeds 3.98, just under
MAX_AUDIO_GAIN, which proves the clamp is not min(1, ...) but leaves the upper
bound free — remove the clamp entirely and the suite stayed green. Verified by
mutation: the new case reds without it.

Correct audioLeveller's rationale, which justified riding a gain node with
"volume is 0..1 and normaliseEnvelope clamps every keyframe into it". Both
now span the same range, so the real reason is ownership: the volume lane is
the author's envelope, and a leveller writing into it would redraw their work.
---
 packages/core/src/audioLeveller.ts            | 12 ++++---
 .../engine/src/services/audioMixer.test.ts    | 32 +++++++++++++++++
 .../propertyPanelFlatMediaSection.test.tsx    | 35 +++++++++++++++++++
 .../editor/propertyPanelFlatMediaSection.tsx  | 10 ++++--
 .../editor/propertyPanelMediaSection.tsx      |  5 +++
 5 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/packages/core/src/audioLeveller.ts b/packages/core/src/audioLeveller.ts
index 8133e03ff9..2a889f84b6 100644
--- a/packages/core/src/audioLeveller.ts
+++ b/packages/core/src/audioLeveller.ts
@@ -13,11 +13,13 @@
  *
  * ## Why the lane rides a `gain` node
  *
- * The obvious home is the track's volume lane, and that cannot work: volume is
- * 0..1 and `normaliseEnvelope` clamps every keyframe into it, so a volume lane
- * can only ever attenuate. Lifting a quiet passage needs a `gain` node, which
- * spans -60..+12 dB — which is what the audio skill means when it calls `gain`
- * "what an automation lane rides when a track has to move".
+ * The obvious home is the track's volume lane. Both now span the same range —
+ * `normaliseEnvelope` clamps keyframes to 0..+12 dB, not 0..1 — so the reason
+ * is no longer that a volume lane can only attenuate. It is ownership: the
+ * volume lane is the fader the author draws, and a leveller that wrote into it
+ * would silently redraw their envelope. A `gain` node is a separate stage the
+ * leveller owns outright, which is what the audio skill means when it calls
+ * `gain` "what an automation lane rides when a track has to move".
  */
 
 import {
diff --git a/packages/engine/src/services/audioMixer.test.ts b/packages/engine/src/services/audioMixer.test.ts
index 891658b723..53bc73a89f 100644
--- a/packages/engine/src/services/audioMixer.test.ts
+++ b/packages/engine/src/services/audioMixer.test.ts
@@ -286,6 +286,38 @@ describe("processCompositionAudio", () => {
     expect(capturedFilterScripts[1]).toContain("volume=3.98");
   });
 
+  it("clamps an out-of-range gain to the shared authoring ceiling", async () => {
+    const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
+    const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
+    tempDirs.push(baseDir, workDir);
+    writeFileSync(join(baseDir, "quiet.wav"), "stub");
+
+    const result = await processCompositionAudio(
+      [
+        {
+          id: "quiet",
+          src: "quiet.wav",
+          start: 0,
+          end: 2,
+          mediaStart: 0,
+          layer: 0,
+          volume: 99,
+          type: "audio",
+        },
+      ],
+      baseDir,
+      workDir,
+      join(baseDir, "out.m4a"),
+      2,
+    );
+
+    expect(result.success).toBe(true);
+    // Pins the UPPER bound: the 3.98 case above only proves the clamp is not
+    // min(1, ...). Without this, changing MAX_AUDIO_GAIN's effect in the mixer
+    // leaves this suite green.
+    expect(capturedFilterScripts[1]).toContain("volume=3.981072");
+  });
+
   it("lets an FX tail run past the clip, still bounded by the composition", async () => {
     // A reverb is still decaying when the clip's own audio stops. Trimming at
     // the clip boundary is what cut every tail short in the render.
diff --git a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
index 125f5a1830..9ae2f79df7 100644
--- a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
@@ -153,6 +153,41 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
     act(() => root.unmount());
   });
 
+  it("refuses to commit from the percent slider on a clip authored above unity", () => {
+    // The control tops out at 100%, so any commit from it would cap a boosted
+    // clip and silently drop up to 12 dB that now genuinely renders. Held until
+    // the dB fader that can represent these levels replaces it.
+    const onSetAttribute = vi.fn();
+    const element = makeVideoElement({ dataAttributes: { volume: "1.949845" } });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <FlatMediaSection
+          projectDir={null}
+          element={element}
+          styles={{}}
+          onSetStyle={vi.fn()}
+          onSetAttribute={onSetAttribute}
+          onSetHtmlAttribute={vi.fn()}
+        />,
+      );
+    });
+
+    const volumeTrack = host.querySelectorAll('[data-flat-slider-track="true"]')[0];
+    Object.defineProperty(volumeTrack, "getBoundingClientRect", {
+      value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
+    });
+    act(() => {
+      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 50 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 50 }));
+    });
+
+    expect(onSetAttribute).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
   it("commits a new volume value on slider track pointerdown", () => {
     const onSetAttribute = vi.fn();
     const element = makeVideoElement({ dataAttributes: { volume: "0.2" } });
diff --git a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.tsx b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.tsx
index 997483e136..806d83dcf1 100644
--- a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.tsx
@@ -207,7 +207,13 @@ export function FlatMediaSection({
         <>
           {/* The slider is disabled while a lane owns the level: a value set
               here would be overwritten by the envelope on the next tick. The
-              toggle beside it carries the tooltip. */}
+              toggle beside it carries the tooltip.
+
+              It is also disabled above unity, for the same reason in a
+              different guise — this control tops out at 100%, so committing
+              from it would silently cap a boosted clip and drop up to 12 dB
+              that now genuinely renders. A hold, not a fix: the dB fader that
+              can represent these levels replaces this control outright. */}
           <div
             className="hf-volume-row flex items-center gap-1"
             data-volume-automated={volumeAutomated ? "" : undefined}
@@ -220,7 +226,7 @@ export function FlatMediaSection({
                 max={100}
                 tier={volumePercent === 100 ? "default" : "explicitCustom"}
                 displayValue={`${volumePercent}%`}
-                disabled={volumeAutomated}
+                disabled={volumeAutomated || volume > 1}
                 onCommit={(next) => void onSetAttribute("volume", formatNumericValue(next / 100))}
               />
             </div>
diff --git a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx b/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
index 14b06f14d9..c8c00e542d 100644
--- a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
+++ b/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
@@ -246,6 +246,10 @@ export function MediaSection({
 
         {(isVideo || isAudio) && (
           <>
+            {/* Held above unity: this control tops out at 100%, so committing
+                from it would silently cap a boosted clip and drop up to 12 dB
+                that now genuinely renders. The dB fader that can represent
+                these levels replaces this control outright. */}
             <div className="grid min-w-0 gap-1.5">
               <span className={LABEL}>Volume</span>
               <SliderControl
@@ -254,6 +258,7 @@ export function MediaSection({
                 min={0}
                 max={100}
                 step={1}
+                disabled={volume > 1}
                 displayValue={`${volumePercent}%`}
                 formatDisplayValue={(next) => `${Math.round(next)}%`}
                 onCommit={(next) => {