@hyperframes/engine 0.7.71 → 0.7.73

package/dist/services/videoFrameExtractor.d.ts

@@ -50,6 +50,17 @@ export interface ExtractionOptions {
     quality?: number;
     format?: VideoFrameFormat;
     sdrToHdrTransfer?: HdrTransfer;
+    /**
+     * Bounded per-source FFmpeg retries. Default 0 preserves stable behavior;
+     * the producer may canary at most one retry after observing typed failures.
+     */
+    maxTransientRetries?: number;
+    /**
+     * Collect metadata-probe failures into `ExtractionResult.errors` instead
+     * of preserving the legacy Promise rejection. Default false; only the
+     * candidate enforce lane may opt into typed aggregation.
+     */
+    collectProbeFailures?: boolean;
 }
 /**
  * Per-phase timings and counters emitted by `extractAllVideoFrames`.
@@ -94,14 +105,50 @@ export interface ExtractionPhaseBreakdown {
     extractMs: number;
     cacheHits: number;
     cacheMisses: number;
+    /** Number of per-source transient failures retried inside this extraction. */
+    transientRetries?: number;
+}
+export type VideoExtractionFailureKind = "cancelled" | "source_missing" | "source_rejected" | "download_not_found" | "download_transient" | "invalid_media" | "media_start_out_of_range" | "ffmpeg_unavailable" | "ffmpeg_timeout" | "ffmpeg_transient" | "ffmpeg_failed" | "zero_output" | "internal";
+export interface VideoExtractionFailure {
+    videoId: string;
+    /** Always populated by this engine version; optional for source compatibility with older consumers. */
+    kind?: VideoExtractionFailureKind;
+    /** Always populated by this engine version; absent legacy values fail closed. */
+    retryable?: boolean;
+    /**
+     * Operator diagnostic retained inside the engine result. Producer-facing
+     * errors must summarize `kind`/counts and must not forward this field: it
+     * can contain a local path or a signed source URL.
+     */
+    error: string;
+}
+export declare class VideoSourceExtractionError extends Error {
+    readonly kind: VideoExtractionFailureKind;
+    readonly retryable: boolean;
+    readonly diagnostic: string;
+    readonly hyperframesVideoSourceExtractionError: true;
+    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string);
 }
+export declare function isVideoSourceExtractionError(error: unknown): error is VideoSourceExtractionError;
+/**
+ * Convert legacy/raw downloader and filesystem errors into the bounded
+ * extraction taxonomy. New extraction code should throw
+ * `VideoSourceExtractionError` directly; this classifier keeps older utility
+ * boundaries safe while they migrate.
+ */
+export declare function classifyVideoExtractionError(error: unknown): VideoSourceExtractionError;
+export declare function runVideoExtractionWithRetry<T>(operation: () => Promise<T>, options?: {
+    signal?: AbortSignal;
+    onRetry?: () => Promise<void> | void;
+    maxTransientRetries?: number;
+}): Promise<{
+    result: T;
+    retries: number;
+}>;
 export interface ExtractionResult {
     success: boolean;
     extracted: ExtractedFrames[];
-    errors: Array<{
-        videoId: string;
-        error: string;
-    }>;
+    errors: VideoExtractionFailure[];
     totalFramesExtracted: number;
     durationMs: number;
     phaseBreakdown: ExtractionPhaseBreakdown;
@@ -122,6 +169,7 @@ export declare function extractVideoFramesRange(videoPath: string, videoId: stri
  * cache entry directory.
  */
 outputDirOverride?: string): Promise<ExtractedFrames>;
+export declare function classifyFfmpegSpawnError(error: unknown, stderr?: string): VideoSourceExtractionError;
 export declare function codecMayHaveAlpha(codec: string | undefined): boolean;
 export declare function decoderForCodec(codec: string | undefined): string;
 export declare function resolveFrameFormat(metadata: VideoMetadata, requested?: VideoFrameFormat): CacheFrameFormat;

package/dist/services/videoFrameExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"videoFrameExtractor.d.ts","sourceRoot":"","sources":["../../src/services/videoFrameExtractor.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAOH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAWL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iCAAkC,CAAC;AACnE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB;;sEAEkE;IAClE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,wBAAwB,EAAE,MAAM,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,wBAAwB,CAAC;CAC1C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAqD/D;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAqC/D;AAED,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,sBAAsB,CAAC,CAAC;AAC5D;;;;;GAKG;AACH,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,eAAe,CAAC,CA4G1B;AA2BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKjE;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EACvB,SAAS,CAAC,EAAE,gBAAgB,GAC3B,gBAAgB,CAIlB;AAyMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CA0CR;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,OAAO,CACd,IAAI,CAAC,YAAY,EAAE,sBAAsB,GAAG,iBAAiB,GAAG,sBAAsB,CAAC,CACxF,EACD,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAigB3B;AA0BD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,eAAe,EAC1B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,UAAQ,EACZ,UAAU,SAAI,GACb,MAAM,GAAG,IAAI,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GAAG;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQhE;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CASA;IACd,OAAO,CAAC,aAAa,CAOb;IACR,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAuB;IAEvC,QAAQ,CACN,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,IAAI,UAAQ,GACX,IAAI;IAQP,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAe5D,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,gBAAgB;IA4CxB,sBAAsB,CACpB,UAAU,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBzD,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IASxD,OAAO,IAAI,IAAI;CAchB;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,EAAE,EACtB,SAAS,EAAE,eAAe,EAAE,GAC3B,gBAAgB,CAWlB"}
+{"version":3,"file":"videoFrameExtractor.d.ts","sourceRoot":"","sources":["../../src/services/videoFrameExtractor.ts"],"names":[],"mappings":"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"}

package/dist/services/videoFrameExtractor.js

@@ -12,7 +12,7 @@ import { decodeUrlPathVariants, MEDIA_DURATION_CLAMP_EPSILON_SECONDS } from "@hy
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { extractMediaMetadata } from "../utils/ffprobe.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
-import { downloadToTemp, isHttpUrl } from "../utils/urlDownloader.js";
+import { downloadToTemp, isHttpUrl, UrlDownloadError } from "../utils/urlDownloader.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -34,6 +34,123 @@ const SDR_TO_HDR_COLORSPACE_FILTER = "colorspace=all=bt2020:iall=bt709:range=tv"
 function sdrToHdrTransformKey(transfer) {
     return `sdr2hdr-${transfer}`;
 }
+export class VideoSourceExtractionError extends Error {
+    kind;
+    retryable;
+    diagnostic;
+    hyperframesVideoSourceExtractionError = true;
+    constructor(kind, retryable, message, diagnostic = message) {
+        super(message);
+        this.kind = kind;
+        this.retryable = retryable;
+        this.diagnostic = diagnostic;
+        this.name = "VideoSourceExtractionError";
+    }
+}
+export function isVideoSourceExtractionError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "hyperframesVideoSourceExtractionError" in error &&
+        error.hyperframesVideoSourceExtractionError === true);
+}
+function boundedTransientRetryBudget(value) {
+    return Number.isFinite(value) && (value ?? 0) >= 1 ? 1 : 0;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Convert legacy/raw downloader and filesystem errors into the bounded
+ * extraction taxonomy. New extraction code should throw
+ * `VideoSourceExtractionError` directly; this classifier keeps older utility
+ * boundaries safe while they migrate.
+ */
+export function classifyVideoExtractionError(error) {
+    if (isVideoSourceExtractionError(error))
+        return error;
+    const diagnostic = errorText(error);
+    const lowered = diagnostic.toLowerCase();
+    if (error instanceof UrlDownloadError) {
+        if (error.kind === "cancelled") {
+            return new VideoSourceExtractionError("cancelled", false, "Video extraction cancelled", diagnostic);
+        }
+        if (error.kind === "http_not_found") {
+            return new VideoSourceExtractionError("download_not_found", false, "Video source was not found", diagnostic);
+        }
+        if (error.kind === "http_rejected") {
+            return new VideoSourceExtractionError("source_rejected", false, "Video source download was rejected", diagnostic);
+        }
+        if (error.retryable) {
+            return new VideoSourceExtractionError("download_transient", true, "Video source download failed transiently", diagnostic);
+        }
+        return new VideoSourceExtractionError("internal", false, "Video source download failed internally", diagnostic);
+    }
+    if (lowered.includes("cancelled") || lowered.includes("aborted")) {
+        return new VideoSourceExtractionError("cancelled", false, "Video extraction cancelled", diagnostic);
+    }
+    if (lowered.includes("video file not found")) {
+        return new VideoSourceExtractionError("source_missing", false, "Video source is missing", diagnostic);
+    }
+    if (lowered.includes("only https urls are permitted") ||
+        lowered.includes("private/reserved address") ||
+        lowered.includes("invalid url")) {
+        return new VideoSourceExtractionError("source_rejected", false, "Video source URL is not permitted", diagnostic);
+    }
+    const httpStatus = diagnostic.match(/\bHTTP\s+(\d{3})\b/i)?.[1];
+    if (httpStatus) {
+        const status = Number(httpStatus);
+        if (status === 404 || status === 410) {
+            return new VideoSourceExtractionError("download_not_found", false, "Video source was not found", diagnostic);
+        }
+        if (status === 408 || status === 429 || status >= 500) {
+            return new VideoSourceExtractionError("download_transient", true, "Video source download failed transiently", diagnostic);
+        }
+        return new VideoSourceExtractionError("source_rejected", false, "Video source download was rejected", diagnostic);
+    }
+    if (lowered.includes("[urldownloader] download timeout") ||
+        lowered.includes("[urldownloader] download failed") ||
+        lowered.includes("fetch failed") ||
+        lowered.includes("network")) {
+        return new VideoSourceExtractionError("download_transient", true, "Video source download failed transiently", diagnostic);
+    }
+    if (lowered.includes("ffprobe not found")) {
+        return new VideoSourceExtractionError("ffmpeg_unavailable", false, "FFprobe is unavailable", diagnostic);
+    }
+    if (lowered.includes("ffprobe deadline")) {
+        return new VideoSourceExtractionError("ffmpeg_timeout", true, "Video inspection timed out", diagnostic);
+    }
+    if (lowered.includes("ffprobe") ||
+        lowered.includes("failed to parse ffprobe output") ||
+        lowered.includes("no video stream found")) {
+        return new VideoSourceExtractionError("invalid_media", false, "Video source could not be inspected", diagnostic);
+    }
+    return new VideoSourceExtractionError("internal", false, "Video extraction failed internally", diagnostic);
+}
+export async function runVideoExtractionWithRetry(operation, options = {}) {
+    const maxTransientRetries = boundedTransientRetryBudget(options.maxTransientRetries);
+    let retries = 0;
+    for (;;) {
+        if (options.signal?.aborted) {
+            throw new VideoSourceExtractionError("cancelled", false, "Video extraction cancelled");
+        }
+        try {
+            return { result: await operation(), retries };
+        }
+        catch (error) {
+            const classified = classifyVideoExtractionError(error);
+            if (options.signal?.aborted) {
+                throw new VideoSourceExtractionError("cancelled", false, "Video extraction cancelled", classified.diagnostic);
+            }
+            if (classified.kind === "cancelled" ||
+                !classified.retryable ||
+                retries >= maxTransientRetries) {
+                throw classified;
+            }
+            retries += 1;
+            await options.onRetry?.();
+        }
+    }
+}
 export function parseVideoElements(html) {
     const videos = [];
     const { document } = parseHTML(unwrapTemplate(html));
@@ -134,7 +251,19 @@ outputDirOverride) {
     const videoOutputDir = outputDirOverride ?? join(outputDir, videoId);
     if (!existsSync(videoOutputDir))
         mkdirSync(videoOutputDir, { recursive: true });
-    const metadata = await extractMediaMetadata(videoPath);
+    let metadata;
+    try {
+        metadata = await extractMediaMetadata(videoPath);
+    }
+    catch (error) {
+        throw classifyVideoExtractionError(error);
+    }
+    if (!(metadata.durationSeconds > 0)) {
+        throw new VideoSourceExtractionError("invalid_media", false, "Video source has no positive duration", `Video source duration is ${metadata.durationSeconds}s`);
+    }
+    if (startTime >= metadata.durationSeconds) {
+        throw new VideoSourceExtractionError("media_start_out_of_range", false, "Video media start is outside the source duration", `Video media start ${startTime}s is outside source duration ${metadata.durationSeconds}s`);
+    }
     const format = resolveFrameFormat(metadata, options.format);
     const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${format}`;
     const outputPattern = join(videoOutputDir, framePattern);
@@ -190,13 +319,10 @@ outputDirOverride) {
     args.push("-y", outputPattern);
     const processResult = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
     if (processResult.terminationReason === "abort") {
-        throw new Error("Video frame extraction cancelled");
+        throw new VideoSourceExtractionError("cancelled", false, "Video extraction cancelled");
     }
     if (processResult.terminationReason === "spawn_error") {
-        if (processResult.error?.code === "ENOENT") {
-            throw new Error("[FFmpeg] ffmpeg not found");
-        }
-        throw processResult.error ?? new Error(processResult.stderr);
+        throw classifyFfmpegSpawnError(processResult.error, processResult.stderr);
     }
     if (!processResult.success) {
         // With the SDR-to-HDR remap folded into this pass, a filter failure
@@ -206,10 +332,17 @@ outputDirOverride) {
         const hdrPrefix = options.sdrToHdrTransfer
             ? `SDR→HDR conversion failed (colorspace filter in extract pass, target ${options.sdrToHdrTransfer}): `
             : "";
-        const timeoutSuffix = processResult.terminationReason === "deadline"
-            ? ` (timed out after ${ffmpegProcessTimeout} ms)`
-            : "";
-        throw new Error(`${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ${processResult.stderr.slice(-500)}`);
+        const timedOut = processResult.terminationReason === "deadline";
+        const timeoutSuffix = timedOut ? ` (timed out after ${ffmpegProcessTimeout} ms)` : "";
+        const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
+            processResult.stderr.slice(-500);
+        if (timedOut) {
+            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic);
+        }
+        const transientIo = /resource temporarily unavailable|device or resource busy|input\/output error/i.test(processResult.stderr);
+        throw new VideoSourceExtractionError(transientIo ? "ffmpeg_transient" : "ffmpeg_failed", transientIo, transientIo
+            ? "Video frame extraction hit a transient I/O failure"
+            : "Video source could not be decoded", diagnostic);
     }
     const framePaths = new Map();
     const files = readdirSync(videoOutputDir)
@@ -218,6 +351,9 @@ outputDirOverride) {
     files.forEach((file, index) => {
         framePaths.set(index, join(videoOutputDir, file));
     });
+    if (framePaths.size === 0 && duration > 0) {
+        throw new VideoSourceExtractionError("zero_output", false, "Video source produced no decodable frames", `FFmpeg exited successfully but produced no frames (start=${startTime}, duration=${duration})`);
+    }
     return {
         videoId,
         srcPath: videoPath,
@@ -229,6 +365,20 @@ outputDirOverride) {
         framePaths,
     };
 }
+const TRANSIENT_FFMPEG_SPAWN_CODES = new Set(["EAGAIN", "EMFILE", "ENFILE"]);
+export function classifyFfmpegSpawnError(error, stderr = "") {
+    const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : "";
+    if (code === "ENOENT") {
+        return new VideoSourceExtractionError("ffmpeg_unavailable", false, "FFmpeg is unavailable", "[FFmpeg] ffmpeg not found");
+    }
+    const diagnostic = error instanceof Error ? error.message : stderr;
+    const retryable = TRANSIENT_FFMPEG_SPAWN_CODES.has(code);
+    return new VideoSourceExtractionError(retryable ? "ffmpeg_transient" : "ffmpeg_failed", retryable, retryable
+        ? "FFmpeg could not be started due to transient resource pressure"
+        : "FFmpeg could not be started", diagnostic);
+}
 /**
  * Resolve the used-segment duration for a video, falling back to the source's
  * natural duration when the caller hasn't specified bounds (end=Infinity) or
@@ -481,6 +631,10 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         extractMs: 0,
         cacheHits: 0,
         cacheMisses: 0,
+        transientRetries: 0,
+    };
+    const recordTransientRetries = (count) => {
+        breakdown.transientRetries = (breakdown.transientRetries ?? 0) + count;
     };
     // Phase 1: Resolve paths and download remote videos
     const phase1Start = Date.now();
@@ -499,7 +653,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             if (isHttpUrl(videoPath)) {
                 const downloadDir = join(options.outputDir, "_downloads");
                 mkdirSync(downloadDir, { recursive: true });
-                videoPath = await downloadToTemp(videoPath, downloadDir);
+                videoPath = await downloadToTemp(videoPath, downloadDir, undefined, signal, () => recordTransientRetries(1));
             }
             if (!existsSync(videoPath)) {
                 // Loud: silent miss leaves the rendered video frozen at frame 0 with
@@ -513,13 +667,24 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                         `If your <video> lives inside a sub-composition, prefer project-root-relative paths ` +
                         `(e.g. src="assets/foo.mp4") over "../assets/foo.mp4".\n`);
                 }
-                errors.push({ videoId: video.id, error: `Video file not found: ${videoPath}` });
+                errors.push({
+                    videoId: video.id,
+                    kind: "source_missing",
+                    retryable: false,
+                    error: `Video file not found: ${videoPath}`,
+                });
                 continue;
             }
             resolvedVideos.push({ video, videoPath });
         }
         catch (err) {
-            errors.push({ videoId: video.id, error: err instanceof Error ? err.message : String(err) });
+            const classified = classifyVideoExtractionError(err);
+            errors.push({
+                videoId: video.id,
+                kind: classified.kind,
+                retryable: classified.retryable,
+                error: classified.diagnostic,
+            });
         }
     }
     breakdown.resolveMs = Date.now() - phase1Start;
@@ -547,7 +712,37 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     });
     // Phase 2: Probe color spaces and normalize if mixed HDR/SDR
     const phase2ProbeStart = Date.now();
-    const videoMetadata = await Promise.all(resolvedVideos.map(({ videoPath }) => extractMediaMetadata(videoPath)));
+    const metadataResults = await Promise.all(resolvedVideos.map(async ({ video, videoPath }, index) => {
+        try {
+            // Keep the default/off path byte-for-byte compatible with the legacy
+            // Promise.all rejection. Classification is introduced only when a
+            // bounded retry or explicit typed aggregation is enabled.
+            const attempted = !options.collectProbeFailures &&
+                boundedTransientRetryBudget(options.maxTransientRetries) === 0
+                ? { result: await extractMediaMetadata(videoPath), retries: 0 }
+                : await runVideoExtractionWithRetry(() => extractMediaMetadata(videoPath), {
+                    signal,
+                    maxTransientRetries: options.maxTransientRetries,
+                    onRetry: () => recordTransientRetries(1),
+                });
+            return {
+                video,
+                videoPath,
+                metadata: attempted.result,
+                cacheKeyInput: cacheKeyInputs[index] ?? null,
+            };
+        }
+        catch (error) {
+            if (!options.collectProbeFailures)
+                throw error;
+            errors.push(extractionError(video.id, error));
+            return null;
+        }
+    }));
+    const probedVideos = metadataResults.filter((entry) => entry !== null);
+    resolvedVideos.splice(0, resolvedVideos.length, ...probedVideos.map(({ video, videoPath }) => ({ video, videoPath })));
+    cacheKeyInputs.splice(0, cacheKeyInputs.length, ...probedVideos.map(({ cacheKeyInput }) => cacheKeyInput));
+    const videoMetadata = probedVideos.map(({ metadata }) => metadata);
     const videoColorSpaces = videoMetadata.map((m) => m.colorSpace);
     // Canonical per-index record of the SDR-to-HDR transform decision. BOTH the
     // cache key (transform discriminator) and the extraction options read from
@@ -591,6 +786,8 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 if (entry.video.mediaStart >= metadata.durationSeconds) {
                     errors.push({
                         videoId: entry.video.id,
+                        kind: "media_start_out_of_range",
+                        retryable: false,
                         error: `SDR→HDR conversion skipped: mediaStart (${entry.video.mediaStart}s) ≥ source duration (${metadata.durationSeconds}s)`,
                     });
                     hdrSkippedIndices.add(i);
@@ -625,13 +822,10 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     for (let i = 0; i < resolvedVideos.length; i++) {
         if (signal?.aborted)
             break;
-        const entry = resolvedVideos[i];
-        if (!entry)
-            continue;
         const vfrProbeStart = Date.now();
-        const metadata = await extractMediaMetadata(entry.videoPath);
+        const metadata = videoMetadata[i];
         breakdown.vfrProbeMs += Date.now() - vfrProbeStart;
-        if (metadata.isVFR)
+        if (metadata?.isVFR)
             breakdown.vfrPreflightCount += 1;
     }
     breakdown.vfrPreflightMs = Date.now() - vfrPreflightStart;
@@ -648,7 +842,13 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         }
     }
     function extractionError(videoId, err) {
-        return { videoId, error: err instanceof Error ? err.message : String(err) };
+        const classified = classifyVideoExtractionError(err);
+        return {
+            videoId,
+            kind: classified.kind,
+            retryable: classified.retryable,
+            error: classified.diagnostic,
+        };
     }
     function scopedExtractionOptions(work) {
         return { ...options, format: work.format, sdrToHdrTransfer: work.sdrToHdrTransfer };
@@ -693,14 +893,33 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             result: rehydratePublishedCache(work, { entry: lookup.entry, srcPath: keyInput.videoPath }),
         };
     }
-    async function extractDirectMiss(miss) {
+    async function extractDirectMiss(miss, maxTransientRetries = options.maxTransientRetries ?? 0) {
         const { work, cacheTarget } = miss;
         if (!cacheTarget) {
-            return extractVideoFramesRange(work.videoPath, work.video.id, work.video.mediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config);
+            const outputDir = join(options.outputDir, work.video.id);
+            const attempted = await runVideoExtractionWithRetry(() => extractVideoFramesRange(work.videoPath, work.video.id, work.video.mediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config), {
+                signal,
+                maxTransientRetries,
+                onRetry: () => {
+                    recordTransientRetries(1);
+                    rmSync(outputDir, { recursive: true, force: true });
+                },
+            });
+            return attempted.result;
         }
         const partialDir = partialCacheEntryDir(cacheTarget.entry);
+        rmSync(partialDir, { recursive: true, force: true });
         mkdirSync(partialDir, { recursive: true });
-        const result = await extractVideoFramesRange(work.videoPath, work.video.id, work.video.mediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config, partialDir);
+        const attempted = await runVideoExtractionWithRetry(() => extractVideoFramesRange(work.videoPath, work.video.id, work.video.mediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config, partialDir), {
+            signal,
+            maxTransientRetries,
+            onRetry: () => {
+                recordTransientRetries(1);
+                rmSync(partialDir, { recursive: true, force: true });
+                mkdirSync(partialDir, { recursive: true });
+            },
+        });
+        const result = attempted.result;
         const published = publishCacheEntry(cacheTarget.entry, partialDir);
         if (!published.published) {
             breakdown.cachePublishFailures += 1;
@@ -708,9 +927,9 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         }
         return rehydratePublishedCache(work, cacheTarget);
     }
-    async function executeDirectMiss(miss) {
+    async function executeDirectMiss(miss, maxTransientRetries = options.maxTransientRetries ?? 0) {
         try {
-            return { result: await extractDirectMiss(miss) };
+            return { result: await extractDirectMiss(miss, maxTransientRetries) };
         }
         catch (err) {
             return { error: extractionError(miss.work.video.id, err) };
@@ -747,6 +966,10 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             : join(options.outputDir, group.groupId);
         try {
             rmSync(tempDir, { recursive: true, force: true });
+            // A long union can hit the fixed FFmpeg deadline even when each shorter
+            // member range succeeds. Do not retry the optimization itself; preserve
+            // the established grouped→direct fallback and apply bounded retries only
+            // to the individual source ranges below.
             const superset = await extractVideoFramesRange(first.videoPath, group.groupId, group.baseStart, group.unionDuration, scopedExtractionOptions(first), signal, config, tempDir);
             const outcomes = [];
             for (const member of group.members) {
@@ -844,7 +1067,14 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             const message = isFollower
                 ? `[shared extraction, leader ${outcome.error.videoId}] ${outcome.error.error}`
                 : outcome.error.error;
-            return { error: { videoId: prepared.work.video.id, error: message } };
+            return {
+                error: {
+                    videoId: prepared.work.video.id,
+                    kind: outcome.error.kind,
+                    retryable: outcome.error.retryable,
+                    error: message,
+                },
+            };
         }
         return { result: { ...outcome.result, videoId: prepared.work.video.id } };
     });