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
This commit is contained in:
Miguel Ángel
2026-11-05 16:20:28 +00:00
committed by GitHub
parent a664f99ec8
commit d40d0b251f
5 changed files with 180 additions and 34 deletions
@@ -28,6 +28,7 @@
"src/services/htmlCompiler.naturalDuration.test.ts",
"src/services/htmlCompiler.probeCount.test.ts",
"src/services/htmlCompiler.variableMedia.test.ts",
"src/services/render/audioDeliveryLimit.integration.test.ts",
"src/services/render/audioPadTrim.integration.test.ts",
"src/services/render/audioTruePeak.test.ts",
"src/services/render/blurDifferential.integration.test.ts",
@@ -62,6 +62,7 @@ import {
import { buildSyntheticRenderJob } from "./shared.js";
import { assemble } from "./assemble.js";
import { constrainAacTruePeak } from "../render/audioPadTrim.js";
import { limitDeliveryPeaks } from "../render/audioDeliveryLimit.js";
function ffmpegOrThrow(args: string[]): void {
const ffmpeg = spawnSync(getFfmpegBinary(), ["-nostdin", "-loglevel", "error", ...args]);
@@ -1072,7 +1073,7 @@ describe.skipIf(spawnSync(getFfmpegBinary(), ["-version"]).status !== 0)(
["-nostdin", "-i", join(stitched, "audio.m4a"), "-af", "volumedetect", "-f", "null", "-"],
{ encoding: "utf-8" },
);
expect(Number(/max_volume: (-?[\d.]+) dB/.exec(volume.stderr)?.[1])).toBeLessThan(-1);
expect(Number(/max_volume: (-?[\d.]+) dB/.exec(volume.stderr)?.[1])).toBeLessThanOrEqual(-1);
const withCfr = join(runRoot, "plan-stitch-cfr");
await buildLocalExecutionPlan(project, { ...config, cfr: true }, withCfr, {
@@ -1253,17 +1254,29 @@ describe.skipIf(spawnSync(getFfmpegBinary(), ["-version"]).status !== 0)(
expect(planned.chunkCount).toBe(1);
const delivered = join(runRoot, "loudness-delivered.mp4");
await assemble(planDir, [video], join(planDir, "audio.m4a"), delivered);
// Built as delivery is: the track read as 16-bit (the mixer does; noise encodes 0.4 dB hotter for it), float PCM
// fitted to the frames, then guardDeliveryPeaks: the peak limit, the whole-mix cut.
const referenceSource = join(runRoot, "loudness-reference-source.wav");
ffmpegOrThrow([
...[
"-i",
join(project, "tone.wav"),
"-af",
"aformat=sample_fmts=s16,apad,atrim=0:3.033333",
],
...["-c:a", "pcm_f32le", "-y", referenceSource],
]);
const reference = join(runRoot, "loudness-reference.m4a");
const encoded = await encodeAac(join(project, "tone.wav"), reference, 91 / 30, {
timeout: 30_000,
filter: "apad,atrim=0:3.033333",
});
const encoded = await encodeAac(referenceSource, reference, 91 / 30, { timeout: 30_000 });
expect(encoded.success, encoded.stderr).toBe(true);
const held = await constrainAacTruePeak({
const delivery = {
audioPath: reference,
sourcePath: join(project, "tone.wav"),
sourcePath: referenceSource,
targetDurationSeconds: 91 / 30,
});
};
const limited = await limitDeliveryPeaks({ ...delivery, timeoutMs: 60_000 });
expect(limited.success, limited.error).toBe(true);
const held = await constrainAacTruePeak(delivery);
expect(held.success, held.error).toBe(true);
const measure = (path: string) => {
const result = spawnSync(
@@ -0,0 +1,69 @@
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { encodeAac, getFfmpegBinary, resolveHeadlessShellPath } from "@hyperframes/engine";
import { limitDeliveryPeaks } from "./audioDeliveryLimit.js";
import { measureTruePeakDbfs } from "./audioTruePeak.js";
const ready = (path: string | undefined | null, flag: string) =>
!!path && spawnSync(path, [flag], { encoding: "utf8" }).status === 0;
const browser = (() => {
try {
return resolveHeadlessShellPath();
} catch {
// A configured path that does not exist: no browser to limit with.
return null;
}
})();
const CAN_RUN = ready(getFfmpegBinary(), "-version") && ready(browser, "--version");
const dirs: string[] = [];
afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })));
/** A drum hit every 0.5 s over a quiet bed, true peak about +0.1 dBTP, as float PCM; and its AAC. */
async function mixOverTheCeiling() {
const dir = mkdtempSync(join(tmpdir(), "hf-delivery-limit-"));
dirs.push(dir);
const sourcePath = join(dir, "audio-source.wav");
const hit = "0.98*sin(2*PI*90*t)*exp(-mod(t,0.5)*25)";
const made = spawnSync(getFfmpegBinary(), [
...["-v", "error", "-y", "-f", "lavfi", "-i"],
`aevalsrc='${hit}+0.02*sin(2*PI*1000*t)|${hit}+0.02*sin(2*PI*1500*t)':s=48000:d=6`,
...["-c:a", "pcm_f32le", sourcePath],
]);
if (made.status !== 0) throw new Error(String(made.stderr));
const audioPath = join(dir, "audio.m4a");
const encoded = await encodeAac(sourcePath, audioPath, 6, { timeout: 60_000 });
if (!encoded.success) throw new Error(encoded.stderr);
return { sourcePath, audioPath };
}
describe.skipIf(!CAN_RUN)("limitDeliveryPeaks on a real mix", () => {
// 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
// than the -1 dBTP rule asks.
it("brings the encode under -1 dBTP losing no more than 0.2 dB past it, the same bytes every time", async () => {
const runs = [];
for (let run = 0; run < 2; run++) {
const mix = await mixOverTheCeiling();
const before = await measureTruePeakDbfs(mix.audioPath, { timeoutMs: 60_000 });
expect(before).toBeGreaterThan(-1);
const limited = await limitDeliveryPeaks({
...mix,
targetDurationSeconds: 6,
timeoutMs: 120_000,
});
expect(limited.success).toBe(true);
const after = await measureTruePeakDbfs(mix.audioPath, { timeoutMs: 60_000 });
runs.push({
after,
bytes: createHash("sha256").update(readFileSync(mix.audioPath)).digest("hex"),
});
}
expect(runs[0]!.after).toBeLessThanOrEqual(-1);
expect(runs[0]!.after).toBeGreaterThanOrEqual(-1.2);
expect(runs[1]!.bytes).toBe(runs[0]!.bytes);
}, 300_000);
});
@@ -7,12 +7,14 @@ const INPUT = {
targetDurationSeconds: 8,
timeoutMs: 1000,
};
const LIMITED = "/w/audio-source-limited.wav";
const LIMITED = ["/w/audio-source-limited-a.wav", "/w/audio-source-limited-b.wav"];
function deps(peak: number) {
/** `peaks`: what each measure reads in turn, the first encode's then each limited encode's; the last one repeats. */
function deps(...peaks: number[]) {
let read = 0;
return {
measure: vi.fn(async () => peak),
applyChain: vi.fn(async () => ({ path: LIMITED, envelopeBaked: false })),
measure: vi.fn(async () => peaks[Math.min(read++, peaks.length - 1)]!),
applyChain: vi.fn(async () => ({ path: LIMITED[0]!, envelopeBaked: false })),
encode: vi.fn(async () => ({ success: true })),
rename: vi.fn(),
sourceExists: vi.fn(() => true),
@@ -30,21 +32,46 @@ describe("limitDeliveryPeaks", () => {
expect(d.encode).not.toHaveBeenCalled();
});
it("re-encodes a mix over the ceiling through a true-peak limit 2 dB under it", async () => {
const d = deps(2.4);
const ceilings = (d: ReturnType<typeof deps>) =>
d.applyChain.mock.calls.map(
([, chain]) =>
(chain as { nodes: { params: { ceiling: number } }[] }).nodes[0]!.params.ceiling,
);
it("limits a mix over the ceiling at the ceiling itself when its encode lands under", async () => {
const d = deps(2.4, -1.1);
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
expect(ceilings(d)).toEqual([-1]);
expect(d.applyChain).toHaveBeenCalledWith(
INPUT.sourcePath,
{
version: 1,
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: -3 } }],
},
LIMITED,
expect.anything(),
LIMITED[0],
expect.anything(),
);
expect(d.encode).toHaveBeenCalledWith(LIMITED, INPUT.audioPath, 8, expect.anything());
expect(d.encode).toHaveBeenCalledWith(LIMITED[0], INPUT.audioPath, 8, expect.anything());
// The whole-mix cut behind this measures against the limited mix, not the original.
expect(d.rename).toHaveBeenCalledWith(LIMITED, INPUT.sourcePath, { copyFallback: true });
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
});
it("lowers the ceiling by what each encode measured over, from the original mix, never past -3", async () => {
const d = deps(2.4, -0.4, -0.9, 0.5);
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
expect(ceilings(d).map((c) => Number(c.toFixed(2)))).toEqual([-1, -1.65, -1.8]);
expect(d.applyChain.mock.calls.every(([from]) => from === INPUT.sourcePath)).toBe(true);
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
const deep = deps(2.4, 3, 3);
await limitDeliveryPeaks(INPUT, deep as unknown as Deps);
expect(ceilings(deep)).toEqual([-1, -3]);
});
it("keeps the last good pass when a later limit cannot run", async () => {
const d = deps(2.4, -0.5);
d.applyChain.mockResolvedValueOnce({ path: LIMITED[0]!, envelopeBaked: false });
d.applyChain.mockRejectedValueOnce(new Error("browser gone"));
await limitDeliveryPeaks(INPUT, d as unknown as Deps);
expect(d.encode).toHaveBeenCalledTimes(1);
expect(d.rename).toHaveBeenCalledWith(LIMITED[0], INPUT.sourcePath, { copyFallback: true });
});
it("leaves the first encode for the whole-mix cut when the limit cannot run, and says so", async () => {
@@ -9,12 +9,14 @@ import {
import { AAC_DELIVERY_TRUE_PEAK_DBFS } from "./audioPadTrim.js";
import { measureTruePeakDbfs } from "./audioTruePeak.js";
// The worklet's 4x detector can land up to 1.7 dB over its ceiling, hence 2 dB under the -1 dBTP limit.
const LIMIT_CEILING_DBTP = AAC_DELIVERY_TRUE_PEAK_DBFS - 2;
const LIMIT_CHAIN = {
// Each pass lowers the ceiling by what the last encode measured over it; past -3 dBTP the whole-mix cut takes over.
const LIMIT_PASSES = 3;
const LOWEST_CEILING_DBTP = AAC_DELIVERY_TRUE_PEAK_DBFS - 2;
const PASS_HEADROOM_DB = 0.05;
const limitChain = (ceiling: number) => ({
version: 1 as const,
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling: LIMIT_CEILING_DBTP } }],
};
nodes: [{ type: "truepeak", id: "delivery", params: { ceiling } }],
});
interface DeliveryLimitDeps {
measure: typeof measureTruePeakDbfs;
@@ -48,15 +50,48 @@ export async function limitDeliveryPeaks(
const peak = await deps.measure(audioPath, { timeoutMs, signal });
if (peak <= AAC_DELIVERY_TRUE_PEAK_DBFS) return { success: true };
const limitedPath = join(dirname(sourcePath), "audio-source-limited.wav");
const alternating = ["a", "b"].map((k) =>
join(dirname(sourcePath), `audio-source-limited-${k}.wav`),
);
let encodedFrom: string | undefined;
let ceiling = AAC_DELIVERY_TRUE_PEAK_DBFS;
for (let pass = 0; pass < LIMIT_PASSES; pass++) {
const limitedPath = alternating[pass % 2]!;
const result = await limitPass(input, deps, ceiling, limitedPath);
if ("encodeFailure" in result) return result.encodeFailure;
if ("limitFailed" in result) break;
encodedFrom = limitedPath;
if (result.peak <= AAC_DELIVERY_TRUE_PEAK_DBFS || ceiling <= LOWEST_CEILING_DBTP) break;
ceiling = Math.max(
ceiling - (result.peak - AAC_DELIVERY_TRUE_PEAK_DBFS) - PASS_HEADROOM_DB,
LOWEST_CEILING_DBTP,
);
}
if (encodedFrom) deps.rename(encodedFrom, sourcePath, { copyFallback: true });
return { success: true };
}
type DeliveryLimitResult = Awaited<ReturnType<typeof limitDeliveryPeaks>>;
/** One pass: the original mix limited at `ceiling` into `limitedPath`, encoded to the delivery file, and measured. */
async function limitPass(
input: Parameters<typeof limitDeliveryPeaks>[0],
deps: DeliveryLimitDeps,
ceiling: number,
limitedPath: string,
): Promise<{ peak: number } | { limitFailed: true } | { encodeFailure: DeliveryLimitResult }> {
const { audioPath, sourcePath, signal, timeoutMs } = input;
try {
await deps.applyChain(sourcePath, LIMIT_CHAIN, limitedPath, { trackId: "delivery", signal });
await deps.applyChain(sourcePath, limitChain(ceiling), limitedPath, {
trackId: "delivery",
signal,
});
} catch (error) {
if (signal?.aborted) throw error;
input.warn?.("[audio] true-peak limit failed, the whole-mix cut applies", {
error: error instanceof Error ? error.message : String(error),
});
return { success: true };
return { limitFailed: true };
}
const encoded = await deps.encode(limitedPath, audioPath, input.targetDurationSeconds, {
signal,
@@ -64,11 +99,12 @@ export async function limitDeliveryPeaks(
});
if (!encoded.success) {
return {
success: false,
error: `[audioDeliveryLimit] ${describeFfmpegFailure(encoded, timeoutMs)}`,
failureReason: encoded.failureReason,
encodeFailure: {
success: false,
error: `[audioDeliveryLimit] ${describeFfmpegFailure(encoded, timeoutMs)}`,
failureReason: encoded.failureReason,
},
};
}
deps.rename(limitedPath, sourcePath, { copyFallback: true });
return { success: true };
return { peak: await deps.measure(audioPath, { timeoutMs, signal }) };
}