mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(engine,producer): render media readers treat private project files as missing A video, audio, GIF or HEIC src that names a file the file servers refuse (git metadata, env, credentials, tool state, app records), as written or through a link, is now treated as missing by every render-time reader: the compile-time duration probe and keyframe advisory, GIF and HEIC prep, the media drop step, the HDR probe, frame extraction and the audio mixer. The engine's isPrivateUnderAssetRoots judges a path from every asset root that holds it, so a render's own work folder inside the project's .hyperframes/ keeps its downloaded and prepared files. * fix(engine): probe refuses a text file that ffmpeg reads as text-art video ffmpeg's tty and bintext demuxers turn a text file (such as .asc or .nfo) into a video stream that draws the text into frames. Every probe now refuses an input whose container is tty or whose video codec is ansi, bintext, xbin or idf, as not media. Probing, frame extraction and audio reads all go through the same probe, on every render. No demuxer for real video or audio produces these, so local renders keep every other format. * fix(engine,producer,cli): playlist entries and check probes skip private files - A media playlist (HLS segment, key or map URI, ffconcat file) that names a private file inside its own folder is refused as not media, like one that names a file outside it. - `hyperframes check` no longer probes a media source outside the project or private in it: mediaPath returns null for such a file and the audio, heard-clip and HDR checks skip it. - The compiler's duration probe and keyframe check judge privacy from every asset root, as the render-time readers do.
1602 lines
60 KiB
TypeScript
1602 lines
60 KiB
TypeScript
// 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<string> {
|
|
// `--` 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<string, MediaProbeCacheEntry<VideoMetadata>>();
|
|
const finalVideoFrameTimestampCache = new Map<string, MediaProbeCacheEntry<number>>();
|
|
const finalVideoFrameTimestampSignalCaches = new WeakMap<
|
|
AbortSignal,
|
|
Map<string, MediaProbeCacheEntry<number>>
|
|
>();
|
|
const audioMetadataCache = new Map<string, MediaProbeCacheEntry<AudioMetadata>>();
|
|
const audioMetadataSignalCaches = new WeakMap<
|
|
AbortSignal,
|
|
Map<string, MediaProbeCacheEntry<AudioMetadata>>
|
|
>();
|
|
export interface MediaProbeCacheEntry<T = FFProbeOutput> {
|
|
identity: string | null;
|
|
promise: Promise<T>;
|
|
}
|
|
|
|
const mediaProbeOutputCache = new Map<string, MediaProbeCacheEntry>();
|
|
const mediaProbeOutputSignalCaches = new WeakMap<AbortSignal, Map<string, MediaProbeCacheEntry>>();
|
|
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<string, string>;
|
|
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<boolean> {
|
|
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<boolean> {
|
|
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<string, string>();
|
|
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<string, string>();
|
|
|
|
/** 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<T>(
|
|
cache: Map<string, MediaProbeCacheEntry<T>>,
|
|
key: string,
|
|
identity: string | null,
|
|
): Promise<T> | undefined {
|
|
const cached = cache.get(key);
|
|
return cached?.identity === identity ? cached.promise : undefined;
|
|
}
|
|
|
|
export function writeMetadataCache<T>(
|
|
cache: Map<string, MediaProbeCacheEntry<T>>,
|
|
key: string,
|
|
identity: string | null,
|
|
promise: Promise<T>,
|
|
): 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<string, Promise<StoredProbeFacts | null>>();
|
|
|
|
/** The facts stored for a declared URL, fetched once; null when there are none or they cannot be read. */
|
|
function readStoredFacts(filePath: string): Promise<StoredProbeFacts | null> | 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<string> {
|
|
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<number | undefined> | undefined;
|
|
|
|
/** The major version of the ffprobe this process runs; undefined when it cannot be read. */
|
|
function ffprobeMajor(): Promise<number | undefined> {
|
|
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<string> {
|
|
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<VideoMetadata, "videoStreamLeadSeconds" | "mediaTimeOffsetSeconds">,
|
|
): 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<VideoMetadata, "mediaTimeOffsetSeconds">,
|
|
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<FFProbeOutput> {
|
|
let cache = mediaProbeOutputCache;
|
|
if (signal) {
|
|
cache = mediaProbeOutputSignalCaches.get(signal) ?? new Map<string, MediaProbeCacheEntry>();
|
|
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<Buffer> {
|
|
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<boolean> {
|
|
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<MediaProbeProfile> {
|
|
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<string, string | undefined> | 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<VideoMetadata, "width" | "height" | "sampleAspectRatio" | "rotation">,
|
|
): { 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<boolean | undefined> {
|
|
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<VideoMetadata> {
|
|
const identity = mediaFileIdentity(filePath);
|
|
const cached = readMetadataCache(videoMetadataCache, filePath, identity);
|
|
if (cached) return cached;
|
|
|
|
const probePromise = (async (): Promise<VideoMetadata> => {
|
|
// 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<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">,
|
|
): { 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<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">,
|
|
): 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<number | undefined> {
|
|
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<number | undefined> {
|
|
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<number[] | undefined>(
|
|
(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<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">,
|
|
signal?: AbortSignal,
|
|
): Promise<number> {
|
|
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<number | undefined> => {
|
|
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<AudioMetadata> {
|
|
// 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<AudioMetadata> {
|
|
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<number | null> {
|
|
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<string, Promise<KeyframeAnalysis>>();
|
|
|
|
/** 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<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">,
|
|
): Promise<KeyframeAnalysis> {
|
|
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<number> {
|
|
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<KeyframeAnalysis> {
|
|
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,
|
|
};
|
|
}
|