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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXN7wsMK6GqT3MNtqXw

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
2026-11-05 01:39:01 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent aace91b5ec
commit f6ae9bfb43
8 changed files with 304 additions and 27 deletions
@@ -15,7 +15,7 @@
import { describe, expect, it, mock, spyOn } from "bun:test";
import * as fs from "node:fs";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
@@ -606,3 +606,132 @@ describe("constrainAacTruePeak from a PCM source", () => {
}
});
});
describe("padOrTrimAudioToVideoFrameCount from a PCM source", () => {
// A second AAC generation reads hotter than the first: the fake peaks model that measured case.
function pcmHarness(dir: string, peaks: { fromPcm: number[]; fromAac: number }) {
const inputs: string[] = [];
const sourcePath = join(dir, "audio-source.wav");
const input: PadTrimAudioInput = {
videoPath: join(dir, "video.mp4"),
audioPath: join(dir, "audio.m4a"),
outputPath: join(dir, "audio.duration-normalized.m4a"),
sourcePath,
probeVideoFrameInfo: async () => ({ frameCount: 120, fpsNum: 30, fpsDen: 1 }),
probeAudioInfo: async () => ({ durationSeconds: 4.021 }),
probeAudioTruePeakDbfs: async (path) =>
path === sourcePath
? -3
: inputs.at(-1) === sourcePath
? peaks.fromPcm[inputs.length - 1]!
: peaks.fromAac,
encodeAac: async (from, output) => {
inputs.push(from);
writeFileSync(output, "aac");
return { success: true };
},
};
return { input, inputs, sourcePath };
}
it("trims a compliant mix from its PCM, so a second AAC generation cannot push it over and cut it", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-trim-pcm-"));
try {
const { input, inputs, sourcePath } = pcmHarness(dir, { fromPcm: [-1.8], fromAac: 0.2 });
const result = await padOrTrimAudioToVideoFrameCount(input);
expect(result.success, result.error).toBe(true);
expect(result.operation).toBe("trim");
expect(inputs).toEqual([sourcePath]);
expect(result).not.toHaveProperty("audioLoweredDb");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("re-encodes a peak correction from the PCM, not from the normalized AAC", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-trim-pcm-cut-"));
try {
const { input, inputs, sourcePath } = pcmHarness(dir, { fromPcm: [0.5, -1.6], fromAac: 3 });
const result = await padOrTrimAudioToVideoFrameCount(input);
expect(result.success, result.error).toBe(true);
expect(inputs).toEqual([sourcePath, sourcePath]);
expect(result.audioLoweredDb).toBe(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe("constrainAacTruePeak keeps its PCM source matching the delivered AAC", () => {
function peakHarness(dir: string, rewrite: { success: boolean }) {
const audioPath = join(dir, "audio.m4a");
const sourcePath = join(dir, "audio-source.wav");
writeFileSync(audioPath, "aac");
writeFileSync(sourcePath, "pcm");
const rewrites: string[] = [];
let corrected = false;
const run = (firstPeak: number) =>
constrainAacTruePeak({
audioPath,
sourcePath,
targetDurationSeconds: 4,
probeTruePeakDbfs: async (path) =>
path === sourcePath ? -3 : path === audioPath && !corrected ? firstPeak : -1.6,
encodeAac: async (_from, output) => {
corrected = true;
writeFileSync(output, "corrected aac");
return { success: true };
},
rewriteSource: async (_from, output, filter) => {
rewrites.push(filter);
if (rewrite.success) writeFileSync(output, "cut pcm");
return rewrite;
},
});
return { run, rewrites, sourcePath };
}
it("applies the cut to the PCM too, so encoding it again reproduces the delivered AAC", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-"));
try {
const { run, rewrites, sourcePath } = peakHarness(dir, { success: true });
const result = await run(0.5);
expect(result).toEqual({ success: true, loweredDb: 2 });
expect(rewrites).toEqual(["volume=-2.000dB"]);
expect(readFileSync(sourcePath, "utf-8")).toBe("cut pcm");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("leaves the PCM alone when no cut is needed", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-none-"));
try {
const { run, rewrites, sourcePath } = peakHarness(dir, { success: true });
expect(await run(-1.8)).toEqual({ success: true });
expect(rewrites).toEqual([]);
expect(readFileSync(sourcePath, "utf-8")).toBe("pcm");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("removes a PCM it could not cut rather than leave one louder than the delivered AAC", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-cut-source-fail-"));
try {
const { run, sourcePath } = peakHarness(dir, { success: false });
expect(await run(0.5)).toEqual({ success: true, loweredDb: 2, sourceStale: true });
expect(existsSync(sourcePath)).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
@@ -78,6 +78,8 @@ export interface PadTrimAudioInput {
audioPath: string;
/** Path the helper writes the duration-corrected audio to. */
outputPath: string;
/** The PCM `audioPath` was encoded from: a pad, trim or peak correction encodes it instead of decoding the AAC. */
sourcePath?: string;
signal?: AbortSignal;
/** Deadline for each ffmpeg process; defaults to the engine's `ffmpegProcessTimeout`. */
timeoutMs?: number;
@@ -135,8 +137,10 @@ export interface PadTrimAudioPlan {
cleanupPaths: string[];
}
const gainFilter = (gainDb: number) => `volume=${gainDb.toFixed(3)}dB`;
function aacTruePeakCorrectionFilter(targetDurationSeconds: number, attenuationDb: number) {
return `volume=${attenuationDb.toFixed(3)}dB,apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
return `${gainFilter(attenuationDb)},apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
}
/**
@@ -235,7 +239,7 @@ export async function padOrTrimAudioToVideoFrameCount(
const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
const runner =
input.runFfmpeg ?? ((args: string[]) => defaultRunFfmpeg(args, timeoutMs, input.signal));
const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal);
const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath);
// Injected runners usually do not materialize media. Tests that exercise
// peak correction opt in with a matching probe; production always uses the
// real post-codec measurement.
@@ -309,7 +313,12 @@ export async function padOrTrimAudioToVideoFrameCount(
const ffmpegResult =
step.kind === "copy"
? await runner(step.args)
: await encode(input.audioPath, input.outputPath, targetDurationSeconds, step.filter);
: await encode(
input.sourcePath ?? input.audioPath,
input.outputPath,
targetDurationSeconds,
step.filter,
);
if (!ffmpegResult.success) {
return {
success: false,
@@ -341,6 +350,7 @@ export async function padOrTrimAudioToVideoFrameCount(
if (probeTruePeak) {
const correction = await enforceAacTruePeak({
audioPath: input.outputPath,
sourcePath: input.sourcePath,
targetDurationSeconds,
signal: input.signal,
probeTruePeak,
@@ -382,11 +392,13 @@ export async function constrainAacTruePeak(input: {
timeoutMs?: number;
probeTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
encodeAac?: AacEncoder;
rewriteSource?: SourceRewriter;
}): Promise<{
success: boolean;
error?: string;
failureReason?: "external_interruption";
loweredDb?: number;
sourceStale?: true;
}> {
const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
return enforceAacTruePeak({
@@ -398,9 +410,24 @@ export async function constrainAacTruePeak(input: {
input.probeTruePeakDbfs ??
((audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal })),
encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath),
rewriteSource:
input.rewriteSource ??
((sourcePath, outputPath, filter) =>
defaultRunFfmpeg(
["-i", sourcePath, "-af", filter, "-c:a", "pcm_f32le", "-y", outputPath],
timeoutMs,
input.signal,
)),
});
}
/** Writes `sourcePath` through `filter` to `outputPath` as float PCM. */
type SourceRewriter = (
sourcePath: string,
outputPath: string,
filter: string,
) => Promise<StepResult>;
interface EnforceAacTruePeakInput {
audioPath: string;
sourcePath?: string;
@@ -408,6 +435,27 @@ interface EnforceAacTruePeakInput {
signal?: AbortSignal;
probeTruePeak: (audioPath: string, signal?: AbortSignal) => Promise<number>;
encode: AacEncoder;
/** Given with `sourcePath`, a cut is also applied to the PCM so it still encodes to `audioPath`. */
rewriteSource?: SourceRewriter;
}
/** Applies the delivered cut to the PCM. False means the PCM no longer matches the delivered AAC, even if deleting it was refused. */
async function cutSource(
input: EnforceAacTruePeakInput,
scratchDir: string,
attenuationDb: number,
): Promise<boolean> {
if (!input.sourcePath || !input.rewriteSource) return true;
const cutPath = join(scratchDir, "source.wav");
try {
const result = await input.rewriteSource(input.sourcePath, cutPath, gainFilter(attenuationDb));
if (!result.success) throw new Error(result.error);
renameWithRetry(cutPath, input.sourcePath, { copyFallback: true });
return true;
} catch {
removeScratch(input.sourcePath);
return false;
}
}
async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
@@ -415,6 +463,7 @@ async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
error?: string;
failureReason?: "external_interruption";
loweredDb?: number;
sourceStale?: true;
}> {
let scratchDir: string | undefined;
try {
@@ -434,8 +483,12 @@ async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
}
if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
if (measuredPath !== correctedPath) return { success: true };
const sourceCut = await cutSource(input, scratchDir, attenuationDb);
renameWithRetry(correctedPath, input.audioPath, { copyFallback: true });
return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
const loweredDb = Number((-attenuationDb).toFixed(2));
return sourceCut
? { success: true, loweredDb }
: { success: true, loweredDb, sourceStale: true };
}
if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
@@ -450,7 +503,7 @@ async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
const referenceDbfs = Math.max(truePeakDbfs, (sourcePeakDbfs ?? -Infinity) + attenuationDb);
attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - referenceDbfs;
const result = await input.encode(
input.audioPath,
input.sourcePath ?? input.audioPath,
correctedPath,
input.targetDurationSeconds,
aacTruePeakCorrectionFilter(input.targetDurationSeconds, attenuationDb),
@@ -123,6 +123,7 @@ describe("the true-peak correction", () => {
const scan = (dbfs: string) =>
ran(true, `${FRAME.replaceAll("-3.0", dbfs)}\n${SUMMARY.replace("-3.0", dbfs)}`);
vi.mocked(runFfmpeg).mockImplementation(async (args, opts) => {
if (args.includes("pcm_f32le")) writeFileSync(args.at(-1)!, "cut mix");
const result = scan(args.some((arg) => arg.includes(".true-peak-")) ? "-1.6" : "-0.3");
opts?.onStderr?.(result.stderr);
return result;
@@ -92,6 +92,17 @@ describe("runAssembleStage audio duration parity", () => {
);
});
it("normalizes from the PCM the audio stage kept, not from its AAC", async () => {
await runAssembleStage(makeInput({ audioPcmPath: "/tmp/audio-source.wav" }));
expect(padOrTrimAudioMock).toHaveBeenCalledWith(
expect.objectContaining({
audioPath: "/tmp/audio.m4a",
sourcePath: "/tmp/audio-source.wav",
}),
);
});
it("gives a silent mp4's faststart the render's configured ffmpeg timeout", async () => {
await runAssembleStage(makeInput({ hasAudio: false }));
@@ -36,6 +36,7 @@ export interface AssembleStageInput {
videoOnlyPath: string;
/** Mixed audio path (only read when `hasAudio` is true). */
audioOutputPath: string;
audioPcmPath?: string;
/** Final on-disk output. A directory when `format` is `"hls"`. */
outputPath: string;
hasAudio: boolean;
@@ -116,6 +117,7 @@ async function assembleOutput(
const normalizeResult = await padOrTrimAudioToVideoFrameCount({
videoPath: videoOnlyPath,
audioPath: audioOutputPath,
sourcePath: input.audioPcmPath,
outputPath: normalizedAudioPath,
signal: abortSignal,
timeoutMs: ffmpegProcessTimeout,
@@ -127,6 +127,56 @@ describe("runAudioStage", () => {
expect(existsSync(pcm)).toBe(false);
});
it("leaves the delivered PCM for assembly when asked to keep it", async () => {
const input = makeInput({ keepDeliverySource: true });
const pcm = join(input.workDir, "audio-source.wav");
processCompositionAudioMock.mockImplementationOnce(async () => {
writeFileSync(pcm, "retained mix");
return { success: true, tracksProcessed: 1 };
});
const result = await runAudioStage(input);
expect(result.deliverySourcePath).toBe(pcm);
expect(existsSync(pcm)).toBe(true);
});
it("does not hand assembly an uncut PCM whose rewrite failed and whose delete was refused", async () => {
const input = makeInput({ keepDeliverySource: true });
const pcm = join(input.workDir, "audio-source.wav");
processCompositionAudioMock.mockImplementationOnce(async () => {
writeFileSync(pcm, "uncut mix");
return { success: true, tracksProcessed: 1 };
});
constrainAacTruePeakMock.mockResolvedValueOnce({
success: true,
loweredDb: 2,
sourceStale: true,
});
const result = await runAudioStage(input);
expect(result.audioLoweredDb).toBe(2);
expect(result.deliverySourcePath).toBeUndefined();
});
it("removes a PCM it was asked to keep when the peak check fails", async () => {
const input = makeInput({ keepDeliverySource: true });
const pcm = join(input.workDir, "audio-source.wav");
processCompositionAudioMock.mockImplementationOnce(async () => {
writeFileSync(pcm, "retained mix");
return { success: true, tracksProcessed: 1 };
});
constrainAacTruePeakMock.mockResolvedValueOnce({
success: false,
error: "peak probe failed",
loweredDb: undefined,
});
await expect(runAudioStage(input)).rejects.toThrow("peak probe failed");
expect(existsSync(pcm)).toBe(false);
});
it("surfaces the mixer's error as audioError when the mix fails", async () => {
processCompositionAudioMock.mockResolvedValue({
success: false,
@@ -17,6 +17,7 @@
* - `perfStages.audioProcessMs` is set whether or not the call ran.
*/
import { existsSync } from "node:fs";
import { join } from "node:path";
import type { Fps } from "@hyperframes/core";
import {
@@ -55,6 +56,8 @@ export interface AudioStageInput {
assertNotAborted: () => void;
/** Where a per-track failure's detail goes. Optional so tests need not pass one. */
log?: ProducerLogger;
/** Leave the delivered PCM in `workDir` for the assemble stage; its owner removes the dir. */
keepDeliverySource?: boolean;
}
export interface AudioStageResult {
@@ -62,6 +65,8 @@ export interface AudioStageResult {
audioLoweredDb?: number;
/** Always `join(workDir, MIXED_AUDIO_FILENAME)`. */
audioOutputPath: string;
/** The PCM `audioOutputPath` encodes, when `keepDeliverySource` asked for it. */
deliverySourcePath?: string;
/** True iff the audio mix actually produced a file. False when there are no audio elements. */
hasAudio: boolean;
/** Wall-clock ms for the audio mix phase. Zero-elements path is near-zero but always set. */
@@ -104,37 +109,61 @@ async function runAudioStageScoped(input: AudioStageInput): Promise<AudioStageRe
const stageStart = Date.now();
const pcmSourcePath = join(input.workDir, "audio-source.wav");
const duration = (input.totalFrames * input.fps.den) / input.fps.num;
let deliverySourcePath: string | undefined;
try {
const result = await mixAudioForDelivery(input, duration, pcmSourcePath);
let audioLoweredDb: number | undefined;
if (result.hasAudio) {
const guardStart = Date.now();
const limited = await limitDeliveryPeaks({
audioPath: result.audioOutputPath,
sourcePath: pcmSourcePath,
targetDurationSeconds: duration,
signal: input.abortSignal,
timeoutMs: input.ffmpegProcessTimeout,
warn: (message, details) => input.log?.warn?.(message, details),
});
if (!limited.success) throw encoderFailureError("Audio true-peak limit failed", limited);
const peak = await constrainAacTruePeak({
audioPath: result.audioOutputPath,
sourcePath: pcmSourcePath,
targetDurationSeconds: duration,
signal: input.abortSignal,
timeoutMs: input.ffmpegProcessTimeout,
});
if (!peak.success) throw encoderFailureError("Audio true-peak check failed", peak);
audioLoweredDb = peak.loweredDb;
const guard = await guardDeliveryPeaks(
input,
result.audioOutputPath,
pcmSourcePath,
duration,
);
audioLoweredDb = guard.loweredDb;
input.log?.info("[audio] phases", { ...result.audioPhaseMs, guard: Date.now() - guardStart });
if (input.keepDeliverySource && !guard.sourceStale && existsSync(pcmSourcePath)) {
deliverySourcePath = pcmSourcePath;
}
}
return { ...result, audioLoweredDb, audioProcessMs: Date.now() - stageStart };
return {
...result,
audioLoweredDb,
deliverySourcePath,
audioProcessMs: Date.now() - stageStart,
};
} finally {
removeScratch(pcmSourcePath);
if (!deliverySourcePath) removeScratch(pcmSourcePath);
}
}
async function guardDeliveryPeaks(
input: AudioStageInput,
audioPath: string,
sourcePath: string,
duration: number,
): Promise<{ loweredDb?: number; sourceStale?: true }> {
const limited = await limitDeliveryPeaks({
audioPath,
sourcePath,
targetDurationSeconds: duration,
signal: input.abortSignal,
timeoutMs: input.ffmpegProcessTimeout,
warn: (message, details) => input.log?.warn?.(message, details),
});
if (!limited.success) throw encoderFailureError("Audio true-peak limit failed", limited);
const peak = await constrainAacTruePeak({
audioPath,
sourcePath,
targetDurationSeconds: duration,
signal: input.abortSignal,
timeoutMs: input.ffmpegProcessTimeout,
});
if (!peak.success) throw encoderFailureError("Audio true-peak check failed", peak);
return { loweredDb: peak.loweredDb, sourceStale: peak.sourceStale };
}
async function mixAudioForDelivery(
input: AudioStageInput,
duration: number,
@@ -3681,6 +3681,7 @@ async function executeRenderPipeline(input: {
abortSignal: executionSignal,
assertNotAborted,
log,
keepDeliverySource: true,
}),
);
pendingAudio = audioStage.catch(() => undefined);
@@ -4732,7 +4733,7 @@ async function executeRenderPipeline(input: {
const effectiveBitrate = job.config.crf != null ? undefined : job.config.videoBitrate;
const audioResult = await audioStage;
const { audioOutputPath, hasAudio } = audioResult;
const { audioOutputPath, deliverySourcePath, hasAudio } = audioResult;
perfStages.audioProcessMs = audioResult.audioProcessMs;
recordLimiterAttenuation(job, audioResult.audioLoweredDb);
if (audioResult.audioError) {
@@ -5547,6 +5548,7 @@ async function executeRenderPipeline(input: {
job,
videoOnlyPath,
audioOutputPath,
audioPcmPath: deliverySourcePath,
outputPath: stagedOutputPath,
hasAudio,
format: outputFormat,