fix(audio): master chain reaches tracks the render adds; honest plain-limiter copy

- Master chain: it was carried on each parsed AudioElement, so a track the
  producer adds itself (appendAutoDetectedVideoAudio, the browser-discovered
  audio in probeStage) never had it, and a composition whose only audio was
  such a track exported with no master chain, no ceiling and no warning. It is
  now a composition property: parseMasterFxChain(html) at compile, carried on
  CompiledComposition and CompositionMetadata, passed to processCompositionAudio
  by runAudioStage (in-process and distributed plan). AudioElement.masterFxChain
  is removed so there is one source. Each forward (compile stage, local
  orchestrator, distributed plan) has a test that fails when it is dropped.
- Plain limiter: it follows the level with no lookahead and Level after is
  applied past the ceiling, so it cannot promise "nothing gets past" or "never
  clips". Studio copy (description, panel text, knob label, summary) and the
  hyperframes-audio skill now say a fast or inter-sample peak can pass it and
  point to the true-peak limiter for a delivery limit. A copy test guards it.

— Jerrai

Author: jerrai-bot-heygen

docs/reference/audio-effects.mdx

@@ -193,7 +193,7 @@ dangles.
 
 The master bus is the `data-fx-chain` on the top-level composition root. It runs
 once over the sum of every clip and every group, after each group's own chain and
-fader, so a limiter here sees the true peak of the whole mix. A clip can belong to
+fader, so a limiter here sees the peak of the whole mix. A clip can belong to
 only one group, so this is the way to put one effect across everything.
 
 - Only the **top-level** composition root is read as the master bus. On a clip or

packages/core/src/audioFx.ts

@@ -288,7 +288,8 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
     id: "limiter",
     label: "Limiter",
     group: "dynamics",
-    description: "Hard ceiling — nothing gets past the limit.",
+    description:
+      "Peak limiter that follows the signal's level. It has no lookahead, so a fast peak or an inter-sample peak can pass the ceiling; use the true-peak limiter for a delivery limit.",
     params: [
       {
         kind: "number",

packages/core/src/audioFxCopy.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { defaultAudioFxParams, HF_AUDIO_FX } from "./audioFx.js";
+import { defaultAudioFxParams, getAudioFxDef, HF_AUDIO_FX } from "./audioFx.js";
 import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";
 import { audioBandAt, BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
 
@@ -197,3 +197,25 @@ describe("the true-peak copy does not promise a hard ceiling", () => {
     expect(hint).toMatch(/headroom/);
   });
 });
+
+describe("the plain limiter copy does not promise a hard ceiling", () => {
+  // The limiter follows the signal's level with no lookahead, and Level after is applied past
+  // the ceiling, so a fast or inter-sample peak can end above it.
+  it("says nothing about never clipping or nothing getting past", () => {
+    const copy = EFFECT_COPY.limiter;
+    const summary = SUMMARY.limiter;
+    const description = getAudioFxDef("limiter")?.description;
+    if (!copy || !summary || !description) throw new Error("limiter copy is missing");
+    const shown = [
+      description,
+      copy.does,
+      copy.reachFor,
+      copy.params.limit?.label,
+      summary({}),
+    ].join("\n");
+    expect(shown).not.toMatch(
+      /never|nothing|guarantee|hard ceiling|no louder|must not|cannot exceed/i,
+    );
+    expect(shown).toMatch(/can (still )?(get )?pass|get past/i);
+  });
+});

packages/core/src/audioFxCopy.ts

@@ -152,13 +152,13 @@ export const EFFECT_COPY: Record<string, EffectCopy> = {
   },
   limiter: {
     title: "Peak Ceiling",
-    does: "Nothing gets louder than this, ever. A safety net at the end of the chain.",
-    reachFor: "You want to be sure it never clips or spikes.",
+    does: "Pulls the loudest moments down toward this ceiling. It reacts to what it hears, so a fast peak can still get past, and Level after is applied on top of it.",
+    reachFor: "You want peaks held down and can accept a small overshoot.",
     primary: "limit",
     primaryEnds: { low: "A lot of headroom", high: "Right up to the edge" },
     params: {
       limit: {
-        label: "Never exceed",
+        label: "Ceiling",
         ends: { low: "A lot of headroom", high: "Right up to the edge" },
       },
       attack: { label: "How fast it catches" },
@@ -411,7 +411,7 @@ export const SUMMARY: Record<string, (p: P) => string> = {
       : `${n(p.gain) > 0 ? "More" : "Less"} sparkle above ${hz(p.frequency)}`,
   compressor: (p) =>
     `Evening out — ${strength(Math.min(1, (n(p.ratio, 3) - 1) / 7), ["gentle", "moderate", "firm"])}`,
-  limiter: (p) => `Nothing louder than ${n(p.limit, -1)} dB`,
+  limiter: (p) => `Peaks pulled down toward ${n(p.limit, -1)} dB`,
   truepeak: (p) => `Peaks pulled down toward ${n(p.ceiling, -1)} dBTP`,
   gate: (p) => `Closing gaps quieter than ${n(p.threshold, -45)} dB`,
   saturate: (p) =>

packages/engine/src/index.ts

@@ -254,6 +254,7 @@ export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
 export {
   MIXED_AUDIO_FILENAME,
   parseAudioElements,
+  parseMasterFxChain,
   processCompositionAudio,
 } from "./services/audioMixer.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";

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

@@ -6,7 +6,12 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { applyVolumeEnvelopeToWav } from "./audioVolumeEnvelope.js";
 import { defaultAudioFxParams, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
 import { applyAudioFxChain, AudioFxRenderError, readWav, writeWav } from "./audioFxRender.js";
-import { MIXED_AUDIO_FILENAME, parseAudioElements, processCompositionAudio } from "./audioMixer.js";
+import {
+  MIXED_AUDIO_FILENAME,
+  parseAudioElements,
+  parseMasterFxChain,
+  processCompositionAudio,
+} from "./audioMixer.js";
 import { resolveHeadlessShellPath } from "./browserManager.js";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 
@@ -556,23 +561,24 @@ describe("master bus: reading it", () => {
   const CHAIN = '{"version":1,"nodes":[]}';
   const attr = `data-fx-chain='${CHAIN}'`;
 
-  it("hands the root's chain to every element as the master, not as the clip's own", () => {
-    const [a] = parseAudioElements(html(`data-composition-id="main" ${attr}`));
-    expect(a?.masterFxChain).toBe(CHAIN);
+  it("reads the root's chain as the master, not as a clip's own", () => {
+    const doc = html(`data-composition-id="main" ${attr}`);
+    expect(parseMasterFxChain(doc)).toBe(CHAIN);
+    const [a] = parseAudioElements(doc);
     expect(a?.fxChain).toBeUndefined();
     expect(a?.groupFxChain).toBeUndefined();
   });
 
   it("has none when the root carries none", () => {
-    const [a] = parseAudioElements(html(`data-composition-id="main"`));
-    expect(a?.masterFxChain).toBeUndefined();
+    expect(parseMasterFxChain(html(`data-composition-id="main"`))).toBeUndefined();
   });
 
   it("leaves a sub-composition root's chain as it was: not the master, not its clips' chain", () => {
     const inner = `<div data-composition-id="inner" ${attr}><audio id="b" src="b.wav" data-start="0" data-duration="1"></audio></div>`;
-    const [a, b] = parseAudioElements(html(`data-composition-id="main"`, inner));
+    const doc = html(`data-composition-id="main"`, inner);
+    expect(parseMasterFxChain(doc)).toBeUndefined();
+    const [a, b] = parseAudioElements(doc);
     for (const el of [a, b]) {
-      expect(el?.masterFxChain).toBeUndefined();
       expect(el?.fxChain).toBeUndefined();
       expect(el?.groupFxChain).toBeUndefined();
     }
@@ -581,10 +587,9 @@ describe("master bus: reading it", () => {
   it("takes the master from the top-level root when a sub-composition root carries one too", () => {
     const MASTER = '{"version":1,"nodes":[{"type":"gain","id":"m","params":{"gain":-3}}]}';
     const inner = `<div data-composition-id="inner" ${attr}></div>`;
-    const els = parseAudioElements(
-      html(`data-composition-id="main" data-fx-chain='${MASTER}'`, inner),
-    );
-    expect(els.map((e) => e.masterFxChain)).toEqual([MASTER]);
+    expect(
+      parseMasterFxChain(html(`data-composition-id="main" data-fx-chain='${MASTER}'`, inner)),
+    ).toBe(MASTER);
   });
 });
 
@@ -602,13 +607,14 @@ describe.skipIf(!HAS_FFMPEG)("master bus: reporting an unreadable chain", () =>
           layer: 0,
           volume: 1,
           type: "audio",
-          masterFxChain: "{not json",
         },
       ],
       dir,
       join(dir, "work"),
       join(dir, `bad-${MIXED_AUDIO_FILENAME}`),
       1,
+      undefined,
+      { masterFxChain: "{not json" },
     );
     expect(result.success).toBe(false);
     expect(result.failures?.[0]?.elementId).toBe("master");
@@ -640,16 +646,16 @@ describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {
     });
     const out = join(dir, `limited-${MIXED_AUDIO_FILENAME}`);
     const flat = join(dir, `flat-${MIXED_AUDIO_FILENAME}`);
-    const mix = (path: string, masterFxChain?: string) => {
-      const extra = masterFxChain ? { masterFxChain } : {};
-      return processCompositionAudio(
-        [element("a", extra), element("b", extra)],
+    const mix = (path: string, masterFxChain?: string) =>
+      processCompositionAudio(
+        [element("a"), element("b")],
         dir,
         join(dir, "work"),
         path,
         1,
+        undefined,
+        { masterFxChain },
       );
-    };
     expect((await mix(flat)).success).toBe(true);
     expect((await mix(out, master)).success).toBe(true);
     // The unprocessed sum has nowhere to go but full scale.
@@ -661,9 +667,18 @@ describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {
   const mixedPeakDb = async (
     name: string,
     elements: Parameters<typeof processCompositionAudio>[0],
+    masterFxChain?: string,
   ): Promise<number> => {
     const out = join(dir, `${name}-${MIXED_AUDIO_FILENAME}`);
-    const result = await processCompositionAudio(elements, dir, join(dir, "work"), out, 1);
+    const result = await processCompositionAudio(
+      elements,
+      dir,
+      join(dir, "work"),
+      out,
+      1,
+      undefined,
+      { masterFxChain },
+    );
     expect(result.success).toBe(true);
     return maxVolumeDb(out);
   };
@@ -682,11 +697,10 @@ describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {
     );
     const clip = (id: string) =>
       `<audio id="${id}" src="${id}.wav" data-start="0" data-end="1" data-duration="1"></audio>`;
-    const elements = parseAudioElements(
-      `<div data-composition-id="main" data-fx-chain='${master}'>${clip("a")}${clip("b")}</div>`,
-    );
+    const html = `<div data-composition-id="main" data-fx-chain='${master}'>${clip("a")}${clip("b")}</div>`;
+    const elements = parseAudioElements(html);
     expect(elements).toHaveLength(2);
-    expect(await mixedPeakDb("once", elements)).toBeCloseTo(-12, 0);
+    expect(await mixedPeakDb("once", elements, parseMasterFxChain(html))).toBeCloseTo(-12, 0);
   }, 180_000);
 
   it("keeps the sum in float until the chain has read it", async () => {
@@ -695,10 +709,7 @@ describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {
     writeTone("a", 0.9);
     writeTone("b", 0.9);
     const masterFxChain = chainJson({ type: "gain", params: { gain: -6 } });
-    const peak = await mixedPeakDb("float", [
-      element("a", { masterFxChain }),
-      element("b", { masterFxChain }),
-    ]);
+    const peak = await mixedPeakDb("float", [element("a"), element("b")], masterFxChain);
     expect(peak).toBeGreaterThan(-2);
   }, 180_000);
 
@@ -714,8 +725,8 @@ describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {
         params: { ceiling: -20, lookahead: 3, release: 80 },
       }),
       groupVolume: 0.5,
-      masterFxChain: chainJson({ type: "gain", params: { gain: 12 } }),
     };
-    expect(await mixedPeakDb("ordered", [element("g", group)])).toBeCloseTo(-14, 0);
+    const masterFxChain = chainJson({ type: "gain", params: { gain: 12 } });
+    expect(await mixedPeakDb("ordered", [element("g", group)], masterFxChain)).toBeCloseTo(-14, 0);
   }, 180_000);
 });

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

@@ -586,9 +586,9 @@ describe("processCompositionAudio", () => {
   });
 
   it.each([
-    ["the master pass", { masterFxChain: gainChain }],
-    ["a group bus", { groupId: "bus", groupFxChain: gainChain }],
-  ])("removes its work directory when %s throws a fatal FX error", async (_label, extra) => {
+    ["the master pass", {}, { masterFxChain: gainChain }],
+    ["a group bus", { groupId: "bus", groupFxChain: gainChain }, {}],
+  ])("removes its work directory when %s fails fatally", async (_label, extra, config) => {
     const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
     const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
     tempDirs.push(baseDir, workDir);
@@ -614,6 +614,8 @@ describe("processCompositionAudio", () => {
         workDir,
         join(baseDir, "out.m4a"),
         2,
+        undefined,
+        config,
       ),
     ).rejects.toThrow(AudioFxRenderError);
     expect(existsSync(workDir)).toBe(false);

packages/engine/src/services/audioMixer.ts

@@ -555,6 +555,15 @@ export function volumeLaneKeyframes(
   return out;
 }
 
+/**
+ * The top-level root's `data-fx-chain`. It belongs to the composition, not to a clip,
+ * so `processCompositionAudio` takes it beside the tracks: a track the render adds
+ * itself has no parsed element to carry it.
+ */
+export function parseMasterFxChain(html: string): string | undefined {
+  return readMasterFxChain(parseHTML(unwrapTemplate(html)).document);
+}
+
 export function parseAudioElements(html: string): AudioElement[] {
   const elements: AudioElement[] = [];
   const { document } = parseHTML(unwrapTemplate(html));
@@ -587,7 +596,6 @@ export function parseAudioElements(html: string): AudioElement[] {
     resolveAudioGroups(document).map((group) => [group.id, group] as const),
   );
   const memberGroupHidden = (el: AudioMediaElement): boolean => isMemberGroupHidden(groupsById, el);
-  const masterFxChain = readMasterFxChain(document);
 
   // <audio> and <video data-has-audio> tracks differ only in the emitted id
 
@@ -619,7 +627,6 @@ export function parseAudioElements(html: string): AudioElement[] {
       ...(fades.fadeOut > 0 ? { fadeOut: fades.fadeOut } : {}),
       ...(fxChain ? { fxChain } : {}),
       ...(automation ? { automation } : {}),
-      ...(masterFxChain ? { masterFxChain } : {}),
       ...(group
         ? {
             groupId: group.id,
@@ -1170,7 +1177,10 @@ export async function processCompositionAudio(
   outputPath: string,
   totalDuration: number,
   signal?: AbortSignal,
-  config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>,
+  config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">> & {
+    /** Serialised master bus chain, from `parseMasterFxChain`. */
+    masterFxChain?: string;
+  },
   compiledDir?: string,
 ): Promise<MixResult> {
   const startMs = Date.now();
@@ -1517,7 +1527,7 @@ export async function processCompositionAudio(
   // Parsed before any group is mixed, so a malformed master chain fails fast and
   // as a failure, the way an unreadable group chain does.
   let masterChain: HfAudioFxChain | undefined;
-  const masterFxJson = elements.find((element) => element.masterFxChain)?.masterFxChain;
+  const masterFxJson = config?.masterFxChain;
   if (masterFxJson) {
     try {
       masterChain = parseAudioFxChain(masterFxJson);

packages/engine/src/services/audioMixer.types.ts

@@ -35,7 +35,6 @@ export interface AudioElement {
   groupFxChain?: string;
   groupAutomation?: string;
   groupVolume?: number;
-  masterFxChain?: string;
   type: "audio" | "video";
 }
 

packages/producer/src/services/distributed/plan.masterBus.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { plan } from "./plan.js";
+
+const MASTER_CHAIN = '{"version":1,"nodes":[]}';
+const seen = vi.hoisted((): { audioInput?: { masterFxChain?: string } } => ({}));
+
+vi.mock("../render/stages/audioStage.js", () => ({
+  runAudioStage: async (input: { masterFxChain?: string; workDir: string }) => {
+    seen.audioInput = input;
+    return {
+      audioOutputPath: `${input.workDir}/audio.m4a`,
+      hasAudio: false,
+      audioProcessMs: 0,
+    };
+  },
+}));
+
+let runRoot: string;
+
+beforeEach(() => {
+  runRoot = mkdtempSync(join(tmpdir(), "hf-plan-master-bus-"));
+});
+
+afterEach(() => {
+  rmSync(runRoot, { recursive: true, force: true });
+});
+
+it("plan() gives the audio stage the composition's master chain", async () => {
+  const projectDir = join(runRoot, "project");
+  mkdirSync(projectDir, { recursive: true });
+  writeFileSync(
+    join(projectDir, "index.html"),
+    `<!doctype html>
+<html><head><meta charset="utf-8"></head><body>
+  <div data-composition-id="root" data-width="320" data-height="240" data-duration="1" data-fx-chain='${MASTER_CHAIN}'>
+    <p>master bus plan fixture</p>
+  </div>
+</body></html>`,
+    "utf-8",
+  );
+  const planDir = join(runRoot, "plan");
+  mkdirSync(planDir, { recursive: true });
+
+  await plan(projectDir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);
+
+  expect(seen.audioInput?.masterFxChain).toBe(MASTER_CHAIN);
+});