From e6b9ee20e50611ba5fe8aa98aceed5163b4319f5 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 22:44:41 -0700
Subject: [PATCH 01/10] feat(studio-server): share loudness measurement with an
 absolute target and video support

normalize-audio moves its measure/plan code into @hyperframes/studio-server/loudness,
gains an absolute mode (--lufs, default -16, clamped at +12 dB and -1.5 dBTP) and
accepts <video> clips with sound. Adds the @hyperframes/core/audible-video subpath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../cli/src/commands/normalize-audio.test.ts  |  10 +
 packages/cli/src/commands/normalize-audio.ts  | 540 ++++--------------
 packages/core/package.json                    |  10 +
 packages/studio-server/package.json           |  10 +
 .../src/helpers/loudness.test.ts              | 118 ++++
 .../studio-server/src/helpers/loudness.ts     | 521 +++++++++++++++++
 packages/studio-server/tsup.config.ts         |   1 +
 7 files changed, 785 insertions(+), 425 deletions(-)
 create mode 100644 packages/studio-server/src/helpers/loudness.test.ts
 create mode 100644 packages/studio-server/src/helpers/loudness.ts

diff --git a/packages/cli/src/commands/normalize-audio.test.ts b/packages/cli/src/commands/normalize-audio.test.ts
index 87f1f6ce47..a9a93753b6 100644
--- a/packages/cli/src/commands/normalize-audio.test.ts
+++ b/packages/cli/src/commands/normalize-audio.test.ts
@@ -175,3 +175,13 @@ describe("updateAudioVolume", () => {
     );
   });
 });
+
+describe("normalize-audio on video clips", () => {
+  it("finds a video with sound as a target and skips a muted one", () => {
+    const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true"></video><video id="b-roll" src="b.mp4" muted></video><audio id="music" src="m.mp3"></audio>`;
+    expect(audioTags(html).map((tag) => tag.id)).toEqual(["a-roll", "music"]);
+    expect(updateAudioVolume(html, "a-roll", 0.5)).toContain(
+      `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-volume="0.5"></video>`,
+    );
+  });
+});
diff --git a/packages/cli/src/commands/normalize-audio.ts b/packages/cli/src/commands/normalize-audio.ts
index e85528ca6f..f31ef96336 100644
--- a/packages/cli/src/commands/normalize-audio.ts
+++ b/packages/cli/src/commands/normalize-audio.ts
@@ -1,410 +1,36 @@
-import { execFile } from "node:child_process";
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
-import { promisify } from "node:util";
-import { formatAudioGain, MAX_AUDIO_GAIN_DB } from "@hyperframes/core/audio-gain";
-import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+import { relative } from "node:path";
+import {
+  absoluteLoudnessPlan,
+  audioNormalizationPlan,
+  audioTags,
+  DEFAULT_TARGET_LUFS,
+  measureAudio,
+  requiredFfmpeg,
+  resolveLocalAudioPath,
+  updateAudioVolume,
+  type AbsoluteLoudnessPlan,
+  type AudioNormalizationPlan,
+  type AudioTag,
+  type LoudnessLimit,
+} from "@hyperframes/studio-server/loudness";
 import { defineCommand } from "citty";
 import { c } from "../ui/colors.js";
 import { resolveProject } from "../utils/project.js";
 import { failCommand } from "../utils/commandResult.js";
 import type { Example } from "./_examples.js";
 
-const execFileAsync = promisify(execFile);
-const FFMPEG_TIMEOUT_MS = 120_000;
-const DEFAULT_TOLERANCE_LU = 0.5;
-
-interface AttributeSpan {
-  value: string;
-  valueStart: number;
-  valueEnd: number;
-}
-
-interface TagRange {
-  start: number;
-  end: number;
-}
-
-interface ParsedStartTag extends TagRange {
-  closing: boolean;
-  name: string;
-}
-
-interface ScanResult {
-  cursor: number;
-  audioRange: TagRange | null;
-}
-
-export interface AudioTag {
-  id: string;
-  src: string;
-  volume: number;
-  mediaStart: number;
-  duration: number | null;
-  start: number;
-  end: number;
-  volumeAttribute: AttributeSpan | null;
-}
-
-export interface LoudnessMeasurement {
-  integratedLufs: number;
-  truePeakDbfs: number;
-}
-
-export interface NormalizationTrack extends LoudnessMeasurement {
-  id: string;
-  volume: number;
-}
-
-export interface AudioNormalizationPlan {
-  referenceId: string;
-  targetId: string;
-  referenceLufs: number;
-  targetLufs: number;
-  previousVolume: number;
-  volume: number;
-  gainDb: number;
-  changeDb: number;
-  projectedLufs: number;
-  projectedTruePeakDbfs: number;
-}
-
-function authoredNumber(
-  raw: string | undefined,
-  fallback: number,
-  attribute: string,
-  id: string,
-  strictlyPositive = false,
-): number {
-  if (raw === undefined) return fallback;
-  const value = Number(raw);
-  if (!Number.isFinite(value) || (strictlyPositive ? value <= 0 : value < 0)) {
-    throw new Error(`Audio #${id} has an invalid ${attribute}: ${raw}`);
-  }
-  return value;
-}
-
-function attributeFromMatch(
-  match: RegExpMatchArray,
-  absoluteOffset: number,
-): [string, AttributeSpan] | null {
-  if (match.index === undefined) return null;
-  const name = match[1]?.toLowerCase();
-  const value = matchedAttributeValue(match);
-  if (!name || value === undefined) return null;
-
-  const whole = match[0];
-  const localValueStart = attributeValueStart(whole);
-  const valueStart = absoluteOffset + match.index + localValueStart;
-  return [name, { value, valueStart, valueEnd: valueStart + value.length }];
-}
-
-function matchedAttributeValue(match: RegExpMatchArray): string | undefined {
-  return match[2] ?? match[3] ?? match[4];
-}
-
-function attributeValueStart(attribute: string): number {
-  let cursor = attribute.indexOf("=") + 1;
-  while (/\s/.test(attribute[cursor] ?? "")) cursor += 1;
-  const quote = attribute[cursor];
-  return quote === '"' || quote === "'" ? cursor + 1 : cursor;
-}
-
-function attributesInTag(html: string, from: number, to: number): Map<string, AttributeSpan> {
-  const tag = html.slice(from, to);
-  const nameEnd = tag.search(/\s|\/?\s*>/);
-  const attributes = new Map<string, AttributeSpan>();
-  if (nameEnd < 0) return attributes;
-
-  const pattern = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
-  for (const match of tag.slice(nameEnd).matchAll(pattern)) {
-    const attribute = attributeFromMatch(match, from + nameEnd);
-    if (attribute) attributes.set(...attribute);
-  }
-  return attributes;
-}
-
-function startTagEnd(html: string, start: number): number {
-  let quote = "";
-  let end = start + 1;
-  for (; end < html.length; end += 1) {
-    const char = html[end];
-    if (quote) {
-      if (char === quote) quote = "";
-    } else if (char === '"' || char === "'") {
-      quote = char;
-    } else if (char === ">") {
-      return end + 1;
-    }
-  }
-  throw new Error("Unterminated HTML start tag");
-}
-
-function commentEnd(html: string, start: number): number {
-  const end = html.indexOf("-->", start + 4);
-  if (end < 0) throw new Error("Unterminated HTML comment");
-  return end + 3;
-}
-
-function parsedStartTag(html: string, start: number): ParsedStartTag | null {
-  const match = html.slice(start).match(/^<\s*(\/?)\s*([a-z][a-z\d:-]*)\b/i);
-  if (!match) return null;
-  return {
-    start,
-    end: startTagEnd(html, start),
-    closing: match[1] === "/",
-    name: match[2]?.toLowerCase() ?? "",
-  };
-}
-
-function rawTextElementEnd(html: string, lower: string, tag: ParsedStartTag): number | null {
-  if (tag.closing || (tag.name !== "script" && tag.name !== "style")) return null;
-  const closeStart = lower.indexOf(`</${tag.name}`, tag.end);
-  if (closeStart < 0) throw new Error(`Unterminated <${tag.name}> element`);
-  return startTagEnd(html, closeStart);
-}
-
-function scanMarkup(html: string, lower: string, start: number): ScanResult {
-  if (html.startsWith("<!--", start)) {
-    return { cursor: commentEnd(html, start), audioRange: null };
-  }
-  const tag = parsedStartTag(html, start);
-  if (!tag) {
-    const marker = html[start + 1];
-    const cursor = marker === "!" || marker === "?" ? startTagEnd(html, start) : start + 1;
-    return { cursor, audioRange: null };
-  }
-  const rawTextEnd = rawTextElementEnd(html, lower, tag);
-  if (rawTextEnd !== null) return { cursor: rawTextEnd, audioRange: null };
-  const audioRange = !tag.closing && tag.name === "audio" ? { start, end: tag.end } : null;
-  return { cursor: tag.end, audioRange };
-}
-
-function audioTagRanges(html: string): TagRange[] {
-  const lower = html.toLowerCase();
-  const ranges: TagRange[] = [];
-  let cursor = 0;
-  while (cursor < html.length) {
-    const start = html.indexOf("<", cursor);
-    if (start < 0) break;
-    const scanned = scanMarkup(html, lower, start);
-    if (scanned.audioRange) ranges.push(scanned.audioRange);
-    cursor = scanned.cursor;
-  }
-  return ranges;
-}
-
-function trimmedAttribute(attributes: Map<string, AttributeSpan>, name: string): string {
-  return attributes.get(name)?.value.trim() ?? "";
-}
-
-/**
- * How much of the source the composition actually plays.
- *
- * `data-duration` is the explicit trim; absent, `data-end` still bounds the
- * clip's timeline window, and the parser, the runtime and the render mixer all
- * honour it. Measuring the whole file for a `data-end`-trimmed clip reads a
- * loudness the composition never plays — and `--write` then "corrects" an
- * already-matched clip by tens of dB.
- */
-function authoredDuration(attributes: Map<string, AttributeSpan>, id: string): number | null {
-  const raw = attributes.get("data-duration")?.value;
-  if (raw !== undefined) return authoredNumber(raw, 0, "data-duration", id, true);
-
-  const rawEnd = attributes.get("data-end")?.value;
-  if (rawEnd === undefined) return null;
-  const end = authoredNumber(rawEnd, 0, "data-end", id, true);
-  const start = authoredNumber(attributes.get("data-start")?.value, 0, "data-start", id);
-  return end > start ? end - start : null;
-}
-
-function requiredAudioIdentity(attributes: Map<string, AttributeSpan>) {
-  const id = trimmedAttribute(attributes, "id");
-  const src = trimmedAttribute(attributes, "src");
-  if (!id) throw new Error("Every normalized <audio> element needs an id");
-  if (!src) throw new Error(`Audio #${id} has no src`);
-  return { id, src };
-}
-
-function audioTagFromRange(html: string, range: TagRange): AudioTag {
-  const attributes = attributesInTag(html, range.start, range.end);
-  const { id, src } = requiredAudioIdentity(attributes);
-  const volumeAttribute = attributes.get("data-volume") ?? null;
-  return {
-    id,
-    src,
-    volume: authoredNumber(volumeAttribute?.value, 1, "data-volume", id),
-    mediaStart: authoredNumber(
-      attributes.get("data-media-start")?.value,
-      0,
-      "data-media-start",
-      id,
-    ),
-    duration: authoredDuration(attributes, id),
-    start: range.start,
-    end: range.end,
-    volumeAttribute,
-  };
-}
-
-/** Read the authored audio clips without reserializing the composition. */
-export function audioTags(html: string): AudioTag[] {
-  const seen = new Set<string>();
-  const tags: AudioTag[] = [];
-  for (const range of audioTagRanges(html)) {
-    const tag = audioTagFromRange(html, range);
-    if (seen.has(tag.id)) throw new Error(`Duplicate audio id "${tag.id}"`);
-    seen.add(tag.id);
-    tags.push(tag);
-  }
-  return tags;
-}
-
-/** Resolve only a file contained by the project. Remote and traversal sources are not measured. */
-export function resolveLocalAudioPath(projectDir: string, src: string): string {
-  const withoutSuffix = src.split(/[?#]/, 1)[0] ?? "";
-  let decoded = "";
-  try {
-    decoded = decodeURIComponent(withoutSuffix);
-  } catch {
-    throw new Error(`Audio source must be a local project file: ${src}`);
-  }
-  if (!decoded || isAbsolute(decoded) || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(decoded)) {
-    throw new Error(`Audio source must be a local project file: ${src}`);
-  }
-  const root = resolve(projectDir);
-  const file = resolve(root, decoded);
-  const rel = relative(root, file);
-  if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
-    throw new Error(`Audio source must be a local project file: ${src}`);
-  }
-  return file;
-}
-
-/** Parse FFmpeg's final EBU R128 summary, not its per-window log lines. */
-export function parseEbur128Summary(stderr: string): LoudnessMeasurement {
-  const summaryAt = stderr.lastIndexOf("Summary:");
-  const summary = summaryAt >= 0 ? stderr.slice(summaryAt) : "";
-  const integrated = summary.match(/\bI:\s*(-?\d+(?:\.\d+)?)\s+LUFS\b/);
-  const peak = summary.match(/\bPeak:\s*(-?\d+(?:\.\d+)?)\s+dBFS\b/);
-  const integratedLufs = Number(integrated?.[1]);
-  const truePeakDbfs = Number(peak?.[1]);
-  if (!Number.isFinite(integratedLufs)) {
-    throw new Error("FFmpeg did not report integrated loudness for this audio stream");
-  }
-  if (!Number.isFinite(truePeakDbfs)) {
-    throw new Error("FFmpeg did not report true peak for this audio stream");
-  }
-  return { integratedLufs, truePeakDbfs };
-}
-
-function gainDb(volume: number): number {
-  return volume > 0 ? 20 * Math.log10(volume) : Number.NEGATIVE_INFINITY;
-}
-
-/** Calculate the target's absolute authored gain while keeping the reference unchanged. */
-export function audioNormalizationPlan(
-  referenceTrack: NormalizationTrack,
-  targetTrack: NormalizationTrack,
-): AudioNormalizationPlan {
-  if (!(referenceTrack.volume > 0) || !(targetTrack.volume > 0)) {
-    throw new Error("Muted audio cannot be used for loudness matching");
-  }
-  const referenceLufs = referenceTrack.integratedLufs + gainDb(referenceTrack.volume);
-  const targetLufs = targetTrack.integratedLufs + gainDb(targetTrack.volume);
-  const wantedGainDb = referenceLufs - targetTrack.integratedLufs;
-  if (wantedGainDb > MAX_AUDIO_GAIN_DB + 1e-9) {
-    throw new Error(
-      `Matching #${targetTrack.id} needs ${wantedGainDb.toFixed(1)} dB, beyond the +${MAX_AUDIO_GAIN_DB} dB authoring ceiling. ` +
-        `A gap this large belongs in the source file, not the mixer — mixer gain raises the noise floor with the signal. ` +
-        `Normalize ${targetTrack.id}'s asset offline (e.g. ffmpeg loudnorm), or lower #${referenceTrack.id} instead.`,
-    );
-  }
-  const volume = 10 ** (wantedGainDb / 20);
-  const projectedTruePeakDbfs = targetTrack.truePeakDbfs + wantedGainDb;
-  if (projectedTruePeakDbfs > 0) {
-    throw new Error(
-      `Matching #${targetTrack.id} would clip at +${projectedTruePeakDbfs.toFixed(1)} dBFS; limit or preprocess the source first`,
-    );
-  }
-  return {
-    referenceId: referenceTrack.id,
-    targetId: targetTrack.id,
-    referenceLufs,
-    targetLufs,
-    previousVolume: targetTrack.volume,
-    volume,
-    gainDb: wantedGainDb,
-    changeDb: wantedGainDb - gainDb(targetTrack.volume),
-    projectedLufs: targetTrack.integratedLufs + wantedGainDb,
-    projectedTruePeakDbfs,
-  };
-}
-
-/** Patch one authored attribute in place so scripts/styles/comments remain byte-stable. */
-export function updateAudioVolume(html: string, id: string, volume: number): string {
-  const tag = audioTags(html).find((candidate) => candidate.id === id);
-  if (!tag) throw new Error(`Audio #${id} was not found`);
-  const value = formatAudioGain(volume);
-  if (tag.volumeAttribute) {
-    return (
-      html.slice(0, tag.volumeAttribute.valueStart) +
-      value +
-      html.slice(tag.volumeAttribute.valueEnd)
-    );
-  }
-
-  let insertion = tag.end - 1;
-  let tail = insertion - 1;
-  while (tail >= tag.start && /\s/.test(html[tail] ?? "")) tail -= 1;
-  if (html[tail] === "/") {
-    insertion = tail;
-    while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
-  } else {
-    while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
-  }
-  return html.slice(0, insertion) + ` data-volume="${value}"` + html.slice(insertion);
-}
-
-/**
- * FFmpeg arguments that measure exactly the window the composition plays.
- *
- * `-ss` / `-t` go BEFORE `-i`, as INPUT options. After `-i` they bound the
- * output, and with `-f null` there is no real output to bound: ffmpeg keeps
- * feeding the filter graph past the limit, so ebur128 integrates audio the clip
- * never plays. Measured on a 12 s file whose first 4 s — the played window — is
- * -61.8 LUFS: output-side `-t 4` reported -33.8 LUFS, input-side reports -61.8,
- * the same as physically cutting the file first.
- */
-export function loudnessMeasureArgs(
-  file: string,
-  tag: Pick<AudioTag, "mediaStart" | "duration">,
-): string[] {
-  const args = ["-hide_banner", "-nostats"];
-  if (tag.mediaStart > 0) args.push("-ss", String(tag.mediaStart));
-  if (tag.duration !== null && tag.duration > 0) args.push("-t", String(tag.duration));
-  args.push("-i", file, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-");
-  return args;
-}
+export {
+  audioNormalizationPlan,
+  audioTags,
+  loudnessMeasureArgs,
+  parseEbur128Summary,
+  resolveLocalAudioPath,
+  updateAudioVolume,
+} from "@hyperframes/studio-server/loudness";
 
-async function measureAudio(
-  ffmpegPath: string,
-  file: string,
-  tag: Pick<AudioTag, "mediaStart" | "duration">,
-): Promise<LoudnessMeasurement> {
-  const result = await execFileAsync(ffmpegPath, loudnessMeasureArgs(file, tag), {
-    encoding: "utf8",
-    maxBuffer: 16 * 1024 * 1024,
-    timeout: FFMPEG_TIMEOUT_MS,
-  });
-  return parseEbur128Summary(result.stderr);
-}
+const DEFAULT_TOLERANCE_LU = 0.5;
 
-/**
- * Under `--json` every outcome has to be one parseable document, including the
- * failures — this command exists to be driven by an agent, and an agent doing
- * `JSON.parse(stdout)` on a bare error line just throws.
- */
 function fail(message: string, json: boolean, cause?: unknown): never {
   if (json) console.log(JSON.stringify({ ok: false, error: message }, null, 2));
   else console.error(c.error(message));
@@ -420,13 +46,14 @@ function byId(tags: readonly AudioTag[], rawId: string, role: string): AudioTag
 
 interface NormalizeAudioOptions {
   dir?: string;
-  reference: string;
+  reference?: string;
   target: string;
+  lufs: string;
   tolerance: string;
   write: boolean;
 }
 
-interface NormalizeAudioResult extends AudioNormalizationPlan {
+interface WriteOutcome {
   ok: true;
   wrote: boolean;
   withinTolerance: boolean;
@@ -434,6 +61,8 @@ interface NormalizeAudioResult extends AudioNormalizationPlan {
   indexPath: string;
 }
 
+type NormalizeAudioResult = WriteOutcome & ModePlan;
+
 function selectedTags(html: string, referenceId: string, targetId: string) {
   const tags = audioTags(html);
   const referenceTag = byId(tags, referenceId, "Reference");
@@ -444,12 +73,6 @@ function selectedTags(html: string, referenceId: string, targetId: string) {
   return { referenceTag, targetTag };
 }
 
-function requiredFfmpeg(): string {
-  const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
-  if (!ffmpegPath) throw new Error("FFmpeg is required to measure integrated loudness");
-  return ffmpegPath;
-}
-
 function existingAudioFile(projectDir: string, tag: AudioTag): string {
   const file = resolveLocalAudioPath(projectDir, tag.src);
   if (!existsSync(file)) {
@@ -476,7 +99,6 @@ async function measuredPlan(
   );
 }
 
-/** Never leave a half-written composition behind if the process dies mid-write. */
 function writeAtomically(path: string, contents: string): void {
   const temporary = `${path}.hf-normalize-${process.pid}.tmp`;
   writeFileSync(temporary, contents);
@@ -491,22 +113,61 @@ function parsedTolerance(raw: string): number {
   return tolerance;
 }
 
+function parsedLufs(raw: string): number {
+  const lufs = Number(raw);
+  if (!Number.isFinite(lufs) || lufs >= 0) throw new Error("--lufs must be a negative number");
+  return lufs;
+}
+
+async function measuredAbsolutePlan(
+  projectDir: string,
+  targetTag: AudioTag,
+  targetLufs: number,
+): Promise<AbsoluteLoudnessPlan> {
+  const measurement = await measureAudio(
+    requiredFfmpeg(),
+    existingAudioFile(projectDir, targetTag),
+    targetTag,
+  );
+  return absoluteLoudnessPlan(
+    { id: targetTag.id, volume: targetTag.volume, ...measurement },
+    targetLufs,
+  );
+}
+
+type ModePlan =
+  | (AudioNormalizationPlan & { mode: "reference" })
+  | (AbsoluteLoudnessPlan & { mode: "absolute" });
+
+async function plannedNormalization(
+  projectDir: string,
+  html: string,
+  options: NormalizeAudioOptions,
+  tolerance: number,
+): Promise<{ targetTag: AudioTag; withinTolerance: boolean; plan: ModePlan }> {
+  if (options.reference === undefined) {
+    const targetTag = byId(audioTags(html), options.target, "Target");
+    const plan = await measuredAbsolutePlan(projectDir, targetTag, parsedLufs(options.lufs));
+    const withinTolerance = Math.abs(plan.changeDb) <= tolerance;
+    return { targetTag, withinTolerance, plan: { mode: "absolute", ...plan } };
+  }
+  const { referenceTag, targetTag } = selectedTags(html, options.reference, options.target);
+  const plan = await measuredPlan(projectDir, referenceTag, targetTag);
+  const withinTolerance = Math.abs(plan.referenceLufs - plan.targetLufs) <= tolerance;
+  return { targetTag, withinTolerance, plan: { mode: "reference", ...plan } };
+}
+
 async function normalizeAudio(options: NormalizeAudioOptions): Promise<NormalizeAudioResult> {
   const project = resolveProject(options.dir);
   const html = readFileSync(project.indexPath, "utf8");
-  const { referenceTag, targetTag } = selectedTags(html, options.reference, options.target);
-  // Before the measurement, not after: each EBU R128 pass is bounded at 120s, so
-  // validating this afterwards made a typo'd --tolerance cost two of them before
-  // failing on an argument that was wrong the whole time.
   const tolerance = parsedTolerance(options.tolerance);
-  const plan = await measuredPlan(project.dir, referenceTag, targetTag);
-  const withinTolerance = Math.abs(plan.referenceLufs - plan.targetLufs) <= tolerance;
+  const { targetTag, withinTolerance, plan } = await plannedNormalization(
+    project.dir,
+    html,
+    options,
+    tolerance,
+  );
   const wrote = options.write && !withinTolerance;
-  // Re-read: two EBU R128 passes ran since the snapshot above, each bounded
-  // only by FFMPEG_TIMEOUT_MS, and the skill tells agents to keep Studio open
-  // on the project while normalizing. Serializing the stale snapshot would
-  // silently revert every edit made during that window. The write is one
-  // attribute patch, so re-applying it to the current file is the same edit.
   if (wrote) {
     writeAtomically(
       project.indexPath,
@@ -516,11 +177,28 @@ async function normalizeAudio(options: NormalizeAudioOptions): Promise<Normalize
   return { ok: true, wrote, withinTolerance, tolerance, indexPath: project.indexPath, ...plan };
 }
 
-function printHumanResult(result: NormalizeAudioResult): void {
+const LIMIT_TEXT: Record<LoudnessLimit, string> = {
+  "gain-ceiling": "stopped at the +12 dB authoring ceiling",
+  "true-peak": "stopped short of -1.5 dBTP",
+};
+
+function printMeasuredLine(result: NormalizeAudioResult): void {
+  if (result.mode === "reference") {
+    console.log(
+      `${c.bold(`#${result.referenceId}`)} ${result.referenceLufs.toFixed(1)} LUFS → ` +
+        `${c.bold(`#${result.targetId}`)} ${result.targetLufs.toFixed(1)} LUFS`,
+    );
+    return;
+  }
+  const limit = result.limitedBy ? ` (${LIMIT_TEXT[result.limitedBy]})` : "";
   console.log(
-    `${c.bold(`#${result.referenceId}`)} ${result.referenceLufs.toFixed(1)} LUFS → ` +
-      `${c.bold(`#${result.targetId}`)} ${result.targetLufs.toFixed(1)} LUFS`,
+    `${c.bold(`#${result.targetId}`)} ${result.sourceLufs.toFixed(1)} LUFS → ` +
+      `${result.projectedLufs.toFixed(1)} LUFS, target ${result.targetLufs.toFixed(1)}${limit}`,
   );
+}
+
+function printHumanResult(result: NormalizeAudioResult): void {
+  printMeasuredLine(result);
   if (result.withinTolerance) {
     console.log(
       c.success(`Already matched within ${result.tolerance.toFixed(1)} LU; no change needed.`),
@@ -540,6 +218,10 @@ function printHumanResult(result: NormalizeAudioResult): void {
 }
 
 export const examples: Example[] = [
+  [
+    "Bring one clip (audio or a video with sound) to -16 LUFS",
+    "hyperframes normalize-audio --target voiceover --write",
+  ],
   [
     "Measure two authored clips and preview the matching gain",
     "hyperframes normalize-audio --reference target-audio --target user-audio",
@@ -553,20 +235,27 @@ export const examples: Example[] = [
 export default defineCommand({
   meta: {
     name: "normalize-audio",
-    description: "Match one local audio clip to another using integrated LUFS",
+    description:
+      "Normalize a clip with sound to an absolute LUFS target, or match it to another clip",
   },
   args: {
     dir: { type: "positional", description: "Project directory", required: false },
     reference: {
       type: "string",
-      description: "Audio element id whose effective loudness should be preserved",
-      required: true,
+      description:
+        "Audio or video element id whose effective loudness should be preserved (omit to use --lufs)",
+      required: false,
     },
     target: {
       type: "string",
-      description: "Audio element id whose data-volume should be matched",
+      description: "Audio or video element id whose data-volume should be set",
       required: true,
     },
+    lufs: {
+      type: "string",
+      description: `Absolute integrated loudness target without --reference (default ${DEFAULT_TARGET_LUFS})`,
+      default: String(DEFAULT_TARGET_LUFS),
+    },
     write: {
       type: "boolean",
       description: "Persist the measured target gain into index.html",
@@ -585,6 +274,7 @@ export default defineCommand({
         dir: args.dir,
         reference: args.reference,
         target: args.target,
+        lufs: args.lufs,
         tolerance: args.tolerance,
         write: args.write,
       });
diff --git a/packages/core/package.json b/packages/core/package.json
index 836954ea54..f9f03d31c9 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -244,6 +244,12 @@
       "import": "./src/audioGain.ts",
       "types": "./src/audioGain.ts"
     },
+    "./audible-video": {
+      "bun": "./src/audibleVideo.ts",
+      "node": "./dist/audibleVideo.js",
+      "import": "./src/audibleVideo.ts",
+      "types": "./src/audibleVideo.ts"
+    },
     "./audio-fade": {
       "bun": "./src/audioFade.ts",
       "node": "./dist/audioFade.js",
@@ -628,6 +634,10 @@
         "import": "./dist/audioGain.js",
         "types": "./dist/audioGain.d.ts"
       },
+      "./audible-video": {
+        "import": "./dist/audibleVideo.js",
+        "types": "./dist/audibleVideo.d.ts"
+      },
       "./audio-fade": {
         "import": "./dist/audioFade.js",
         "types": "./dist/audioFade.d.ts"
diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json
index d406ce4af2..462b2d3a53 100644
--- a/packages/studio-server/package.json
+++ b/packages/studio-server/package.json
@@ -81,6 +81,12 @@
       "import": "./src/helpers/mediaCodecMap.ts",
       "types": "./src/helpers/mediaCodecMap.ts"
     },
+    "./loudness": {
+      "bun": "./src/helpers/loudness.ts",
+      "node": "./dist/helpers/loudness.js",
+      "import": "./src/helpers/loudness.ts",
+      "types": "./src/helpers/loudness.ts"
+    },
     "./proxy-transcoder": {
       "bun": "./src/helpers/proxyTranscoder.ts",
       "node": "./dist/helpers/proxyTranscoder.js",
@@ -142,6 +148,10 @@
         "import": "./dist/helpers/mediaCodecMap.js",
         "types": "./dist/helpers/mediaCodecMap.d.ts"
       },
+      "./loudness": {
+        "import": "./dist/helpers/loudness.js",
+        "types": "./dist/helpers/loudness.d.ts"
+      },
       "./proxy-transcoder": {
         "import": "./dist/helpers/proxyTranscoder.js",
         "types": "./dist/helpers/proxyTranscoder.d.ts"
diff --git a/packages/studio-server/src/helpers/loudness.test.ts b/packages/studio-server/src/helpers/loudness.test.ts
new file mode 100644
index 0000000000..026508d29c
--- /dev/null
+++ b/packages/studio-server/src/helpers/loudness.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  absoluteLoudnessPlan,
+  audioTags,
+  loudnessMeasureArgs,
+  updateAudioVolume,
+} from "./loudness.js";
+
+const track = (integratedLufs: number, truePeakDbfs: number, volume = 1) => ({
+  id: "vo",
+  volume,
+  integratedLufs,
+  truePeakDbfs,
+});
+
+describe("audioTags with video", () => {
+  it("includes a video with sound as a normalizable clip", () => {
+    const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-duration="4"></video>`;
+    expect(audioTags(html)).toEqual([
+      expect.objectContaining({ tag: "video", id: "a-roll", src: "talk.mp4", duration: 4 }),
+    ]);
+  });
+
+  it("includes an unmuted video that does not declare data-has-audio", () => {
+    expect(audioTags(`<video id="v" src="v.mp4"></video>`).map((t) => t.id)).toEqual(["v"]);
+  });
+
+  it.each([
+    `<video id="b-roll" src="b.mp4" muted></video>`,
+    `<video id="b-roll" src="b.mp4" muted data-start="0"></video>`,
+    `<video id="b-roll" src="b.mp4" muted=""></video>`,
+    `<video id="b-roll" src="b.mp4" data-has-audio="false"></video>`,
+    `<video id="b-roll" src="b.mp4" data-has-audio=""></video>`,
+  ])("skips a silent video without throwing: %s", (html) => {
+    expect(audioTags(html)).toEqual([]);
+  });
+
+  it("does not read muted out of another attribute's value", () => {
+    const html = `<video id="v" src="v.mp4" title="be muted later"></video>`;
+    expect(audioTags(html).map((t) => t.id)).toEqual(["v"]);
+  });
+
+  it("skips a video it could not address instead of failing the run", () => {
+    const html = `<video src="v.mp4"></video><audio id="music" src="m.mp3"></audio>`;
+    expect(audioTags(html).map((t) => t.id)).toEqual(["music"]);
+  });
+
+  it("still requires an id on every audio element", () => {
+    expect(() => audioTags(`<audio src="m.mp3"></audio>`)).toThrow(/needs an id/);
+  });
+
+  it("rejects an id shared by an audio and a video", () => {
+    const html = `<audio id="x" src="a.mp3"></audio><video id="x" src="v.mp4"></video>`;
+    expect(() => audioTags(html)).toThrow(/duplicate/i);
+  });
+
+  it("writes data-volume on the video tag", () => {
+    const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true"></video>`;
+    expect(updateAudioVolume(html, "a-roll", 2)).toBe(
+      `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-volume="2"></video>`,
+    );
+  });
+});
+
+describe("loudnessMeasureArgs with a playback rate", () => {
+  it("measures the source span a sped-up clip actually plays", () => {
+    const args = loudnessMeasureArgs("clip.mp4", { mediaStart: 0, duration: 4, playbackRate: 2 });
+    expect(args.slice(args.indexOf("-t"), args.indexOf("-t") + 2)).toEqual(["-t", "8"]);
+  });
+
+  it("reads data-playback-rate from the tag", () => {
+    const html = `<audio id="a" src="a.wav" data-duration="3" data-playback-rate="0.5"></audio>`;
+    expect(audioTags(html)[0]).toEqual(expect.objectContaining({ playbackRate: 0.5 }));
+  });
+});
+
+describe("absoluteLoudnessPlan", () => {
+  it("targets -16 LUFS by default", () => {
+    const plan = absoluteLoudnessPlan(track(-19.2, -8));
+    expect(plan.gainDb).toBeCloseTo(3.2, 6);
+    expect(plan.projectedLufs).toBeCloseTo(-16, 6);
+    expect(plan.volume).toBeCloseTo(10 ** (3.2 / 20), 6);
+    expect(plan.limitedBy).toBeNull();
+  });
+
+  it("reports the change relative to the clip's current gain", () => {
+    const plan = absoluteLoudnessPlan(track(-16, -6, 2));
+    expect(plan.gainDb).toBeCloseTo(0, 6);
+    expect(plan.changeDb).toBeCloseTo(-6.0206, 3);
+  });
+
+  it("stops at the +12 dB ceiling and says so", () => {
+    const plan = absoluteLoudnessPlan(track(-40, -30));
+    expect(plan.gainDb).toBeCloseTo(12, 6);
+    expect(plan.limitedBy).toBe("gain-ceiling");
+  });
+
+  it("stops short of -1.5 dBTP and says so", () => {
+    const plan = absoluteLoudnessPlan(track(-22, -3));
+    expect(plan.gainDb).toBeCloseTo(1.5, 6);
+    expect(plan.projectedTruePeakDbfs).toBeCloseTo(-1.5, 6);
+    expect(plan.limitedBy).toBe("true-peak");
+  });
+
+  it("attenuates a clip that is too loud", () => {
+    const plan = absoluteLoudnessPlan(track(-10, 0));
+    expect(plan.gainDb).toBeCloseTo(-6, 6);
+    expect(plan.limitedBy).toBeNull();
+  });
+
+  it("refuses a silent window", () => {
+    expect(() => absoluteLoudnessPlan(track(-70, -90))).toThrow(/silent/);
+  });
+
+  it("treats a muted clip's change as the applied gain", () => {
+    expect(absoluteLoudnessPlan(track(-19, -10, 0)).changeDb).toBeCloseTo(3, 6);
+  });
+});
diff --git a/packages/studio-server/src/helpers/loudness.ts b/packages/studio-server/src/helpers/loudness.ts
new file mode 100644
index 0000000000..1217913923
--- /dev/null
+++ b/packages/studio-server/src/helpers/loudness.ts
@@ -0,0 +1,521 @@
+import { execFile } from "node:child_process";
+import { isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isAudibleVideoElement } from "@hyperframes/core/audible-video";
+import { formatAudioGain, MAX_AUDIO_GAIN_DB } from "@hyperframes/core/audio-gain";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+
+const execFileAsync = promisify(execFile);
+
+const FFMPEG_TIMEOUT_MS = 120_000;
+
+interface AttributeSpan {
+  value: string;
+  valueStart: number;
+  valueEnd: number;
+}
+
+interface TagRange {
+  start: number;
+  end: number;
+}
+
+type MediaTagName = "audio" | "video";
+
+interface MediaTagRange extends TagRange {
+  name: MediaTagName;
+}
+
+interface ParsedStartTag extends TagRange {
+  closing: boolean;
+  name: string;
+}
+
+interface ScanResult {
+  cursor: number;
+  mediaRange: MediaTagRange | null;
+}
+
+export interface AudioTag {
+  tag: MediaTagName;
+  id: string;
+  src: string;
+  volume: number;
+  mediaStart: number;
+  duration: number | null;
+  playbackRate: number;
+  start: number;
+  end: number;
+  volumeAttribute: AttributeSpan | null;
+}
+
+export interface LoudnessMeasurement {
+  integratedLufs: number;
+  truePeakDbfs: number;
+}
+
+export interface NormalizationTrack extends LoudnessMeasurement {
+  id: string;
+  volume: number;
+}
+
+export interface AudioNormalizationPlan {
+  referenceId: string;
+  targetId: string;
+  referenceLufs: number;
+  targetLufs: number;
+  previousVolume: number;
+  volume: number;
+  gainDb: number;
+  changeDb: number;
+  projectedLufs: number;
+  projectedTruePeakDbfs: number;
+}
+
+function authoredNumber(
+  raw: string | undefined,
+  fallback: number,
+  attribute: string,
+  id: string,
+  strictlyPositive = false,
+): number {
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || (strictlyPositive ? value <= 0 : value < 0)) {
+    throw new Error(`Audio #${id} has an invalid ${attribute}: ${raw}`);
+  }
+  return value;
+}
+
+function attributeFromMatch(
+  match: RegExpMatchArray,
+  absoluteOffset: number,
+): [string, AttributeSpan] | null {
+  if (match.index === undefined) return null;
+  const name = match[1]?.toLowerCase();
+  const value = matchedAttributeValue(match);
+  if (!name || value === undefined) return null;
+
+  const whole = match[0];
+  const localValueStart = attributeValueStart(whole);
+  const valueStart = absoluteOffset + match.index + localValueStart;
+  return [name, { value, valueStart, valueEnd: valueStart + value.length }];
+}
+
+function matchedAttributeValue(match: RegExpMatchArray): string | undefined {
+  return match[2] ?? match[3] ?? match[4];
+}
+
+function attributeValueStart(attribute: string): number {
+  let cursor = attribute.indexOf("=") + 1;
+  while (/\s/.test(attribute[cursor] ?? "")) cursor += 1;
+  const quote = attribute[cursor];
+  return quote === '"' || quote === "'" ? cursor + 1 : cursor;
+}
+
+function attributesInTag(html: string, from: number, to: number): Map<string, AttributeSpan> {
+  const tag = html.slice(from, to);
+  const nameEnd = tag.search(/\s|\/?\s*>/);
+  const attributes = new Map<string, AttributeSpan>();
+  if (nameEnd < 0) return attributes;
+
+  const pattern = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+  for (const match of tag.slice(nameEnd).matchAll(pattern)) {
+    const attribute = attributeFromMatch(match, from + nameEnd);
+    if (attribute) attributes.set(...attribute);
+  }
+  return attributes;
+}
+
+function startTagEnd(html: string, start: number): number {
+  let quote = "";
+  let end = start + 1;
+  for (; end < html.length; end += 1) {
+    const char = html[end];
+    if (quote) {
+      if (char === quote) quote = "";
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === ">") {
+      return end + 1;
+    }
+  }
+  throw new Error("Unterminated HTML start tag");
+}
+
+function commentEnd(html: string, start: number): number {
+  const end = html.indexOf("-->", start + 4);
+  if (end < 0) throw new Error("Unterminated HTML comment");
+  return end + 3;
+}
+
+function parsedStartTag(html: string, start: number): ParsedStartTag | null {
+  const match = html.slice(start).match(/^<\s*(\/?)\s*([a-z][a-z\d:-]*)\b/i);
+  if (!match) return null;
+  return {
+    start,
+    end: startTagEnd(html, start),
+    closing: match[1] === "/",
+    name: match[2]?.toLowerCase() ?? "",
+  };
+}
+
+function rawTextElementEnd(html: string, lower: string, tag: ParsedStartTag): number | null {
+  if (tag.closing || (tag.name !== "script" && tag.name !== "style")) return null;
+  const closeStart = lower.indexOf(`</${tag.name}`, tag.end);
+  if (closeStart < 0) throw new Error(`Unterminated <${tag.name}> element`);
+  return startTagEnd(html, closeStart);
+}
+
+function scanMarkup(html: string, lower: string, start: number): ScanResult {
+  if (html.startsWith("<!--", start)) {
+    return { cursor: commentEnd(html, start), mediaRange: null };
+  }
+  const tag = parsedStartTag(html, start);
+  if (!tag) {
+    const marker = html[start + 1];
+    const cursor = marker === "!" || marker === "?" ? startTagEnd(html, start) : start + 1;
+    return { cursor, mediaRange: null };
+  }
+  const rawTextEnd = rawTextElementEnd(html, lower, tag);
+  if (rawTextEnd !== null) return { cursor: rawTextEnd, mediaRange: null };
+  return { cursor: tag.end, mediaRange: mediaRangeOf(tag) };
+}
+
+function mediaRangeOf(tag: ParsedStartTag): MediaTagRange | null {
+  if (tag.closing) return null;
+  if (tag.name === "audio" || tag.name === "video") {
+    return { start: tag.start, end: tag.end, name: tag.name };
+  }
+  return null;
+}
+
+function mediaTagRanges(html: string): MediaTagRange[] {
+  const lower = html.toLowerCase();
+  const ranges: MediaTagRange[] = [];
+  let cursor = 0;
+  while (cursor < html.length) {
+    const start = html.indexOf("<", cursor);
+    if (start < 0) break;
+    const scanned = scanMarkup(html, lower, start);
+    if (scanned.mediaRange) ranges.push(scanned.mediaRange);
+    cursor = scanned.cursor;
+  }
+  return ranges;
+}
+
+function trimmedAttribute(attributes: Map<string, AttributeSpan>, name: string): string {
+  return attributes.get(name)?.value.trim() ?? "";
+}
+
+/**
+ * How much of the source the composition actually plays.
+ *
+ * `data-duration` is the explicit trim; absent, `data-end` still bounds the
+ * clip's timeline window, and the parser, the runtime and the render mixer all
+ * honour it. Measuring the whole file for a `data-end`-trimmed clip reads a
+ * loudness the composition never plays — and `--write` then "corrects" an
+ * already-matched clip by tens of dB.
+ */
+function authoredDuration(attributes: Map<string, AttributeSpan>, id: string): number | null {
+  const raw = attributes.get("data-duration")?.value;
+  if (raw !== undefined) return authoredNumber(raw, 0, "data-duration", id, true);
+
+  const rawEnd = attributes.get("data-end")?.value;
+  if (rawEnd === undefined) return null;
+  const end = authoredNumber(rawEnd, 0, "data-end", id, true);
+  const start = authoredNumber(attributes.get("data-start")?.value, 0, "data-start", id);
+  return end > start ? end - start : null;
+}
+
+function requiredAudioIdentity(attributes: Map<string, AttributeSpan>) {
+  const id = trimmedAttribute(attributes, "id");
+  const src = trimmedAttribute(attributes, "src");
+  if (!id) throw new Error("Every normalized <audio> element needs an id");
+  if (!src) throw new Error(`Audio #${id} has no src`);
+  return { id, src };
+}
+
+/** Boolean attributes carry no `=`, so the value map cannot see them. */
+function hasBareAttribute(html: string, range: TagRange, name: string): boolean {
+  const unquoted = html.slice(range.start, range.end).replace(/"[^"]*"|'[^']*'/g, '""');
+  return new RegExp(`\\s${name}(?=[\\s/>=])`, "i").test(unquoted);
+}
+
+function isAudibleVideoTag(
+  html: string,
+  range: TagRange,
+  attributes: Map<string, AttributeSpan>,
+): boolean {
+  return isAudibleVideoElement({
+    tagName: "video",
+    hasAttribute: (name) => attributes.has(name) || hasBareAttribute(html, range, name),
+    getAttribute: (name) => attributes.get(name)?.value ?? null,
+  });
+}
+
+/**
+ * A video joins the scan only when it carries sound and can be addressed.
+ * Silent footage, and a video no command could name, are skipped rather than
+ * failing a run that is about some other clip.
+ */
+function inScopeVideo(
+  html: string,
+  range: TagRange,
+  attributes: Map<string, AttributeSpan>,
+): boolean {
+  return (
+    isAudibleVideoTag(html, range, attributes) &&
+    trimmedAttribute(attributes, "id") !== "" &&
+    trimmedAttribute(attributes, "src") !== ""
+  );
+}
+
+function mediaTagFromRange(html: string, range: MediaTagRange): AudioTag | null {
+  const attributes = attributesInTag(html, range.start, range.end);
+  if (range.name === "video" && !inScopeVideo(html, range, attributes)) return null;
+  const { id, src } = requiredAudioIdentity(attributes);
+  const volumeAttribute = attributes.get("data-volume") ?? null;
+  return {
+    tag: range.name,
+    id,
+    src,
+    volume: authoredNumber(volumeAttribute?.value, 1, "data-volume", id),
+    mediaStart: authoredNumber(
+      attributes.get("data-media-start")?.value,
+      0,
+      "data-media-start",
+      id,
+    ),
+    duration: authoredDuration(attributes, id),
+    playbackRate: authoredNumber(
+      attributes.get("data-playback-rate")?.value,
+      1,
+      "data-playback-rate",
+      id,
+      true,
+    ),
+    start: range.start,
+    end: range.end,
+    volumeAttribute,
+  };
+}
+
+/** Read the authored clips with sound — `<audio>` and audible `<video>` — without reserializing. */
+export function audioTags(html: string): AudioTag[] {
+  const seen = new Set<string>();
+  const tags: AudioTag[] = [];
+  for (const range of mediaTagRanges(html)) {
+    const tag = mediaTagFromRange(html, range);
+    if (!tag) continue;
+    if (seen.has(tag.id)) throw new Error(`Duplicate audio id "${tag.id}"`);
+    seen.add(tag.id);
+    tags.push(tag);
+  }
+  return tags;
+}
+
+/** Resolve only a file contained by the project. Remote and traversal sources are not measured. */
+export function resolveLocalAudioPath(projectDir: string, src: string): string {
+  const withoutSuffix = src.split(/[?#]/, 1)[0] ?? "";
+  let decoded = "";
+  try {
+    decoded = decodeURIComponent(withoutSuffix);
+  } catch {
+    throw new Error(`Audio source must be a local project file: ${src}`);
+  }
+  if (!decoded || isAbsolute(decoded) || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(decoded)) {
+    throw new Error(`Audio source must be a local project file: ${src}`);
+  }
+  const root = resolve(projectDir);
+  const file = resolve(root, decoded);
+  const rel = relative(root, file);
+  if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+    throw new Error(`Audio source must be a local project file: ${src}`);
+  }
+  return file;
+}
+
+/** Parse FFmpeg's final EBU R128 summary, not its per-window log lines. */
+export function parseEbur128Summary(stderr: string): LoudnessMeasurement {
+  const summaryAt = stderr.lastIndexOf("Summary:");
+  const summary = summaryAt >= 0 ? stderr.slice(summaryAt) : "";
+  const integrated = summary.match(/\bI:\s*(-?\d+(?:\.\d+)?)\s+LUFS\b/);
+  const peak = summary.match(/\bPeak:\s*(-?\d+(?:\.\d+)?)\s+dBFS\b/);
+  const integratedLufs = Number(integrated?.[1]);
+  const truePeakDbfs = Number(peak?.[1]);
+  if (!Number.isFinite(integratedLufs)) {
+    throw new Error("FFmpeg did not report integrated loudness for this audio stream");
+  }
+  if (!Number.isFinite(truePeakDbfs)) {
+    throw new Error("FFmpeg did not report true peak for this audio stream");
+  }
+  return { integratedLufs, truePeakDbfs };
+}
+
+export function gainDb(volume: number): number {
+  return volume > 0 ? 20 * Math.log10(volume) : Number.NEGATIVE_INFINITY;
+}
+
+/** Calculate the target's absolute authored gain while keeping the reference unchanged. */
+export function audioNormalizationPlan(
+  referenceTrack: NormalizationTrack,
+  targetTrack: NormalizationTrack,
+): AudioNormalizationPlan {
+  if (!(referenceTrack.volume > 0) || !(targetTrack.volume > 0)) {
+    throw new Error("Muted audio cannot be used for loudness matching");
+  }
+  const referenceLufs = referenceTrack.integratedLufs + gainDb(referenceTrack.volume);
+  const targetLufs = targetTrack.integratedLufs + gainDb(targetTrack.volume);
+  const wantedGainDb = referenceLufs - targetTrack.integratedLufs;
+  if (wantedGainDb > MAX_AUDIO_GAIN_DB + 1e-9) {
+    throw new Error(
+      `Matching #${targetTrack.id} needs ${wantedGainDb.toFixed(1)} dB, beyond the +${MAX_AUDIO_GAIN_DB} dB authoring ceiling. ` +
+        `A gap this large belongs in the source file, not the mixer — mixer gain raises the noise floor with the signal. ` +
+        `Normalize ${targetTrack.id}'s asset offline (e.g. ffmpeg loudnorm), or lower #${referenceTrack.id} instead.`,
+    );
+  }
+  const volume = 10 ** (wantedGainDb / 20);
+  const projectedTruePeakDbfs = targetTrack.truePeakDbfs + wantedGainDb;
+  if (projectedTruePeakDbfs > 0) {
+    throw new Error(
+      `Matching #${targetTrack.id} would clip at +${projectedTruePeakDbfs.toFixed(1)} dBFS; limit or preprocess the source first`,
+    );
+  }
+  return {
+    referenceId: referenceTrack.id,
+    targetId: targetTrack.id,
+    referenceLufs,
+    targetLufs,
+    previousVolume: targetTrack.volume,
+    volume,
+    gainDb: wantedGainDb,
+    changeDb: wantedGainDb - gainDb(targetTrack.volume),
+    projectedLufs: targetTrack.integratedLufs + wantedGainDb,
+    projectedTruePeakDbfs,
+  };
+}
+
+/** Patch one authored attribute in place so scripts/styles/comments remain byte-stable. */
+export function updateAudioVolume(html: string, id: string, volume: number): string {
+  const tag = audioTags(html).find((candidate) => candidate.id === id);
+  if (!tag) throw new Error(`Audio #${id} was not found`);
+  const value = formatAudioGain(volume);
+  if (tag.volumeAttribute) {
+    return (
+      html.slice(0, tag.volumeAttribute.valueStart) +
+      value +
+      html.slice(tag.volumeAttribute.valueEnd)
+    );
+  }
+
+  let insertion = tag.end - 1;
+  let tail = insertion - 1;
+  while (tail >= tag.start && /\s/.test(html[tail] ?? "")) tail -= 1;
+  if (html[tail] === "/") {
+    insertion = tail;
+    while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
+  } else {
+    while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
+  }
+  return html.slice(0, insertion) + ` data-volume="${value}"` + html.slice(insertion);
+}
+
+/**
+ * FFmpeg arguments that measure exactly the window the composition plays.
+ *
+ * `-ss` / `-t` go BEFORE `-i`, as INPUT options. After `-i` they bound the
+ * output, and with `-f null` there is no real output to bound: ffmpeg keeps
+ * feeding the filter graph past the limit, so ebur128 integrates audio the clip
+ * never plays. Measured on a 12 s file whose first 4 s — the played window — is
+ * -61.8 LUFS: output-side `-t 4` reported -33.8 LUFS, input-side reports -61.8,
+ * the same as physically cutting the file first.
+ */
+export function loudnessMeasureArgs(file: string, tag: MeasuredWindow): string[] {
+  const args = ["-hide_banner", "-nostats"];
+  if (tag.mediaStart > 0) args.push("-ss", String(tag.mediaStart));
+  const sourceSpan = tag.duration === null ? null : tag.duration * (tag.playbackRate ?? 1);
+  if (sourceSpan !== null && sourceSpan > 0) args.push("-t", String(sourceSpan));
+  args.push("-i", file, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-");
+  return args;
+}
+
+export type MeasuredWindow = Pick<AudioTag, "mediaStart" | "duration"> &
+  Partial<Pick<AudioTag, "playbackRate">>;
+
+export async function measureAudio(
+  ffmpegPath: string,
+  file: string,
+  tag: MeasuredWindow,
+): Promise<LoudnessMeasurement> {
+  const result = await execFileAsync(ffmpegPath, loudnessMeasureArgs(file, tag), {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: FFMPEG_TIMEOUT_MS,
+  });
+  return parseEbur128Summary(result.stderr);
+}
+
+export function requiredFfmpeg(): string {
+  const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
+  if (!ffmpegPath) throw new Error("FFmpeg is required to measure integrated loudness");
+  return ffmpegPath;
+}
+
+export const DEFAULT_TARGET_LUFS = -16;
+export const NORMALIZE_TRUE_PEAK_CEILING_DBFS = -1.5;
+/** EBU R128's absolute gate: a window this quiet has no integrated loudness to match. */
+const SILENCE_LUFS = -70;
+
+export type LoudnessLimit = "gain-ceiling" | "true-peak";
+
+export interface AbsoluteLoudnessPlan {
+  targetId: string;
+  targetLufs: number;
+  sourceLufs: number;
+  previousVolume: number;
+  volume: number;
+  gainDb: number;
+  changeDb: number;
+  projectedLufs: number;
+  projectedTruePeakDbfs: number;
+  limitedBy: LoudnessLimit | null;
+}
+
+/**
+ * The authored gain that brings one clip's played window to an absolute
+ * loudness. Unlike reference matching it never refuses: past the +12 dB
+ * authoring ceiling or the true-peak ceiling it applies the most that fits and
+ * names which limit stopped it.
+ */
+export function absoluteLoudnessPlan(
+  track: NormalizationTrack,
+  targetLufs: number = DEFAULT_TARGET_LUFS,
+): AbsoluteLoudnessPlan {
+  if (track.integratedLufs <= SILENCE_LUFS) {
+    throw new Error(`#${track.id} is silent in the played window; there is nothing to normalize`);
+  }
+  const wantedGainDb = targetLufs - track.integratedLufs;
+  const peakRoomDb = NORMALIZE_TRUE_PEAK_CEILING_DBFS - track.truePeakDbfs;
+  const limits: Array<[LoudnessLimit | null, number]> = [
+    [null, wantedGainDb],
+    ["gain-ceiling", MAX_AUDIO_GAIN_DB],
+    ["true-peak", peakRoomDb],
+  ];
+  const [limitedBy, appliedGainDb] = limits.reduce((lowest, candidate) =>
+    candidate[1] < lowest[1] - 1e-9 ? candidate : lowest,
+  );
+  const previousGainDb = track.volume > 0 ? gainDb(track.volume) : 0;
+  return {
+    targetId: track.id,
+    targetLufs,
+    sourceLufs: track.integratedLufs,
+    previousVolume: track.volume,
+    volume: 10 ** (appliedGainDb / 20),
+    gainDb: appliedGainDb,
+    changeDb: appliedGainDb - previousGainDb,
+    projectedLufs: track.integratedLufs + appliedGainDb,
+    projectedTruePeakDbfs: track.truePeakDbfs + appliedGainDb,
+    limitedBy,
+  };
+}
diff --git a/packages/studio-server/tsup.config.ts b/packages/studio-server/tsup.config.ts
index 19148acb89..1f828c16cc 100644
--- a/packages/studio-server/tsup.config.ts
+++ b/packages/studio-server/tsup.config.ts
@@ -6,6 +6,7 @@ export default defineConfig({
     "helpers/screenshotClip": "src/helpers/screenshotClip.ts",
     "helpers/mediaCodecMap": "src/helpers/mediaCodecMap.ts",
     "helpers/proxyTranscoder": "src/helpers/proxyTranscoder.ts",
+    "helpers/loudness": "src/helpers/loudness.ts",
     "helpers/mediaProxyPreview": "src/helpers/mediaProxyPreview.ts",
     "helpers/manualEditsRenderScript": "src/helpers/manualEditsRenderScript.ts",
     "helpers/studioMotionRenderScript": "src/helpers/studioMotionRenderScript.ts",

From fbfe64240404eece3493b4b264507f833c5d9d90 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 22:48:54 -0700
Subject: [PATCH 02/10] feat(studio-server): add a measure-only loudness
 normalize endpoint

POST /projects/:id/loudness/normalize measures a clip's played window (audio or
video) and answers the -16 LUFS data-volume plan; Studio writes the attribute.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/studio-server/src/createStudioApi.ts |   2 +
 .../studio-server/src/routes/loudness.test.ts |  90 ++++++++++++++
 packages/studio-server/src/routes/loudness.ts | 111 ++++++++++++++++++
 3 files changed, 203 insertions(+)
 create mode 100644 packages/studio-server/src/routes/loudness.test.ts
 create mode 100644 packages/studio-server/src/routes/loudness.ts

diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts
index 36932d0480..d39576c446 100644
--- a/packages/studio-server/src/createStudioApi.ts
+++ b/packages/studio-server/src/createStudioApi.ts
@@ -9,6 +9,7 @@ import { registerImageThumbnailRoutes } from "./routes/imageThumbnail.js";
 import { registerThumbnailRoutes } from "./routes/thumbnail.js";
 import { registerWaveformRoutes } from "./routes/waveform.js";
 import { registerFreezeFrameRoutes } from "./routes/freezeFrame.js";
+import { registerLoudnessRoutes } from "./routes/loudness.js";
 import { registerFontRoutes } from "./routes/fonts.js";
 import { registerRegistryRoutes } from "./routes/registry.js";
 import { registerSelectionRoutes } from "./routes/selection.js";
@@ -63,6 +64,7 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono {
   registerMediaRoutes(api, adapter);
   registerWaveformRoutes(api, adapter);
   registerFreezeFrameRoutes(api, adapter);
+  registerLoudnessRoutes(api, adapter);
   registerFontRoutes(api);
   registerRegistryRoutes(api, adapter);
   registerGlobalAssetRoutes(api);
diff --git a/packages/studio-server/src/routes/loudness.test.ts b/packages/studio-server/src/routes/loudness.test.ts
new file mode 100644
index 0000000000..c089c22975
--- /dev/null
+++ b/packages/studio-server/src/routes/loudness.test.ts
@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Hono } from "hono";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerLoudnessRoutes, type MeasureLoudness } from "./loudness";
+import type { StudioApiAdapter } from "../types";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function setup(measure: MeasureLoudness) {
+  const projectDir = mkdtempSync(join(tmpdir(), "hf-loudness-route-"));
+  dirs.push(projectDir);
+  writeFileSync(join(projectDir, "talk.mp4"), "video");
+  const adapter: StudioApiAdapter = {
+    listProjects: () => [],
+    resolveProject: async (id: string) => ({ id, dir: projectDir }),
+    bundle: async () => null,
+    lint: async () => ({ findings: [] }),
+    runtimeUrl: "/api/runtime.js",
+    rendersDir: () => "/tmp/renders",
+    startRender: () => ({ id: "j", status: "rendering", progress: 0, outputPath: "/tmp/o.mp4" }),
+  };
+  const app = new Hono();
+  registerLoudnessRoutes(app, adapter, measure);
+  const post = (body: unknown) =>
+    app.request("/projects/p/loudness/normalize", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  return { post, projectDir };
+}
+
+describe("POST /projects/:id/loudness/normalize", () => {
+  it("measures the played source window of a video and answers the -16 LUFS gain", async () => {
+    const measure = vi.fn<MeasureLoudness>(async () => ({
+      integratedLufs: -19.2,
+      truePeakDbfs: -8,
+    }));
+    const { post, projectDir } = setup(measure);
+    const res = await post({
+      id: "a-roll",
+      src: "talk.mp4",
+      mediaStart: 1,
+      duration: 4,
+      playbackRate: 2,
+      volume: 1,
+    });
+    expect(res.status).toBe(200);
+    const { plan } = await res.json();
+    expect(plan.gainDb).toBeCloseTo(3.2, 6);
+    expect(plan.targetId).toBe("a-roll");
+    expect(measure).toHaveBeenCalledWith(join(projectDir, "talk.mp4"), {
+      mediaStart: 1,
+      duration: 4,
+      playbackRate: 2,
+    });
+  });
+
+  it("names the limit when the gain had to stop short", async () => {
+    const { post } = setup(async () => ({ integratedLufs: -22, truePeakDbfs: -3 }));
+    const { plan } = await (await post({ src: "talk.mp4" })).json();
+    expect(plan.limitedBy).toBe("true-peak");
+  });
+
+  it("refuses a source outside the project", async () => {
+    const { post } = setup(async () => ({ integratedLufs: -16, truePeakDbfs: -3 }));
+    expect((await post({ src: "../etc/passwd" })).status).toBe(400);
+    expect((await post({ src: "https://x.test/a.mp3" })).status).toBe(400);
+  });
+
+  it("rejects malformed numbers", async () => {
+    const { post } = setup(async () => ({ integratedLufs: -16, truePeakDbfs: -3 }));
+    const res = await post({ src: "talk.mp4", playbackRate: 0 });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/playbackRate/);
+  });
+
+  it("404s a missing file and 422s a silent one", async () => {
+    const { post } = setup(async () => ({ integratedLufs: -70, truePeakDbfs: -90 }));
+    expect((await post({ src: "missing.wav" })).status).toBe(404);
+    const silent = await post({ src: "talk.mp4" });
+    expect(silent.status).toBe(422);
+    expect((await silent.json()).error).toMatch(/silent/);
+  });
+});
diff --git a/packages/studio-server/src/routes/loudness.ts b/packages/studio-server/src/routes/loudness.ts
new file mode 100644
index 0000000000..cd49910c68
--- /dev/null
+++ b/packages/studio-server/src/routes/loudness.ts
@@ -0,0 +1,111 @@
+import { existsSync } from "node:fs";
+import type { Hono } from "hono";
+import type { StudioApiAdapter } from "../types.js";
+import {
+  absoluteLoudnessPlan,
+  DEFAULT_TARGET_LUFS,
+  measureAudio,
+  requiredFfmpeg,
+  resolveLocalAudioPath,
+  type LoudnessMeasurement,
+  type MeasuredWindow,
+} from "../helpers/loudness.js";
+
+export type MeasureLoudness = (
+  file: string,
+  window: MeasuredWindow,
+) => Promise<LoudnessMeasurement>;
+
+interface NormalizeRequest {
+  id: string;
+  src: string;
+  window: MeasuredWindow;
+  volume: number;
+  targetLufs: number;
+}
+
+const defaultMeasure: MeasureLoudness = (file, window) =>
+  measureAudio(requiredFfmpeg(), file, window);
+
+class InvalidField extends Error {}
+
+function numberField(
+  body: Record<string, unknown>,
+  name: string,
+  fallback: number,
+  valid: (value: number) => boolean,
+): number {
+  const raw = body[name];
+  if (raw === undefined || raw === null) return fallback;
+  if (typeof raw === "number" && Number.isFinite(raw) && valid(raw)) return raw;
+  throw new InvalidField(`${name} is out of range`);
+}
+
+function readNormalizeRequest(body: Record<string, unknown>): NormalizeRequest {
+  const src = typeof body.src === "string" ? body.src.trim() : "";
+  if (!src) throw new InvalidField("src is required");
+  const duration = numberField(body, "duration", 0, (v) => v > 0);
+  return {
+    id: typeof body.id === "string" && body.id ? body.id : src,
+    src,
+    window: {
+      mediaStart: numberField(body, "mediaStart", 0, (v) => v >= 0),
+      duration: duration > 0 ? duration : null,
+      playbackRate: numberField(body, "playbackRate", 1, (v) => v > 0),
+    },
+    volume: numberField(body, "volume", 1, (v) => v >= 0),
+    targetLufs: numberField(body, "targetLufs", DEFAULT_TARGET_LUFS, (v) => v < 0),
+  };
+}
+
+function parseNormalizeRequest(body: Record<string, unknown>): NormalizeRequest | string {
+  try {
+    return readNormalizeRequest(body);
+  } catch (error) {
+    if (error instanceof InvalidField) return error.message;
+    throw error;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Measure one clip's played window and answer the `data-volume` that brings it
+ * to the target. Measure-only: Studio writes the attribute through its own
+ * edit path so the change is one undo step like any other.
+ */
+export function registerLoudnessRoutes(
+  api: Hono,
+  adapter: StudioApiAdapter,
+  measure: MeasureLoudness = defaultMeasure,
+): void {
+  api.post("/projects/:id/loudness/normalize", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body: unknown = await c.req.json().catch(() => null);
+    if (!isRecord(body)) return c.json({ error: "invalid body" }, 400);
+    const request = parseNormalizeRequest(body);
+    if (typeof request === "string") return c.json({ error: request }, 400);
+
+    let file: string;
+    try {
+      file = resolveLocalAudioPath(project.dir, request.src);
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+    if (!existsSync(file)) return c.json({ error: "file not found" }, 404);
+
+    try {
+      const measurement = await measure(file, request.window);
+      const plan = absoluteLoudnessPlan(
+        { id: request.id, volume: request.volume, ...measurement },
+        request.targetLufs,
+      );
+      return c.json({ plan });
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : String(error) }, 422);
+    }
+  });
+}

From b88f1cf1519da9d48a635ccba49d7a28f1c7fc7f Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 23:04:35 -0700
Subject: [PATCH 03/10] chore: register the loudness and audible-video subpaths
 in their descriptors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/core/package-subpaths.json          |  6 ++++++
 packages/studio-server/package-subpaths.json |  6 ++++++
 packages/studio-server/package.json          | 20 ++++++++++----------
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index f2626dd280..40277e2cb9 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -230,6 +230,12 @@
       "types": "./dist/audioGain.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./audible-video": {
+      "source": "./src/audibleVideo.ts",
+      "runtime": "./dist/audibleVideo.js",
+      "types": "./dist/audibleVideo.d.ts",
+      "environments": ["browser",  "bun",  "node"]
+    },
     "./audio-fade": {
       "source": "./src/audioFade.ts",
       "runtime": "./dist/audioFade.js",
diff --git a/packages/studio-server/package-subpaths.json b/packages/studio-server/package-subpaths.json
index 1e6b5f1ada..eee07bc2fc 100644
--- a/packages/studio-server/package-subpaths.json
+++ b/packages/studio-server/package-subpaths.json
@@ -80,6 +80,12 @@
       "types": "./dist/helpers/proxyTranscoder.d.ts",
       "environments": ["bun", "node"]
     },
+    "./loudness": {
+      "source": "./src/helpers/loudness.ts",
+      "runtime": "./dist/helpers/loudness.js",
+      "types": "./dist/helpers/loudness.d.ts",
+      "environments": ["bun",  "node"]
+    },
     "./media-proxy-preview": {
       "source": "./src/helpers/mediaProxyPreview.ts",
       "runtime": "./dist/helpers/mediaProxyPreview.js",
diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json
index 462b2d3a53..203525c164 100644
--- a/packages/studio-server/package.json
+++ b/packages/studio-server/package.json
@@ -81,18 +81,18 @@
       "import": "./src/helpers/mediaCodecMap.ts",
       "types": "./src/helpers/mediaCodecMap.ts"
     },
-    "./loudness": {
-      "bun": "./src/helpers/loudness.ts",
-      "node": "./dist/helpers/loudness.js",
-      "import": "./src/helpers/loudness.ts",
-      "types": "./src/helpers/loudness.ts"
-    },
     "./proxy-transcoder": {
       "bun": "./src/helpers/proxyTranscoder.ts",
       "node": "./dist/helpers/proxyTranscoder.js",
       "import": "./src/helpers/proxyTranscoder.ts",
       "types": "./src/helpers/proxyTranscoder.ts"
     },
+    "./loudness": {
+      "bun": "./src/helpers/loudness.ts",
+      "node": "./dist/helpers/loudness.js",
+      "import": "./src/helpers/loudness.ts",
+      "types": "./src/helpers/loudness.ts"
+    },
     "./media-proxy-preview": {
       "bun": "./src/helpers/mediaProxyPreview.ts",
       "node": "./dist/helpers/mediaProxyPreview.js",
@@ -148,14 +148,14 @@
         "import": "./dist/helpers/mediaCodecMap.js",
         "types": "./dist/helpers/mediaCodecMap.d.ts"
       },
-      "./loudness": {
-        "import": "./dist/helpers/loudness.js",
-        "types": "./dist/helpers/loudness.d.ts"
-      },
       "./proxy-transcoder": {
         "import": "./dist/helpers/proxyTranscoder.js",
         "types": "./dist/helpers/proxyTranscoder.d.ts"
       },
+      "./loudness": {
+        "import": "./dist/helpers/loudness.js",
+        "types": "./dist/helpers/loudness.d.ts"
+      },
       "./media-proxy-preview": {
         "import": "./dist/helpers/mediaProxyPreview.js",
         "types": "./dist/helpers/mediaProxyPreview.d.ts"

From d3e48e362a823071d22d6733692f0ea034999601 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 00:37:14 -0700
Subject: [PATCH 04/10] style: format the loudness and audible-video subpath
 descriptors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/core/package-subpaths.json          | 2 +-
 packages/studio-server/package-subpaths.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index 40277e2cb9..7e434e8207 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -234,7 +234,7 @@
       "source": "./src/audibleVideo.ts",
       "runtime": "./dist/audibleVideo.js",
       "types": "./dist/audibleVideo.d.ts",
-      "environments": ["browser",  "bun",  "node"]
+      "environments": ["browser", "bun", "node"]
     },
     "./audio-fade": {
       "source": "./src/audioFade.ts",
diff --git a/packages/studio-server/package-subpaths.json b/packages/studio-server/package-subpaths.json
index eee07bc2fc..287eda0b10 100644
--- a/packages/studio-server/package-subpaths.json
+++ b/packages/studio-server/package-subpaths.json
@@ -84,7 +84,7 @@
       "source": "./src/helpers/loudness.ts",
       "runtime": "./dist/helpers/loudness.js",
       "types": "./dist/helpers/loudness.d.ts",
-      "environments": ["bun",  "node"]
+      "environments": ["bun", "node"]
     },
     "./media-proxy-preview": {
       "source": "./src/helpers/mediaProxyPreview.ts",

From 4b17169a5889c27916bbbb81bb619d02db381a0d Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 23:12:51 -0700
Subject: [PATCH 05/10] feat(studio): add Normalize loudness and Duck under
 voice to the clip menu

Normalize measures the clip on studio-server and writes data-volume as one undoable
edit; Duck toggles a carve against every overlapping voice (audio or video with
sound) at the default strength. Both live in clipMenuAudioItems with one hook-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/editor/carveOutput.ts      |  68 +++++++++
 .../src/components/editor/useFxCarve.ts       |  63 +-------
 .../studio/src/hooks/useRenderClipContent.ts  |  19 +--
 .../src/player/components/ClipContextMenu.tsx |   3 +
 .../components/clipMenuAudioItems.test.tsx    |  65 ++++++++
 .../player/components/clipMenuAudioItems.tsx  |  86 +++++++++++
 .../player/components/clipMenuDuck.test.ts    | 110 ++++++++++++++
 .../src/player/components/clipMenuDuck.ts     | 140 ++++++++++++++++++
 .../components/clipMenuNormalize.test.ts      |  95 ++++++++++++
 .../player/components/clipMenuNormalize.ts    |  74 +++++++++
 .../studio/src/utils/previewRelativePath.ts   |  19 +++
 11 files changed, 663 insertions(+), 79 deletions(-)
 create mode 100644 packages/studio/src/components/editor/carveOutput.ts
 create mode 100644 packages/studio/src/player/components/clipMenuAudioItems.test.tsx
 create mode 100644 packages/studio/src/player/components/clipMenuAudioItems.tsx
 create mode 100644 packages/studio/src/player/components/clipMenuDuck.test.ts
 create mode 100644 packages/studio/src/player/components/clipMenuDuck.ts
 create mode 100644 packages/studio/src/player/components/clipMenuNormalize.test.ts
 create mode 100644 packages/studio/src/player/components/clipMenuNormalize.ts
 create mode 100644 packages/studio/src/utils/previewRelativePath.ts

diff --git a/packages/studio/src/components/editor/carveOutput.ts b/packages/studio/src/components/editor/carveOutput.ts
new file mode 100644
index 0000000000..c893a99e2e
--- /dev/null
+++ b/packages/studio/src/components/editor/carveOutput.ts
@@ -0,0 +1,68 @@
+import {
+  HF_AUDIO_FX_ATTR,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { type HfAutomation } from "@hyperframes/core/audio-automation";
+import { isCarveVoiceElement } from "./useFxCarveGrouping.js";
+import { automationAttrValue, HF_AUDIO_AUTOMATION_ATTR } from "./propertyPanelAutomation";
+import type { CarveClip } from "./useFxCarveNodes.js";
+import { readClipClock } from "./clipAudioClock.js";
+
+/** Lanes belonging to nodes the carve generated, which a re-run replaces. */
+export function withoutCarveLanes(automation: HfAutomation, chain: HfAudioFxChain): HfAutomation {
+  const prefixes = chain.nodes.filter((n) => n.fromCarve && n.id).map((n) => `fx.${n.id}.`);
+  if (prefixes.length === 0) return automation;
+  return {
+    version: automation.version,
+    lanes: automation.lanes.filter((lane) => !prefixes.some((p) => lane.target.startsWith(p))),
+  };
+}
+
+/**
+ * Every named voice that is actually there with something to decode. A source
+ * naming a deleted track is skipped rather than failing the whole analysis.
+ *
+ * Read out to plain values here rather than carrying elements around: it is
+ * what lets the src and the start be non-null by construction downstream
+ * instead of by assertion.
+ */
+export function resolveCarveVoices(doc: Document, sources: readonly string[]): CarveClip[] {
+  const voices: CarveClip[] = [];
+  for (const id of sources) {
+    const el = doc.getElementById(id);
+    // By tag name, not `instanceof HTMLAudioElement`: these elements belong to
+    // the composition's iframe document, so the constructor they were made
+    // from is not this realm's and the instanceof is false for every one.
+    if (!isCarveVoiceElement(el)) continue;
+    const src = el.getAttribute("src");
+    if (!src) continue;
+    const clock = readClipClock((name) => el.getAttribute(name));
+    voices.push({ src, start: el.getAttribute("data-start"), clock });
+  }
+  return voices;
+}
+
+/**
+ * What the carve generated is only justified by the voices it was measured
+ * from: switched off, or left naming none — every source deleted, say — there
+ * is nothing those filters are making room for. Left behind they keep dipping
+ * the bed with nothing in the panel to explain them.
+ */
+export async function dropCarveOutput(
+  chain: HfAudioFxChain,
+  automation: HfAutomation,
+  onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
+): Promise<void> {
+  const carriedOver = withoutCarveLanes(automation, chain);
+  if (carriedOver.lanes.length !== automation.lanes.length) {
+    await onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(carriedOver) || null);
+  }
+  const kept = chain.nodes.filter((n) => !n.fromCarve);
+  if (kept.length !== chain.nodes.length) {
+    await onSetAttributeQuiet(
+      HF_AUDIO_FX_ATTR,
+      kept.length ? serializeAudioFxChain({ version: 1, nodes: kept }) : null,
+    );
+  }
+}
diff --git a/packages/studio/src/components/editor/useFxCarve.ts b/packages/studio/src/components/editor/useFxCarve.ts
index 44959f0826..8f5752850c 100644
--- a/packages/studio/src/components/editor/useFxCarve.ts
+++ b/packages/studio/src/components/editor/useFxCarve.ts
@@ -25,16 +25,15 @@ import {
   carverAgainst,
   collectCarveCandidates,
   CARVE_ABORTED,
-  isCarveVoiceElement,
   isPromiseLike,
   resolveNextCarveSettings,
 } from "./useFxCarveGrouping.js";
 import { type HfAutomation } from "@hyperframes/core/audio-automation";
-import { automationAttrValue, HF_AUDIO_AUTOMATION_ATTR } from "./propertyPanelAutomation";
 import { trackCarveChanged } from "./audioFxTelemetry.js";
 import type { DomEditSelection } from "./domEditingTypes";
 import { usePlayerStore } from "../../player";
-import { carveLanes, measureCarve, mintCarveNodes, type CarveClip } from "./useFxCarveNodes.js";
+import { dropCarveOutput, resolveCarveVoices, withoutCarveLanes } from "./carveOutput.js";
+import { carveLanes, measureCarve, mintCarveNodes } from "./useFxCarveNodes.js";
 import { readClipClock } from "./clipAudioClock.js";
 import { spanOf } from "./propertyPanelAudioFxGroupUtils.js";
 import type { AudioTrackOption } from "./propertyPanelFxCarveModule.js";
@@ -56,16 +55,6 @@ function carveAction(
   return "strength";
 }
 
-/** Lanes belonging to nodes the carve generated, which a re-run replaces. */
-function withoutCarveLanes(automation: HfAutomation, chain: HfAudioFxChain): HfAutomation {
-  const prefixes = chain.nodes.filter((n) => n.fromCarve && n.id).map((n) => `fx.${n.id}.`);
-  if (prefixes.length === 0) return automation;
-  return {
-    version: automation.version,
-    lanes: automation.lanes.filter((lane) => !prefixes.some((p) => lane.target.startsWith(p))),
-  };
-}
-
 /**
  * Every setting here describes the filters, so changing one rebuilds them.
  * There is no apply button: a carve naming a voice with no filters behind it
@@ -87,54 +76,6 @@ function carveNeedsReanalysis(
   );
 }
 
-/**
- * Every named voice that is actually there with something to decode. A source
- * naming a deleted track is skipped rather than failing the whole analysis.
- *
- * Read out to plain values here rather than carrying elements around: it is
- * what lets the src and the start be non-null by construction downstream
- * instead of by assertion.
- */
-function resolveCarveVoices(doc: Document, sources: readonly string[]): CarveClip[] {
-  const voices: CarveClip[] = [];
-  for (const id of sources) {
-    const el = doc.getElementById(id);
-    // By tag name, not `instanceof HTMLAudioElement`: these elements belong to
-    // the composition's iframe document, so the constructor they were made
-    // from is not this realm's and the instanceof is false for every one.
-    if (!isCarveVoiceElement(el)) continue;
-    const src = el.getAttribute("src");
-    if (!src) continue;
-    const clock = readClipClock((name) => el.getAttribute(name));
-    voices.push({ src, start: el.getAttribute("data-start"), clock });
-  }
-  return voices;
-}
-
-/**
- * What the carve generated is only justified by the voices it was measured
- * from: switched off, or left naming none — every source deleted, say — there
- * is nothing those filters are making room for. Left behind they keep dipping
- * the bed with nothing in the panel to explain them.
- */
-async function dropCarveOutput(
-  chain: HfAudioFxChain,
-  automation: HfAutomation,
-  onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
-): Promise<void> {
-  const carriedOver = withoutCarveLanes(automation, chain);
-  if (carriedOver.lanes.length !== automation.lanes.length) {
-    await onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(carriedOver) || null);
-  }
-  const kept = chain.nodes.filter((n) => !n.fromCarve);
-  if (kept.length !== chain.nodes.length) {
-    await onSetAttributeQuiet(
-      HF_AUDIO_FX_ATTR,
-      kept.length ? serializeAudioFxChain({ version: 1, nodes: kept }) : null,
-    );
-  }
-}
-
 export function useFxCarve(
   element: DomEditSelection,
   chain: HfAudioFxChain,
diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.ts
index aa6d7b7200..f0b4eac451 100644
--- a/packages/studio/src/hooks/useRenderClipContent.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.ts
@@ -1,4 +1,5 @@
 import { buildProjectApiPath } from "../utils/projectRouting";
+import { resolvePreviewRelative } from "../utils/previewRelativePath";
 import { useCallback, type ReactNode } from "react";
 import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
@@ -33,24 +34,6 @@ export function normalizeCompositionSrc(
   return compSrc;
 }
 
-/** Resolve a media src to its project-relative preview path, or null. */
-function resolvePreviewRelative(
-  src: string | undefined,
-  pid: string,
-  origin: string,
-): string | null {
-  if (!src) return null;
-  try {
-    const parsed = new URL(src, origin);
-    const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
-    return parsed.pathname.startsWith(base)
-      ? decodeURIComponent(parsed.pathname.slice(base.length))
-      : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * The trimmed source slice as start/end fractions (0–1) of the source, so the
  * waveform can window its peaks to the clip edges. Undefined when the source
diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsx
index 77f76a784d..723e3f455c 100644
--- a/packages/studio/src/player/components/ClipContextMenu.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.tsx
@@ -6,6 +6,7 @@ import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 import { useMenuKeyboardNav } from "./menuKeyboardNav";
 import type { TimelineClipMenuItem } from "./TimelineTypes";
 import { ClipMenuToolItems } from "./clipMenuToolItems";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
 
 interface ClipContextMenuProps {
   x: number;
@@ -155,6 +156,8 @@ export const ClipContextMenu = memo(function ClipContextMenu({
         </>
       )}
 
+      <ClipMenuAudioItems element={element} onClose={onClose} />
+
       {(onCopy || onPaste || onDuplicate) && (
         <>
           {onCopy && (
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
new file mode 100644
index 0000000000..c264bc3bfc
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import type { TimelineElement } from "../store/timelineElement";
+
+const showToast = vi.fn();
+const setQuiet = vi.fn(async () => {});
+const iframe = document.createElement("iframe");
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContextOptional: () => ({
+    projectId: "p1",
+    showToast,
+    previewIframeRef: { current: iframe },
+  }),
+}));
+vi.mock("../../contexts/TimelineEditContext", () => ({
+  useTimelineEditContextOptional: () => ({ onSetElementAttributeQuiet: setQuiet }),
+}));
+
+const harness = createHappyDomRootHarness();
+
+function render(element: TimelineElement) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  act(() =>
+    harness.mount(host).render(<ClipMenuAudioItems element={element} onClose={() => {}} />),
+  );
+  return host;
+}
+
+const base = { start: 0, duration: 4, track: 0 };
+
+describe("ClipMenuAudioItems", () => {
+  it("offers nothing on a muted video", () => {
+    const host = render({ ...base, id: "b", tag: "video", hasAudio: true, muted: true });
+    expect(host.textContent).toBe("");
+  });
+
+  it("normalizes a video with sound by writing data-volume as one edit", async () => {
+    const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => Response.json({ plan })),
+    );
+    const element: TimelineElement = {
+      ...base,
+      id: "a-roll",
+      tag: "video",
+      hasAudio: true,
+      src: "talk.mp4",
+    };
+    const host = render(element);
+    const button = [...host.querySelectorAll("button")].find((b) =>
+      b.textContent?.includes("Normalize loudness"),
+    );
+    await act(async () => button?.click());
+    await vi.waitFor(() => expect(setQuiet).toHaveBeenCalled());
+    expect(setQuiet).toHaveBeenCalledWith(element, "data-volume", "2", "Normalize loudness");
+    expect(showToast).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
+    vi.unstubAllGlobals();
+  });
+});
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsx
new file mode 100644
index 0000000000..a4c81075bf
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx
@@ -0,0 +1,86 @@
+import { formatAudioGain } from "@hyperframes/core/audio-gain";
+import type { TimelineElement } from "../store/timelineElement";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { clipHasSound, normalizeToastText, requestNormalizePlan } from "./clipMenuNormalize";
+import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
+
+const ITEM_CLASS =
+  "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer";
+
+const DUCK_TOAST: Record<DuckOutcome, string> = {
+  ducked: "Ducks under the voice. Normalize the voice first for the most even result.",
+  off: "No longer ducks under the voice.",
+  "no-voice": "No overlapping voice to duck under.",
+  aborted: "Could not group the voices to duck under.",
+};
+
+/** Sound group of the clip menu: Normalize loudness (one-shot) and Duck under voice (toggle). */
+export function ClipMenuAudioItems({
+  element,
+  onClose,
+}: {
+  element: TimelineElement;
+  onClose: () => void;
+}) {
+  const shell = useStudioShellContextOptional();
+  const { onSetElementAttributeQuiet, onGroupClips } = useTimelineEditContextOptional();
+  const doc = shell?.previewIframeRef.current?.contentDocument ?? null;
+  const bed = doc?.getElementById(element.domId ?? element.id) ?? null;
+  const ducked = bed ? readBedCarve(bed)?.enabled === true : false;
+  if (!clipHasSound(element) || !shell || !onSetElementAttributeQuiet) return null;
+  const { showToast, projectId } = shell;
+
+  const normalize = async () => {
+    onClose();
+    try {
+      const plan = await requestNormalizePlan(projectId, element);
+      await onSetElementAttributeQuiet(
+        element,
+        "data-volume",
+        formatAudioGain(plan.volume),
+        "Normalize loudness",
+      );
+      showToast(normalizeToastText(plan), "info");
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : String(error), "error");
+    }
+  };
+
+  const toggleDuck = async () => {
+    onClose();
+    if (!doc || !bed) return;
+    const outcome = await setDuckUnderVoice(
+      doc,
+      bed,
+      !ducked,
+      async (attr, value) => {
+        await onSetElementAttributeQuiet(element, attr, value, "Duck under voice");
+      },
+      onGroupClips ? (ids, groupId) => onGroupClips(ids, groupId, "Voice") : undefined,
+    ).catch((): DuckOutcome => "aborted");
+    showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
+  };
+
+  return (
+    <>
+      <button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>
+        <span>Normalize loudness</span>
+      </button>
+      {isDuckableBed(bed) && (
+        <button
+          type="button"
+          role="menuitemcheckbox"
+          aria-checked={ducked}
+          className={ITEM_CLASS}
+          onClick={() => void toggleDuck()}
+        >
+          <span>
+            <span className="inline-block w-3">{ducked ? "✓" : ""}</span>Duck under voice
+          </span>
+        </button>
+      )}
+      <div className="my-1 border-t border-neutral-700/60" />
+    </>
+  );
+}
diff --git a/packages/studio/src/player/components/clipMenuDuck.test.ts b/packages/studio/src/player/components/clipMenuDuck.test.ts
new file mode 100644
index 0000000000..0431eb439a
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuDuck.test.ts
@@ -0,0 +1,110 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { duckVoiceSources, isDuckableBed, readBedCarve, setDuckUnderVoice } from "./clipMenuDuck";
+
+function compose(body: string): Document {
+  const doc = document.implementation.createHTMLDocument("c");
+  doc.body.innerHTML = body;
+  return doc;
+}
+
+const BED = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>`;
+
+describe("duckVoiceSources", () => {
+  it("offers an overlapping video with sound and a voiceover, never the bed or silent video", () => {
+    const doc = compose(`${BED}
+      <video id="talk" src="talk.mp4" data-start="0" data-duration="6" data-has-audio="true"></video>
+      <video id="b-roll" src="b.mp4" data-start="0" data-duration="6" muted></video>
+      <audio id="voiceover" src="vo.wav" data-start="2" data-duration="3"></audio>
+      <audio id="late-vo" src="vo2.wav" data-start="20" data-duration="3"></audio>`);
+    const bed = doc.getElementById("music");
+    expect(bed && duckVoiceSources(doc, bed)).toEqual(["talk", "voiceover"]);
+  });
+});
+
+describe("isDuckableBed", () => {
+  it("allows a music clip and refuses a voice clip", () => {
+    const doc = compose(`${BED}<audio id="voiceover" src="voiceover.wav"></audio>`);
+    expect(isDuckableBed(doc.getElementById("music"))).toBe(true);
+    expect(isDuckableBed(doc.getElementById("voiceover"))).toBe(false);
+  });
+});
+
+describe("setDuckUnderVoice", () => {
+  it("writes a carve at core's default strength naming the one voice", async () => {
+    const doc = compose(
+      `${BED}<audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`,
+    );
+    const bed = doc.getElementById("music");
+    if (!bed) throw new Error("fixture");
+    const write = vi.fn(async (attr: string, value: string | null) => {
+      if (value === null) bed.removeAttribute(attr);
+      else bed.setAttribute(attr, value);
+    });
+    await expect(setDuckUnderVoice(doc, bed, true, write)).resolves.toBe("ducked");
+    expect(readBedCarve(bed)).toEqual({ enabled: true, sources: ["voiceover"], strength: 0.25 });
+  });
+
+  it("groups several voices first so the carve names one group", async () => {
+    const doc = compose(`${BED}
+      <audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>
+      <audio id="narration" src="n.wav" data-start="5" data-duration="3"></audio>`);
+    const bed = doc.getElementById("music");
+    if (!bed) throw new Error("fixture");
+    const write = vi.fn(async (attr: string, value: string | null) => {
+      if (value !== null) bed.setAttribute(attr, value);
+    });
+    const group = vi.fn(async () => {});
+    await setDuckUnderVoice(doc, bed, true, write, group);
+    expect(group).toHaveBeenCalledWith(["voiceover", "narration"], "voiceover-2");
+    expect(readBedCarve(bed)?.sources).toEqual(["voiceover-2"]);
+  });
+
+  it("reports no voice instead of writing an empty carve", async () => {
+    const doc = compose(BED);
+    const bed = doc.getElementById("music");
+    if (!bed) throw new Error("fixture");
+    const write = vi.fn(async () => {});
+    await expect(setDuckUnderVoice(doc, bed, true, write)).resolves.toBe("no-voice");
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it("turning it off disables the carve and drops the generated nodes and lanes", async () => {
+    const chain = {
+      version: 1,
+      nodes: [
+        { id: "c1", type: "peaking", enabled: true, fromCarve: true, params: {} },
+        { id: "eq", type: "highpass", enabled: true, params: {} },
+      ],
+    };
+    const automation = {
+      version: 1,
+      lanes: [
+        {
+          target: "fx.c1.gain",
+          points: [
+            { t: 0, v: 0 },
+            { t: 1, v: -3 },
+          ],
+        },
+      ],
+    };
+    const doc = compose(BED);
+    const bed = doc.getElementById("music");
+    if (!bed) throw new Error("fixture");
+    bed.setAttribute(
+      "data-fx-carve",
+      JSON.stringify({ enabled: true, sources: ["vo"], strength: 0.25 }),
+    );
+    bed.setAttribute("data-fx-chain", JSON.stringify(chain));
+    bed.setAttribute("data-automation", JSON.stringify(automation));
+    const writes: Array<[string, string | null]> = [];
+    await setDuckUnderVoice(doc, bed, false, async (attr, value) => {
+      writes.push([attr, value]);
+    });
+    const byAttr = new Map(writes);
+    expect(JSON.parse(byAttr.get("data-fx-carve") ?? "{}").enabled).toBe(false);
+    expect(byAttr.get("data-automation")).toBeNull();
+    expect(byAttr.get("data-fx-chain")).not.toContain("c1");
+  });
+});
diff --git a/packages/studio/src/player/components/clipMenuDuck.ts b/packages/studio/src/player/components/clipMenuDuck.ts
new file mode 100644
index 0000000000..168b060643
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuDuck.ts
@@ -0,0 +1,140 @@
+import {
+  HF_AUDIO_FX_ATTR,
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import {
+  clipsOverlap,
+  DEFAULT_CARVE,
+  HF_AUDIO_CARVE_ATTR,
+  normalizeCarveSettings,
+  type HfCarveSettings,
+} from "@hyperframes/core/audio-carve";
+import { resolveCarveSourceIds } from "@hyperframes/core/audio-groups";
+import { parseAutomation, type HfAutomation } from "@hyperframes/core/audio-automation";
+import {
+  carveBedRoles,
+  collectCarveCandidates,
+  CARVE_ABORTED,
+  isPromiseLike,
+  resolveNextCarveSettings,
+} from "../../components/editor/useFxCarveGrouping";
+import {
+  dropCarveOutput,
+  resolveCarveVoices,
+  withoutCarveLanes,
+} from "../../components/editor/carveOutput";
+import { carveLanes, measureCarve, mintCarveNodes } from "../../components/editor/useFxCarveNodes";
+import { readClipClock } from "../../components/editor/clipAudioClock";
+import {
+  automationAttrValue,
+  HF_AUDIO_AUTOMATION_ATTR,
+} from "../../components/editor/propertyPanelAutomation";
+import { spanOf } from "../../components/editor/propertyPanelAudioFxGroupUtils";
+
+export type WriteBedAttribute = (attr: string, value: string | null) => Promise<void>;
+export type GroupClips = (clipIds: readonly string[], groupId: string) => Promise<void>;
+
+export function readBedCarve(bed: Element): HfCarveSettings | null {
+  const raw = bed.getAttribute(HF_AUDIO_CARVE_ATTR);
+  if (!raw) return null;
+  try {
+    return normalizeCarveSettings(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function readChain(bed: Element): HfAudioFxChain {
+  const raw = bed.getAttribute(HF_AUDIO_FX_ATTR);
+  try {
+    return raw ? parseAudioFxChain(raw) : { version: 1, nodes: [] };
+  } catch {
+    return { version: 1, nodes: [] };
+  }
+}
+
+function readAutomation(bed: Element): HfAutomation {
+  const raw = bed.getAttribute(HF_AUDIO_AUTOMATION_ATTR);
+  try {
+    return raw ? parseAutomation(raw) : { version: 1, lanes: [] };
+  } catch {
+    return { version: 1, lanes: [] };
+  }
+}
+
+export function isDuckableBed(bed: Element | null): bed is Element {
+  return bed !== null && carveBedRoles(bed.id, bed).couldBeBed;
+}
+
+/** Every overlapping clip with speech, including a video's own sound; never the bed itself. */
+export function duckVoiceSources(doc: Document, bed: Element): string[] {
+  const bedSpan = spanOf(bed.getAttribute("data-start"), bed.getAttribute("data-duration"));
+  const others = Array.from(doc.querySelectorAll("audio[id], video[id]")).filter(
+    (el) => el.id !== bed.id,
+  );
+  const overlaps = (el: Element) =>
+    clipsOverlap(bedSpan, spanOf(el.getAttribute("data-start"), el.getAttribute("data-duration")));
+  return collectCarveCandidates(doc, others, overlaps, bed.id)
+    .filter((candidate) => candidate.kind === "voice" || candidate.kind === "unknown")
+    .map((candidate) => candidate.id);
+}
+
+async function writeMeasuredCarve(
+  doc: Document,
+  bed: Element,
+  settings: HfCarveSettings,
+  write: WriteBedAttribute,
+): Promise<void> {
+  const expanded = resolveCarveSourceIds(doc, settings.sources).filter((id) => id !== bed.id);
+  const voices = resolveCarveVoices(doc, expanded);
+  if (voices.length === 0) return;
+  const measured = await measureCarve(doc, voices, settings.strength, {
+    src: bed.getAttribute("src"),
+    start: bed.getAttribute("data-start"),
+    clock: readClipClock((name) => bed.getAttribute(name)),
+  });
+  if (!measured) return;
+  const chain = readChain(bed);
+  const automation = readAutomation(bed);
+  const { next, carvedNodes, duckNode } = mintCarveNodes(chain, measured.carved, measured.duck);
+  await write(HF_AUDIO_FX_ATTR, serializeAudioFxChain(next));
+  const lanes = carveLanes(carvedNodes, duckNode, measured.duck, measured.voiceMix, measured.bands);
+  const carriedOver = withoutCarveLanes(automation, chain);
+  const nextAutomation = { version: 1, lanes: [...carriedOver.lanes, ...lanes] };
+  await write(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(nextAutomation) || null);
+}
+
+export type DuckOutcome = "ducked" | "no-voice" | "aborted" | "off";
+
+/**
+ * Switch the carve on a music bed. On: carve against every overlapping voice at
+ * core's default strength (several voices are grouped first, as the carve lint
+ * requires). Off: `enabled:false`, which drops the generated filters and lanes.
+ */
+export async function setDuckUnderVoice(
+  doc: Document,
+  bed: Element,
+  on: boolean,
+  write: WriteBedAttribute,
+  groupClips?: GroupClips,
+): Promise<DuckOutcome> {
+  const current = readBedCarve(bed);
+  if (!on) {
+    await dropCarveOutput(readChain(bed), readAutomation(bed), write);
+    await write(
+      HF_AUDIO_CARVE_ATTR,
+      JSON.stringify({ ...(current ?? DEFAULT_CARVE), enabled: false }),
+    );
+    return "off";
+  }
+  const sources = duckVoiceSources(doc, bed);
+  if (sources.length === 0) return "no-voice";
+  const resolved = resolveNextCarveSettings({ ...DEFAULT_CARVE, sources }, doc, groupClips);
+  const settings = isPromiseLike(resolved) ? await resolved : resolved;
+  if (settings === CARVE_ABORTED || settings === null) return "aborted";
+  await write(HF_AUDIO_CARVE_ATTR, JSON.stringify(settings));
+  await writeMeasuredCarve(doc, bed, settings, write);
+  return "ducked";
+}
diff --git a/packages/studio/src/player/components/clipMenuNormalize.test.ts b/packages/studio/src/player/components/clipMenuNormalize.test.ts
new file mode 100644
index 0000000000..e19a041bc0
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuNormalize.test.ts
@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import {
+  clipHasSound,
+  normalizeRequestBody,
+  normalizeToastText,
+  requestNormalizePlan,
+} from "./clipMenuNormalize";
+import type { TimelineElement } from "../store/timelineElement";
+
+const clip = (over: Partial<TimelineElement>): TimelineElement => ({
+  id: "vo",
+  tag: "audio",
+  start: 0,
+  duration: 4,
+  track: 0,
+  ...over,
+});
+
+describe("clipHasSound", () => {
+  it("is true for audio and for a video with sound, false for silent or muted video", () => {
+    expect(clipHasSound(clip({}))).toBe(true);
+    expect(clipHasSound(clip({ tag: "video", hasAudio: true }))).toBe(true);
+    expect(clipHasSound(clip({ tag: "video", hasAudio: false }))).toBe(false);
+    expect(clipHasSound(clip({ tag: "video", hasAudio: true, muted: true }))).toBe(false);
+    expect(clipHasSound(clip({ tag: "img" }))).toBe(false);
+  });
+});
+
+describe("normalizeRequestBody", () => {
+  it("sends the played source window and the current gain", () => {
+    const body = normalizeRequestBody(
+      clip({ domId: "a-roll", playbackStart: 2, playbackRate: 2, volume: 0.5, duration: 3 }),
+      "talk.mp4",
+    );
+    expect(body).toEqual({
+      id: "a-roll",
+      src: "talk.mp4",
+      mediaStart: 2,
+      duration: 3,
+      playbackRate: 2,
+      volume: 0.5,
+    });
+  });
+});
+
+describe("normalizeToastText", () => {
+  it("names the target and the change", () => {
+    expect(
+      normalizeToastText({
+        targetLufs: -16,
+        projectedLufs: -16,
+        volume: 1.44,
+        changeDb: 3.2,
+        limitedBy: null,
+      }),
+    ).toBe("Normalized to −16 LUFS (+3.2 dB)");
+  });
+
+  it("says so when a limit held it back", () => {
+    expect(
+      normalizeToastText({
+        targetLufs: -16,
+        projectedLufs: -18.4,
+        volume: 4,
+        changeDb: 12,
+        limitedBy: "gain-ceiling",
+      }),
+    ).toBe("Raised to −18 LUFS (+12.0 dB), the most the +12 dB ceiling allows");
+  });
+});
+
+describe("requestNormalizePlan", () => {
+  it("posts the project-relative source and returns the plan", async () => {
+    const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+    const fetchImpl = vi.fn<typeof fetch>(async () => Response.json({ plan }));
+    const origin = window.location.origin;
+    const el = clip({ src: `${origin}/api/projects/p1/preview/assets/vo.wav` });
+    await expect(requestNormalizePlan("p1", el, fetchImpl)).resolves.toEqual(plan);
+    const [url, init] = fetchImpl.mock.calls[0] ?? [];
+    expect(url).toBe("/api/projects/p1/loudness/normalize");
+    expect(JSON.parse(String(init?.body))).toEqual(
+      expect.objectContaining({ src: "assets/vo.wav" }),
+    );
+  });
+
+  it("surfaces the server's reason", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      Response.json({ error: "#vo is silent" }, { status: 422 }),
+    );
+    await expect(
+      requestNormalizePlan("p1", clip({ src: "assets/vo.wav" }), fetchImpl),
+    ).rejects.toThrow(/silent/);
+  });
+});
diff --git a/packages/studio/src/player/components/clipMenuNormalize.ts b/packages/studio/src/player/components/clipMenuNormalize.ts
new file mode 100644
index 0000000000..cb54f7b063
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuNormalize.ts
@@ -0,0 +1,74 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
+import { resolvePreviewRelative } from "../../utils/previewRelativePath";
+import { resolveMediaPreviewUrl } from "./thumbnailUtils";
+import type { TimelineElement } from "../store/timelineElement";
+
+export interface NormalizePlan {
+  targetLufs: number;
+  projectedLufs: number;
+  volume: number;
+  changeDb: number;
+  limitedBy: "gain-ceiling" | "true-peak" | null;
+}
+
+export function clipHasSound(el: TimelineElement): boolean {
+  if (el.tag === "audio") return true;
+  return el.tag === "video" && el.hasAudio === true && el.muted !== true;
+}
+
+export function normalizeRequestBody(el: TimelineElement, projectRelativeSrc: string) {
+  return {
+    id: el.domId ?? el.id,
+    src: projectRelativeSrc,
+    mediaStart: el.playbackStart ?? 0,
+    duration: el.duration > 0 ? el.duration : undefined,
+    playbackRate: el.playbackRate ?? 1,
+    volume: el.volume ?? 1,
+  };
+}
+
+const signedDb = (db: number) => `${db >= 0 ? "+" : "−"}${Math.abs(db).toFixed(1)} dB`;
+const lufsText = (lufs: number) => `${lufs < 0 ? "−" : ""}${Math.abs(lufs).toFixed(0)} LUFS`;
+
+const LIMIT_SUFFIX = {
+  "gain-ceiling": "the most the +12 dB ceiling allows",
+  "true-peak": "held back to keep peaks under −1.5 dBTP",
+} satisfies Record<NonNullable<NormalizePlan["limitedBy"]>, string>;
+
+export function normalizeToastText(plan: NormalizePlan): string {
+  if (!plan.limitedBy)
+    return `Normalized to ${lufsText(plan.targetLufs)} (${signedDb(plan.changeDb)})`;
+  const reached = `${lufsText(Math.round(plan.projectedLufs))}`;
+  return `Raised to ${reached} (${signedDb(plan.changeDb)}), ${LIMIT_SUFFIX[plan.limitedBy]}`;
+}
+
+function isNormalizePlan(value: unknown): value is NormalizePlan {
+  if (typeof value !== "object" || value === null) return false;
+  return ["targetLufs", "projectedLufs", "volume", "changeDb"].every(
+    (key) => typeof Reflect.get(value, key) === "number",
+  );
+}
+
+export async function requestNormalizePlan(
+  projectId: string,
+  el: TimelineElement,
+  fetchImpl: typeof fetch = fetch,
+): Promise<NormalizePlan> {
+  const origin = window.location.origin;
+  const relative = resolvePreviewRelative(
+    resolveMediaPreviewUrl(el.src ?? "", projectId, origin),
+    projectId,
+    origin,
+  );
+  if (!relative) throw new Error("Only project media can be normalized");
+  const res = await fetchImpl(buildProjectApiPath(projectId, "/loudness/normalize"), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(normalizeRequestBody(el, relative)),
+  });
+  const body: unknown = await res.json().catch(() => null);
+  const plan = typeof body === "object" && body !== null ? Reflect.get(body, "plan") : null;
+  if (res.ok && isNormalizePlan(plan)) return plan;
+  const error = typeof body === "object" && body !== null ? Reflect.get(body, "error") : null;
+  throw new Error(typeof error === "string" ? error : "Could not measure this clip");
+}
diff --git a/packages/studio/src/utils/previewRelativePath.ts b/packages/studio/src/utils/previewRelativePath.ts
new file mode 100644
index 0000000000..19a4c95436
--- /dev/null
+++ b/packages/studio/src/utils/previewRelativePath.ts
@@ -0,0 +1,19 @@
+import { buildProjectApiPath } from "./projectRouting";
+
+/** Resolve a media src to its project-relative preview path, or null. */
+export function resolvePreviewRelative(
+  src: string | undefined,
+  pid: string,
+  origin: string,
+): string | null {
+  if (!src) return null;
+  try {
+    const parsed = new URL(src, origin);
+    const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
+    return parsed.pathname.startsWith(base)
+      ? decodeURIComponent(parsed.pathname.slice(base.length))
+      : null;
+  } catch {
+    return null;
+  }
+}

From c2bbd3c516fcc097cefd796e3c16ec51eccfe511 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 23:28:13 -0700
Subject: [PATCH 06/10] refactor(studio): tighten carveOutput docs to the
 package comment share

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/editor/carveOutput.ts      | 20 +++----------------
 1 file changed, 3 insertions(+), 17 deletions(-)

diff --git a/packages/studio/src/components/editor/carveOutput.ts b/packages/studio/src/components/editor/carveOutput.ts
index c893a99e2e..e605c6025e 100644
--- a/packages/studio/src/components/editor/carveOutput.ts
+++ b/packages/studio/src/components/editor/carveOutput.ts
@@ -19,21 +19,12 @@ export function withoutCarveLanes(automation: HfAutomation, chain: HfAudioFxChai
   };
 }
 
-/**
- * Every named voice that is actually there with something to decode. A source
- * naming a deleted track is skipped rather than failing the whole analysis.
- *
- * Read out to plain values here rather than carrying elements around: it is
- * what lets the src and the start be non-null by construction downstream
- * instead of by assertion.
- */
+/** Every named voice still present with a src; a deleted source is skipped, not fatal. */
 export function resolveCarveVoices(doc: Document, sources: readonly string[]): CarveClip[] {
   const voices: CarveClip[] = [];
   for (const id of sources) {
     const el = doc.getElementById(id);
-    // By tag name, not `instanceof HTMLAudioElement`: these elements belong to
-    // the composition's iframe document, so the constructor they were made
-    // from is not this realm's and the instanceof is false for every one.
+    // By tag name: iframe-realm elements fail `instanceof HTMLAudioElement`.
     if (!isCarveVoiceElement(el)) continue;
     const src = el.getAttribute("src");
     if (!src) continue;
@@ -43,12 +34,7 @@ export function resolveCarveVoices(doc: Document, sources: readonly string[]): C
   return voices;
 }
 
-/**
- * What the carve generated is only justified by the voices it was measured
- * from: switched off, or left naming none — every source deleted, say — there
- * is nothing those filters are making room for. Left behind they keep dipping
- * the bed with nothing in the panel to explain them.
- */
+/** Remove the filters and lanes a carve generated once it no longer names a voice. */
 export async function dropCarveOutput(
   chain: HfAudioFxChain,
   automation: HfAutomation,

From cc2f68cff904d664d38eaf1760af78bc7778341b Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 29 Sep 2026 23:30:38 -0700
Subject: [PATCH 07/10] feat(producer): report how far the true-peak limiter
 lowered the export

The AAC true-peak pass now returns its attenuation; the render logs "Audio lowered
by X.X dB to stay under -1 dBTP" and sets RenderJob.audioLoweredDb, which Studio
servers carry in the complete SSE event and the /renders record. Also exports
useAudioMetersVisible from @hyperframes/studio for hosts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/cli/src/server/studioServer.test.ts  | 14 +++++
 packages/cli/src/server/studioServer.ts       |  7 ++-
 .../src/services/render/audioPadTrim.test.ts  |  2 +
 .../src/services/render/audioPadTrim.ts       | 19 ++++--
 .../render/stages/assembleStage.test.ts       | 32 ++++++++++
 .../services/render/stages/assembleStage.ts   | 14 ++++-
 .../src/services/renderOrchestrator.ts        |  1 +
 .../studio-server/src/routes/render.test.ts   | 58 +++++++++++++++++++
 packages/studio-server/src/routes/render.ts   |  6 ++
 packages/studio-server/src/types.ts           |  1 +
 packages/studio/src/index.ts                  |  1 +
 .../studio/src/timelineChromeExports.test.tsx |  7 +++
 packages/studio/vite.adapter.ts               |  7 ++-
 13 files changed, 161 insertions(+), 8 deletions(-)

diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.ts
index 67d366a4d7..bd9bea6152 100644
--- a/packages/cli/src/server/studioServer.test.ts
+++ b/packages/cli/src/server/studioServer.test.ts
@@ -55,6 +55,7 @@ vi.mock("@hyperframes/engine", () => ({
   buildChromeArgs: () => [],
   killTrackedProcesses: () => {},
   closeBrowserPool: () => engineState.closeBrowserPool(),
+  getSystemTotalMb: () => 0,
 }));
 vi.mock("../browser/gpuPolicy.js", () => ({
   resolveCaptureBrowserGpuMode: async () => "software",
@@ -291,6 +292,19 @@ describe("createStudioServer shutdown", () => {
     };
   }
 
+  it("hands the limiter's audioLoweredDb to the job state and the render sidecar", async () => {
+    producerState.executeRenderJob = async (job) => {
+      if (typeof job === "object" && job !== null) Reflect.set(job, "audioLoweredDb", 1.44);
+    };
+    const outputPath = join(mkdtempSync(join(tmpdir(), "hf-lowered-")), "out.mp4");
+    server = createStudioServer({ projectDir: tmpProject() });
+    const state = server.adapter.startRender(startRenderOpts("job-lowered", outputPath));
+    await vi.waitFor(() => expect(state.status, state.error).toBe("complete"), { timeout: 5_000 });
+    expect(state.audioLoweredDb).toBe(1.44);
+    const meta = JSON.parse(readFileSync(outputPath.replace(/\.mp4$/, ".meta.json"), "utf8"));
+    expect(meta.audioLoweredDb).toBe(1.44);
+  });
+
   it("cancels an in-flight render's signal and waits for it before draining the browser pool", async () => {
     const events: string[] = [];
     let started!: () => void;
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 4463450418..de80551dbf 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -621,12 +621,17 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
             removeCancelledOutput();
             return;
           }
+          if (job.audioLoweredDb !== undefined) state.audioLoweredDb = job.audioLoweredDb;
           state.status = "complete";
           state.progress = 100;
           const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
           writeFileSync(
             metaPath,
-            JSON.stringify({ status: "complete", durationMs: Date.now() - startTime }),
+            JSON.stringify({
+              status: "complete",
+              durationMs: Date.now() - startTime,
+              ...(job.audioLoweredDb !== undefined ? { audioLoweredDb: job.audioLoweredDb } : {}),
+            }),
           );
           // Refreshed HERE, not just at render start: a render can run for
           // minutes, and `hyperframes telemetry disable` during one must be
diff --git a/packages/producer/src/services/render/audioPadTrim.test.ts b/packages/producer/src/services/render/audioPadTrim.test.ts
index 30e5841b22..af4637e7da 100644
--- a/packages/producer/src/services/render/audioPadTrim.test.ts
+++ b/packages/producer/src/services/render/audioPadTrim.test.ts
@@ -307,6 +307,7 @@ describe("padOrTrimAudioToVideoFrameCount", () => {
 
     expect(result.success).toBe(true);
     expect(captured.args).toHaveLength(1);
+    expect(result).not.toHaveProperty("audioLoweredDb");
   });
 
   it("attenuates the duration-normalized artifact with AAC correction headroom", async () => {
@@ -360,6 +361,7 @@ describe("padOrTrimAudioToVideoFrameCount", () => {
 
       expect(result.success, result.error).toBe(true);
       expect(corrections).toEqual([-1.5, -2.4, -2.94]);
+      expect(result.audioLoweredDb).toBe(2.94);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
diff --git a/packages/producer/src/services/render/audioPadTrim.ts b/packages/producer/src/services/render/audioPadTrim.ts
index db16b01bec..b8481ad2b7 100644
--- a/packages/producer/src/services/render/audioPadTrim.ts
+++ b/packages/producer/src/services/render/audioPadTrim.ts
@@ -102,6 +102,8 @@ export interface PadTrimAudioResult {
   error?: string;
   /** Stable machine-readable cause for failures safe to retry on a fresh host. */
   failureReason?: "external_interruption";
+  /** dB the true-peak limiter lowered the whole mix by; absent when it did not engage. */
+  audioLoweredDb?: number;
 }
 
 export type PadTrimAudioStepKind = "copy" | "trim" | "normalize";
@@ -384,6 +386,7 @@ export async function padOrTrimAudioToVideoFrameCount(
     for (const path of plan.cleanupPaths) rmSync(path, { force: true });
   }
 
+  let loweredDb = 0;
   if (probeTruePeak) {
     const correction = await enforceAacTruePeak({
       audioPath: input.outputPath,
@@ -403,6 +406,7 @@ export async function padOrTrimAudioToVideoFrameCount(
         failureReason: correction.failureReason,
       };
     }
+    loweredDb = correction.loweredDb ?? 0;
   }
   return {
     success: true,
@@ -410,6 +414,7 @@ export async function padOrTrimAudioToVideoFrameCount(
     targetDurationSeconds,
     sourceDurationSeconds: audioInfo.durationSeconds,
     operation: plan.operation,
+    ...(loweredDb > 0 ? { audioLoweredDb: loweredDb } : {}),
   };
 }
 
@@ -425,9 +430,12 @@ interface EnforceAacTruePeakInput {
   }>;
 }
 
-async function enforceAacTruePeak(
-  input: EnforceAacTruePeakInput,
-): Promise<{ success: boolean; error?: string; failureReason?: "external_interruption" }> {
+async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
+  success: boolean;
+  error?: string;
+  failureReason?: "external_interruption";
+  loweredDb?: number;
+}> {
   let scratchDir: string | undefined;
   try {
     scratchDir = mkdtempSync(join(dirname(input.audioPath), ".true-peak-"));
@@ -445,8 +453,9 @@ async function enforceAacTruePeak(
         return { success: false, error: "audioPadTrim: FFmpeg reported an invalid true peak" };
       }
       if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
-        if (measuredPath === correctedPath) renameSync(correctedPath, input.audioPath);
-        return { success: true };
+        if (measuredPath !== correctedPath) return { success: true };
+        renameSync(correctedPath, input.audioPath);
+        return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
 
diff --git a/packages/producer/src/services/render/stages/assembleStage.test.ts b/packages/producer/src/services/render/stages/assembleStage.test.ts
index 80cce8aa4b..afd7f15329 100644
--- a/packages/producer/src/services/render/stages/assembleStage.test.ts
+++ b/packages/producer/src/services/render/stages/assembleStage.test.ts
@@ -16,6 +16,7 @@ vi.mock("@hyperframes/engine", () => ({
 }));
 
 vi.mock("../audioPadTrim.js", () => ({
+  AAC_DELIVERY_TRUE_PEAK_DBFS: -1,
   padOrTrimAudioToVideoFrameCount: padOrTrimAudioMock,
 }));
 
@@ -238,3 +239,34 @@ describe("runAssembleStage HLS packaging", () => {
     expect(packageHlsMock).not.toHaveBeenCalled();
   });
 });
+
+describe("runAssembleStage limiter honesty", () => {
+  beforeEach(resetMocks);
+
+  it("records and logs how far the true-peak limiter lowered the mix", async () => {
+    padOrTrimAudioMock.mockResolvedValue({
+      success: true,
+      outputPath: "/tmp/audio.duration-normalized.m4a",
+      targetDurationSeconds: 1,
+      sourceDurationSeconds: 1,
+      operation: "copy",
+      audioLoweredDb: 1.44,
+    });
+    const logger = { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
+    const input = makeInput();
+    input.job.config.logger = logger;
+
+    await runAssembleStage(input);
+
+    expect(input.job.audioLoweredDb).toBe(1.44);
+    expect(logger.info).toHaveBeenCalledWith("Audio lowered by 1.4 dB to stay under −1 dBTP", {
+      audioLoweredDb: 1.44,
+    });
+  });
+
+  it("leaves the job untouched when the limiter did not engage", async () => {
+    const input = makeInput();
+    await runAssembleStage(input);
+    expect(input.job).not.toHaveProperty("audioLoweredDb");
+  });
+});
diff --git a/packages/producer/src/services/render/stages/assembleStage.ts b/packages/producer/src/services/render/stages/assembleStage.ts
index 542e3481e5..adabe3b675 100644
--- a/packages/producer/src/services/render/stages/assembleStage.ts
+++ b/packages/producer/src/services/render/stages/assembleStage.ts
@@ -23,11 +23,12 @@
 import { applyFaststart, muxVideoWithAudio, packageHls } from "@hyperframes/engine";
 import { extname } from "node:path";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
-import { padOrTrimAudioToVideoFrameCount } from "../audioPadTrim.js";
+import { AAC_DELIVERY_TRUE_PEAK_DBFS, padOrTrimAudioToVideoFrameCount } from "../audioPadTrim.js";
 import { encoderFailureError } from "../encoderInterruption.js";
 import { DEFAULT_HLS_SEGMENT_SECONDS } from "../hlsConfig.js";
 import type { RenderOutputFormat } from "../renderFormat.js";
 import { updateJobStatus } from "../shared.js";
+import { defaultLogger } from "../../../logger.js";
 
 export interface AssembleStageInput {
   job: RenderJob;
@@ -55,6 +56,16 @@ export interface AssembleStageResult {
   assembleMs: number;
 }
 
+function recordLimiterAttenuation(job: RenderJob, audioLoweredDb: number | undefined): void {
+  if (audioLoweredDb === undefined) return;
+  job.audioLoweredDb = audioLoweredDb;
+  const ceiling = `−${Math.abs(AAC_DELIVERY_TRUE_PEAK_DBFS)} dBTP`;
+  (job.config.logger ?? defaultLogger).info(
+    `Audio lowered by ${audioLoweredDb.toFixed(1)} dB to stay under ${ceiling}`,
+    { audioLoweredDb },
+  );
+}
+
 export async function runAssembleStage(input: AssembleStageInput): Promise<AssembleStageResult> {
   const {
     job,
@@ -88,6 +99,7 @@ export async function runAssembleStage(input: AssembleStageInput): Promise<Assem
     if (!normalizeResult.success) {
       throw encoderFailureError("Audio duration normalization failed", normalizeResult);
     }
+    recordLimiterAttenuation(job, normalizeResult.audioLoweredDb);
     if (isHls) {
       await runHlsPackaging(input, normalizeResult.outputPath);
     } else {
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index d3f814f115..d147c31a4f 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -725,6 +725,7 @@ export interface RenderJob {
   totalFrames?: number;
   framesRendered?: number;
   perfSummary?: RenderPerfSummary;
+  audioLoweredDb?: number;
   failedStage?: string;
   errorDetails?: {
     message: string;
diff --git a/packages/studio-server/src/routes/render.test.ts b/packages/studio-server/src/routes/render.test.ts
index b4853a2def..e888951de1 100644
--- a/packages/studio-server/src/routes/render.test.ts
+++ b/packages/studio-server/src/routes/render.test.ts
@@ -763,3 +763,61 @@ describe("POST /projects/:id/render — variables forwarding", () => {
     }
   });
 });
+
+describe("audioLoweredDb — the limiter's attenuation reaches the host", () => {
+  async function completedJobProgress(audioLoweredDb: number | undefined): Promise<string> {
+    const spy = vi.fn();
+    const { adapter, rendersDir } = createAdapter(spy);
+    const baseStartRender = adapter.startRender.bind(adapter);
+    adapter.startRender = (opts) => {
+      const state = baseStartRender(opts);
+      state.status = "complete";
+      state.progress = 100;
+      if (audioLoweredDb !== undefined) state.audioLoweredDb = audioLoweredDb;
+      return state;
+    };
+    const app = new Hono();
+    registerRenderRoutes(app, adapter);
+    try {
+      const started = await app.request("http://localhost/projects/demo/render", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
+      });
+      const { jobId } = (await started.json()) as { jobId: string };
+      return await (await app.request(`http://localhost/render/${jobId}/progress`)).text();
+    } finally {
+      rmSync(rendersDir, { recursive: true, force: true });
+    }
+  }
+
+  it("carries audioLoweredDb in the complete progress event", async () => {
+    const body = await completedJobProgress(1.44);
+    expect(body).toContain('"status":"complete"');
+    expect(body).toContain('"audioLoweredDb":1.44');
+  });
+
+  it("omits it when the limiter did not engage", async () => {
+    expect(await completedJobProgress(undefined)).not.toContain("audioLoweredDb");
+  });
+
+  it("lists it on the render record from the sidecar, and omits it otherwise", async () => {
+    const { app, rendersDir, cleanup } = buildApp(vi.fn());
+    try {
+      writeFileSync(join(rendersDir, "loud.mp4"), "x");
+      writeFileSync(
+        join(rendersDir, "loud.meta.json"),
+        JSON.stringify({ status: "complete", audioLoweredDb: 1.44 }),
+      );
+      writeFileSync(join(rendersDir, "quiet.mp4"), "x");
+      writeFileSync(join(rendersDir, "quiet.meta.json"), JSON.stringify({ status: "complete" }));
+      const { renders } = (await (
+        await app.request("http://localhost/projects/demo/renders")
+      ).json()) as { renders: Array<{ id: string; audioLoweredDb?: number }> };
+      expect(renders.find((r) => r.id === "loud")?.audioLoweredDb).toBe(1.44);
+      expect(renders.find((r) => r.id === "quiet")).not.toHaveProperty("audioLoweredDb");
+    } finally {
+      cleanup();
+    }
+  });
+});
diff --git a/packages/studio-server/src/routes/render.ts b/packages/studio-server/src/routes/render.ts
index 951188e28c..9e312a97fc 100644
--- a/packages/studio-server/src/routes/render.ts
+++ b/packages/studio-server/src/routes/render.ts
@@ -168,6 +168,9 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
             status: current.status,
             stage: current.stage,
             error: current.error,
+            ...(current.status === "complete" && current.audioLoweredDb !== undefined
+              ? { audioLoweredDb: current.audioLoweredDb }
+              : {}),
           }),
         });
         if (current.status !== "rendering") break;
@@ -300,6 +303,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
         const metaPath = join(rendersDir, `${rid}.meta.json`);
         let status: "complete" | "failed" = "complete";
         let durationMs: number | undefined;
+        let audioLoweredDb: number | undefined;
         if (existsSync(metaPath)) {
           try {
             const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
@@ -309,6 +313,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
             // an earlier attempt left behind failed metadata.
             if (meta.status === "failed" && !existsSync(fp)) status = "failed";
             if (meta.durationMs) durationMs = meta.durationMs;
+            if (typeof meta.audioLoweredDb === "number") audioLoweredDb = meta.audioLoweredDb;
           } catch {
             /* ignore */
           }
@@ -320,6 +325,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
           createdAt: stat.mtimeMs,
           status,
           durationMs,
+          ...(audioLoweredDb !== undefined ? { audioLoweredDb } : {}),
         };
       })
       .sort((a, b) => b.createdAt - a.createdAt);
diff --git a/packages/studio-server/src/types.ts b/packages/studio-server/src/types.ts
index 3d79952f15..719bbc317f 100644
--- a/packages/studio-server/src/types.ts
+++ b/packages/studio-server/src/types.ts
@@ -19,6 +19,7 @@ export interface RenderJobState {
   stage?: string;
   outputPath: string;
   error?: string;
+  audioLoweredDb?: number;
   /**
    * Optional abort hook set by the adapter. The cancel route calls this to
    * stop an in-flight render; adapters that can't abort may omit it (the
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index f12013cced..b79b3d6df6 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -175,6 +175,7 @@ export { TimelineHistoryButtons } from "./components/TimelineHistoryButtons";
 export type { TimelineHistoryButtonsProps } from "./components/TimelineHistoryButtons";
 export { AudioMeterStrip } from "./components/nle/AudioMeterStrip";
 export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
+export { useAudioMetersVisible } from "./utils/audioMeterVisibility";
 export { useClipboard } from "./hooks/useClipboard";
 export type { UseClipboardOptions } from "./hooks/useClipboard";
 
diff --git a/packages/studio/src/timelineChromeExports.test.tsx b/packages/studio/src/timelineChromeExports.test.tsx
index 1fa3554787..c52f84edf0 100644
--- a/packages/studio/src/timelineChromeExports.test.tsx
+++ b/packages/studio/src/timelineChromeExports.test.tsx
@@ -6,6 +6,7 @@ import {
   AudioMeterStrip,
   TimelineHistoryButtons,
   TimelineToolbar,
+  useAudioMetersVisible as exportedAudioMetersVisible,
   useClipboard,
   usePlayerStore,
   type UseClipboardOptions,
@@ -51,6 +52,12 @@ describe("timeline chrome package exports, outside Studio's shell", () => {
     await act(async () => root.unmount());
   });
 
+  it("exports the meter visibility store a host toggles", () => {
+    expect(exportedAudioMetersVisible).toBe(useAudioMetersVisible);
+    exportedAudioMetersVisible.getState().setVisible(true);
+    expect(useAudioMetersVisible.getState().visible).toBe(true);
+  });
+
   it("runs the clipboard with no DOM edit session", async () => {
     const toasts: string[] = [];
     const options: UseClipboardOptions = {
diff --git a/packages/studio/vite.adapter.ts b/packages/studio/vite.adapter.ts
index 939f33aec7..76c1815de0 100644
--- a/packages/studio/vite.adapter.ts
+++ b/packages/studio/vite.adapter.ts
@@ -369,12 +369,17 @@ export function createViteAdapter(
             removeCancelledOutput();
             return;
           }
+          if (job.audioLoweredDb !== undefined) state.audioLoweredDb = job.audioLoweredDb;
           state.status = "complete";
           state.progress = 100;
           const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
           writeFileSync(
             metaPath,
-            JSON.stringify({ status: "complete", durationMs: Date.now() - startTime }),
+            JSON.stringify({
+              status: "complete",
+              durationMs: Date.now() - startTime,
+              ...(job.audioLoweredDb !== undefined ? { audioLoweredDb: job.audioLoweredDb } : {}),
+            }),
           );
         } catch (err) {
           if (abortController.signal.aborted) {

From ec7081649130e58a81f49ad3edc7bc368c4866c3 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 21:21:50 -0700
Subject: [PATCH 08/10] fix(studio-server): scan HTML start tags without a
 backtracking regex

The start-tag regex backtracked quadratically on '<' followed by many spaces
(CodeQL js/polynomial-redos). A linear character scan reads the same name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/helpers/loudness.test.ts              | 21 ++++++++++++++++
 .../studio-server/src/helpers/loudness.ts     | 24 +++++++++++++++----
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/packages/studio-server/src/helpers/loudness.test.ts b/packages/studio-server/src/helpers/loudness.test.ts
index 026508d29c..f49d16006f 100644
--- a/packages/studio-server/src/helpers/loudness.test.ts
+++ b/packages/studio-server/src/helpers/loudness.test.ts
@@ -116,3 +116,24 @@ describe("absoluteLoudnessPlan", () => {
     expect(absoluteLoudnessPlan(track(-19, -10, 0)).changeDb).toBeCloseTo(3, 6);
   });
 });
+
+describe("audioTags on hostile markup", () => {
+  it("scans '<' followed by many spaces in linear time", () => {
+    const html = `${"<" + " ".repeat(50_000)}<audio id="vo" src="vo.mp3"></audio>`;
+    const started = performance.now();
+    expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+    expect(performance.now() - started).toBeLessThan(500);
+  });
+
+  it("scans many '<' + spaces runs in linear time", () => {
+    const html = `${("<" + " ".repeat(20)).repeat(20_000)}<audio id="vo" src="vo.mp3"></audio>`;
+    const started = performance.now();
+    expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+    expect(performance.now() - started).toBeLessThan(1000);
+  });
+
+  it("still reads tags written with spaces around the slash and name", () => {
+    const html = `< audio id="vo" src="vo.mp3">< / audio><a_b></a_b>`;
+    expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+  });
+});
diff --git a/packages/studio-server/src/helpers/loudness.ts b/packages/studio-server/src/helpers/loudness.ts
index 1217913923..75c8790dea 100644
--- a/packages/studio-server/src/helpers/loudness.ts
+++ b/packages/studio-server/src/helpers/loudness.ts
@@ -149,14 +149,30 @@ function commentEnd(html: string, start: number): number {
   return end + 3;
 }
 
+const isSpaceAt = (html: string, index: number) => /\s/.test(html.charAt(index));
+const isWordAt = (html: string, index: number) => /\w/.test(html.charAt(index));
+
+function skipSpaces(html: string, index: number): number {
+  let cursor = index;
+  while (cursor < html.length && isSpaceAt(html, cursor)) cursor++;
+  return cursor;
+}
+
 function parsedStartTag(html: string, start: number): ParsedStartTag | null {
-  const match = html.slice(start).match(/^<\s*(\/?)\s*([a-z][a-z\d:-]*)\b/i);
-  if (!match) return null;
+  let cursor = skipSpaces(html, start + 1);
+  const closing = html.charAt(cursor) === "/";
+  if (closing) cursor = skipSpaces(html, cursor + 1);
+  const nameStart = cursor;
+  if (!/[a-z]/i.test(html.charAt(cursor))) return null;
+  while (/[a-z\d:-]/i.test(html.charAt(cursor + 1))) cursor++;
+  let nameEnd = cursor + 1;
+  while (nameEnd > nameStart && isWordAt(html, nameEnd - 1) === isWordAt(html, nameEnd)) nameEnd--;
+  if (nameEnd === nameStart) return null;
   return {
     start,
     end: startTagEnd(html, start),
-    closing: match[1] === "/",
-    name: match[2]?.toLowerCase() ?? "",
+    closing,
+    name: html.slice(nameStart, nameEnd).toLowerCase(),
   };
 }
 

From ab7e31ba78c994ad54b26200cfdcb724757d0cba Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 21:21:52 -0700
Subject: [PATCH 09/10] fix(studio): refuse to normalize a volume-automated
 clip and honour save outcomes

A volume lane owns the clip's gain in preview and render, so writing
data-volume changed nothing while the toast claimed success; Normalize now
refuses with a clear message. Normalize and Duck also check each quiet-save
outcome, stop at the first failed or refused write and report it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/clipMenuAudioItems.test.tsx    | 64 ++++++++++++++++++-
 .../player/components/clipMenuAudioItems.tsx  | 38 ++++++++---
 .../player/components/clipMenuNormalize.ts    | 22 +++++++
 3 files changed, 114 insertions(+), 10 deletions(-)

diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
index c264bc3bfc..7b1a35820e 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -1,12 +1,12 @@
 // @vitest-environment happy-dom
 import { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { ClipMenuAudioItems } from "./clipMenuAudioItems";
 import type { TimelineElement } from "../store/timelineElement";
 
 const showToast = vi.fn();
-const setQuiet = vi.fn(async () => {});
+const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});
 const iframe = document.createElement("iframe");
 
 vi.mock("../../contexts/StudioContext", () => ({
@@ -32,6 +32,17 @@ function render(element: TimelineElement) {
 }
 
 const base = { start: 0, duration: 4, track: 0 };
+const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+const clickItem = async (host: HTMLElement, label: string) => {
+  const button = [...host.querySelectorAll("button")].find((b) => b.textContent?.includes(label));
+  await act(async () => button?.click());
+};
+
+beforeEach(() => {
+  showToast.mockClear();
+  setQuiet.mockReset();
+  setQuiet.mockResolvedValue(undefined);
+});
 
 describe("ClipMenuAudioItems", () => {
   it("offers nothing on a muted video", () => {
@@ -62,4 +73,53 @@ describe("ClipMenuAudioItems", () => {
     expect(showToast).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
     vi.unstubAllGlobals();
   });
+
+  it("refuses to normalize a clip whose volume lane owns its gain", async () => {
+    const fetchSpy = vi.fn(async () => Response.json({ plan }));
+    vi.stubGlobal("fetch", fetchSpy);
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],
+    });
+    const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3", automation });
+    await clickItem(host, "Normalize loudness");
+    await vi.waitFor(() => expect(showToast).toHaveBeenCalled());
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("volume is automated"), "error");
+    expect(setQuiet).not.toHaveBeenCalled();
+    expect(fetchSpy).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it("reports a failed save instead of claiming the clip was normalized", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => Response.json({ plan })),
+    );
+    setQuiet.mockResolvedValue({ status: "failed", reason: "disk full" });
+    const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3" });
+    await clickItem(host, "Normalize loudness");
+    await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("disk full", "error"));
+    expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Normalized"), "info");
+    vi.unstubAllGlobals();
+  });
+
+  it("stops ducking at the first refused save and says why", async () => {
+    document.body.appendChild(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("fixture");
+    doc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
+      <audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`;
+    setQuiet.mockResolvedValue({
+      status: "refused",
+      reason: "Cannot edit timeline while recording",
+    });
+    const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" });
+    await clickItem(host, "Duck under voice");
+    await vi.waitFor(() =>
+      expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error"),
+    );
+    expect(setQuiet).toHaveBeenCalledTimes(1);
+    expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Ducks under"), "info");
+    iframe.remove();
+  });
 });
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsx
index a4c81075bf..0df27dd0f2 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx
@@ -2,7 +2,15 @@ import { formatAudioGain } from "@hyperframes/core/audio-gain";
 import type { TimelineElement } from "../store/timelineElement";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { useStudioShellContextOptional } from "../../contexts/StudioContext";
-import { clipHasSound, normalizeToastText, requestNormalizePlan } from "./clipMenuNormalize";
+import {
+  clipHasSound,
+  normalizeToastText,
+  requestNormalizePlan,
+  throwUnlessSaved,
+  TimelineSaveError,
+  VOLUME_LANE_REFUSAL,
+  volumeLaneOwnsGain,
+} from "./clipMenuNormalize";
 import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
 
 const ITEM_CLASS =
@@ -33,13 +41,19 @@ export function ClipMenuAudioItems({
 
   const normalize = async () => {
     onClose();
+    if (volumeLaneOwnsGain(element)) {
+      showToast(VOLUME_LANE_REFUSAL, "error");
+      return;
+    }
     try {
       const plan = await requestNormalizePlan(projectId, element);
-      await onSetElementAttributeQuiet(
-        element,
-        "data-volume",
-        formatAudioGain(plan.volume),
-        "Normalize loudness",
+      throwUnlessSaved(
+        await onSetElementAttributeQuiet(
+          element,
+          "data-volume",
+          formatAudioGain(plan.volume),
+          "Normalize loudness",
+        ),
       );
       showToast(normalizeToastText(plan), "info");
     } catch (error) {
@@ -55,10 +69,18 @@ export function ClipMenuAudioItems({
       bed,
       !ducked,
       async (attr, value) => {
-        await onSetElementAttributeQuiet(element, attr, value, "Duck under voice");
+        throwUnlessSaved(
+          await onSetElementAttributeQuiet(element, attr, value, "Duck under voice"),
+        );
       },
       onGroupClips ? (ids, groupId) => onGroupClips(ids, groupId, "Voice") : undefined,
-    ).catch((): DuckOutcome => "aborted");
+    ).catch((error: unknown): DuckOutcome | TimelineSaveError =>
+      error instanceof TimelineSaveError ? error : "aborted",
+    );
+    if (outcome instanceof TimelineSaveError) {
+      showToast(outcome.message, "error");
+      return;
+    }
     showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
   };
 
diff --git a/packages/studio/src/player/components/clipMenuNormalize.ts b/packages/studio/src/player/components/clipMenuNormalize.ts
index cb54f7b063..50b6e50dd9 100644
--- a/packages/studio/src/player/components/clipMenuNormalize.ts
+++ b/packages/studio/src/player/components/clipMenuNormalize.ts
@@ -2,6 +2,8 @@ import { buildProjectApiPath } from "../../utils/projectRouting";
 import { resolvePreviewRelative } from "../../utils/previewRelativePath";
 import { resolveMediaPreviewUrl } from "./thumbnailUtils";
 import type { TimelineElement } from "../store/timelineElement";
+import { parseAutomation, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 
 export interface NormalizePlan {
   targetLufs: number;
@@ -16,6 +18,26 @@ export function clipHasSound(el: TimelineElement): boolean {
   return el.tag === "video" && el.hasAudio === true && el.muted !== true;
 }
 
+export const VOLUME_LANE_REFUSAL =
+  "This clip's volume is automated. Remove its volume automation to normalize it.";
+
+export function volumeLaneOwnsGain(el: TimelineElement): boolean {
+  if (!el.automation) return false;
+  try {
+    return parseAutomation(el.automation).lanes.some(
+      (lane) => lane.target === VOLUME_TARGET && lane.points.length > 0,
+    );
+  } catch {
+    return false;
+  }
+}
+
+export class TimelineSaveError extends Error {}
+
+export function throwUnlessSaved(outcome: TimelineEditOutcome | void): void {
+  if (outcome && outcome.status !== "saved") throw new TimelineSaveError(outcome.reason);
+}
+
 export function normalizeRequestBody(el: TimelineElement, projectRelativeSrc: string) {
   return {
     id: el.domId ?? el.id,

From c0ac120ed6d456acfcc5d65027b3a9cf465a12e4 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 21:53:00 -0700
Subject: [PATCH 10/10] chore(core): drop the duplicate audible-video subpath
 descriptor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/core/package-subpaths.json |  6 ------
 packages/core/package.json          | 10 ----------
 2 files changed, 16 deletions(-)

diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index 7e434e8207..f2626dd280 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -230,12 +230,6 @@
       "types": "./dist/audioGain.d.ts",
       "environments": ["browser", "bun", "node"]
     },
-    "./audible-video": {
-      "source": "./src/audibleVideo.ts",
-      "runtime": "./dist/audibleVideo.js",
-      "types": "./dist/audibleVideo.d.ts",
-      "environments": ["browser", "bun", "node"]
-    },
     "./audio-fade": {
       "source": "./src/audioFade.ts",
       "runtime": "./dist/audioFade.js",
diff --git a/packages/core/package.json b/packages/core/package.json
index f9f03d31c9..836954ea54 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -244,12 +244,6 @@
       "import": "./src/audioGain.ts",
       "types": "./src/audioGain.ts"
     },
-    "./audible-video": {
-      "bun": "./src/audibleVideo.ts",
-      "node": "./dist/audibleVideo.js",
-      "import": "./src/audibleVideo.ts",
-      "types": "./src/audibleVideo.ts"
-    },
     "./audio-fade": {
       "bun": "./src/audioFade.ts",
       "node": "./dist/audioFade.js",
@@ -634,10 +628,6 @@
         "import": "./dist/audioGain.js",
         "types": "./dist/audioGain.d.ts"
       },
-      "./audible-video": {
-        "import": "./dist/audibleVideo.js",
-        "types": "./dist/audibleVideo.d.ts"
-      },
       "./audio-fade": {
         "import": "./dist/audioFade.js",
         "types": "./dist/audioFade.d.ts"