diff --git a/packages/producer/src/services/render/audioPadTrim.test.ts b/packages/producer/src/services/render/audioPadTrim.test.ts index e7c79362a1..434bf73a24 100644 --- a/packages/producer/src/services/render/audioPadTrim.test.ts +++ b/packages/producer/src/services/render/audioPadTrim.test.ts @@ -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 }); + } + }); +}); diff --git a/packages/producer/src/services/render/audioPadTrim.ts b/packages/producer/src/services/render/audioPadTrim.ts index efcdea9c33..cbe9b45a5a 100644 --- a/packages/producer/src/services/render/audioPadTrim.ts +++ b/packages/producer/src/services/render/audioPadTrim.ts @@ -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; 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; + interface EnforceAacTruePeakInput { audioPath: string; sourcePath?: string; @@ -408,6 +435,27 @@ interface EnforceAacTruePeakInput { signal?: AbortSignal; probeTruePeak: (audioPath: string, signal?: AbortSignal) => Promise; 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 { + 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), diff --git a/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts b/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts index 790f711509..b050234ecc 100644 --- a/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts +++ b/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts @@ -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; diff --git a/packages/producer/src/services/render/stages/assembleStage.test.ts b/packages/producer/src/services/render/stages/assembleStage.test.ts index faa18b14f7..be7bda2857 100644 --- a/packages/producer/src/services/render/stages/assembleStage.test.ts +++ b/packages/producer/src/services/render/stages/assembleStage.test.ts @@ -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 })); diff --git a/packages/producer/src/services/render/stages/assembleStage.ts b/packages/producer/src/services/render/stages/assembleStage.ts index 3fb4505a92..67ae31391b 100644 --- a/packages/producer/src/services/render/stages/assembleStage.ts +++ b/packages/producer/src/services/render/stages/assembleStage.ts @@ -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, diff --git a/packages/producer/src/services/render/stages/audioStage.test.ts b/packages/producer/src/services/render/stages/audioStage.test.ts index b40676fa24..af17d7694c 100644 --- a/packages/producer/src/services/render/stages/audioStage.test.ts +++ b/packages/producer/src/services/render/stages/audioStage.test.ts @@ -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, diff --git a/packages/producer/src/services/render/stages/audioStage.ts b/packages/producer/src/services/render/stages/audioStage.ts index 9e1c5047cd..511a3abfc7 100644 --- a/packages/producer/src/services/render/stages/audioStage.ts +++ b/packages/producer/src/services/render/stages/audioStage.ts @@ -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 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, diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 3f3f7e2ab0..76cd9ad616 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -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,