mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
@@ -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 }) };
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user