Skip to content

Write HTML. Render video. Built for agents.

perf(producer): the plan's true-peak check runs in parallel segments (#5925)

Miguel Ángelc77061e3af54
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 77b306e58e..0550b6acec 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -360,6 +360,7 @@ export {
type RunFfmpegOptions,
type RunFfmpegResult,
} from "./utils/runFfmpeg.js";
+export { aacSegmentCount } from "./services/aacEncode.js";
export {
ManagedChildProcess,
type ManagedChildProcessOptions,
diff --git a/packages/producer/src/services/render/audioPadTrim.ts b/packages/producer/src/services/render/audioPadTrim.ts
index 2ebe8f7337..522361064b 100644
--- a/packages/producer/src/services/render/audioPadTrim.ts
+++ b/packages/producer/src/services/render/audioPadTrim.ts
@@ -33,6 +33,7 @@ import {
type AudioMetadata,
} from "@hyperframes/engine";
import { redactKnownPaths, redactTelemetryString } from "@hyperframes/core";
+import { measureTruePeakDbfs } from "./audioTruePeak.js";
/**
* Tolerance used to decide whether an audio file is already short enough to
@@ -306,7 +307,7 @@ export async function padOrTrimAudioToVideoFrameCount(
(input.runFfmpeg
? undefined
: (audioPath: string, signal?: AbortSignal) =>
- defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal));
+ measureTruePeakDbfs(audioPath, { timeoutMs, signal }));
// Probe video and audio in parallel — the two ffprobe invocations are
// independent and account for most of this function's wall-clock time.
@@ -448,8 +449,11 @@ export async function constrainAacTruePeak(input: {
audioPath: input.audioPath,
targetDurationSeconds: input.targetDurationSeconds,
signal: input.signal,
- probeTruePeak: (audioPath, signal) =>
- defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal),
+ probeTruePeak: async (audioPath, signal) => {
+ const { sampleRate } = await extractAudioMetadata(audioPath, { signal });
+ const segments = { durationSeconds: input.targetDurationSeconds, sampleRate };
+ return measureTruePeakDbfs(audioPath, { timeoutMs, signal, segments });
+ },
runner: (args) => defaultRunFfmpeg(args, timeoutMs, input.signal),
});
}
@@ -641,27 +645,6 @@ async function defaultProbeAudioInfo(
};
}
-async function defaultProbeAudioTruePeakDbfs(
- audioPath: string,
- timeoutMs: number,
- signal?: AbortSignal,
-): Promise<number> {
- const result = await runFfmpeg(
- ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"],
- { signal, timeout: timeoutMs },
- );
- if (!result.success) {
- throw new Error(`[audioPadTrim] ${describeFfmpegFailure(result, timeoutMs)}`);
- }
- const matches = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
- const token = matches.at(-1)?.[1]?.toLowerCase();
- const value = token === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
- if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
- throw new Error("[audioPadTrim] FFmpeg did not report AAC true peak");
- }
- return value;
-}
-
async function defaultRunFfmpeg(
args: string[],
timeoutMs: number,
diff --git a/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts b/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts
new file mode 100644
index 0000000000..9f328542cf
--- /dev/null
+++ b/packages/producer/src/services/render/audioTruePeak.fakeFfmpeg.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { runFfmpeg, type RunFfmpegResult } from "@hyperframes/engine";
+import { measureTruePeakDbfs } from "./audioTruePeak.js";
+
+vi.mock("@hyperframes/engine", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@hyperframes/engine")>()),
+ runFfmpeg: vi.fn(),
+}));
+
+const FRAME =
+ "[Parsed_ebur128_0 @ 0x1] t: 0.1 M:-20.0 S:-20.0 I:-20.0 LUFS FTPK: -3.0 dBFS TPK: -3.0 dBFS";
+const SUMMARY = " True peak:\n Peak: -3.0 dBFS";
+const ran = (success: boolean, stderr: string): RunFfmpegResult => ({
+ success,
+ exitCode: success ? 0 : 1,
+ stderr,
+ durationMs: 1,
+ terminationReason: "exit",
+});
+const segments = { durationSeconds: 180, sampleRate: 48_000 };
+
+afterEach(() => vi.mocked(runFfmpeg).mockReset());
+
+describe("measureTruePeakDbfs against ffmpeg's stderr", () => {
+ it("throws when ffmpeg prints no true-peak summary", async () => {
+ vi.mocked(runFfmpeg).mockImplementation(async (_, opts) => {
+ opts?.onStderr?.(`${FRAME}\n`);
+ return ran(true, FRAME);
+ });
+ await expect(measureTruePeakDbfs("in.m4a", { timeoutMs: 1000 })).rejects.toThrow(
+ "FFmpeg did not report AAC true peak",
+ );
+ });
+
+ it("measures a rate other than 48 kHz in one whole-file pass", async () => {
+ vi.mocked(runFfmpeg).mockResolvedValue(ran(true, `${FRAME}\n${SUMMARY}`));
+ const peak = await measureTruePeakDbfs("in.m4a", {
+ timeoutMs: 1000,
+ segments: { ...segments, sampleRate: 44_100 },
+ });
+ expect(peak).toBe(-3);
+ expect(runFfmpeg).toHaveBeenCalledOnce();
+ });
+
+ it("stops the other segment scans when one fails", async () => {
+ const others: (AbortSignal | undefined)[] = [];
+ vi.mocked(runFfmpeg).mockImplementation(async (args, opts) => {
+ if (args.some((arg) => arg.startsWith("atrim=start_sample=0:"))) return ran(false, "boom");
+ others.push(opts?.signal);
+ const signal = opts?.signal;
+ if (signal) await new Promise((stop) => signal.addEventListener("abort", stop));
+ return ran(false, "stopped");
+ });
+ await expect(measureTruePeakDbfs("in.m4a", { timeoutMs: 1000, segments })).rejects.toThrow();
+ expect(others.map((signal) => signal?.aborted)).toEqual([true, true]);
+ });
+});
diff --git a/packages/producer/src/services/render/audioTruePeak.test.ts b/packages/producer/src/services/render/audioTruePeak.test.ts
new file mode 100644
index 0000000000..abff9f5c19
--- /dev/null
+++ b/packages/producer/src/services/render/audioTruePeak.test.ts
@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { getFfmpegBinary } from "@hyperframes/engine";
+import { measureTruePeakDbfs } from "./audioTruePeak.js";
+
+const RATE = 48_000;
+const SECONDS = 180; // three segments: cuts at 60 s and 120 s, each later one starting 4800 samples early
+const CUT = 60 * RATE;
+const BLOCK = RATE / 10;
+// From silence, a scan that starts on this burst reads it 0.7 dB louder than a whole-file scan.
+const BURST = [-0.45, 0.9, -0.9];
+
+const hasFfmpeg = (() => {
+ try {
+ execFileSync(getFfmpegBinary(), ["-version"], { stdio: "ignore" });
+ return true;
+ } catch {
+ return false;
+ }
+})();
+
+const dir = mkdtempSync(join(tmpdir(), "hf-true-peak-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function monoWav(name: string, burstAt?: number): string {
+ const data = Buffer.alloc(SECONDS * RATE * 2);
+ if (burstAt !== undefined) {
+ BURST.forEach((v, i) => data.writeInt16LE(Math.round(v * 32767), (burstAt + i) * 2));
+ }
+ const header = Buffer.alloc(44);
+ header.write("RIFF", 0);
+ header.writeUInt32LE(36 + data.length, 4);
+ header.write("WAVEfmt ", 8);
+ header.writeUInt32LE(16, 16);
+ header.writeUInt16LE(1, 20);
+ header.writeUInt16LE(1, 22);
+ header.writeUInt32LE(RATE, 24);
+ header.writeUInt32LE(RATE * 2, 28);
+ header.writeUInt16LE(2, 32);
+ header.writeUInt16LE(16, 34);
+ header.write("data", 36);
+ header.writeUInt32LE(data.length, 40);
+ const path = join(dir, `${name}.wav`);
+ writeFileSync(path, Buffer.concat([header, data]));
+ return path;
+}
+
+async function bothWays(path: string): Promise<[number, number]> {
+ const timeoutMs = 60_000;
+ const segments = { durationSeconds: SECONDS, sampleRate: RATE };
+ return Promise.all([
+ measureTruePeakDbfs(path, { timeoutMs }),
+ measureTruePeakDbfs(path, { timeoutMs, segments }),
+ ]);
+}
+
+describe.skipIf(!hasFfmpeg)("measureTruePeakDbfs in segments", () => {
+ it.each([
+ ["ends on a segment cut", CUT - BURST.length],
+ ["starts where a middle segment's scan starts", CUT - BLOCK],
+ ["starts where the last segment's scan starts", 2 * CUT - BLOCK],
+ ])(
+ "reads a peak that %s exactly as one whole-file pass",
+ async (_, at) => {
+ const [whole, segmented] = await bothWays(monoWav(`burst-${at}`, at));
+ expect(whole).toBeGreaterThan(-1);
+ expect(segmented).toBe(whole);
+ },
+ 60_000,
+ );
+
+ it("reads silence as -inf", async () => {
+ expect(await bothWays(monoWav("silence"))).toEqual([
+ Number.NEGATIVE_INFINITY,
+ Number.NEGATIVE_INFINITY,
+ ]);
+ }, 60_000);
+});
diff --git a/packages/producer/src/services/render/audioTruePeak.ts b/packages/producer/src/services/render/audioTruePeak.ts
new file mode 100644
index 0000000000..7b5bc2e202
--- /dev/null
+++ b/packages/producer/src/services/render/audioTruePeak.ts
@@ -0,0 +1,103 @@
+import { aacSegmentCount, describeFfmpegFailure, runFfmpeg } from "@hyperframes/engine";
+
+/** Peaks in dBFS as ffmpeg's ebur128 prints them (one decimal). */
+interface TruePeakScan {
+ peak: number;
+ /** From the per-100 ms frame log: the first block, and the loudest block after it. */
+ firstBlock: number;
+ laterBlocks: number;
+}
+
+const toDbfs = (token: string) =>
+ token.toLowerCase() === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
+
+function checkedDbfs(value: number): number {
+ if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
+ throw new Error("[audioTruePeak] FFmpeg did not report AAC true peak");
+ }
+ return value;
+}
+
+async function scanTruePeak(
+ audioPath: string,
+ trim: string,
+ timeoutMs: number,
+ signal?: AbortSignal,
+): Promise<TruePeakScan> {
+ let firstBlock: number | undefined;
+ let laterBlocks = Number.NEGATIVE_INFINITY;
+ let partialLine = "";
+ const readLines = (chunk: string) => {
+ const lines = (partialLine + chunk).split(/\r|\n/);
+ partialLine = lines.pop() ?? "";
+ for (const line of lines) {
+ const ftpk = /FTPK:([^d]*)dBFS/.exec(line)?.[1];
+ if (!ftpk) continue;
+ // Runs in a stderr listener, so it must not throw; a bad token is checked after the run.
+ const block = Math.max(...ftpk.trim().split(/\s+/).map(toDbfs));
+ if (firstBlock === undefined) firstBlock = block;
+ else laterBlocks = Math.max(laterBlocks, block);
+ }
+ };
+ const result = await runFfmpeg(
+ ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", `${trim}ebur128=peak=true`, "-f", "null", "-"],
+ { signal, timeout: timeoutMs, onStderr: readLines },
+ );
+ if (!result.success) {
+ throw new Error(`[audioTruePeak] ${describeFfmpegFailure(result, timeoutMs)}`);
+ }
+ const summary = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
+ return {
+ peak: checkedDbfs(toDbfs(summary.at(-1)?.[1] ?? "nan")),
+ firstBlock: checkedDbfs(firstBlock ?? Number.NEGATIVE_INFINITY),
+ laterBlocks: checkedDbfs(laterBlocks),
+ };
+}
+
+/**
+ * The true peak one `ebur128=peak=true` pass over the whole file reports, measured in parallel
+ * segments when the length is known and the rate is 48 kHz: the same digit, not an estimate.
+ */
+export async function measureTruePeakDbfs(
+ audioPath: string,
+ options: {
+ timeoutMs: number;
+ signal?: AbortSignal;
+ segments?: { durationSeconds: number; sampleRate: number };
+ },
+): Promise<number> {
+ const { timeoutMs, signal, segments } = options;
+ const wholeFile = async () => (await scanTruePeak(audioPath, "", timeoutMs, signal)).peak;
+ // ebur128 resamples any other rate to 48 kHz, which would move samples near each cut.
+ // It logs one peak per 100 ms block; its 4x oversampler reads 15 samples back, 16 ahead.
+ const block = 4800;
+ const count = segments?.sampleRate === 48_000 ? aacSegmentCount(segments.durationSeconds) : 1;
+ if (!segments || count === 1) return wholeFile();
+
+ const cut = (k: number) => k * Math.floor((segments.durationSeconds * 10) / count) * block;
+ const peers = new AbortController();
+ const segmentSignal = signal ? AbortSignal.any([signal, peers.signal]) : peers.signal;
+ const scans = await Promise.all(
+ Array.from({ length: count }, (_, k) => {
+ // A later segment starts one block early and drops that block: its oversampler starts
+ // from mirrored history there, and the previous segment stops 16 samples short.
+ const start = k === 0 ? 0 : cut(k) - block;
+ const end = k === count - 1 ? "" : `:end_sample=${cut(k + 1)}`;
+ return scanTruePeak(
+ audioPath,
+ `atrim=start_sample=${start}${end},`,
+ timeoutMs,
+ segmentSignal,
+ );
+ }),
+ ).catch((error: unknown) => {
+ peers.abort();
+ throw error;
+ });
+ const last = scans[count - 1]!;
+ const counted = Math.max(scans[0]!.peak, ...scans.slice(1).map((scan) => scan.laterBlocks));
+ // The last segment's final partial block is logged only in its summary, which also holds its
+ // dropped first block. When that first block alone could be the loudest, measure the whole file.
+ if (last.peak > last.firstBlock || last.peak <= counted) return Math.max(counted, last.peak);
+ return wholeFile();
+}