// fallow-ignore-file code-duplication complexity import { spawn } from "child_process"; import { createReadStream, mkdtempSync, readFileSync, rmSync, statSync } from "fs"; import { chunkCrc32 } from "./crc32.js"; import { StringDecoder } from "node:string_decoder"; import { tmpdir } from "os"; import { basename, join } from "path"; import { redactTelemetryString } from "@hyperframes/core"; import { alphaDecoderFor, pixelFormatHasAlpha, videoStreamHasAlpha, } from "@hyperframes/parsers/media-alpha"; import { urlInputArgs } from "./urlInput.js"; import { TextArtMediaError } from "./notMediaPayload.js"; import { decodableAudioStream, misstatesPcmByteRate } from "@hyperframes/parsers/media-streams"; import { runFfmpeg } from "./runFfmpeg.js"; import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js"; import { ManagedChildProcess } from "./managedChildProcess.js"; import { trackChildProcess } from "./processTracker.js"; const FFPROBE_STDERR_MAX_BYTES = 8 * 1024; /** Bound on collected stdout. Generous — real -show_streams JSON is well * under this — but finite, unlike the previous unbounded accumulation. */ const FFPROBE_STDOUT_MAX_CHARS = 8_000_000; const FFPROBE_ERROR_MAX_CHARS = 4 * 1024; function redactFfprobeInput(stderr: string, filePath: string): string { if (!filePath) return stderr; let redacted = stderr.split(filePath).join("[input]"); const inputBasename = basename(filePath); if (inputBasename) redacted = redacted.split(inputBasename).join("[input]"); // ManagedChildProcess retains an 8 KiB byte tail. When that boundary lands // inside the input path, stderr starts with only a suffix of the path, so // neither exact-path nor generic absolute-path redaction can recognize it. if (!redacted.startsWith("[input]")) { for (let offset = 1; offset < filePath.length; offset += 1) { const suffix = filePath.slice(offset); if (suffix.length < 4 || !redacted.startsWith(suffix)) continue; const boundary = redacted[suffix.length]; if (boundary !== undefined && !/[\s:'")\]}]/.test(boundary)) continue; redacted = `[input]${redacted.slice(suffix.length)}`; break; } } return redacted; } function sanitizeFfprobeDiagnostic(stderr: string, filePath: string): string { const stderrWithoutInput = redactFfprobeInput(stderr, filePath); const redacted = redactTelemetryString(stderrWithoutInput, FFPROBE_STDERR_MAX_BYTES); if (redacted.length <= FFPROBE_ERROR_MAX_CHARS) return redacted; return `…${redacted.slice(-(FFPROBE_ERROR_MAX_CHARS - 1))}`; } /** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */ export async function runFfprobe( filePath: string, argsWithoutInput: string[], signal?: AbortSignal, stdoutOptions?: { retainTail?: boolean; maxChars?: number }, ): Promise { // `--` stops option parsing so a path like "-intro.mp4" is a filename, but // it does NOT cover a path of exactly "-": ffprobe rewrites that to `fd:` // AFTER option parsing and then reads stdin. Since stdin here is a pipe the // parent never writes to and never ends, the probe hangs for the full 30s // deadline and fails with an empty diagnostic (ffprobe never errored, so // stderr is blank). Reject it up front with something a caller can read. if (filePath === "-") { throw new Error('[FFmpeg] Refusing to probe "-": stdin is not a supported input path.'); } const command = getFfprobeBinary(); const args = [ "-v", "error", ...urlInputArgs(filePath, { tool: "ffprobe" }), ...argsWithoutInput, "--", filePath, ]; const proc = spawn(command, args, { // Nothing is ever written to the child's stdin; leaving it as a pipe is // what lets a stdin-reading invocation block indefinitely. stdio: ["ignore", "pipe", "pipe"], // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows. windowsHide: true, }); trackChildProcess(proc); // Decoded through StringDecoder rather than per-chunk toString(): a // multi-byte character split across a 64 KiB pipe boundary decodes to U+FFFD // on both sides. -show_format output above ~64 KiB with non-ASCII tag text // (an MKV with many chapters, or title/artist tags) came back silently // mangled — JSON.parse still succeeds, so nothing surfaced it, and tag // lookups like alpha_mode could miss. const decoder = new StringDecoder("utf8"); let stdout = ""; let stdoutTruncated = false; const stdoutMaxChars = stdoutOptions?.maxChars ?? FFPROBE_STDOUT_MAX_CHARS; proc.stdout.on("data", (data: Buffer) => { // stderr is capped by ManagedChildProcess; stdout had no bound at all, and // analyzeKeyframeIntervals emits one line per frame — an all-intra ProRes // proxy can produce an unbounded string. if (stdoutTruncated) return; stdout += decoder.write(data); // Checked AFTER appending: a single chunk can already exceed the bound, // so a pre-append check only ever stops the second one. if (stdout.length > stdoutMaxChars) { if (stdoutOptions?.retainTail) { stdout = stdout.slice(-stdoutMaxChars); } else { stdoutTruncated = true; stdout = ""; } } }); const managed = new ManagedChildProcess(proc, { signal, deadlineAtMs: Date.now() + 30_000, stderrMaxBytes: FFPROBE_STDERR_MAX_BYTES, }); const outcome = await managed.wait(); stdout += decoder.end(); if (stdoutTruncated) { throw new Error( `[FFmpeg] ffprobe output exceeded ${stdoutMaxChars} characters; refusing to parse a truncated result.`, ); } if (outcome.reason === "spawn_error") { if ((outcome.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") { const configured = process.env[FFPROBE_PATH_ENV]?.trim(); throw new Error( configured ? `[FFmpeg] ffprobe not found at ${FFPROBE_PATH_ENV}="${configured}". Please install FFmpeg.` : "[FFmpeg] ffprobe not found. Please install FFmpeg.", ); } throw outcome.error ?? new Error(outcome.stderr); } if (outcome.reason !== "exit" || outcome.exitCode !== 0) { const diagnostic = sanitizeFfprobeDiagnostic(outcome.stderr, filePath); throw new Error( `[FFmpeg] ffprobe ${outcome.reason} with code ${outcome.exitCode}: ${diagnostic}`, ); } return stdout; } function parseProbeJson(stdout: string): FFProbeOutput { try { return JSON.parse(stdout); } catch (e) { throw new Error( `[FFmpeg] Failed to parse ffprobe output: ${e instanceof Error ? e.message : e}`, ); } } const videoMetadataCache = new Map>(); const finalVideoFrameTimestampCache = new Map>(); const finalVideoFrameTimestampSignalCaches = new WeakMap< AbortSignal, Map> >(); const audioMetadataCache = new Map>(); const audioMetadataSignalCaches = new WeakMap< AbortSignal, Map> >(); export interface MediaProbeCacheEntry { identity: string | null; promise: Promise; } const mediaProbeOutputCache = new Map(); const mediaProbeOutputSignalCaches = new WeakMap>(); const MEDIA_PROBE_OUTPUT_CACHE_MAX_ENTRIES = 128; // Ignore decoded-vs-container duration differences below this: ffprobe's // container summary is edit-list-corrected (encoder priming delay trimmed) while // a decoded final frame's own timestamp + sample count is not, so the two differ // by a few milliseconds even on an honest file. const AUDIO_DURATION_PROBE_MARGIN_SECONDS = 0.05; // How far before the container's claimed end the decode probe starts reading, // so it decodes only the tail instead of the whole stream. const AUDIO_DURATION_PROBE_TAIL_SECONDS = 1; const FFPROBE_READ_INTERVAL_EXPLICIT_FAR_END = "+2147483647"; export interface VideoColorSpace { /** Color transfer characteristics, e.g. "bt709", "smpte2084", "arib-std-b67" */ colorTransfer: string; /** Color primaries, e.g. "bt709", "bt2020" */ colorPrimaries: string; /** Color matrix/space, e.g. "bt709", "bt2020nc" */ colorSpace: string; } export interface VideoMetadata { durationSeconds: number; videoStreamDurationSeconds: number; /** Absolute presentation timestamp at which the selected video stream * starts. FFmpeg input seeks are relative to this point, while ffprobe frame * timestamps are absolute, so callers crossing those APIs must normalize by * this value. Absent only in legacy/manually-constructed metadata. */ videoStreamStartSeconds?: number; /** Seconds after the file's media time 0 (its earliest audio/video stream start) at which video begins. */ videoStreamLeadSeconds?: number; mediaTimeOffsetSeconds?: number; width: number; height: number; fps: number; videoCodec: string; hasAudio: boolean; /** True when r_frame_rate and avg_frame_rate differ significantly (>10%), indicating variable frame rate. */ isVFR: boolean; /** True when the stream carries an alpha channel. */ hasAlpha: boolean; /** VP8/VP9 without an alpha tag: whether a frame decoded with the alpha-aware decoder had an alpha plane. * Absent when not probed or the probe failed. */ alphaPlaneDecoded?: boolean; /** Color space info from the video stream. Null if ffprobe didn't report it. */ colorSpace: VideoColorSpace | null; colorRange?: string; pixelFormat?: string; sampleAspectRatio?: number; rotation?: number; /** Decoded frame count from the video stream's `nb_frames`. Omitted when the * container does not surface a reliable count (still images, malformed * streams, or muxes that require `-count_packets` to populate). Callers * that gate on a frame count must treat `undefined` as "no answer". */ frames?: number; } export interface AudioMetadata { durationSeconds: number; /** Audio stream's own duration (from `stream.duration`), falling back to * container duration when the stream field is absent. Prefer this over * `durationSeconds` for stream-level parity checks. */ streamDurationSeconds?: number; sampleRate: number; channels: number; audioCodec: string; bitrate?: number; /** Seconds after the file's media time 0 at which its last audio or video stream starts. */ latestStreamLeadSeconds?: number; audioStreamLeadSeconds?: number; mediaTimeOffsetSeconds?: number; audioStreamCount?: number; /** PCM whose header byte rate is not sample rate x channels x sample size: a seek by it lands at the wrong time. */ misstatedByteRate?: boolean; /** The track read for these facts and for the mix, by its place among the audio streams (decodableAudioStream). */ audioStream: number; } interface FFProbeStream { codec_type: string; codec_name?: string; /** e.g. "LC", "HE-AAC", "HE-AACv2" — where the SBR marker lives, since * codec_name is plain "aac" for all of them. */ profile?: string; width?: number; height?: number; duration?: string; start_time?: string; nb_frames?: string; nb_read_packets?: string; pix_fmt?: string; sample_aspect_ratio?: string; r_frame_rate?: string; avg_frame_rate?: string; sample_rate?: string; channels?: number; bit_rate?: string; bits_per_sample?: number; color_range?: string; color_transfer?: string; color_primaries?: string; color_space?: string; tags?: Record; side_data_list?: { rotation?: number }[]; disposition?: { attached_pic?: number }; } interface FFProbeFormat { duration?: string; start_time?: string; bit_rate?: string; format_name?: string; } interface FFProbeOutput { streams: FFProbeStream[]; format: FFProbeFormat; } interface StillImageMetadata { width: number; height: number; colorSpace: VideoColorSpace | null; } export interface MediaProbeProfile { hasVideoStream: boolean; hasAudioStream: boolean; visualKind: "none" | "still" | "moving"; } const STILL_IMAGE_DEMUXERS = new Set([ "apng", "bmp_pipe", "dds_pipe", "dpx_pipe", "exr_pipe", "gif", "ico", "image2", "image2pipe", "jpeg_pipe", "jxl_pipe", "png_pipe", "qdraw_pipe", "sgi_pipe", "svg_pipe", "tiff_pipe", "webp_pipe", ]); async function hasAvifFileBrand(filePath: string): Promise { try { const chunks: Buffer[] = []; for await (const chunk of createReadStream(filePath, { start: 0, end: 4095 })) { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); } const bytes = Buffer.concat(chunks); if (bytes.length < 16 || bytes.toString("ascii", 4, 8) !== "ftyp") return false; const boxSize = bytes.readUInt32BE(0); if (boxSize < 16 || boxSize > bytes.length) return false; const avifBrands = new Set(["avif", "avis"]); if (avifBrands.has(bytes.toString("ascii", 8, 12))) return true; for (let offset = 16; offset + 4 <= boxSize; offset += 4) { if (avifBrands.has(bytes.toString("ascii", offset, offset + 4))) return true; } return false; } catch { return false; } } async function isStillImageVisual(output: FFProbeOutput, filePath: string): Promise { const formatNames = (output.format.format_name ?? "") .split(",") .map((name) => name.trim().toLowerCase()) .filter(Boolean); return ( formatNames.some((name) => STILL_IMAGE_DEMUXERS.has(name)) || (await hasAvifFileBrand(filePath)) ); } function isPngImageProbe(output: FFProbeOutput): boolean { const formatNames = (output.format.format_name ?? "") .split(",") .map((name) => name.trim().toLowerCase()); return ( formatNames.includes("png_pipe") || output.streams.some( (stream) => stream.codec_type === "video" && stream.codec_name?.toLowerCase() === "png", ) ); } const contentAddressedUrls = new Map(); const withoutQuery = (url: string) => url.split(/[?#]/, 1)[0] ?? url; /** A URL whose bytes can never change (its path holds their hash), so probes of it are cacheable. */ export function declareContentAddressedUrl(url: string, sha256: string): void { contentAddressedUrls.set(withoutQuery(url), sha256); } const probeFactsUrls = new Map(); /** Where the ffprobe JSON of a content-addressed URL was stored beforehand: reading it replaces probing the file. */ export function declareProbeFactsUrl(url: string, factsUrl: string): void { probeFactsUrls.set(withoutQuery(url), factsUrl); } export function mediaFileIdentity(filePath: string): string | null { if (/^https?:\/\//i.test(filePath)) { const sha256 = contentAddressedUrls.get(withoutQuery(filePath)); return sha256 ? `sha256:${sha256}` : null; } try { const stat = statSync(filePath, { bigint: true }); return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":"); } catch { return null; } } export function readMetadataCache( cache: Map>, key: string, identity: string | null, ): Promise | undefined { const cached = cache.get(key); return cached?.identity === identity ? cached.promise : undefined; } export function writeMetadataCache( cache: Map>, key: string, identity: string | null, promise: Promise, ): void { const entry = { identity, promise }; cache.set(key, entry); void promise.then( () => { // Without a file identity, share only the in-flight probe, never its result. if (identity === null && cache.get(key) === entry) cache.delete(key); }, () => { if (cache.get(key) === entry) cache.delete(key); }, ); } /** Part of the name a stored probe is kept under: bump it with the args below. */ export const PROBE_FACTS_VERSION = "v2"; const PROBE_JSON_ARGS = ["-print_format", "json", "-show_format", "-show_streams"]; interface StoredProbeFacts { ffprobe: FFProbeOutput; /** Major version of the ffprobe that read the facts; absent in facts stored before it was recorded. */ ffprobeMajor?: number; /** What `extractFinalVideoFrameTimestamp` answers for the stream window it names. */ finalFrame?: { streamStart: number; streamDuration: number; seconds: number; /** `duration_time` of the final video packet; absent in facts stored before it was read. */ lastPacketSeconds?: number; }; } const storedFacts = new Map>(); /** The facts stored for a declared URL, fetched once; null when there are none or they cannot be read. */ function readStoredFacts(filePath: string): Promise | undefined { if (!/^https?:\/\//i.test(filePath)) return undefined; const factsUrl = probeFactsUrls.get(withoutQuery(filePath)); if (!factsUrl) return undefined; let facts = storedFacts.get(factsUrl); if (!facts) { facts = (async () => { try { const response = await fetch(factsUrl, { signal: AbortSignal.timeout(10_000) }); if (!response.ok) return null; const parsed = JSON.parse(await response.text()) as StoredProbeFacts; return Array.isArray(parsed.ffprobe?.streams) ? parsed : null; } catch { return null; } })(); storedFacts.set(factsUrl, facts); } return facts; } /** The ffprobe JSON `probeMediaOutput` works from; a declared URL's stored copy is read in place of probing it. */ export function readProbeJson(filePath: string, signal?: AbortSignal): Promise { const pending = readStoredFacts(filePath); if (!pending) return runFfprobe(filePath, PROBE_JSON_ARGS, signal); return pending.then((stored) => stored ? JSON.stringify(stored.ffprobe) : runFfprobe(filePath, PROBE_JSON_ARGS, signal), ); } let runtimeFfprobeMajor: Promise | undefined; /** The major version of the ffprobe this process runs; undefined when it cannot be read. */ function ffprobeMajor(): Promise { runtimeFfprobeMajor ??= new Promise((resolve) => { let out = ""; const binary = getFfprobeBinary(); const proc = spawn(binary, ["-version"], { stdio: ["ignore", "pipe", "ignore"], windowsHide: true, }); proc.stdout.on("data", (chunk) => (out += String(chunk))); proc.on("error", () => resolve(undefined)); proc.on("close", () => resolve(Number(/version n?(\d+)/.exec(out)?.[1]) || undefined)); }); return runtimeFfprobeMajor; } /** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */ export async function buildProbeFactsText(filePath: string, signal?: AbortSignal): Promise { const facts: StoredProbeFacts = { ffprobe: parseProbeJson(await runFfprobe(filePath, PROBE_JSON_ARGS, signal)), ffprobeMajor: await ffprobeMajor(), }; try { const metadata = await extractMediaMetadata(filePath); const window = resolveStreamWindow(filePath, { videoStreamStartSeconds: metadata.videoStreamStartSeconds, videoStreamDurationSeconds: resolvePlayableVideoDuration(metadata) - (metadata.videoStreamLeadSeconds ?? 0), }); if (window.videoStreamDurationSeconds > 0) { facts.finalFrame = { streamStart: window.videoStreamStartSeconds, streamDuration: window.videoStreamDurationSeconds, seconds: await extractFinalVideoFrameTimestamp(filePath, window, signal), lastPacketSeconds: await extractFinalPacketDuration(filePath, window, signal), }; } } catch { if (signal?.aborted) throw signal.reason; } return JSON.stringify(facts); } export function videoStartOnMediaTimeline( metadata: Pick, ): number { return (metadata.videoStreamLeadSeconds ?? 0) + (metadata.mediaTimeOffsetSeconds ?? 0); } export function formatFfmpegSeconds(seconds: number): string { const text = String(seconds); return text.includes("e") ? String(+seconds.toFixed(6)) : text; } function readIntervalSpec(startSeconds: number, end: number | string): string { const to = typeof end === "number" ? formatFfmpegSeconds(end) : end; return `${formatFfmpegSeconds(startSeconds)}%${to}`; } export function ffmpegSeekSeconds( metadata: Pick, mediaTime: number, ): number { return mediaTime - (metadata.mediaTimeOffsetSeconds ?? 0); } export function resolvePlayableVideoDuration(metadata: VideoMetadata): number { return Number.isFinite(metadata.videoStreamDurationSeconds) && metadata.videoStreamDurationSeconds > 0 ? (metadata.videoStreamLeadSeconds ?? 0) + metadata.videoStreamDurationSeconds : metadata.durationSeconds; } async function probeMediaOutput(filePath: string, signal?: AbortSignal): Promise { let cache = mediaProbeOutputCache; if (signal) { cache = mediaProbeOutputSignalCaches.get(signal) ?? new Map(); mediaProbeOutputSignalCaches.set(signal, cache); } const identity = mediaFileIdentity(filePath); const cached = cache.get(filePath); if (identity !== null && cached?.identity === identity) { // The no-signal fallback is process-scoped, so touch its entries to make // the fixed-size map an LRU. Signal-owned maps are released with their // render and do not need process-lifetime eviction. if (!signal) { cache.delete(filePath); cache.set(filePath, cached); } return cached.promise; } const promise = readProbeJson(filePath, signal).then((json) => refuseTextArt(parseProbeJson(json)), ); if (identity !== null) { cache.set(filePath, { identity, promise }); if (!signal && cache.size > MEDIA_PROBE_OUTPUT_CACHE_MAX_ENTRIES) { const oldestPath = cache.keys().next().value; if (oldestPath !== undefined) cache.delete(oldestPath); } } promise.catch(() => { if (cache.get(filePath)?.promise === promise) { cache.delete(filePath); } }); return promise; } class StructurallyIncompletePngError extends Error {} const TEXT_ART_CODECS = new Set(["ansi", "bintext", "xbin", "idf"]); function refuseTextArt(output: FFProbeOutput): FFProbeOutput { const formats = (output.format?.format_name ?? "").toLowerCase().split(","); const drawsText = (output.streams ?? []).some( (stream) => stream.codec_type === "video" && TEXT_ART_CODECS.has(stream.codec_name?.toLowerCase() ?? ""), ); if (formats.includes("tty") || drawsText) throw new TextArtMediaError(); return output; } async function readFileRange( filePath: string, start: number, length: number, signal?: AbortSignal, ): Promise { const chunks: Buffer[] = []; for await (const chunk of createReadStream(filePath, { start, end: start + length - 1, highWaterMark: length, signal, })) { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); } return Buffer.concat(chunks); } async function hasCompletePngStructure(filePath: string, signal?: AbortSignal): Promise { try { signal?.throwIfAborted(); const fileSize = statSync(filePath).size; // Range streams are read-only and skip large IDAT payloads without loading // the entire image into memory. const signature = await readFileRange(filePath, 0, 8, signal); signal?.throwIfAborted(); if ( signature.length !== 8 || !signature.equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ) { return false; } let seenHeader = false; let seenImageData = false; let offset = 8; while (offset + 12 <= fileSize) { signal?.throwIfAborted(); const chunkHeader = await readFileRange(filePath, offset, 8, signal); signal?.throwIfAborted(); if (chunkHeader.length !== 8) return false; const chunkLength = chunkHeader.readUInt32BE(0); const chunkEnd = offset + 12 + chunkLength; if (chunkEnd > fileSize) return false; const chunkType = chunkHeader.toString("ascii", 4, 8); if (chunkType === "IHDR") seenHeader = chunkLength === 13 && offset === 8; if (chunkType === "IDAT") seenImageData = true; if (chunkType === "IEND") return seenHeader && seenImageData && chunkLength === 0; offset = chunkEnd; } return false; } catch (error) { if (signal?.aborted) throw signal.reason ?? error; return false; } } /** * Probe stream capabilities without assuming the caller's element type. * File extensions and HTTP MIME are deliberately ignored: extensionless * assets and valid media served through generic CDN content types must work. */ export async function probeMediaProfile( filePath: string, options?: { signal?: AbortSignal }, ): Promise { try { const output = await probeMediaOutput(filePath, options?.signal); options?.signal?.throwIfAborted(); const videoStreams = output.streams.filter((stream) => stream.codec_type === "video"); const hasMovingVideoStream = videoStreams.some( (stream) => stream.disposition?.attached_pic !== 1, ); const isStillImage = videoStreams.length > 0 && (await isStillImageVisual(output, filePath)); options?.signal?.throwIfAborted(); if ( isStillImage && isPngImageProbe(output) && !(await hasCompletePngStructure(filePath, options?.signal)) ) { throw new StructurallyIncompletePngError("[FFmpeg] PNG input is structurally incomplete"); } return { hasVideoStream: videoStreams.length > 0, hasAudioStream: decodableAudioStream(output.streams) !== null, visualKind: isStillImage ? "still" : hasMovingVideoStream ? "moving" : "none", }; } catch (error) { if (options?.signal?.aborted) throw options.signal.reason ?? error; if (error instanceof StructurallyIncompletePngError) throw error; // Preserve the PNG parser fallback used by extractMediaMetadata when the // packaged ffprobe binary is unavailable. Signature parsing (not the file // extension) keeps extensionless PNGs eligible for preflight. const stillImage = extractStillImageMetadata(filePath); if (stillImage && (await hasCompletePngStructure(filePath, options?.signal))) { return { hasVideoStream: true, hasAudioStream: false, visualKind: "still" }; } throw error; } } export function extractPngMetadataFromBuffer(buf: Buffer): StillImageMetadata | null { if ( buf.length < 8 || buf[0] !== 137 || buf[1] !== 80 || buf[2] !== 78 || buf[3] !== 71 || buf[4] !== 13 || buf[5] !== 10 || buf[6] !== 26 || buf[7] !== 10 ) { return null; } let width = 0; let height = 0; let seenIdat = false; let colorSpaceFromCicp: VideoColorSpace | null = null; let pos = 8; while (pos + 12 <= buf.length) { const chunkLen = buf.readUInt32BE(pos); const chunkType = buf.toString("ascii", pos + 4, pos + 8); if (pos + 12 + chunkLen > buf.length) return null; const chunkData = buf.subarray(pos + 8, pos + 8 + chunkLen); const chunkCrc = buf.readUInt32BE(pos + 8 + chunkLen); if (chunkCrc32(chunkType, chunkData) !== chunkCrc) return null; // First IHDR only. PNG permits exactly one and it must come first, but a // malformed file can carry more — without this anchor a trailing // [IHDR 1x1] silently replaced the real 4K dimensions, and the producer // laid out a one-pixel image. `>= 13` is the spec length; the old `>= 8` // accepted a truncated header and read height out of the CRC bytes. if (chunkType === "IHDR" && chunkLen >= 13 && width === 0 && height === 0) { width = buf.readUInt32BE(pos + 8); height = buf.readUInt32BE(pos + 12); } if (chunkType === "IDAT") { seenIdat = true; } if (chunkType === "cICP" && chunkLen === 4 && !seenIdat) { const primariesCode = chunkData[0] ?? 0; const transferCode = chunkData[1] ?? 0; const matrixCode = chunkData[2] ?? 0; colorSpaceFromCicp = { colorPrimaries: primariesCode === 9 ? "bt2020" : primariesCode === 1 ? "bt709" : `unknown-${primariesCode}`, colorTransfer: transferCode === 16 ? "smpte2084" : transferCode === 18 ? "arib-std-b67" : transferCode === 1 ? "bt709" : `unknown-${transferCode}`, colorSpace: matrixCode === 9 ? "bt2020nc" : matrixCode === 0 ? "gbr" : `unknown-${matrixCode}`, }; } // Everything this parser extracts has been found, so stop walking. // // Not just an optimisation: cICP must precede IDAT (enforced above), so // continuing only ever visits chunks we ignore — while making whole-file // integrity a precondition for returning anything. A truncated or // bad-CRC trailing chunk in an otherwise-good HDR PNG used to null the // entire result, and the caller then re-throws the swallowed ffprobe // error instead of using the fallback it just computed. if (width > 0 && height > 0 && colorSpaceFromCicp !== null) break; if (chunkType === "IEND") break; pos += 12 + chunkLen; } return width > 0 && height > 0 ? { width, height, colorSpace: colorSpaceFromCicp } : null; } function extractStillImageMetadata(filePath: string): StillImageMetadata | null { try { return extractPngMetadataFromBuffer(readFileSync(filePath)); } catch { return null; } } /** * Read an ffprobe tag case-insensitively. ffmpeg/libavformat versions disagree * on tag casing — VP9 alpha is `alpha_mode` in older builds and `ALPHA_MODE` * in newer ones; HDR tags vary similarly. Use this for any sidecar tag where * you want to be resilient across muxer versions. */ export function readTagCI( tags: Record | undefined, name: string, ): string { if (!tags) return ""; const target = name.toLowerCase(); for (const [key, value] of Object.entries(tags)) { if (key.toLowerCase() === target && typeof value === "string") return value; } return ""; } /** * Parse an ffprobe rational frame rate ("30000/1001") or plain number. * * Returns 0 for anything not a usable positive rate. Exported so tests * exercise the shipped function directly instead of re-importing the module * behind a spawn mock. * * Every guard here is load-bearing, because a bad value is NOT caught * downstream: callers use `meta.fps || 30`, which only rescues 0 and NaN. * Infinity and negatives are truthy and flow into buildEncoderArgs as * `-r Infinity` / `-r -30`, which ffmpeg rejects mid-render, and into * frameCount arithmetic that then goes negative or non-finite. * * - the QUOTIENT is checked, not just the operands: "1e308/1e-10" and * "2/1e-320" have finite parts and an infinite result; * - the sign is checked: "-30/1", "30/-1" and "-60" all parsed clean; * - more than two parts is rejected: "30/1/2" used to fall through to the * bare parseFloat below and return 30, as did "60fps", because parseFloat * stops at trailing garbage; * - sub-0.005 rates round to 0 at 2dp and would be replaced by the caller's * 30fps default, re-encoding a 300-second 1/300-fps timelapse as a * ~1/30-second clip. Kept as 0 is wrong too, so they are floored to the * smallest representable 2dp rate instead. */ export function parseFrameRate(frameRateStr: string | undefined): number { if (!frameRateStr) return 0; const parts = frameRateStr.split("/"); if (parts.length > 2) return 0; // Number(), never parseFloat — on BOTH the rational operands and the plain // form. parseFloat stops at trailing garbage, so "60fps" parsed as 60 and, // once the plain path was fixed but the operands were not, "60fps/1" and // "30garbage/1garbage" still slipped through the rational branch. const strict = (part: string | undefined): number => part === undefined || part.trim() === "" ? NaN : Number(part.trim()); const raw = parts.length === 2 ? (() => { const num = strict(parts[0]); const den = strict(parts[1]); if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return NaN; return num / den; })() : strict(frameRateStr); if (!Number.isFinite(raw) || raw <= 0) return 0; // Checked AFTER rounding as well as before. `raw * 100` overflows for a // finite-but-huge rate ("1e307", "1e307/1"), so `rounded` became Infinity // and sailed past the positivity check — reaching exactly the `-r Infinity` // failure the finite guard above exists to prevent. const rounded = Math.round(raw * 100) / 100; if (!Number.isFinite(rounded)) return 0; // A real but very slow rate must not collapse to 0 and inherit the // caller's 30fps default. return rounded > 0 ? rounded : 0.01; } function displayRotation(stream: FFProbeStream): { rotation?: number } { const turn = Number( stream.side_data_list?.find((data) => data.rotation !== undefined)?.rotation ?? stream.tags?.rotate ?? 0, ); return Number.isFinite(turn) && turn % 360 !== 0 ? { rotation: turn } : {}; } export function displaySize( metadata: Pick, ): { width: number; height: number } { const width = Math.round(metadata.width * (metadata.sampleAspectRatio ?? 1)); return Math.abs(metadata.rotation ?? 0) % 180 === 90 ? { width: metadata.height, height: width } : { width, height: metadata.height }; } export function parseSampleAspectRatio(value: string | undefined): number | undefined { const [num, den] = (value ?? "").split(":").map(Number); if (!num || !den || !Number.isFinite(num) || !Number.isFinite(den)) return undefined; const ratio = num / den; return Math.abs(ratio - 1) < 1e-3 ? undefined : ratio; } /** * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any * failure. ffprobe cannot pick a decoder, so ffmpeg writes the frame as rawvideo, which keeps its pix_fmt. */ export async function probeDecodedAlphaPlane( filePath: string, decoder: string, ): Promise { let probeDir: string | undefined; try { probeDir = mkdtempSync(join(tmpdir(), "hf-decoded-alpha-")); const framePath = join(probeDir, "frame.nut"); const decoded = await runFfmpeg( [ "-v", "error", ...urlInputArgs(filePath), "-c:v", decoder, "-i", filePath, "-frames:v", "1", "-vf", "scale=8:8", "-c:v", "rawvideo", "-f", "nut", framePath, ], { timeout: 30_000 }, ); if (!decoded.success) return undefined; const stdout = await runFfprobe(framePath, [ "-select_streams", "v:0", "-show_entries", "stream=pix_fmt", "-of", "json", ]); const pixFmt = (JSON.parse(stdout) as FFProbeOutput).streams?.[0]?.pix_fmt; return pixFmt ? pixelFormatHasAlpha(pixFmt) : undefined; } catch { return undefined; } finally { if (probeDir) rmSync(probeDir, { recursive: true, force: true }); } } /** * Probe a media file (video, image, or container) and return normalized metadata. * * Despite the legacy name `extractVideoMetadata` (still exported as a * deprecated alias below), this also handles still images such as PNG so it * can be used uniformly for any visual asset the HDR pipeline encounters. */ export async function extractMediaMetadata(filePath: string): Promise { const identity = mediaFileIdentity(filePath); const cached = readMetadataCache(videoMetadataCache, filePath, identity); if (cached) return cached; const probePromise = (async (): Promise => { // Lazily memoized. This is a pure fallback, but it used to run eagerly // and synchronously BEFORE the first await: readFileSync plus a CRC walk // per file, so a caller fanning out over composition.images with // Promise.all executed every parse back-to-back before a single ffprobe // was spawned (12 4K PNGs: 2649 ms vs 170 ms probe-only) — event-loop // stall that also blocks Puppeteer IPC and progress reporting. On the // happy path the result was then discarded. let stillImageMetaMemo: StillImageMetadata | null | undefined; const stillImage = (): StillImageMetadata | null => { stillImageMetaMemo ??= extractStillImageMetadata(filePath); return stillImageMetaMemo; }; let output: FFProbeOutput | null = null; try { output = await probeMediaOutput(filePath); } catch (error) { if (!stillImage()) throw error; } const videoStream = output?.streams.find((s) => s.codec_type === "video"); if (!videoStream) { const stillImageMeta = stillImage(); if (stillImageMeta) { return { durationSeconds: 0, videoStreamDurationSeconds: 0, videoStreamStartSeconds: 0, width: stillImageMeta.width, height: stillImageMeta.height, fps: 0, videoCodec: "png", hasAudio: false, isVFR: false, hasAlpha: false, colorSpace: stillImageMeta.colorSpace, frames: 1, }; } throw new Error("[FFmpeg] No video stream found"); } const rFps = parseFrameRate(videoStream.r_frame_rate); const avgFps = parseFrameRate(videoStream.avg_frame_rate); const fps = avgFps || rFps; // VFR: r_frame_rate (max/nominal) differs from avg_frame_rate (actual average) by >10% const isVFR = rFps > 0 && avgFps > 0 && Math.abs(rFps - avgFps) / Math.max(rFps, avgFps) > 0.1; const colorTransfer = videoStream.color_transfer || ""; const colorPrimaries = videoStream.color_primaries || ""; const colorSpaceVal = videoStream.color_space || ""; // Merged per field, not whole-object. ffprobe emits color_space "gbr" for // every PNG — even a plain rgb24 with no colour metadata — so a // whole-object `??` meant the cICP fallback was discarded whenever // ffprobe ran at all, which is exactly the build it exists to cover: one // that reports gbr but does not decode cICP. An HDR PQ PNG then resolved // colorTransfer "" and graded SDR. const isPng = output !== null && isPngImageProbe(output); const cicp = !isPng || (colorTransfer && colorPrimaries && colorSpaceVal) ? null : stillImage()?.colorSpace; const merged = { colorTransfer: colorTransfer || cicp?.colorTransfer || "", colorPrimaries: colorPrimaries || cicp?.colorPrimaries || "", colorSpace: colorSpaceVal || cicp?.colorSpace || "", }; const colorSpace = merged.colorTransfer || merged.colorPrimaries || merged.colorSpace ? merged : null; const pixelFormat = videoStream.pix_fmt || ""; const sampleAspectRatio = parseSampleAspectRatio(videoStream.sample_aspect_ratio); const hasAlpha = videoStreamHasAlpha(videoStream); const alphaDecoder = hasAlpha ? null : alphaDecoderFor(videoStream.codec_name); const alphaPlaneDecoded = alphaDecoder ? await probeDecodedAlphaPlane(filePath, alphaDecoder) : undefined; let containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0; const streamDuration = videoStream.duration ? parseFloat(videoStream.duration) : 0; // Recorder output (WebM/Matroska written to a pipe) carries no duration header: read it off the packets. if (!(containerDuration > 0) && !(streamDuration > 0) && !isPng) { containerDuration = (await scanPacketDuration(filePath, fps)) ?? 0; } const parsedStreamStart = videoStream.start_time ? parseFloat(videoStream.start_time) : 0; const streamStart = Number.isFinite(parsedStreamStart) ? parsedStreamStart : 0; // `nb_frames` is populated by the container demuxer; a muxer that requires // `-count_packets` to enumerate frames will leave it undefined, in which // case the caller must treat the frame-count check as "no answer". This // path is hit by, for example, fragmented MP4 where the moov box lacks a // frame count — the captured duration is still correct. const parsedNbFrames = videoStream.nb_frames ? parseInt(videoStream.nb_frames, 10) : NaN; const frames = Number.isFinite(parsedNbFrames) && parsedNbFrames > 0 ? parsedNbFrames : undefined; // When the video stream omits its own duration, the container duration // (format.duration) includes the longest stream — often a longer audio // track in stock/looping clips. Cross-check with nb_frames to bound the // video-specific extent and avoid inflating the expected frame count. let effectiveStreamDuration: number; if (streamDuration > 0) { effectiveStreamDuration = streamDuration; } else if (frames !== undefined && fps > 0 && containerDuration > 0) { const frameDerivedDuration = frames / fps; // Only override when the frame-derived duration is meaningfully shorter // (>10% gap). Within 10% the container value is close enough and may // account for a trailing hold frame that nb_frames does not include. effectiveStreamDuration = frameDerivedDuration < containerDuration * 0.9 ? frameDerivedDuration : containerDuration; } else { effectiveStreamDuration = containerDuration; } return { durationSeconds: containerDuration, videoStreamDurationSeconds: effectiveStreamDuration, videoStreamStartSeconds: streamStart, videoStreamLeadSeconds: streamLeadSeconds(output, videoStream), mediaTimeOffsetSeconds: mediaTimeOffsetSeconds(output), width: videoStream.width || stillImage()?.width || 0, height: videoStream.height || stillImage()?.height || 0, fps, videoCodec: videoStream.codec_name || "unknown", hasAudio: decodableAudioStream(output?.streams ?? []) !== null, isVFR, hasAlpha, ...(alphaPlaneDecoded === undefined ? {} : { alphaPlaneDecoded }), colorSpace, colorRange: videoStream.color_range, pixelFormat, ...(sampleAspectRatio === undefined ? {} : { sampleAspectRatio }), ...displayRotation(videoStream), frames, }; })(); writeMetadataCache(videoMetadataCache, filePath, identity, probePromise); return probePromise; } /** * Normalized span of a video stream (not its container), plus its cache key. * Computed here so callers cannot normalize or key differently. */ function resolveStreamWindow( filePath: string, metadata: Pick, ): { videoStreamStartSeconds: number; videoStreamDurationSeconds: number; cacheKey: string } { const videoStreamDurationSeconds = metadata.videoStreamDurationSeconds; const candidateStart = metadata.videoStreamStartSeconds ?? 0; const videoStreamStartSeconds = Number.isFinite(candidateStart) ? candidateStart : 0; const cacheKey = `${filePath}\0${String(videoStreamStartSeconds)}\0${String(videoStreamDurationSeconds)}`; return { videoStreamStartSeconds, videoStreamDurationSeconds, cacheKey }; } /** Stored final-frame facts for this stream window; none if undeclared (no await then, so a probe spawns at once). */ export function readStoredFinalFrame( filePath: string, metadata: Pick, ): Promise<{ seconds: number; lastPacketSeconds?: number } | undefined> | undefined { const { videoStreamStartSeconds, videoStreamDurationSeconds } = resolveStreamWindow( filePath, metadata, ); return readStoredFacts(filePath)?.then(async (facts) => { const stored = facts?.finalFrame; // Another major version may place the final frame or stream start differently: probe instead. if (facts?.ffprobeMajor !== undefined && facts.ffprobeMajor !== (await ffprobeMajor())) return undefined; return stored && stored.streamStart === videoStreamStartSeconds && stored.streamDuration === videoStreamDurationSeconds ? stored : undefined; }); } const PACKET_TAIL_CHARS = 64 * 1024; /** The video stream's length from its packets (last end time), for a file whose headers state none. */ async function scanPacketDuration(filePath: string, fps: number): Promise { try { const stdout = await runFfprobe( filePath, [ ...["-select_streams", "v:0", "-show_entries", "packet=pts_time,duration_time"], ...["-of", "csv=p=0"], ], undefined, { retainTail: true, maxChars: PACKET_TAIL_CHARS }, ); const lines = stdout.split("\n"); // A tail cut at the cap starts partway through a line, and its number would read as a huge time. if (stdout.length >= PACKET_TAIL_CHARS) lines.shift(); const frame = fps > 0 ? 1 / fps : 0; const ends = lines .map((line) => line.trim().split(",").map(Number)) .filter(([pts]) => Number.isFinite(pts)) .map(([pts, duration]) => pts! + (Number.isFinite(duration) ? duration! : frame)); return ends.length ? Math.max(...ends) : undefined; } catch { // expected: a file ffprobe cannot scan keeps its "no duration" verdict. return undefined; } } /** * `duration_time` of the stream's last packet (by presentation time), read from the same final * second the final-frame probe reads; undefined when ffprobe reports none. */ async function extractFinalPacketDuration( filePath: string, window: { videoStreamStartSeconds: number; videoStreamDurationSeconds: number }, signal?: AbortSignal, ): Promise { const streamEnd = window.videoStreamStartSeconds + window.videoStreamDurationSeconds; const intervalStart = Math.max(window.videoStreamStartSeconds, streamEnd - 1); const stdout = await runFfprobe( filePath, [ "-select_streams", "v:0", "-read_intervals", readIntervalSpec(intervalStart, streamEnd), "-show_entries", "packet=pts_time,duration_time", "-of", "csv=p=0", ], signal, { retainTail: true, maxChars: 64 * 1024 }, ); const packets = stdout .split("\n") .map((line) => line.trim().split(",").map(Number)) .filter(([pts, duration]) => Number.isFinite(pts) && Number.isFinite(duration)); const last = packets.reduce( (best, packet) => (!best || packet[0]! > best[0]! ? packet : best), undefined, ); return last?.[1]; } /** * Return the FFmpeg input-seek position of the final decoded video frame. * * A fixed seek window near EOF is not sufficient: sub-1fps and sparse VFR * sources can have no frame timestamp inside that window even though the last * decoded frame remains displayed through the stream duration. ffprobe seeks * to the preceding keyframe and walks forward; retaining only its stdout tail * keeps memory bounded even for a pathological long GOP. ffprobe reports * absolute presentation timestamps, but FFmpeg input `-ss` is relative to the * stream start; the result is normalized into that relative seek domain. Some * unindexed transports cannot decode after an interval seek, so an empty tail * probe falls back to a bounded-output full scan rather than rejecting valid * media. The scan may cost decode time, but retains only 64 KiB of timestamps. */ export async function extractFinalVideoFrameTimestamp( filePath: string, metadata: Pick, signal?: AbortSignal, ): Promise { const { videoStreamStartSeconds, videoStreamDurationSeconds: videoDurationSeconds, cacheKey, } = resolveStreamWindow(filePath, metadata); const identity = mediaFileIdentity(filePath); // A caller-owned abort signal cannot safely own a globally shared process // promise: aborting one render would fail unrelated consumers. Calls in the // SAME cancellation scope should still share the expensive interval + // fallback chain, though — duplicate held-tail elements in one render carry // the same signal and otherwise fan out N full-file scans before extraction // dedupe. Weakly key the cache by cancellation owner to preserve both // aggregate work bounds and cross-render isolation. let probeCache = finalVideoFrameTimestampCache; if (signal) { probeCache = finalVideoFrameTimestampSignalCaches.get(signal) ?? new Map(); finalVideoFrameTimestampSignalCaches.set(signal, probeCache); } const cached = readMetadataCache(probeCache, cacheKey, identity); if (cached) return cached; const probePromise = (async () => { const pendingStored = readStoredFinalFrame(filePath, metadata); const stored = pendingStored && (await pendingStored); if (stored) return stored.seconds; if (!(videoDurationSeconds > 0) || !Number.isFinite(videoDurationSeconds)) { throw new Error( `[FFmpeg] Cannot locate final video frame for invalid duration ${String(videoDurationSeconds)}`, ); } const streamEnd = videoStreamStartSeconds + videoDurationSeconds; const intervalStart = Math.max(videoStreamStartSeconds, streamEnd - 1); const parseFinalTimestamp = (stdout: string): number | undefined => stdout .split("\n") .map((line) => line.trim().split(",")[0]?.trim() ?? "") .filter((value) => value.length > 0) .map((value) => Number(value)) .filter((timestamp) => Number.isFinite(timestamp)) .at(-1); const probe = async (readInterval?: string): Promise => { const args = [ "-select_streams", "v:0", "-show_entries", "frame=best_effort_timestamp_time", "-of", "csv=p=0", ]; if (readInterval) args.splice(2, 0, "-read_intervals", readInterval); const stdout = await runFfprobe(filePath, args, signal, { retainTail: true, maxChars: 64 * 1024, }); return parseFinalTimestamp(stdout); }; const timestamp = (await probe(readIntervalSpec(intervalStart, streamEnd))) ?? (await probe(/* full scan */)); if (timestamp === undefined) { throw new Error("[FFmpeg] ffprobe found no decodable final video frame"); } return Math.min(Math.max(timestamp - videoStreamStartSeconds, 0), videoDurationSeconds); })(); writeMetadataCache(probeCache, cacheKey, identity, probePromise); return probePromise; } /** * @deprecated Use `extractMediaMetadata` — this name is kept for backward * compatibility with consumers that imported the original video-only name * before still-image (PNG) support was added. New callers should prefer * `extractMediaMetadata`. */ export const extractVideoMetadata = extractMediaMetadata; export async function extractAudioMetadata( filePath: string, options?: { signal?: AbortSignal }, ): Promise { // A probe bound to a caller's abort signal is shared only among callers of that same signal, // and only when the file has an identity to key it by. const identity = mediaFileIdentity(filePath); const signal = options?.signal; if (signal && identity === null) return probeAudioMetadata(filePath, signal); let cache = audioMetadataCache; if (signal) { cache = audioMetadataSignalCaches.get(signal) ?? new Map(); audioMetadataSignalCaches.set(signal, cache); } const cached = readMetadataCache(cache, filePath, identity); if (cached) return cached; const probePromise = probeAudioMetadata(filePath, signal); writeMetadataCache(cache, filePath, identity, probePromise); return probePromise; } async function probeAudioMetadata(filePath: string, signal?: AbortSignal): Promise { const output = await probeMediaOutput(filePath, signal); const audioStreams = output.streams.filter((s) => s.codec_type === "audio"); const audioStreamIndex = decodableAudioStream(output.streams); const audioStream = audioStreamIndex === null ? undefined : audioStreams[audioStreamIndex]; if (audioStreamIndex === null || !audioStream) throw new Error("[FFmpeg] No audio stream found"); let durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0; const streamDuration = audioStream.duration ? parseFloat(audioStream.duration) : undefined; const sampleRate = audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100; const audioCodec = audioStream.codec_name || "unknown"; // Container summaries can undercount intact audio, so the decoded last frame wins. // The probe returns null instead of throwing: a throw here drops the audio element. if (sampleRate > 0) { const decoded = await probeDecodedAudioDuration( filePath, audioStreamIndex, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal, ); if (decoded !== null) { durationSeconds = reconcileAudioDuration(durationSeconds, decoded, output.format); } } return { durationSeconds, streamDurationSeconds: streamDuration && streamDuration > 0 ? streamDuration : undefined, sampleRate, channels: audioStream.channels || 2, audioCodec, bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined, latestStreamLeadSeconds: latestStreamLeadSeconds(output), audioStreamLeadSeconds: streamLeadSeconds(output, audioStream), mediaTimeOffsetSeconds: mediaTimeOffsetSeconds(output), audioStreamCount: audioStreams.length, audioStream: audioStreamIndex, misstatedByteRate: misstatesPcmByteRate(audioStream), }; } /** A stream starting after the earliest of these plays that much after it. */ function audioVideoStreamStarts(output: FFProbeOutput | null): number[] { return (output?.streams ?? []) .filter( (s) => (s.codec_type === "audio" || s.codec_type === "video") && s.disposition?.attached_pic !== 1, ) .map((s) => parseFloat(s.start_time ?? "")) .filter(Number.isFinite); } function streamLeadSeconds(output: FFProbeOutput | null, stream: FFProbeStream): number { const starts = audioVideoStreamStarts(output); const start = parseFloat(stream.start_time ?? ""); return Number.isFinite(start) && starts.length > 0 ? Math.max(0, start - Math.min(...starts)) : 0; } const BROWSER_PLAYS_FROM_TIMESTAMP_ZERO = /\b(mp4|webm)\b/; function mediaTimeOffsetSeconds(output: FFProbeOutput | null): number { const starts = audioVideoStreamStarts(output); const fromZero = BROWSER_PLAYS_FROM_TIMESTAMP_ZERO.test(output?.format.format_name ?? ""); return fromZero && starts.length > 0 ? Math.max(0, Math.min(...starts)) : 0; } function latestStreamLeadSeconds(output: FFProbeOutput): number { const starts = audioVideoStreamStarts(output); return starts.length > 0 ? Math.max(...starts) - Math.min(...starts) : 0; } function audioStartSeconds(stream: FFProbeStream, format: FFProbeFormat): number { const start = parseFloat(stream.start_time ?? format.start_time ?? ""); return Number.isFinite(start) ? start : 0; } // Raw ADTS durations are bitrate estimates that overclaim after a quiet opening, so a shorter // decode wins there. Elsewhere a shorter decode can be an edit-list trim, so only longer wins. function reconcileAudioDuration( containerSeconds: number, decodedSeconds: number, format: FFProbeFormat, ): number { const difference = decodedSeconds - containerSeconds; const trustShorter = format.format_name === "aac"; if (difference > AUDIO_DURATION_PROBE_MARGIN_SECONDS) return decodedSeconds; if (trustShorter && difference < -AUDIO_DURATION_PROBE_MARGIN_SECONDS) return decodedSeconds; return containerSeconds; } /** * True audio duration from the last decoded frame (timestamp + nb_samples - stream start): tail * first, then the whole file if a bad seek finds nothing. Null, never a throw, except on abort. */ async function probeDecodedAudioDuration( filePath: string, audioStream: number, sampleRate: number, startSeconds: number, containerDurationSeconds: number, signal?: AbortSignal, ): Promise { const probe = async ( readInterval?: string, ): Promise<{ timestamp: number; nbSamples: number } | undefined> => { const args = [ "-select_streams", `a:${audioStream}`, "-show_entries", "frame=best_effort_timestamp_time,nb_samples", "-of", "csv=p=0", ]; if (readInterval) args.unshift("-read_intervals", readInterval); try { const stdout = await runFfprobe( filePath, args, signal, // CSV, not JSON: a tail truncated under the size cap still parses. { retainTail: true, maxChars: 64 * 1024 }, ); return stdout .split("\n") .map((line) => { const [timestampText, samplesText] = line.trim().split(","); const timestamp = Number(timestampText); const nbSamples = Number(samplesText); return Number.isFinite(timestamp) && Number.isFinite(nbSamples) ? { timestamp, nbSamples } : undefined; }) .filter((frame) => frame !== undefined) .at(-1); } catch (error) { if (signal?.aborted) throw signal.reason ?? error; return undefined; } }; const tailStart = Math.max( startSeconds, startSeconds + containerDurationSeconds - AUDIO_DURATION_PROBE_TAIL_SECONDS, ); const lastFrame = (await probe(readIntervalSpec(tailStart, FFPROBE_READ_INTERVAL_EXPLICIT_FAR_END))) ?? (await probe()); if (!lastFrame) return null; return lastFrame.timestamp + lastFrame.nbSamples / sampleRate - startSeconds; } export interface KeyframeAnalysis { avgIntervalSeconds: number; maxIntervalSeconds: number; keyframeCount: number; isProblematic: boolean; } const keyframeCache = new Map>(); /** Advisory threshold for seeking cost; GOP length alone does not establish incorrect output. */ const PROBLEMATIC_KEYFRAME_INTERVAL_SECONDS = 2; /** * Checks keyframe intervals in a video stream; intervals over the threshold below flag `isProblematic`. * Pass the stream's own duration/start (not the container's), which can overstate a single-keyframe GOP. */ export async function analyzeKeyframeIntervals( filePath: string, metadata: Pick, ): Promise { const { videoStreamStartSeconds, videoStreamDurationSeconds, cacheKey } = resolveStreamWindow( filePath, metadata, ); const cached = keyframeCache.get(cacheKey); if (cached) return cached; const promise = analyzeKeyframeIntervalsUncached( filePath, videoStreamStartSeconds, videoStreamDurationSeconds, ); keyframeCache.set(cacheKey, promise); promise.catch(() => { if (keyframeCache.get(cacheKey) === promise) { keyframeCache.delete(cacheKey); } }); return promise; } /** Seconds ffmpeg decodes without output after a seek to `seekSeconds`: back to the keyframe it lands on. */ export async function keyframeGapSeconds( filePath: string, seekSeconds: number, signal?: AbortSignal, ): Promise { const stdout = await runFfprobe( filePath, [ ...["-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0"], ...["-read_intervals", readIntervalSpec(seekSeconds, "+#1")], ], signal, ); const keyframe = parseFloat(stdout.split("\n")[0] ?? ""); return Number.isFinite(keyframe) ? Math.max(0, seekSeconds - keyframe) : 0; } async function analyzeKeyframeIntervalsUncached( filePath: string, videoStreamStartSeconds: number, videoStreamDurationSeconds: number, ): Promise { const stdout = await runFfprobe(filePath, [ "-select_streams", "v:0", "-skip_frame", "nokey", "-show_entries", "frame=pts_time", "-of", "csv=p=0", ]); const timestamps = stdout .split("\n") .map((line) => parseFloat(line.trim())) .filter((t) => Number.isFinite(t)); if (timestamps.length === 0) { return { avgIntervalSeconds: 0, maxIntervalSeconds: 0, keyframeCount: 0, isProblematic: false, }; } if (timestamps.length === 1) { // A single keyframe means the whole stream is one GOP — the worst case, not the healthy one. // `timestamps[0]` is an absolute pts, so compare it against the absolute stream end // (start + duration), not against duration alone. const streamEnd = videoStreamStartSeconds + videoStreamDurationSeconds; // The fallback is unreachable (length === 1); it only satisfies // noUncheckedIndexedAccess. const rawInterval = streamEnd - (timestamps[0] ?? videoStreamStartSeconds); const singleGopInterval = Number.isFinite(rawInterval) ? Math.max(rawInterval, 0) : 0; const roundedInterval = Math.round(singleGopInterval * 100) / 100; return { avgIntervalSeconds: roundedInterval, maxIntervalSeconds: roundedInterval, keyframeCount: 1, isProblematic: singleGopInterval > PROBLEMATIC_KEYFRAME_INTERVAL_SECONDS, }; } let maxInterval = 0; let totalInterval = 0; for (let i = 1; i < timestamps.length; i++) { const interval = (timestamps[i] ?? 0) - (timestamps[i - 1] ?? 0); totalInterval += interval; if (interval > maxInterval) maxInterval = interval; } const avgInterval = totalInterval / (timestamps.length - 1); return { avgIntervalSeconds: Math.round(avgInterval * 100) / 100, maxIntervalSeconds: Math.round(maxInterval * 100) / 100, keyframeCount: timestamps.length, isProblematic: maxInterval > PROBLEMATIC_KEYFRAME_INTERVAL_SECONDS, }; }