Skip to content

Commit d1d631f

Browse files
fix(producer): an export over the ceiling limits its peaks and keeps the mix's level (#6940)
1 parent 89a5953 commit d1d631f

6 files changed

Lines changed: 186 additions & 3 deletions

File tree

‎docs/reference/audio-effects.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,9 +147,10 @@ the others down.
147147
or put a `truepeak` on the
148148
[master bus](#the-master-bus-data-fx-chain-on-the-composition-root); a `limiter`
149149
can let fast peaks through.
150-
- Export keeps the delivered file under -1 dBTP. If a peak passes that, it lowers
151-
the **whole mix** by one flat amount, quiet passages included, and the CLI prints
152-
an `audio_lowered` warning.
150+
- Export keeps the delivered file under -1 dBTP. A mix that passes it goes through
151+
a `truepeak` at -3 dBTP, so only its peaks come down. If a peak still gets over,
152+
export lowers the **whole mix** by one flat amount, quiet passages included, and
153+
the CLI prints an `audio_lowered` warning.
153154
- The render's master gain, `PRODUCER_AUDIO_GAIN` (default `1`), multiplies the
154155
finished sum once, before the master bus chain.
155156
- To check a level, compare the export against its source scaled by the

‎packages/engine/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -405,6 +405,7 @@ export {
405405
type RunFfmpegResult,
406406
} from "./utils/runFfmpeg.js";
407407
export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
408+
export { applyAudioFxChain } from "./services/audioFxRender.js";
408409
export {
409410
ManagedChildProcess,
410411
type ManagedChildProcessOptions,
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import { describe, expect, it, vi } from "vitest";
2+
import { limitDeliveryPeaks } from "./audioDeliveryLimit.js";
3+
4+
const INPUT = {
5+
audioPath: "/w/audio.m4a",
6+
sourcePath: "/w/audio-source.wav",
7+
targetDurationSeconds: 8,
8+
timeoutMs: 1000,
9+
};
10+
const LIMITED = "/w/audio-source-limited.wav";
11+
12+
function deps(peak: number) {
13+
return {
14+
measure: vi.fn(async () => peak),
15+
applyChain: vi.fn(async () => ({ path: LIMITED, envelopeBaked: false })),
16+
encode: vi.fn(async () => ({ success: true })),
17+
rename: vi.fn(),
18+
sourceExists: vi.fn(() => true),
19+
};
20+
}
21+
type Deps = NonNullable<Parameters<typeof limitDeliveryPeaks>[1]>;
22+
23+
describe("limitDeliveryPeaks", () => {
24+
it("leaves a mix under the ceiling alone, with no browser and no encode", async () => {
25+
const d = deps(-1);
26+
await expect(limitDeliveryPeaks(INPUT, d as unknown as Deps)).resolves.toEqual({
27+
success: true,
28+
});
29+
expect(d.applyChain).not.toHaveBeenCalled();
30+
expect(d.encode).not.toHaveBeenCalled();
31+
});
32+
33+
it("re-encodes a mix over the ceiling through a true-peak limit 2 dB under it", async () => {
34+
const d = deps(2.4);
35+
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
36+
expect(d.applyChain).toHaveBeenCalledWith(
37+
INPUT.sourcePath,
38+
{
39+
version: 1,
40+
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: -3 } }],
41+
},
42+
LIMITED,
43+
expect.anything(),
44+
);
45+
expect(d.encode).toHaveBeenCalledWith(LIMITED, INPUT.audioPath, 8, expect.anything());
46+
// The whole-mix cut behind this measures against the limited mix, not the original.
47+
expect(d.rename).toHaveBeenCalledWith(LIMITED, INPUT.sourcePath, { copyFallback: true });
48+
});
49+
50+
it("leaves the first encode for the whole-mix cut when the limit cannot run, and says so", async () => {
51+
const d = deps(2.4);
52+
d.applyChain.mockRejectedValueOnce(new Error("no browser"));
53+
const warn = vi.fn();
54+
await expect(limitDeliveryPeaks({ ...INPUT, warn }, d as unknown as Deps)).resolves.toEqual({
55+
success: true,
56+
});
57+
expect(warn).toHaveBeenCalledWith(expect.stringContaining("whole-mix"), {
58+
error: "no browser",
59+
});
60+
expect(d.encode).not.toHaveBeenCalled();
61+
});
62+
63+
it("fails the render when the limited mix cannot be encoded", async () => {
64+
const d = deps(2.4);
65+
d.encode.mockResolvedValueOnce({
66+
success: false,
67+
exitCode: 1,
68+
stderr: "encoder died",
69+
terminationReason: "exit",
70+
} as never);
71+
const result = await limitDeliveryPeaks(INPUT, d as unknown as Deps);
72+
expect(result.success).toBe(false);
73+
expect(result.error).toContain("audioDeliveryLimit");
74+
expect(d.rename).not.toHaveBeenCalled();
75+
});
76+
77+
it("does nothing when the mix left no source to limit", async () => {
78+
const d = deps(2.4);
79+
d.sourceExists.mockReturnValueOnce(false);
80+
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
81+
expect(d.measure).not.toHaveBeenCalled();
82+
});
83+
});
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import { existsSync } from "node:fs";
2+
import { dirname, join } from "node:path";
3+
import {
4+
applyAudioFxChain,
5+
describeFfmpegFailure,
6+
encodeAac,
7+
renameWithRetry,
8+
} from "@hyperframes/engine";
9+
import { AAC_DELIVERY_TRUE_PEAK_DBFS } from "./audioPadTrim.js";
10+
import { measureTruePeakDbfs } from "./audioTruePeak.js";
11+
12+
// The worklet's 4x detector can land up to 1.7 dB over its ceiling, hence 2 dB under the -1 dBTP limit.
13+
const LIMIT_CEILING_DBTP = AAC_DELIVERY_TRUE_PEAK_DBFS - 2;
14+
const LIMIT_CHAIN = {
15+
version: 1 as const,
16+
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: LIMIT_CEILING_DBTP } }],
17+
};
18+
19+
interface DeliveryLimitDeps {
20+
measure: typeof measureTruePeakDbfs;
21+
applyChain: typeof applyAudioFxChain;
22+
encode: typeof encodeAac;
23+
rename: typeof renameWithRetry;
24+
sourceExists: (path: string) => boolean;
25+
}
26+
27+
/** Holds a mix over the delivery ceiling to it peak by peak, so quiet passages keep their level. The whole-mix cut
28+
* in `constrainAacTruePeak` stays behind this, for what still gets over or a mix this could not limit. */
29+
export async function limitDeliveryPeaks(
30+
input: {
31+
audioPath: string;
32+
sourcePath: string;
33+
targetDurationSeconds: number;
34+
signal?: AbortSignal;
35+
timeoutMs: number;
36+
warn?: (message: string, details: { error: string }) => void;
37+
},
38+
deps: DeliveryLimitDeps = {
39+
measure: measureTruePeakDbfs,
40+
applyChain: applyAudioFxChain,
41+
encode: encodeAac,
42+
rename: renameWithRetry,
43+
sourceExists: existsSync,
44+
},
45+
): Promise<{ success: boolean; error?: string; failureReason?: "external_interruption" }> {
46+
const { audioPath, sourcePath, signal, timeoutMs } = input;
47+
if (!deps.sourceExists(sourcePath)) return { success: true };
48+
const peak = await deps.measure(audioPath, { timeoutMs, signal });
49+
if (peak <= AAC_DELIVERY_TRUE_PEAK_DBFS) return { success: true };
50+
51+
const limitedPath = join(dirname(sourcePath), "audio-source-limited.wav");
52+
try {
53+
await deps.applyChain(sourcePath, LIMIT_CHAIN, limitedPath, { trackId: "delivery", signal });
54+
} catch (error) {
55+
if (signal?.aborted) throw error;
56+
input.warn?.("[audio] true-peak limit failed, the whole-mix cut applies", {
57+
error: error instanceof Error ? error.message : String(error),
58+
});
59+
return { success: true };
60+
}
61+
const encoded = await deps.encode(limitedPath, audioPath, input.targetDurationSeconds, {
62+
signal,
63+
timeout: timeoutMs,
64+
});
65+
if (!encoded.success) {
66+
return {
67+
success: false,
68+
error: `[audioDeliveryLimit] ${describeFfmpegFailure(encoded, timeoutMs)}`,
69+
failureReason: encoded.failureReason,
70+
};
71+
}
72+
deps.rename(limitedPath, sourcePath, { copyFallback: true });
73+
return { success: true };
74+
}

‎packages/producer/src/services/render/stages/audioStage.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ const { processCompositionAudioMock, constrainAacTruePeakMock } = vi.hoisted(()
1414
}));
1515

1616
vi.mock("../audioPadTrim.js", () => ({ constrainAacTruePeak: constrainAacTruePeakMock }));
17+
const limitDeliveryPeaksMock = vi.hoisted(() => vi.fn(async () => ({ success: true })));
18+
vi.mock("../audioDeliveryLimit.js", () => ({ limitDeliveryPeaks: limitDeliveryPeaksMock }));
1719

1820
vi.mock("@hyperframes/engine", async (importOriginal) => {
1921
const actual = await importOriginal<typeof import("@hyperframes/engine")>();
@@ -74,6 +76,18 @@ describe("runAudioStage", () => {
7476
},
7577
);
7678

79+
it("limits the mix's peaks before the whole-mix cut measures it", async () => {
80+
processCompositionAudioMock.mockResolvedValueOnce({ success: true, tracksProcessed: 1 });
81+
limitDeliveryPeaksMock.mockClear();
82+
constrainAacTruePeakMock.mockClear();
83+
84+
await runAudioStage(makeInput());
85+
86+
expect(limitDeliveryPeaksMock.mock.invocationCallOrder[0]).toBeLessThan(
87+
constrainAacTruePeakMock.mock.invocationCallOrder[0] as number,
88+
);
89+
});
90+
7791
it("keeps PCM through the encoded peak check and removes it afterwards", async () => {
7892
const input = makeInput();
7993
const pcm = join(input.workDir, "audio-source.wav");

‎packages/producer/src/services/render/stages/audioStage.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ import {
3131
import type { CompositionMetadata } from "../shared.js";
3232
import type { ProducerLogger } from "../../../logger.js";
3333
import { encoderFailureError } from "../encoderInterruption.js";
34+
import { limitDeliveryPeaks } from "../audioDeliveryLimit.js";
3435
import { constrainAacTruePeak } from "../audioPadTrim.js";
3536

3637
export interface AudioStageInput {
@@ -108,6 +109,15 @@ async function runAudioStageScoped(input: AudioStageInput): Promise<AudioStageRe
108109
let audioLoweredDb: number | undefined;
109110
if (result.hasAudio) {
110111
const guardStart = Date.now();
112+
const limited = await limitDeliveryPeaks({
113+
audioPath: result.audioOutputPath,
114+
sourcePath: pcmSourcePath,
115+
targetDurationSeconds: duration,
116+
signal: input.abortSignal,
117+
timeoutMs: input.ffmpegProcessTimeout,
118+
warn: (message, details) => input.log?.warn?.(message, details),
119+
});
120+
if (!limited.success) throw encoderFailureError("Audio true-peak limit failed", limited);
111121
const peak = await constrainAacTruePeak({
112122
audioPath: result.audioOutputPath,
113123
sourcePath: pcmSourcePath,

0 commit comments

Comments
 (0)