Skip to content

Commit f6ae9bf

Browse files
fix(producer): duration normalization encodes from the delivery PCM, so a compliant mix is never cut (#7199)
* fix(producer): pad/trim audio from the delivery PCM, not its own AAC The assemble stage's duration fix decoded audio.m4a and encoded it again. That second AAC generation read about 2 dB hotter on a measured mix (-1.8 dBTP out of the audio stage, +0.2 after the trim), so the whole-mix cut then lowered an already compliant film by 3.4 dB, overshooting to -2.5 dBTP. A sibling project with a slightly louder music bed escaped the cut, so the two landed about 4 LU apart. - The local render keeps the audio stage's PCM in the work dir until assembly; pad/trim and any peak correction there encode from it. - A whole-mix cut in the audio stage is applied to that PCM too, so it still encodes to exactly the delivered AAC. If it cannot be rewritten it is removed and assembly falls back to the AAC. - The distributed plan does not keep the PCM, so its plan dir is unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]> * refactor(producer): name the assemble stage's PCM input by what it is The comment-ratchet does not let assembleStage.ts gain a comment line, so the new input says what it holds in its name instead. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HebQXN7wsMK6GqT3MNtqXw * fix(producer): assembly never reuses a PCM whose delivered cut was not applied When the audio stage cuts the whole mix and then fails to rewrite the kept PCM, it tries to delete the PCM. Deletion is best-effort and can be refused, for example on Windows, so the uncut PCM could stay on disk. The audio stage handed it to assembly because the file still existed, and assembly would then re-encode a mix louder than the AAC that was actually delivered. The cut now reports when the PCM no longer matches the delivered AAC. The audio stage keeps the PCM only on an explicit success, not because the file exists, and assembly otherwise falls back to the verified AAC. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HebQXN7wsMK6GqT3MNtqXw * test(producer): the fake-FFmpeg PCM rewrite writes its output The true-peak correction now rewrites the kept PCM with FFmpeg and reports the PCM as stale when that output never appears. The fake FFmpeg in this test answered the rewrite without writing anything, so a correct run looked like a failed rewrite. The fake now writes the output, as real FFmpeg does. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HebQXN7wsMK6GqT3MNtqXw --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent aace91b commit f6ae9bf

8 files changed

Lines changed: 304 additions & 27 deletions

File tree

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

Lines changed: 130 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
import { describe, expect, it, mock, spyOn } from "bun:test";
1717
import * as fs from "node:fs";
18-
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
18+
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1919
import { tmpdir } from "node:os";
2020
import { join } from "node:path";
2121
import {
@@ -606,3 +606,132 @@ describe("constrainAacTruePeak from a PCM source", () => {
606606
}
607607
});
608608
});
609+
610+
describe("padOrTrimAudioToVideoFrameCount from a PCM source", () => {
611+
// A second AAC generation reads hotter than the first: the fake peaks model that measured case.
612+
function pcmHarness(dir: string, peaks: { fromPcm: number[]; fromAac: number }) {
613+
const inputs: string[] = [];
614+
const sourcePath = join(dir, "audio-source.wav");
615+
const input: PadTrimAudioInput = {
616+
videoPath: join(dir, "video.mp4"),
617+
audioPath: join(dir, "audio.m4a"),
618+
outputPath: join(dir, "audio.duration-normalized.m4a"),
619+
sourcePath,
620+
probeVideoFrameInfo: async () => ({ frameCount: 120, fpsNum: 30, fpsDen: 1 }),
621+
probeAudioInfo: async () => ({ durationSeconds: 4.021 }),
622+
probeAudioTruePeakDbfs: async (path) =>
623+
path === sourcePath
624+
? -3
625+
: inputs.at(-1) === sourcePath
626+
? peaks.fromPcm[inputs.length - 1]!
627+
: peaks.fromAac,
628+
encodeAac: async (from, output) => {
629+
inputs.push(from);
630+
writeFileSync(output, "aac");
631+
return { success: true };
632+
},
633+
};
634+
return { input, inputs, sourcePath };
635+
}
636+
637+
it("trims a compliant mix from its PCM, so a second AAC generation cannot push it over and cut it", async () => {
638+
const dir = mkdtempSync(join(tmpdir(), "hf-trim-pcm-"));
639+
try {
640+
const { input, inputs, sourcePath } = pcmHarness(dir, { fromPcm: [-1.8], fromAac: 0.2 });
641+
642+
const result = await padOrTrimAudioToVideoFrameCount(input);
643+
644+
expect(result.success, result.error).toBe(true);
645+
expect(result.operation).toBe("trim");
646+
expect(inputs).toEqual([sourcePath]);
647+
expect(result).not.toHaveProperty("audioLoweredDb");
648+
} finally {
649+
rmSync(dir, { recursive: true, force: true });
650+
}
651+
});
652+
653+
it("re-encodes a peak correction from the PCM, not from the normalized AAC", async () => {
654+
const dir = mkdtempSync(join(tmpdir(), "hf-trim-pcm-cut-"));
655+
try {
656+
const { input, inputs, sourcePath } = pcmHarness(dir, { fromPcm: [0.5, -1.6], fromAac: 3 });
657+
658+
const result = await padOrTrimAudioToVideoFrameCount(input);
659+
660+
expect(result.success, result.error).toBe(true);
661+
expect(inputs).toEqual([sourcePath, sourcePath]);
662+
expect(result.audioLoweredDb).toBe(2);
663+
} finally {
664+
rmSync(dir, { recursive: true, force: true });
665+
}
666+
});
667+
});
668+
669+
describe("constrainAacTruePeak keeps its PCM source matching the delivered AAC", () => {
670+
function peakHarness(dir: string, rewrite: { success: boolean }) {
671+
const audioPath = join(dir, "audio.m4a");
672+
const sourcePath = join(dir, "audio-source.wav");
673+
writeFileSync(audioPath, "aac");
674+
writeFileSync(sourcePath, "pcm");
675+
const rewrites: string[] = [];
676+
let corrected = false;
677+
const run = (firstPeak: number) =>
678+
constrainAacTruePeak({
679+
audioPath,
680+
sourcePath,
681+
targetDurationSeconds: 4,
682+
probeTruePeakDbfs: async (path) =>
683+
path === sourcePath ? -3 : path === audioPath && !corrected ? firstPeak : -1.6,
684+
encodeAac: async (_from, output) => {
685+
corrected = true;
686+
writeFileSync(output, "corrected aac");
687+
return { success: true };
688+
},
689+
rewriteSource: async (_from, output, filter) => {
690+
rewrites.push(filter);
691+
if (rewrite.success) writeFileSync(output, "cut pcm");
692+
return rewrite;
693+
},
694+
});
695+
return { run, rewrites, sourcePath };
696+
}
697+
698+
it("applies the cut to the PCM too, so encoding it again reproduces the delivered AAC", async () => {
699+
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-"));
700+
try {
701+
const { run, rewrites, sourcePath } = peakHarness(dir, { success: true });
702+
703+
const result = await run(0.5);
704+
705+
expect(result).toEqual({ success: true, loweredDb: 2 });
706+
expect(rewrites).toEqual(["volume=-2.000dB"]);
707+
expect(readFileSync(sourcePath, "utf-8")).toBe("cut pcm");
708+
} finally {
709+
rmSync(dir, { recursive: true, force: true });
710+
}
711+
});
712+
713+
it("leaves the PCM alone when no cut is needed", async () => {
714+
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-none-"));
715+
try {
716+
const { run, rewrites, sourcePath } = peakHarness(dir, { success: true });
717+
718+
expect(await run(-1.8)).toEqual({ success: true });
719+
expect(rewrites).toEqual([]);
720+
expect(readFileSync(sourcePath, "utf-8")).toBe("pcm");
721+
} finally {
722+
rmSync(dir, { recursive: true, force: true });
723+
}
724+
});
725+
726+
it("removes a PCM it could not cut rather than leave one louder than the delivered AAC", async () => {
727+
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-fail-"));
728+
try {
729+
const { run, sourcePath } = peakHarness(dir, { success: false });
730+
731+
expect(await run(0.5)).toEqual({ success: true, loweredDb: 2, sourceStale: true });
732+
expect(existsSync(sourcePath)).toBe(false);
733+
} finally {
734+
rmSync(dir, { recursive: true, force: true });
735+
}
736+
});
737+
});

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

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@ export interface PadTrimAudioInput {
7878
audioPath: string;
7979
/** Path the helper writes the duration-corrected audio to. */
8080
outputPath: string;
81+
/** The PCM `audioPath` was encoded from: a pad, trim or peak correction encodes it instead of decoding the AAC. */
82+
sourcePath?: string;
8183
signal?: AbortSignal;
8284
/** Deadline for each ffmpeg process; defaults to the engine's `ffmpegProcessTimeout`. */
8385
timeoutMs?: number;
@@ -135,8 +137,10 @@ export interface PadTrimAudioPlan {
135137
cleanupPaths: string[];
136138
}
137139

140+
const gainFilter = (gainDb: number) => `volume=${gainDb.toFixed(3)}dB`;
141+
138142
function aacTruePeakCorrectionFilter(targetDurationSeconds: number, attenuationDb: number) {
139-
return `volume=${attenuationDb.toFixed(3)}dB,apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
143+
return `${gainFilter(attenuationDb)},apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
140144
}
141145

142146
/**
@@ -235,7 +239,7 @@ export async function padOrTrimAudioToVideoFrameCount(
235239
const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
236240
const runner =
237241
input.runFfmpeg ?? ((args: string[]) => defaultRunFfmpeg(args, timeoutMs, input.signal));
238-
const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal);
242+
const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath);
239243
// Injected runners usually do not materialize media. Tests that exercise
240244
// peak correction opt in with a matching probe; production always uses the
241245
// real post-codec measurement.
@@ -309,7 +313,12 @@ export async function padOrTrimAudioToVideoFrameCount(
309313
const ffmpegResult =
310314
step.kind === "copy"
311315
? await runner(step.args)
312-
: await encode(input.audioPath, input.outputPath, targetDurationSeconds, step.filter);
316+
: await encode(
317+
input.sourcePath ?? input.audioPath,
318+
input.outputPath,
319+
targetDurationSeconds,
320+
step.filter,
321+
);
313322
if (!ffmpegResult.success) {
314323
return {
315324
success: false,
@@ -341,6 +350,7 @@ export async function padOrTrimAudioToVideoFrameCount(
341350
if (probeTruePeak) {
342351
const correction = await enforceAacTruePeak({
343352
audioPath: input.outputPath,
353+
sourcePath: input.sourcePath,
344354
targetDurationSeconds,
345355
signal: input.signal,
346356
probeTruePeak,
@@ -382,11 +392,13 @@ export async function constrainAacTruePeak(input: {
382392
timeoutMs?: number;
383393
probeTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
384394
encodeAac?: AacEncoder;
395+
rewriteSource?: SourceRewriter;
385396
}): Promise<{
386397
success: boolean;
387398
error?: string;
388399
failureReason?: "external_interruption";
389400
loweredDb?: number;
401+
sourceStale?: true;
390402
}> {
391403
const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
392404
return enforceAacTruePeak({
@@ -398,23 +410,60 @@ export async function constrainAacTruePeak(input: {
398410
input.probeTruePeakDbfs ??
399411
((audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal })),
400412
encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath),
413+
rewriteSource:
414+
input.rewriteSource ??
415+
((sourcePath, outputPath, filter) =>
416+
defaultRunFfmpeg(
417+
["-i", sourcePath, "-af", filter, "-c:a", "pcm_f32le", "-y", outputPath],
418+
timeoutMs,
419+
input.signal,
420+
)),
401421
});
402422
}
403423

424+
/** Writes `sourcePath` through `filter` to `outputPath` as float PCM. */
425+
type SourceRewriter = (
426+
sourcePath: string,
427+
outputPath: string,
428+
filter: string,
429+
) => Promise<StepResult>;
430+
404431
interface EnforceAacTruePeakInput {
405432
audioPath: string;
406433
sourcePath?: string;
407434
targetDurationSeconds: number;
408435
signal?: AbortSignal;
409436
probeTruePeak: (audioPath: string, signal?: AbortSignal) => Promise<number>;
410437
encode: AacEncoder;
438+
/** Given with `sourcePath`, a cut is also applied to the PCM so it still encodes to `audioPath`. */
439+
rewriteSource?: SourceRewriter;
440+
}
441+
442+
/** Applies the delivered cut to the PCM. False means the PCM no longer matches the delivered AAC, even if deleting it was refused. */
443+
async function cutSource(
444+
input: EnforceAacTruePeakInput,
445+
scratchDir: string,
446+
attenuationDb: number,
447+
): Promise<boolean> {
448+
if (!input.sourcePath || !input.rewriteSource) return true;
449+
const cutPath = join(scratchDir, "source.wav");
450+
try {
451+
const result = await input.rewriteSource(input.sourcePath, cutPath, gainFilter(attenuationDb));
452+
if (!result.success) throw new Error(result.error);
453+
renameWithRetry(cutPath, input.sourcePath, { copyFallback: true });
454+
return true;
455+
} catch {
456+
removeScratch(input.sourcePath);
457+
return false;
458+
}
411459
}
412460

413461
async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
414462
success: boolean;
415463
error?: string;
416464
failureReason?: "external_interruption";
417465
loweredDb?: number;
466+
sourceStale?: true;
418467
}> {
419468
let scratchDir: string | undefined;
420469
try {
@@ -434,8 +483,12 @@ async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
434483
}
435484
if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
436485
if (measuredPath !== correctedPath) return { success: true };
486+
const sourceCut = await cutSource(input, scratchDir, attenuationDb);
437487
renameWithRetry(correctedPath, input.audioPath, { copyFallback: true });
438-
return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
488+
const loweredDb = Number((-attenuationDb).toFixed(2));
489+
return sourceCut
490+
? { success: true, loweredDb }
491+
: { success: true, loweredDb, sourceStale: true };
439492
}
440493
if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
441494

@@ -450,7 +503,7 @@ async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
450503
const referenceDbfs = Math.max(truePeakDbfs, (sourcePeakDbfs ?? -Infinity) + attenuationDb);
451504
attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - referenceDbfs;
452505
const result = await input.encode(
453-
input.audioPath,
506+
input.sourcePath ?? input.audioPath,
454507
correctedPath,
455508
input.targetDurationSeconds,
456509
aacTruePeakCorrectionFilter(input.targetDurationSeconds, attenuationDb),

‎packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ describe("the true-peak correction", () => {
123123
const scan = (dbfs: string) =>
124124
ran(true, `${FRAME.replaceAll("-3.0", dbfs)}\n${SUMMARY.replace("-3.0", dbfs)}`);
125125
vi.mocked(runFfmpeg).mockImplementation(async (args, opts) => {
126+
if (args.includes("pcm_f32le")) writeFileSync(args.at(-1)!, "cut mix");
126127
const result = scan(args.some((arg) => arg.includes(".true-peak-")) ? "-1.6" : "-0.3");
127128
opts?.onStderr?.(result.stderr);
128129
return result;

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,17 @@ describe("runAssembleStage audio duration parity", () => {
9292
);
9393
});
9494

95+
it("normalizes from the PCM the audio stage kept, not from its AAC", async () => {
96+
await runAssembleStage(makeInput({ audioPcmPath: "/tmp/audio-source.wav" }));
97+
98+
expect(padOrTrimAudioMock).toHaveBeenCalledWith(
99+
expect.objectContaining({
100+
audioPath: "/tmp/audio.m4a",
101+
sourcePath: "/tmp/audio-source.wav",
102+
}),
103+
);
104+
});
105+
95106
it("gives a silent mp4's faststart the render's configured ffmpeg timeout", async () => {
96107
await runAssembleStage(makeInput({ hasAudio: false }));
97108

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ export interface AssembleStageInput {
3636
videoOnlyPath: string;
3737
/** Mixed audio path (only read when `hasAudio` is true). */
3838
audioOutputPath: string;
39+
audioPcmPath?: string;
3940
/** Final on-disk output. A directory when `format` is `"hls"`. */
4041
outputPath: string;
4142
hasAudio: boolean;
@@ -116,6 +117,7 @@ async function assembleOutput(
116117
const normalizeResult = await padOrTrimAudioToVideoFrameCount({
117118
videoPath: videoOnlyPath,
118119
audioPath: audioOutputPath,
120+
sourcePath: input.audioPcmPath,
119121
outputPath: normalizedAudioPath,
120122
signal: abortSignal,
121123
timeoutMs: ffmpegProcessTimeout,

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,56 @@ describe("runAudioStage", () => {
127127
expect(existsSync(pcm)).toBe(false);
128128
});
129129

130+
it("leaves the delivered PCM for assembly when asked to keep it", async () => {
131+
const input = makeInput({ keepDeliverySource: true });
132+
const pcm = join(input.workDir, "audio-source.wav");
133+
processCompositionAudioMock.mockImplementationOnce(async () => {
134+
writeFileSync(pcm, "retained mix");
135+
return { success: true, tracksProcessed: 1 };
136+
});
137+
138+
const result = await runAudioStage(input);
139+
140+
expect(result.deliverySourcePath).toBe(pcm);
141+
expect(existsSync(pcm)).toBe(true);
142+
});
143+
144+
it("does not hand assembly an uncut PCM whose rewrite failed and whose delete was refused", async () => {
145+
const input = makeInput({ keepDeliverySource: true });
146+
const pcm = join(input.workDir, "audio-source.wav");
147+
processCompositionAudioMock.mockImplementationOnce(async () => {
148+
writeFileSync(pcm, "uncut mix");
149+
return { success: true, tracksProcessed: 1 };
150+
});
151+
constrainAacTruePeakMock.mockResolvedValueOnce({
152+
success: true,
153+
loweredDb: 2,
154+
sourceStale: true,
155+
});
156+
157+
const result = await runAudioStage(input);
158+
159+
expect(result.audioLoweredDb).toBe(2);
160+
expect(result.deliverySourcePath).toBeUndefined();
161+
});
162+
163+
it("removes a PCM it was asked to keep when the peak check fails", async () => {
164+
const input = makeInput({ keepDeliverySource: true });
165+
const pcm = join(input.workDir, "audio-source.wav");
166+
processCompositionAudioMock.mockImplementationOnce(async () => {
167+
writeFileSync(pcm, "retained mix");
168+
return { success: true, tracksProcessed: 1 };
169+
});
170+
constrainAacTruePeakMock.mockResolvedValueOnce({
171+
success: false,
172+
error: "peak probe failed",
173+
loweredDb: undefined,
174+
});
175+
176+
await expect(runAudioStage(input)).rejects.toThrow("peak probe failed");
177+
expect(existsSync(pcm)).toBe(false);
178+
});
179+
130180
it("surfaces the mixer's error as audioError when the mix fails", async () => {
131181
processCompositionAudioMock.mockResolvedValue({
132182
success: false,

0 commit comments

Comments
 (0)