Skip to content

Commit cb44fe1

Browse files
fix(producer): constrain delivered AAC true peak (#3644)
1 parent 32f9ed9 commit cb44fe1

3 files changed

Lines changed: 286 additions & 3 deletions

File tree

‎packages/producer/src/services/render/audioPadTrim.integration.test.ts‎

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,40 @@ import { mkdtempSync, rmSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { afterEach, describe, expect, it } from "vitest";
6+
import { getFfmpegBinary, muxVideoWithAudio } from "@hyperframes/engine";
67
import { padOrTrimAudioToVideoFrameCount } from "./audioPadTrim.js";
78

89
const dirs: string[] = [];
910
afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })));
1011

12+
function measureLoudness(path: string): { integratedLufs: number; truePeakDbfs: number } {
13+
const result = spawnSync(
14+
getFfmpegBinary(),
15+
[
16+
"-nostdin",
17+
"-hide_banner",
18+
"-nostats",
19+
"-i",
20+
path,
21+
"-af",
22+
"ebur128=peak=true",
23+
"-f",
24+
"null",
25+
"-",
26+
],
27+
{ encoding: "utf8" },
28+
);
29+
const integrated = [...result.stderr.matchAll(/^\s*I:\s*([+-]?[\d.]+) LUFS$/gm)].at(-1)?.[1];
30+
const truePeak = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?[\d.]+) dBFS$/gm)].at(-1)?.[1];
31+
if (result.status !== 0 || integrated === undefined || truePeak === undefined) {
32+
throw new Error(`Could not measure loudness: ${result.stderr}`);
33+
}
34+
return { integratedLufs: Number(integrated), truePeakDbfs: Number(truePeak) };
35+
}
36+
1137
const hasFfmpeg = (() => {
1238
try {
13-
execFileSync("ffmpeg", ["-version"], { stdio: "ignore" });
39+
execFileSync(getFfmpegBinary(), ["-version"], { stdio: "ignore" });
1440
execFileSync("ffprobe", ["-version"], { stdio: "ignore" });
1541
return true;
1642
} catch {
@@ -79,4 +105,77 @@ describe.skipIf(!hasFfmpeg)("audio pad real-media packet contract", () => {
79105
expect(duration).toBeLessThan(16.1);
80106
expect(Number(packets.at(-1)?.duration_time)).toBeLessThan(0.1);
81107
});
108+
109+
it("keeps the delivered AAC below its true-peak ceiling", async () => {
110+
const dir = mkdtempSync(join(tmpdir(), "hf-aac-peak-"));
111+
dirs.push(dir);
112+
const source = join(dir, "source.wav");
113+
const mixed = join(dir, "mixed.m4a");
114+
const video = join(dir, "video.mp4");
115+
const normalized = join(dir, "normalized.m4a");
116+
const delivered = join(dir, "delivered.mp4");
117+
const ffmpeg = getFfmpegBinary();
118+
119+
const sourceResult = spawnSync(ffmpeg, [
120+
"-nostdin",
121+
"-v",
122+
"error",
123+
"-f",
124+
"lavfi",
125+
"-i",
126+
"aevalsrc=if(gte(sin(2*PI*5000*t)\\,0)\\,0.60042\\,-0.60042)|if(gte(sin(2*PI*5000*t)\\,0)\\,0.60042\\,-0.60042):s=48000:d=3:c=stereo",
127+
"-c:a",
128+
"pcm_f32le",
129+
source,
130+
]);
131+
expect(sourceResult.status, sourceResult.stderr?.toString()).toBe(0);
132+
const mixResult = spawnSync(ffmpeg, [
133+
"-nostdin",
134+
"-v",
135+
"error",
136+
"-i",
137+
source,
138+
"-c:a",
139+
"aac",
140+
"-b:a",
141+
"192k",
142+
mixed,
143+
]);
144+
expect(mixResult.status, mixResult.stderr?.toString()).toBe(0);
145+
const videoResult = spawnSync(ffmpeg, [
146+
"-nostdin",
147+
"-v",
148+
"error",
149+
"-f",
150+
"lavfi",
151+
"-i",
152+
"color=black:size=16x16:rate=30:duration=3",
153+
"-c:v",
154+
"libx264",
155+
"-pix_fmt",
156+
"yuv420p",
157+
video,
158+
]);
159+
expect(videoResult.status, videoResult.stderr?.toString()).toBe(0);
160+
161+
const normalizedResult = await padOrTrimAudioToVideoFrameCount({
162+
videoPath: video,
163+
audioPath: mixed,
164+
outputPath: normalized,
165+
probeVideoFrameInfo: async () => ({ frameCount: 90, fpsNum: 30, fpsDen: 1 }),
166+
probeAudioInfo: async () => ({ durationSeconds: 3.029333 }),
167+
});
168+
expect(normalizedResult.success, normalizedResult.error).toBe(true);
169+
expect(normalizedResult.operation).toBe("trim");
170+
171+
const muxResult = await muxVideoWithAudio(video, normalized, delivered);
172+
expect(muxResult.success, muxResult.error).toBe(true);
173+
const sourceLevel = measureLoudness(source);
174+
const deliveredLevel = measureLoudness(delivered);
175+
expect(sourceLevel.truePeakDbfs).toBeCloseTo(-1.5, 1);
176+
expect(deliveredLevel.truePeakDbfs).toBeLessThanOrEqual(-1);
177+
expect(
178+
Math.abs(deliveredLevel.integratedLufs - sourceLevel.integratedLufs),
179+
).toBeLessThanOrEqual(3);
180+
});
82181
});

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

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ describe("buildPadTrimAudioArgs", () => {
111111
});
112112

113113
describe("padOrTrimAudioToVideoFrameCount", () => {
114-
// Build a minimal harness that stubs out the three injectables.
114+
// Build a minimal harness that stubs out the duration probes and ffmpeg runner.
115115
function harness(opts: {
116116
video: ProbeVideoFrameInfo | "throw";
117117
audio: AudioProbeInfo | "throw";
@@ -292,6 +292,43 @@ describe("padOrTrimAudioToVideoFrameCount", () => {
292292
failureReason: "external_interruption",
293293
});
294294
});
295+
296+
it("accepts silence as already below the AAC true-peak ceiling", async () => {
297+
const { input, captured } = harness({
298+
video: { frameCount: 90, fpsNum: 30, fpsDen: 1 },
299+
audio: { durationSeconds: 3 },
300+
});
301+
input.probeAudioTruePeakDbfs = async () => Number.NEGATIVE_INFINITY;
302+
303+
const result = await padOrTrimAudioToVideoFrameCount(input);
304+
305+
expect(result.success).toBe(true);
306+
expect(captured.args).toHaveLength(1);
307+
});
308+
309+
it("attenuates the duration-normalized artifact from its measured AAC true peak", async () => {
310+
const calls: string[][] = [];
311+
const { input } = harness({
312+
video: { frameCount: 90, fpsNum: 30, fpsDen: 1 },
313+
audio: { durationSeconds: 3.029333 },
314+
});
315+
input.probeAudioTruePeakDbfs = async () => 1.5;
316+
input.runFfmpeg = async (args) => {
317+
calls.push(args);
318+
return calls.length === 1
319+
? { success: true }
320+
: { success: false, error: "synthetic correction stop" };
321+
};
322+
323+
const result = await padOrTrimAudioToVideoFrameCount(input);
324+
325+
expect(result.success).toBe(false);
326+
expect(result.error).toBe("synthetic correction stop");
327+
expect(calls).toHaveLength(2);
328+
const correctionArgs = calls[1]!;
329+
expect(correctionArgs[correctionArgs.indexOf("-af") + 1]).toBe("volume=-2.500dB");
330+
expect(correctionArgs[correctionArgs.indexOf("-t") + 1]).toBe("3.000000");
331+
});
295332
});
296333

297334
// ── Public-path path redaction ────────────────────────────────────────────

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

Lines changed: 148 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020
*/
2121

2222
import { spawn } from "node:child_process";
23-
import { rmSync } from "node:fs";
23+
import { mkdtempSync, renameSync, rmSync } from "node:fs";
24+
import { dirname, join } from "node:path";
2425
import {
2526
extractAudioMetadata,
2627
formatFfmpegError,
@@ -39,6 +40,10 @@ import { redactKnownPaths, redactTelemetryString } from "@hyperframes/core";
3940
*/
4041
const AUDIO_DURATION_TOLERANCE_SECONDS = 0.001;
4142

43+
/** Delivery headroom applied after every AAC encode in this stage. */
44+
export const AAC_DELIVERY_TRUE_PEAK_DBFS = -1;
45+
const MAX_TRUE_PEAK_CORRECTION_PASSES = 3;
46+
4247
export interface ProbeVideoFrameInfo {
4348
/** Number of video frames in the stream. */
4449
frameCount: number;
@@ -73,6 +78,7 @@ export interface PadTrimAudioInput {
7378
*/
7479
probeVideoFrameInfo?: (videoPath: string) => Promise<ProbeVideoFrameInfo>;
7580
probeAudioInfo?: (audioPath: string, signal?: AbortSignal) => Promise<AudioProbeInfo>;
81+
probeAudioTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
7682
runFfmpeg?: (args: string[]) => Promise<{
7783
success: boolean;
7884
error?: string;
@@ -110,6 +116,31 @@ export interface PadTrimAudioPlan {
110116
cleanupPaths: string[];
111117
}
112118

119+
function buildAacTruePeakCorrectionArgs(
120+
inputPath: string,
121+
outputPath: string,
122+
targetDurationSeconds: number,
123+
attenuationDb: number,
124+
): string[] {
125+
return [
126+
"-i",
127+
inputPath,
128+
"-map",
129+
"0:a:0",
130+
"-vn",
131+
"-af",
132+
`volume=${attenuationDb.toFixed(3)}dB`,
133+
"-t",
134+
formatSeconds(targetDurationSeconds),
135+
"-c:a",
136+
"aac",
137+
"-b:a",
138+
"192k",
139+
"-y",
140+
outputPath,
141+
];
142+
}
143+
113144
/**
114145
* Pure helper: decide the pad/trim operation and build the ffmpeg argv
115146
* sequence that materializes it. Exported separately so unit tests can pin
@@ -258,6 +289,11 @@ export async function padOrTrimAudioToVideoFrameCount(
258289
((videoPath: string) => defaultProbeVideoFrameInfo(videoPath, input.signal));
259290
const probeAudio = input.probeAudioInfo ?? defaultProbeAudioInfo;
260291
const runner = input.runFfmpeg ?? ((args: string[]) => defaultRunFfmpeg(args, input.signal));
292+
// Injected runners usually do not materialize media. Tests that exercise
293+
// peak correction opt in with a matching probe; production always uses the
294+
// real post-codec measurement.
295+
const probeTruePeak =
296+
input.probeAudioTruePeakDbfs ?? (input.runFfmpeg ? undefined : defaultProbeAudioTruePeakDbfs);
261297

262298
// Probe video and audio in parallel — the two ffprobe invocations are
263299
// independent and account for most of this function's wall-clock time.
@@ -346,6 +382,27 @@ export async function padOrTrimAudioToVideoFrameCount(
346382
} finally {
347383
for (const path of plan.cleanupPaths) rmSync(path, { force: true });
348384
}
385+
386+
if (probeTruePeak) {
387+
const correction = await enforceAacTruePeak({
388+
audioPath: input.outputPath,
389+
targetDurationSeconds,
390+
signal: input.signal,
391+
probeTruePeak,
392+
runner,
393+
});
394+
if (!correction.success) {
395+
return {
396+
success: false,
397+
outputPath: input.outputPath,
398+
targetDurationSeconds,
399+
sourceDurationSeconds: audioInfo.durationSeconds,
400+
operation: plan.operation,
401+
error: correction.error,
402+
failureReason: correction.failureReason,
403+
};
404+
}
405+
}
349406
return {
350407
success: true,
351408
outputPath: input.outputPath,
@@ -355,6 +412,76 @@ export async function padOrTrimAudioToVideoFrameCount(
355412
};
356413
}
357414

415+
interface EnforceAacTruePeakInput {
416+
audioPath: string;
417+
targetDurationSeconds: number;
418+
signal?: AbortSignal;
419+
probeTruePeak: (audioPath: string, signal?: AbortSignal) => Promise<number>;
420+
runner: (args: string[]) => Promise<{
421+
success: boolean;
422+
error?: string;
423+
failureReason?: "external_interruption";
424+
}>;
425+
}
426+
427+
async function enforceAacTruePeak(
428+
input: EnforceAacTruePeakInput,
429+
): Promise<{ success: boolean; error?: string; failureReason?: "external_interruption" }> {
430+
let scratchDir: string | undefined;
431+
try {
432+
scratchDir = mkdtempSync(join(dirname(input.audioPath), ".true-peak-"));
433+
const correctedPath = join(scratchDir, "audio.m4a");
434+
let attenuationDb = 0;
435+
let measuredPath = input.audioPath;
436+
for (let pass = 0; pass <= MAX_TRUE_PEAK_CORRECTION_PASSES; pass += 1) {
437+
const truePeakDbfs = await input.probeTruePeak(measuredPath, input.signal);
438+
if (Number.isNaN(truePeakDbfs) || truePeakDbfs === Number.POSITIVE_INFINITY) {
439+
return { success: false, error: "audioPadTrim: FFmpeg reported an invalid true peak" };
440+
}
441+
if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
442+
if (measuredPath === correctedPath) renameSync(correctedPath, input.audioPath);
443+
return { success: true };
444+
}
445+
if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
446+
447+
attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - truePeakDbfs;
448+
const result = await input.runner(
449+
buildAacTruePeakCorrectionArgs(
450+
input.audioPath,
451+
correctedPath,
452+
input.targetDurationSeconds,
453+
attenuationDb,
454+
),
455+
);
456+
if (!result.success) {
457+
return {
458+
success: false,
459+
error: sanitizeProbeFailure(
460+
result.error ?? "audioPadTrim: failed to constrain AAC true peak",
461+
[input.audioPath, correctedPath],
462+
),
463+
failureReason: result.failureReason,
464+
};
465+
}
466+
measuredPath = correctedPath;
467+
}
468+
return {
469+
success: false,
470+
error: `audioPadTrim: AAC true peak remained above ${AAC_DELIVERY_TRUE_PEAK_DBFS} dBFS after ${MAX_TRUE_PEAK_CORRECTION_PASSES} correction passes`,
471+
};
472+
} catch (err) {
473+
return {
474+
success: false,
475+
error: `audioPadTrim: failed to validate AAC true peak: ${sanitizeProbeFailure(
476+
err,
477+
scratchDir ? [input.audioPath, scratchDir] : [input.audioPath],
478+
)}`,
479+
};
480+
} finally {
481+
if (scratchDir) rmSync(scratchDir, { recursive: true, force: true });
482+
}
483+
}
484+
358485
function failResult(
359486
outputPath: string,
360487
target: number,
@@ -461,6 +588,26 @@ async function defaultProbeAudioInfo(
461588
};
462589
}
463590

591+
async function defaultProbeAudioTruePeakDbfs(
592+
audioPath: string,
593+
signal?: AbortSignal,
594+
): Promise<number> {
595+
const result = await runFfmpeg(
596+
["-i", audioPath, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"],
597+
{ signal },
598+
);
599+
if (!result.success) {
600+
throw new Error(`[audioPadTrim] ${formatFfmpegError(result.exitCode, result.stderr)}`);
601+
}
602+
const matches = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
603+
const token = matches.at(-1)?.[1]?.toLowerCase();
604+
const value = token === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
605+
if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
606+
throw new Error("[audioPadTrim] FFmpeg did not report AAC true peak");
607+
}
608+
return value;
609+
}
610+
464611
async function defaultRunFfmpeg(
465612
args: string[],
466613
signal?: AbortSignal,

0 commit comments

Comments
 (0)