Skip to content

Commit d40d0b2

Browse files
fix(producer): an export over the peak ceiling loses only what it must (#7246)
* fix(producer): an export over the peak ceiling loses only what it must The delivery limiter cut every peak over -1 dBTP down to -3, a fixed 2 dB margin for its detector. It now limits at -1, measures the encode, and lowers the ceiling only by what that encode measured over. * fix(producer): the delivery limit test runs in CI and one pass is its own step * test(producer): build the loudness reference from the 16-bit track the mixer reads
1 parent a664f99 commit d40d0b2

5 files changed

Lines changed: 180 additions & 34 deletions

File tree

‎packages/producer/scripts/integration-tests.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
"src/services/htmlCompiler.naturalDuration.test.ts",
2929
"src/services/htmlCompiler.probeCount.test.ts",
3030
"src/services/htmlCompiler.variableMedia.test.ts",
31+
"src/services/render/audioDeliveryLimit.integration.test.ts",
3132
"src/services/render/audioPadTrim.integration.test.ts",
3233
"src/services/render/audioTruePeak.test.ts",
3334
"src/services/render/blurDifferential.integration.test.ts",

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

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ import {
6262
import { buildSyntheticRenderJob } from "./shared.js";
6363
import { assemble } from "./assemble.js";
6464
import { constrainAacTruePeak } from "../render/audioPadTrim.js";
65+
import { limitDeliveryPeaks } from "../render/audioDeliveryLimit.js";
6566

6667
function ffmpegOrThrow(args: string[]): void {
6768
const ffmpeg = spawnSync(getFfmpegBinary(), ["-nostdin", "-loglevel", "error", ...args]);
@@ -1072,7 +1073,7 @@ describe.skipIf(spawnSync(getFfmpegBinary(), ["-version"]).status !== 0)(
10721073
["-nostdin", "-i", join(stitched, "audio.m4a"), "-af", "volumedetect", "-f", "null", "-"],
10731074
{ encoding: "utf-8" },
10741075
);
1075-
expect(Number(/max_volume: (-?[\d.]+) dB/.exec(volume.stderr)?.[1])).toBeLessThan(-1);
1076+
expect(Number(/max_volume: (-?[\d.]+) dB/.exec(volume.stderr)?.[1])).toBeLessThanOrEqual(-1);
10761077

10771078
const withCfr = join(runRoot, "plan-stitch-cfr");
10781079
await buildLocalExecutionPlan(project, { ...config, cfr: true }, withCfr, {
@@ -1253,17 +1254,29 @@ describe.skipIf(spawnSync(getFfmpegBinary(), ["-version"]).status !== 0)(
12531254
expect(planned.chunkCount).toBe(1);
12541255
const delivered = join(runRoot, "loudness-delivered.mp4");
12551256
await assemble(planDir, [video], join(planDir, "audio.m4a"), delivered);
1257+
// Built as delivery is: the track read as 16-bit (the mixer does; noise encodes 0.4 dB hotter for it), float PCM
1258+
// fitted to the frames, then guardDeliveryPeaks: the peak limit, the whole-mix cut.
1259+
const referenceSource = join(runRoot, "loudness-reference-source.wav");
1260+
ffmpegOrThrow([
1261+
...[
1262+
"-i",
1263+
join(project, "tone.wav"),
1264+
"-af",
1265+
"aformat=sample_fmts=s16,apad,atrim=0:3.033333",
1266+
],
1267+
...["-c:a", "pcm_f32le", "-y", referenceSource],
1268+
]);
12561269
const reference = join(runRoot, "loudness-reference.m4a");
1257-
const encoded = await encodeAac(join(project, "tone.wav"), reference, 91 / 30, {
1258-
timeout: 30_000,
1259-
filter: "apad,atrim=0:3.033333",
1260-
});
1270+
const encoded = await encodeAac(referenceSource, reference, 91 / 30, { timeout: 30_000 });
12611271
expect(encoded.success, encoded.stderr).toBe(true);
1262-
const held = await constrainAacTruePeak({
1272+
const delivery = {
12631273
audioPath: reference,
1264-
sourcePath: join(project, "tone.wav"),
1274+
sourcePath: referenceSource,
12651275
targetDurationSeconds: 91 / 30,
1266-
});
1276+
};
1277+
const limited = await limitDeliveryPeaks({ ...delivery, timeoutMs: 60_000 });
1278+
expect(limited.success, limited.error).toBe(true);
1279+
const held = await constrainAacTruePeak(delivery);
12671280
expect(held.success, held.error).toBe(true);
12681281
const measure = (path: string) => {
12691282
const result = spawnSync(
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
import { spawnSync } from "node:child_process";
2+
import { createHash } from "node:crypto";
3+
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
4+
import { tmpdir } from "node:os";
5+
import { join } from "node:path";
6+
import { afterEach, describe, expect, it } from "vitest";
7+
import { encodeAac, getFfmpegBinary, resolveHeadlessShellPath } from "@hyperframes/engine";
8+
import { limitDeliveryPeaks } from "./audioDeliveryLimit.js";
9+
import { measureTruePeakDbfs } from "./audioTruePeak.js";
10+
11+
const ready = (path: string | undefined | null, flag: string) =>
12+
!!path && spawnSync(path, [flag], { encoding: "utf8" }).status === 0;
13+
const browser = (() => {
14+
try {
15+
return resolveHeadlessShellPath();
16+
} catch {
17+
// A configured path that does not exist: no browser to limit with.
18+
return null;
19+
}
20+
})();
21+
const CAN_RUN = ready(getFfmpegBinary(), "-version") && ready(browser, "--version");
22+
23+
const dirs: string[] = [];
24+
afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })));
25+
26+
/** A drum hit every 0.5 s over a quiet bed, true peak about +0.1 dBTP, as float PCM; and its AAC. */
27+
async function mixOverTheCeiling() {
28+
const dir = mkdtempSync(join(tmpdir(), "hf-delivery-limit-"));
29+
dirs.push(dir);
30+
const sourcePath = join(dir, "audio-source.wav");
31+
const hit = "0.98*sin(2*PI*90*t)*exp(-mod(t,0.5)*25)";
32+
const made = spawnSync(getFfmpegBinary(), [
33+
...["-v", "error", "-y", "-f", "lavfi", "-i"],
34+
`aevalsrc='${hit}+0.02*sin(2*PI*1000*t)|${hit}+0.02*sin(2*PI*1500*t)':s=48000:d=6`,
35+
...["-c:a", "pcm_f32le", sourcePath],
36+
]);
37+
if (made.status !== 0) throw new Error(String(made.stderr));
38+
const audioPath = join(dir, "audio.m4a");
39+
const encoded = await encodeAac(sourcePath, audioPath, 6, { timeout: 60_000 });
40+
if (!encoded.success) throw new Error(encoded.stderr);
41+
return { sourcePath, audioPath };
42+
}
43+
44+
describe.skipIf(!CAN_RUN)("limitDeliveryPeaks on a real mix", () => {
45+
// fails without the fix: one pass at a fixed -3 dBTP left this mix at about -2.9 dBTP, 1.9 dB more off every hit
46+
// than the -1 dBTP rule asks.
47+
it("brings the encode under -1 dBTP losing no more than 0.2 dB past it, the same bytes every time", async () => {
48+
const runs = [];
49+
for (let run = 0; run < 2; run++) {
50+
const mix = await mixOverTheCeiling();
51+
const before = await measureTruePeakDbfs(mix.audioPath, { timeoutMs: 60_000 });
52+
expect(before).toBeGreaterThan(-1);
53+
const limited = await limitDeliveryPeaks({
54+
...mix,
55+
targetDurationSeconds: 6,
56+
timeoutMs: 120_000,
57+
});
58+
expect(limited.success).toBe(true);
59+
const after = await measureTruePeakDbfs(mix.audioPath, { timeoutMs: 60_000 });
60+
runs.push({
61+
after,
62+
bytes: createHash("sha256").update(readFileSync(mix.audioPath)).digest("hex"),
63+
});
64+
}
65+
expect(runs[0]!.after).toBeLessThanOrEqual(-1);
66+
expect(runs[0]!.after).toBeGreaterThanOrEqual(-1.2);
67+
expect(runs[1]!.bytes).toBe(runs[0]!.bytes);
68+
}, 300_000);
69+
});

‎packages/producer/src/services/render/audioDeliveryLimit.test.ts‎

Lines changed: 40 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,14 @@ const INPUT = {
77
targetDurationSeconds: 8,
88
timeoutMs: 1000,
99
};
10-
const LIMITED = "/w/audio-source-limited.wav";
10+
const LIMITED = ["/w/audio-source-limited-a.wav", "/w/audio-source-limited-b.wav"];
1111

12-
function deps(peak: number) {
12+
/** `peaks`: what each measure reads in turn, the first encode's then each limited encode's; the last one repeats. */
13+
function deps(...peaks: number[]) {
14+
let read = 0;
1315
return {
14-
measure: vi.fn(async () => peak),
15-
applyChain: vi.fn(async () => ({ path: LIMITED, envelopeBaked: false })),
16+
measure: vi.fn(async () => peaks[Math.min(read++, peaks.length - 1)]!),
17+
applyChain: vi.fn(async () => ({ path: LIMITED[0]!, envelopeBaked: false })),
1618
encode: vi.fn(async () => ({ success: true })),
1719
rename: vi.fn(),
1820
sourceExists: vi.fn(() => true),
@@ -30,21 +32,46 @@ describe("limitDeliveryPeaks", () => {
3032
expect(d.encode).not.toHaveBeenCalled();
3133
});
3234

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+
const ceilings = (d: ReturnType<typeof deps>) =>
36+
d.applyChain.mock.calls.map(
37+
([, chain]) =>
38+
(chain as { nodes: { params: { ceiling: number } }[] }).nodes[0]!.params.ceiling,
39+
);
40+
41+
it("limits a mix over the ceiling at the ceiling itself when its encode lands under", async () => {
42+
const d = deps(2.4, -1.1);
3543
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
44+
expect(ceilings(d)).toEqual([-1]);
3645
expect(d.applyChain).toHaveBeenCalledWith(
3746
INPUT.sourcePath,
38-
{
39-
version: 1,
40-
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: -3 } }],
41-
},
42-
LIMITED,
47+
expect.anything(),
48+
LIMITED[0],
4349
expect.anything(),
4450
);
45-
expect(d.encode).toHaveBeenCalledWith(LIMITED, INPUT.audioPath, 8, expect.anything());
51+
expect(d.encode).toHaveBeenCalledWith(LIMITED[0], INPUT.audioPath, 8, expect.anything());
4652
// The whole-mix cut behind this measures against the limited mix, not the original.
47-
expect(d.rename).toHaveBeenCalledWith(LIMITED, INPUT.sourcePath, { copyFallback: true });
53+
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
54+
});
55+
56+
it("lowers the ceiling by what each encode measured over, from the original mix, never past -3", async () => {
57+
const d = deps(2.4, -0.4, -0.9, 0.5);
58+
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
59+
expect(ceilings(d).map((c) => Number(c.toFixed(2)))).toEqual([-1, -1.65, -1.8]);
60+
expect(d.applyChain.mock.calls.every(([from]) => from === INPUT.sourcePath)).toBe(true);
61+
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
62+
63+
const deep = deps(2.4, 3, 3);
64+
await limitDeliveryPeaks(INPUT, deep as unknown as Deps);
65+
expect(ceilings(deep)).toEqual([-1, -3]);
66+
});
67+
68+
it("keeps the last good pass when a later limit cannot run", async () => {
69+
const d = deps(2.4, -0.5);
70+
d.applyChain.mockResolvedValueOnce({ path: LIMITED[0]!, envelopeBaked: false });
71+
d.applyChain.mockRejectedValueOnce(new Error("browser gone"));
72+
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
73+
expect(d.encode).toHaveBeenCalledTimes(1);
74+
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
4875
});
4976

5077
it("leaves the first encode for the whole-mix cut when the limit cannot run, and says so", async () => {

‎packages/producer/src/services/render/audioDeliveryLimit.ts‎

Lines changed: 49 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,14 @@ import {
99
import { AAC_DELIVERY_TRUE_PEAK_DBFS } from "./audioPadTrim.js";
1010
import { measureTruePeakDbfs } from "./audioTruePeak.js";
1111

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 = {
12+
// Each pass lowers the ceiling by what the last encode measured over it; past -3 dBTP the whole-mix cut takes over.
13+
const LIMIT_PASSES = 3;
14+
const LOWEST_CEILING_DBTP = AAC_DELIVERY_TRUE_PEAK_DBFS - 2;
15+
const PASS_HEADROOM_DB = 0.05;
16+
const limitChain = (ceiling: number) => ({
1517
version: 1 as const,
16-
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: LIMIT_CEILING_DBTP } }],
17-
};
18+
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling } }],
19+
});
1820

1921
interface DeliveryLimitDeps {
2022
measure: typeof measureTruePeakDbfs;
@@ -48,27 +50,61 @@ export async function limitDeliveryPeaks(
4850
const peak = await deps.measure(audioPath, { timeoutMs, signal });
4951
if (peak <= AAC_DELIVERY_TRUE_PEAK_DBFS) return { success: true };
5052

51-
const limitedPath = join(dirname(sourcePath), "audio-source-limited.wav");
53+
const alternating = ["a", "b"].map((k) =>
54+
join(dirname(sourcePath), `audio-source-limited-${k}.wav`),
55+
);
56+
let encodedFrom: string | undefined;
57+
let ceiling = AAC_DELIVERY_TRUE_PEAK_DBFS;
58+
for (let pass = 0; pass < LIMIT_PASSES; pass++) {
59+
const limitedPath = alternating[pass % 2]!;
60+
const result = await limitPass(input, deps, ceiling, limitedPath);
61+
if ("encodeFailure" in result) return result.encodeFailure;
62+
if ("limitFailed" in result) break;
63+
encodedFrom = limitedPath;
64+
if (result.peak <= AAC_DELIVERY_TRUE_PEAK_DBFS || ceiling <= LOWEST_CEILING_DBTP) break;
65+
ceiling = Math.max(
66+
ceiling - (result.peak - AAC_DELIVERY_TRUE_PEAK_DBFS) - PASS_HEADROOM_DB,
67+
LOWEST_CEILING_DBTP,
68+
);
69+
}
70+
if (encodedFrom) deps.rename(encodedFrom, sourcePath, { copyFallback: true });
71+
return { success: true };
72+
}
73+
74+
type DeliveryLimitResult = Awaited<ReturnType<typeof limitDeliveryPeaks>>;
75+
76+
/** One pass: the original mix limited at `ceiling` into `limitedPath`, encoded to the delivery file, and measured. */
77+
async function limitPass(
78+
input: Parameters<typeof limitDeliveryPeaks>[0],
79+
deps: DeliveryLimitDeps,
80+
ceiling: number,
81+
limitedPath: string,
82+
): Promise<{ peak: number } | { limitFailed: true } | { encodeFailure: DeliveryLimitResult }> {
83+
const { audioPath, sourcePath, signal, timeoutMs } = input;
5284
try {
53-
await deps.applyChain(sourcePath, LIMIT_CHAIN, limitedPath, { trackId: "delivery", signal });
85+
await deps.applyChain(sourcePath, limitChain(ceiling), limitedPath, {
86+
trackId: "delivery",
87+
signal,
88+
});
5489
} catch (error) {
5590
if (signal?.aborted) throw error;
5691
input.warn?.("[audio] true-peak limit failed, the whole-mix cut applies", {
5792
error: error instanceof Error ? error.message : String(error),
5893
});
59-
return { success: true };
94+
return { limitFailed: true };
6095
}
6196
const encoded = await deps.encode(limitedPath, audioPath, input.targetDurationSeconds, {
6297
signal,
6398
timeout: timeoutMs,
6499
});
65100
if (!encoded.success) {
66101
return {
67-
success: false,
68-
error: `[audioDeliveryLimit] ${describeFfmpegFailure(encoded, timeoutMs)}`,
69-
failureReason: encoded.failureReason,
102+
encodeFailure: {
103+
success: false,
104+
error: `[audioDeliveryLimit] ${describeFfmpegFailure(encoded, timeoutMs)}`,
105+
failureReason: encoded.failureReason,
106+
},
70107
};
71108
}
72-
deps.rename(limitedPath, sourcePath, { copyFallback: true });
73-
return { success: true };
109+
return { peak: await deps.measure(audioPath, { timeoutMs, signal }) };
74110
}

0 commit comments

Comments
 (0)