Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+}