Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file code-duplication
/**
* Shared FFmpeg process runner.
*
* Extracts the repeated spawn-stderr-timeout-abort-close-error pattern
* that appears across audioMixer and chunkEncoder into a single helper.
*/
import { spawn, type ChildProcess } from "child_process";
import { getFfmpegBinary } from "./ffmpegBinaries.js";
import { trackChildProcess } from "./processTracker.js";
import {
ManagedChildProcess,
type ManagedChildProcessOutcome,
type ManagedProcessTerminationReason,
} from "./managedChildProcess.js";
export interface RunFfmpegOptions {
signal?: AbortSignal;
timeout?: number;
/** Replaces `timeout`: stop only once this long passes without a new output frame. */
stallTimeout?: number;
onStderr?: (line: string) => void;
}
export interface RunFfmpegResult {
success: boolean;
exitCode: number | null;
signal?: NodeJS.Signals | null;
stderr: string;
durationMs: number;
terminationReason: ManagedProcessTerminationReason;
failureReason?: "external_interruption";
error?: Error;
}
const FFMPEG_SIGTERM_EXIT_LINE = /^Exiting normally, received signal 15\.?\r?$/m;
/**
* Return true only when ffmpeg was terminated from outside this managed call.
*
* FFmpeg handles SIGTERM itself and can therefore report exit code 255 with a
* null Node signal. The exact terminal stderr line covers that case. Managed
* abort/deadline/inactivity reasons always take precedence so our own SIGTERM
* requests never become retryable lifecycle interruptions.
*/
export function isExternalFfmpegInterruption(
result: Pick<RunFfmpegResult, "exitCode" | "signal" | "stderr" | "terminationReason">,
): boolean {
if (result.terminationReason !== "exit" || result.exitCode === 0) return false;
if (result.signal === "SIGTERM") return true;
return result.exitCode === 255 && FFMPEG_SIGTERM_EXIT_LINE.test(result.stderr);
}
/** ffmpeg's stats line as it writes: frames encoded so far and seconds of output written. */
export interface FfmpegStats {
frames?: number;
seconds?: number;
}
/** Reads stderr chunks, which split stats lines anywhere, and reports each complete stats line. */
export function ffmpegStatsReader(onStats: (stats: FfmpegStats) => void): (chunk: string) => void {
let rest = "";
return (chunk) => {
const lines = (rest + chunk).split(/[\r\n]/);
rest = lines.pop() ?? "";
for (const line of lines) {
const frame = /frame=\s*(\d+)/.exec(line)?.[1];
const time = /time=\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(line);
if (frame === undefined && !time) continue;
onStats({
frames: frame === undefined ? undefined : Number(frame),
seconds: time
? Math.round((Number(time[1]) * 3600 + Number(time[2]) * 60 + Number(time[3])) * 100) /
100
: undefined,
});
}
};
}
const DEFAULT_TIMEOUT = 300_000;
const DEFAULT_STDERR_TAIL_LINES = 15;
function formatWindowsFfmpegExit(exitCode: number | null): string | undefined {
if (process.platform !== "win32" || exitCode === null) return undefined;
if (exitCode === 3221225781 || exitCode === -1073741515) {
const ffmpegPath = getFfmpegBinary();
return (
`[FFmpeg] Windows could not start "${ffmpegPath}": ` +
"0xC0000135 (STATUS_DLL_NOT_FOUND). A required DLL could not be loaded. " +
"Install a working 64-bit Windows FFmpeg build with all required runtime DLLs."
);
}
if (exitCode === 3221225595 || exitCode === -1073741701) {
return (
"[FFmpeg] Windows could not start ffmpeg.exe (STATUS_INVALID_IMAGE_FORMAT). " +
"The binary may be corrupted or the wrong architecture. Reinstall a 64-bit Windows FFmpeg build."
);
}
if (exitCode === 3221225794 || exitCode === -1073741502) {
return (
"[FFmpeg] Windows failed while initializing ffmpeg.exe. " +
"The binary may be corrupted, blocked, or missing runtime DLLs. Reinstall a 64-bit Windows FFmpeg build."
);
}
return undefined;
}
/**
* Build a user-facing error message for a failed ffmpeg invocation.
*
* Historically we reported only `FFmpeg exited with code N`, which is useless
* for diagnosing encoder-options failures — a rejected `-preset` surfaces as a
* bare `code -22` with no hint at which argument ffmpeg objected to. Including
* the tail of stderr turns those into a one-line signal (e.g.
* `Error applying encoder options: Invalid argument`) that tells the caller
* exactly which option to fix.
*/
export function formatFfmpegError(
exitCode: number | null,
stderr: string,
tailLines: number = DEFAULT_STDERR_TAIL_LINES,
): string {
const tail = (stderr ?? "")
.split(/\r?\n/)
.filter((line) => line.length > 0)
.slice(-tailLines)
.join("\n");
if (exitCode === null) {
return tail ? `[FFmpeg] ${tail}` : "[FFmpeg] process error";
}
const windowsMessage = formatWindowsFfmpegExit(exitCode);
if (windowsMessage) {
return tail ? `${windowsMessage}\nffmpeg stderr (tail):\n${tail}` : windowsMessage;
}
return tail
? `FFmpeg exited with code ${exitCode}\nffmpeg stderr (tail):\n${tail}`
: `FFmpeg exited with code ${exitCode}`;
}
/** formatFfmpegError, led by the timeout when this process was killed at its deadline. */
export function describeFfmpegFailure(
result: Pick<RunFfmpegResult, "exitCode" | "signal" | "stderr" | "terminationReason">,
timeoutMs: number,
): string {
const error = formatFfmpegError(result.exitCode, result.stderr);
if (result.terminationReason === "deadline") {
return (
`FFmpeg timed out after ${timeoutMs} ms (ffmpegProcessTimeout; long renders can raise ` +
`FFMPEG_PROCESS_TIMEOUT_MS). ${error}`
);
}
if (result.exitCode !== null) return error;
const signalOrRequestedStop =
result.terminationReason === "exit" ? result.signal : result.terminationReason;
return signalOrRequestedStop
? `FFmpeg ended without an exit code (${signalOrRequestedStop}). ${error}`
: error;
}
function spawnFfmpeg(args: string[]): ChildProcess {
// windowsHide: ffmpeg/ffprobe are console-subsystem binaries, so without
// this Node opens a visible console window per spawn on Windows. A render
// shells out dozens of times across parallel workers, which flashes a burst
// of windows across the user's desktop. No-op on macOS and Linux.
const ffmpeg = spawn(getFfmpegBinary(), args, { windowsHide: true });
trackChildProcess(ffmpeg);
return ffmpeg;
}
function succeeded(outcome: ManagedChildProcessOutcome): boolean {
return outcome.reason === "exit" && outcome.exitCode === 0;
}
function toResult(outcome: ManagedChildProcessOutcome, stderr = outcome.stderr): RunFfmpegResult {
const result: RunFfmpegResult = {
success: succeeded(outcome),
exitCode: outcome.exitCode,
signal: outcome.signal,
stderr,
durationMs: outcome.durationMs,
terminationReason: outcome.reason,
error: outcome.error,
};
if (isExternalFfmpegInterruption(result)) {
result.failureReason = "external_interruption";
}
return result;
}
/** A run whose signal had already aborted starts no process. */
const ABORTED_BEFORE_START: RunFfmpegResult = {
success: false,
exitCode: null,
signal: null,
stderr: "",
durationMs: 0,
terminationReason: "abort",
};
export async function runFfmpeg(args: string[], opts?: RunFfmpegOptions): Promise<RunFfmpegResult> {
if (opts?.signal?.aborted) return { ...ABORTED_BEFORE_START };
const stallTimeout = opts?.stallTimeout;
let framesWritten = 0;
const readStats = ffmpegStatsReader(({ frames }) => {
if (frames === undefined || frames <= framesWritten) return;
framesWritten = frames;
managed.markActivity();
});
const managed = new ManagedChildProcess(spawnFfmpeg(args), {
signal: opts?.signal,
...(stallTimeout === undefined
? { deadlineAtMs: Date.now() + (opts?.timeout ?? DEFAULT_TIMEOUT) }
: { inactivityTimeoutMs: stallTimeout }),
onStderr:
stallTimeout === undefined
? opts?.onStderr
: (chunk) => {
readStats(chunk);
opts?.onStderr?.(chunk);
},
});
return toResult(await managed.wait());
}