Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { execFile } from "node:child_process";
import { extname } from "node:path";
import {
firstFrameColourArgs,
parseFirstFrameColour,
type ToneMapSourceColour,
} from "@hyperframes/core";
import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
import { videoStreamHasAlpha } from "@hyperframes/parsers/media-alpha";
export interface FfprobeRunResult {
status: number | null;
stdout: string | Buffer;
stderr: string | Buffer;
/** Spawn-level failure (covers both `NodeJS.ErrnoException` and
* `ExecFileException`); only `code === "ENOENT"` is ever inspected. */
error?: { code?: string | number | null | undefined };
}
/** Injectable ffprobe runner. May be synchronous (tests) or async (the
* default `execFile`-based runner below), so cold scans can run many probes
* concurrently off the event loop. */
export type FfprobeRunner = (
command: string,
args: string[],
options?: { timeout?: number; maxBuffer?: number },
) => FfprobeRunResult | Promise<FfprobeRunResult>;
/** Default runner: genuinely async (`execFile`), unlike the previous
* `spawnSync`-based one — a pool of concurrent probes actually parallelizes
* (mirrors `execFileAsync` in packages/lint/src/hevcPreviewLint.ts). */
const execFileRunner: FfprobeRunner = (command, args, options) =>
new Promise<FfprobeRunResult>((resolvePromise) => {
execFile(
command,
args,
{ timeout: options?.timeout, maxBuffer: options?.maxBuffer, windowsHide: true },
(error, stdout, stderr) => {
if (error && error.code === "ENOENT") {
resolvePromise({ status: null, stdout: "", stderr: "", error });
return;
}
if (error) {
// Nonzero exit / timeout / kill: report a nonzero status; callers
// only distinguish "ok" (0) from "failed" from "ENOENT".
const status = typeof error.code === "number" ? error.code : 1;
resolvePromise({ status, stdout: stdout ?? "", stderr: stderr ?? "" });
return;
}
resolvePromise({ status: 0, stdout: stdout ?? "", stderr: stderr ?? "" });
},
);
});
export type MediaDynamicRange = "hdr" | "sdr" | "unknown";
export type MediaHdrTransfer = "pq" | "hlg" | "unknown";
export interface MediaColorMetadata {
dynamicRange: MediaDynamicRange;
hdrTransfer: MediaHdrTransfer | null;
label: string;
isHdr: boolean;
codecName?: string;
profile?: string;
pixelFormat?: string;
colorSpace?: string;
colorTransfer?: string;
colorPrimaries?: string;
bitsPerRawSample?: string;
}
export interface MediaMetadata {
kind: "video" | "image" | "audio" | "unknown";
color: MediaColorMetadata;
/** Video audio stream, when probed. Absent means the drop path stays muted. */
hasAudio?: boolean;
/** Video stream carries alpha (pix_fmt or the VP8/VP9 alpha_mode tag). */
hasAlpha?: boolean;
probeError?: string;
}
interface FfprobeStream {
codec_type?: string;
codec_name?: string;
profile?: string;
pix_fmt?: string;
color_space?: string;
color_transfer?: string;
color_primaries?: string;
bits_per_raw_sample?: string;
disposition?: { attached_pic?: number };
tags?: Record<string, string | undefined>;
}
const VIDEO_EXT = new Set([
".mp4",
".mov",
".webm",
".mkv",
".avi",
".m4v",
".mxf",
".mts",
".m2ts",
".ts",
]);
const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif"]);
const AUDIO_EXT = new Set([".mp3", ".wav", ".ogg", ".m4a", ".aac", ".flac"]);
function lower(value: string | undefined): string {
return value?.toLowerCase() ?? "";
}
function inferKindFromPath(path: string): MediaMetadata["kind"] {
const ext = extname(path).toLowerCase();
if (VIDEO_EXT.has(ext)) return "video";
if (IMAGE_EXT.has(ext)) return "image";
if (AUDIO_EXT.has(ext)) return "audio";
return "unknown";
}
function colorLabel(input: {
isHdr: boolean;
hdrTransfer: MediaHdrTransfer | null;
colorPrimaries: string;
colorSpace: string;
colorTransfer: string;
}): string {
if (input.isHdr) {
if (input.hdrTransfer === "pq") return "HDR PQ";
if (input.hdrTransfer === "hlg") return "HDR HLG";
return "HDR";
}
if (
input.colorPrimaries.includes("bt709") ||
input.colorSpace.includes("bt709") ||
input.colorTransfer.includes("bt709")
) {
return "SDR Rec.709";
}
return "SDR/unknown";
}
export function classifyMediaColor(stream: FfprobeStream | null | undefined): MediaColorMetadata {
const colorPrimaries = lower(stream?.color_primaries);
const colorSpace = lower(stream?.color_space);
const colorTransfer = lower(stream?.color_transfer);
const isHdr =
colorPrimaries.includes("bt2020") ||
colorSpace.includes("bt2020") ||
colorTransfer === "smpte2084" ||
colorTransfer === "arib-std-b67";
const hdrTransfer: MediaHdrTransfer | null = isHdr
? colorTransfer === "smpte2084"
? "pq"
: colorTransfer === "arib-std-b67"
? "hlg"
: "unknown"
: null;
return {
dynamicRange: stream ? (isHdr ? "hdr" : "sdr") : "unknown",
hdrTransfer,
label: stream
? colorLabel({ isHdr, hdrTransfer, colorPrimaries, colorSpace, colorTransfer })
: "Unknown",
isHdr,
codecName: stream?.codec_name,
profile: stream?.profile,
pixelFormat: stream?.pix_fmt,
colorSpace: stream?.color_space,
colorTransfer: stream?.color_transfer,
colorPrimaries: stream?.color_primaries,
bitsPerRawSample: stream?.bits_per_raw_sample,
};
}
/** The first shown frame's colour tags, which zscale reads per frame. Empty when unread. */
export async function probeFirstFrameColour(
filePath: string,
runner: FfprobeRunner = execFileRunner,
): Promise<ToneMapSourceColour> {
const ffmpegPath =
findFfBinary("ffmpeg", { configuredMustExist: true }) ??
(runner === execFileRunner ? undefined : "ffmpeg");
if (!ffmpegPath) return {};
const result = await runner(ffmpegPath, firstFrameColourArgs(filePath), {
timeout: 15_000,
maxBuffer: 1024 * 1024,
});
return result.status === 0 ? parseFirstFrameColour(String(result.stderr)) : {};
}
export async function probeMediaMetadata(
filePath: string,
runner: FfprobeRunner = execFileRunner,
): Promise<MediaMetadata> {
const kind = inferKindFromPath(filePath);
if (kind === "audio" || kind === "unknown") {
return { kind, color: classifyMediaColor(null) };
}
// The default runner degrades a missing ffprobe to "unavailable" without
// spawning; injected runners own execution and receive the normal command.
const ffprobePath =
findFfBinary("ffprobe", { configuredMustExist: true }) ??
(runner === execFileRunner ? undefined : "ffprobe");
if (!ffprobePath) {
return { kind, color: classifyMediaColor(null), probeError: "ffprobe unavailable" };
}
const result = await runner(
ffprobePath,
[
"-v",
"error",
"-show_entries",
"stream=codec_type,codec_name,profile,pix_fmt,color_space,color_transfer,color_primaries,bits_per_raw_sample:stream_disposition=attached_pic:stream_tags=alpha_mode",
"-of",
"json",
"--",
filePath,
],
{ timeout: 15_000, maxBuffer: 1024 * 1024 },
);
if (result.error?.code === "ENOENT") {
return { kind, color: classifyMediaColor(null), probeError: "ffprobe unavailable" };
}
if (result.status !== 0) {
return { kind, color: classifyMediaColor(null), probeError: "ffprobe failed" };
}
try {
const parsed = JSON.parse(String(result.stdout || "{}")) as { streams?: FfprobeStream[] };
const stream = parsed.streams?.find((item) => {
if (kind === "image") return item.codec_type === "video";
return item.codec_type === kind && item.disposition?.attached_pic !== 1;
});
const metadata: MediaMetadata = { kind, color: classifyMediaColor(stream) };
if (kind === "video") {
metadata.hasAudio = (parsed.streams ?? []).some((item) => item.codec_type === "audio");
metadata.hasAlpha = stream !== undefined && videoStreamHasAlpha(stream);
}
return metadata;
} catch {
return { kind, color: classifyMediaColor(null), probeError: "ffprobe returned invalid json" };
}
}