@hyperframes/engine 0.7.89 → 0.7.92

package/dist/services/videoFrameExtractor.js

@@ -8,9 +8,9 @@
 import { copyFileSync, existsSync, linkSync, mkdirSync, readdirSync, rmSync } from "fs";
 import { isAbsolute, join, posix, resolve, sep } from "path";
 import { parseHTML } from "linkedom";
-import { decodeUrlPathVariants, MEDIA_DURATION_CLAMP_EPSILON_SECONDS } from "@hyperframes/core";
+import { decodeUrlPathVariants, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, toFps, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
-import { extractMediaMetadata } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, } from "../utils/ffprobe.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl, UrlDownloadError } from "../utils/urlDownloader.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
@@ -28,6 +28,75 @@ export const VIDEO_FRAME_FORMATS = ["auto", "jpg", "png"];
 export function isVideoFrameFormat(value) {
     return typeof value === "string" && VIDEO_FRAME_FORMATS.includes(value);
 }
+/**
+ * Resolve the frame count produced for a requested extraction duration.
+ *
+ * CFR extraction uses FFmpeg's fps filter, whose end boundary rounds to the
+ * nearest frame. The VFR path normalizes with `-fps_mode cfr -r`, whose end
+ * boundary rounds up. Keep this calculation shared by superset slicing and
+ * producer coverage accounting so a complete VFR extraction cannot be
+ * rejected because the two paths disagree by one frame.
+ */
+export function extractionFrameCountForDuration(durationSeconds, fps, isVFR) {
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0)
+        return 0;
+    // FFmpeg receives `String(durationSeconds)` and parses at microsecond
+    // precision. Derive the integer microseconds from that same decimal text:
+    // multiplying the binary float first is not equivalent (`2.05 * 1e6` is
+    // 2049999.9999999998 in JS and would incorrectly truncate one microsecond).
+    const serialized = String(durationSeconds).toLowerCase();
+    const decimal = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/.exec(serialized);
+    if (!decimal)
+        return 0;
+    const whole = decimal[1] ?? "0";
+    const fraction = decimal[2] ?? "";
+    const exponent = Number.parseInt(decimal[3] ?? "0", 10);
+    const digits = BigInt(`${whole}${fraction}`);
+    const microsecondScale = exponent + 6 - fraction.length;
+    const microseconds = microsecondScale >= 0
+        ? digits * 10n ** BigInt(microsecondScale)
+        : digits / 10n ** BigInt(-microsecondScale);
+    // Keep the frame-boundary calculation rational too. Converting the exact
+    // microseconds back to a binary float recreates the same problem at .5-frame
+    // boundaries (`2.05 * 30` is 61.49999999999999 in JS).
+    let fpsNumerator;
+    let fpsDenominator;
+    if (typeof fps === "object") {
+        if (!Number.isSafeInteger(fps.num) ||
+            !Number.isSafeInteger(fps.den) ||
+            fps.num <= 0 ||
+            fps.den <= 0) {
+            return 0;
+        }
+        fpsNumerator = BigInt(fps.num);
+        fpsDenominator = BigInt(fps.den);
+    }
+    else {
+        if (!Number.isFinite(fps) || fps <= 0)
+            return 0;
+        // Number-only callers retain their decimal FFmpeg argument exactly. The
+        // production render path supplies Fps, so NTSC rates never round-trip
+        // through `String(30000 / 1001)` here.
+        const serializedFps = String(fps).toLowerCase();
+        const fpsDecimal = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/.exec(serializedFps);
+        if (!fpsDecimal)
+            return 0;
+        const fpsWhole = fpsDecimal[1] ?? "0";
+        const fpsFraction = fpsDecimal[2] ?? "";
+        const fpsExponent = Number.parseInt(fpsDecimal[3] ?? "0", 10);
+        const fpsDigits = BigInt(`${fpsWhole}${fpsFraction}`);
+        const fpsScale = fpsExponent - fpsFraction.length;
+        fpsNumerator = fpsScale >= 0 ? fpsDigits * 10n ** BigInt(fpsScale) : fpsDigits;
+        fpsDenominator = fpsScale >= 0 ? 1n : 10n ** BigInt(-fpsScale);
+    }
+    const frameNumerator = microseconds * fpsNumerator;
+    const frameDenominator = 1000000n * fpsDenominator;
+    const frameCount = isVFR
+        ? (frameNumerator + frameDenominator - 1n) / frameDenominator
+        : (2n * frameNumerator + frameDenominator) / (2n * frameDenominator);
+    const frames = Number(frameCount);
+    return Math.max(1, Number.isSafeInteger(frames) ? frames : Number.MAX_SAFE_INTEGER);
+}
 const EXTRACT_CACHE_MIN_AGE_MS = 60 * 60 * 1000;
 const GC_STALENESS_MS = 24 * 60 * 60 * 1000;
 const SDR_TO_HDR_COLORSPACE_FILTER = "colorspace=all=bt2020:iall=bt709:range=tv";
@@ -180,7 +249,10 @@ export function parseVideoElements(html) {
         // reference; the resolver handles both.
         const start = startAttr ? resolveReferencedStart(document, el, startCache, visiting) : 0;
         // Derive end from data-end → data-start+data-duration → Infinity (natural duration).
-        // The caller (htmlCompiler) clamps Infinity to the composition's absoluteEnd.
+        // Static compilation cannot always clamp root media because GSAP may supply
+        // the root duration at runtime. The producer passes the resolved timeline
+        // end into frame extraction, which caps the source duration only after the
+        // natural duration is known without rewriting authored timing metadata.
         let end = 0;
         if (endAttr) {
             end = parseFloat(endAttr);
@@ -247,7 +319,10 @@ export async function extractVideoFramesRange(videoPath, videoId, startTime, dur
  */
 outputDirOverride) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
-    const { fps, outputDir, quality = 95 } = options;
+    const { outputDir, quality = 95 } = options;
+    const normalizedFps = toFps(options.fps);
+    const fps = fpsToNumber(normalizedFps);
+    const ffmpegFps = fpsToFfmpegArg(normalizedFps);
     const videoOutputDir = outputDirOverride ?? join(outputDir, videoId);
     if (!existsSync(videoOutputDir))
         mkdirSync(videoOutputDir, { recursive: true });
@@ -258,11 +333,12 @@ outputDirOverride) {
     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`);
+    const playableDuration = resolvePlayableVideoDuration(metadata);
+    if (!(playableDuration > 0)) {
+        throw new VideoSourceExtractionError("invalid_media", false, "Video source has no positive duration", `Playable video stream duration is ${playableDuration}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`);
+    if (startTime >= playableDuration) {
+        throw new VideoSourceExtractionError("media_start_out_of_range", false, "Video media start is outside the source duration", `Video media start ${startTime}s is outside playable video duration ${playableDuration}s`);
     }
     const format = resolveFrameFormat(metadata, options.format);
     const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${format}`;
@@ -289,14 +365,23 @@ outputDirOverride) {
     if (codecMayHaveAlpha(metadata.videoCodec)) {
         args.push("-c:v", decoderForCodec(metadata.videoCodec));
     }
-    args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
+    if (options.finalFrameOnly) {
+        // Output-side seek decodes from the start before selecting the final
+        // sample. This is intentionally reserved for the one-frame path: input
+        // seeking is faster, but valid unindexed transports (notably MPEG-TS with
+        // a negative timestamp base) can seek to EOF and emit zero frames.
+        args.push("-i", videoPath, "-ss", String(startTime), "-frames:v", "1");
+    }
+    else {
+        args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
+    }
     const vfFilters = [];
     if (isHdr && isMacOS) {
         // VideoToolbox tone-maps during decode; force output to bt709 SDR format
         vfFilters.push("format=nv12");
     }
-    if (!metadata.isVFR) {
-        vfFilters.push(`fps=${fps}`);
+    if (!options.finalFrameOnly && !metadata.isVFR) {
+        vfFilters.push(`fps=${ffmpegFps}`);
     }
     if (options.sdrToHdrTransfer) {
         // Ordering intent: fps sampling runs BEFORE the colorspace remap so only
@@ -310,8 +395,9 @@ outputDirOverride) {
     }
     if (vfFilters.length > 0)
         args.push("-vf", vfFilters.join(","));
-    if (metadata.isVFR)
-        args.push("-fps_mode", "cfr", "-r", String(fps));
+    if (!options.finalFrameOnly && metadata.isVFR) {
+        args.push("-fps_mode", "cfr", "-r", ffmpegFps);
+    }
     args.push("-q:v", format === "jpg" ? String(Math.ceil((100 - quality) / 3)) : "0");
     // Render-scoped temp frames are read once; level 1 measured 3-5x faster for ~14% larger files.
     if (format === "png")
@@ -384,11 +470,149 @@ export function classifyFfmpegSpawnError(error, stderr = "") {
  * natural duration when the caller hasn't specified bounds (end=Infinity) or
  * the bounds are nonsensical (end<=start).
  */
-function resolveSegmentDuration(requested, mediaStart, metadata) {
+function resolveSegmentDuration(requested, mediaStart, sourceDuration) {
     if (Number.isFinite(requested) && requested > 0)
         return requested;
-    const sourceRemaining = metadata.durationSeconds - mediaStart;
-    return sourceRemaining > 0 ? sourceRemaining : metadata.durationSeconds;
+    const sourceRemaining = sourceDuration - mediaStart;
+    return sourceRemaining > 0 ? sourceRemaining : sourceDuration;
+}
+/**
+ * Return the range that can actually produce video frames.
+ *
+ * Container duration may include a longer audio stream or mux padding. Using
+ * it for video extraction planning can reserve raw-frame scratch for seconds
+ * where no video frames exist. `extractMediaMetadata` already falls back to
+ * the container duration when ffprobe omits the stream duration; keep the
+ * explicit fallback here for callers supplying older/manual metadata.
+ */
+export function resolvePlayableVideoDuration(metadata) {
+    return Number.isFinite(metadata.videoStreamDurationSeconds) &&
+        metadata.videoStreamDurationSeconds > 0
+        ? metadata.videoStreamDurationSeconds
+        : metadata.durationSeconds;
+}
+// Logical duration assigned to a one-frame held-tail representation. This is
+// deliberately below any supported output frame interval: coverage expects
+// one frame, while FFmpeg seeks to the separately probed real frame timestamp.
+const FINAL_FRAME_LOGICAL_DURATION_SECONDS = 1e-6;
+/**
+ * Intersect an authored slot with the render timeline, then select the
+ * smallest playable source range that preserves timeline lookup semantics.
+ *
+ * A finite authored slot can outlive the source. In that case FFmpeg should
+ * still extract at most one source range: lookup either wraps that range for
+ * loops or holds its final frame for non-looping video. Keeping the authored
+ * timeline origin separate from the extracted range is what makes both
+ * behaviours survive the source-duration cap.
+ */
+export function resolveTimelineExtractionWindow(video, resolvedDuration, timelineEnd, sourceDuration) {
+    if (timelineEnd === undefined) {
+        return {
+            compositionStart: video.start,
+            mediaStart: video.mediaStart,
+            durationSeconds: resolvedDuration,
+        };
+    }
+    if (!Number.isFinite(timelineEnd)) {
+        throw new Error(`Video extraction timelineEnd must be finite; got ${String(timelineEnd)}`);
+    }
+    const compositionStart = Math.max(0, video.start);
+    const trimmedPreroll = compositionStart - video.start;
+    const timelineDuration = Math.max(0, timelineEnd - compositionStart);
+    // Infinity means "natural source duration", not an authored infinite slot.
+    // Explicit finite slots may outlive the source (loop or held tail), while an
+    // omitted duration remains source-bounded exactly like the browser runtime.
+    const resolvedVisibleDuration = resolvedDuration - trimmedPreroll;
+    const visibleDuration = Math.max(0, Math.min(resolvedVisibleDuration, timelineDuration));
+    let mediaStart = video.mediaStart + trimmedPreroll;
+    if (visibleDuration > 0 && sourceDuration !== undefined) {
+        const sourceRemaining = Math.max(0, sourceDuration - video.mediaStart);
+        if (sourceRemaining > 0 && video.loop && Number.isFinite(video.end)) {
+            const phaseOffset = trimmedPreroll % sourceRemaining;
+            const phaseRemaining = sourceRemaining - phaseOffset;
+            // The element visibility contract includes its end boundary. Preserve a
+            // complete cycle on equality as well, otherwise a rebased suffix would
+            // wrap to its own first frame instead of the source cycle's first frame.
+            if (visibleDuration >= phaseRemaining) {
+                return {
+                    compositionStart: video.start,
+                    mediaStart: video.mediaStart,
+                    durationSeconds: sourceRemaining,
+                    preserveTimelinePhase: true,
+                };
+            }
+            mediaStart = video.mediaStart + phaseOffset;
+        }
+        else if (sourceRemaining > 0) {
+            const sourceVisibleAfterPreroll = Math.max(0, sourceRemaining - trimmedPreroll);
+            if (visibleDuration <= sourceVisibleAfterPreroll) {
+                return {
+                    compositionStart,
+                    mediaStart,
+                    durationSeconds: visibleDuration,
+                };
+            }
+            // The visible interval enters (or is entirely inside) the held tail.
+            // Extract the visible source suffix. If preroll is already at/past the
+            // final decoded timestamp, the async resolver below replaces this tiny
+            // provisional suffix with one exact final frame.
+            const extractionDuration = Math.min(sourceRemaining, Math.max(sourceVisibleAfterPreroll, FINAL_FRAME_LOGICAL_DURATION_SECONDS));
+            const extractionOffset = sourceRemaining - extractionDuration;
+            return {
+                compositionStart: video.start + extractionOffset,
+                mediaStart: video.mediaStart + extractionOffset,
+                durationSeconds: extractionDuration,
+                preserveTimelineEnd: true,
+                ensureFinalFrame: true,
+            };
+        }
+    }
+    return {
+        compositionStart,
+        mediaStart,
+        durationSeconds: visibleDuration,
+    };
+}
+/**
+ * Replace a held-tail suffix that starts at/after the final decoded timestamp
+ * with one exact frame. This keeps raw HDR scratch O(one frame) without
+ * assuming a one-second seek window contains a CFR/VFR timestamp.
+ */
+export async function resolveFinalFrameExtractionWindow(videoPath, video, metadata, window, signal) {
+    if (!window.ensureFinalFrame)
+        return window;
+    const playableDuration = resolvePlayableVideoDuration(metadata);
+    const finalFrameTimestamp = await extractFinalVideoFrameTimestamp(videoPath, {
+        videoStreamDurationSeconds: playableDuration,
+        videoStreamStartSeconds: metadata.videoStreamStartSeconds,
+    }, signal);
+    if (window.mediaStart < finalFrameTimestamp - 1e-9)
+        return window;
+    const sourceRemaining = playableDuration - video.mediaStart;
+    const logicalDuration = Math.min(sourceRemaining, FINAL_FRAME_LOGICAL_DURATION_SECONDS);
+    return {
+        compositionStart: Math.max(0, video.start),
+        mediaStart: playableDuration - logicalDuration,
+        extractionMediaStart: finalFrameTimestamp,
+        durationSeconds: logicalDuration,
+        preserveTimelineEnd: true,
+        finalFrameOnly: true,
+    };
+}
+/** Resolve source duration first, then intersect it with the render timeline. */
+export function resolveVideoExtractionWindow(video, metadata, timelineEnd) {
+    const playableDuration = resolvePlayableVideoDuration(metadata);
+    if (!(playableDuration > 0)) {
+        throw new VideoSourceExtractionError("invalid_media", false, "Video source has no positive duration", `Playable video stream duration is ${playableDuration}s`);
+    }
+    if (video.mediaStart >= playableDuration) {
+        throw new VideoSourceExtractionError("media_start_out_of_range", false, "Video media start is outside the source duration", `Video media start ${video.mediaStart}s is outside playable video duration ${playableDuration}s`);
+    }
+    const resolvedDuration = resolveSegmentDuration(video.end - video.start, video.mediaStart, playableDuration);
+    return resolveTimelineExtractionWindow(video, resolvedDuration, timelineEnd, playableDuration);
+}
+export function resolveVideoExtractionDuration(video, metadata, timelineEnd) {
+    return resolveVideoExtractionWindow(video, metadata, timelineEnd).durationSeconds;
 }
 /**
  * Codecs whose bitstream is allowed to carry an alpha channel. Default the
@@ -452,7 +676,13 @@ function linkOrCopyFrame(src, dest) {
     }
 }
 function supersetGroupingKey(work, fps) {
-    return [work.videoPath, String(fps), work.format, work.sdrToHdrTransfer ?? ""].join("\0");
+    return [
+        work.videoPath,
+        String(fps),
+        work.format,
+        work.sdrToHdrTransfer ?? "",
+        work.finalFrameOnly ? "final" : "range",
+    ].join("\0");
 }
 function isIntegralFrameOffset(offsetSeconds, fps) {
     const frames = offsetSeconds * fps;
@@ -467,6 +697,15 @@ function windowsOverlapOrTouch(misses, baseStart) {
 function buildSupersetGroup(groupId, misses, fps) {
     if (misses.length < 2)
         return null;
+    if (misses.some(({ work }) => work.finalFrameOnly))
+        return null;
+    // VFR normalization (`-fps_mode cfr -r`) establishes its duplicate/drop
+    // phase relative to each seek. A union extraction therefore cannot be
+    // sliced into the same frames as independently sought member ranges, even
+    // when their offsets land on an integral output-frame boundary. Keep VFR
+    // ranges direct until the extractor has a proven absolute timestamp phase.
+    if (misses.some(({ work }) => work.metadata.isVFR))
+        return null;
     const baseStart = Math.min(...misses.map(({ work }) => work.video.mediaStart));
     if (!misses.every(({ work }) => isIntegralFrameOffset(work.video.mediaStart - baseStart, fps))) {
         return null;
@@ -534,7 +773,7 @@ function planSupersetGroups(misses, fps) {
     }
     return { groups, direct };
 }
-function sliceSupersetMember(member, superset, outputDir, fps) {
+function sliceSupersetMember(member, superset, outputDir, fps, configuredFps) {
     const { work } = member.miss;
     rmSync(outputDir, { recursive: true, force: true });
     mkdirSync(outputDir, { recursive: true });
@@ -542,7 +781,7 @@ function sliceSupersetMember(member, superset, outputDir, fps) {
     // offset_i + k, so its source time is
     // baseStart + (offset_i + k) / fps = mediaStart_i + k / fps.
     // The frame-alignment precondition is what makes offset_i integral.
-    const requestedFrames = Math.round(work.videoDuration * fps);
+    const requestedFrames = extractionFrameCountForDuration(work.videoDuration, configuredFps, work.metadata.isVFR);
     const availableFrames = Math.max(0, superset.totalFrames - member.offsetFrames);
     const frameCount = Math.min(requestedFrames, availableFrames);
     for (let i = 0; i < frameCount; i += 1) {
@@ -612,6 +851,12 @@ export function resolveProjectRelativeSrc(src, baseDir, compiledDir) {
     return candidates.find(existsSync) ?? join(baseDir, cleanSrc);
 }
 export async function extractAllVideoFrames(videos, baseDir, options, signal, config, compiledDir) {
+    if (options.timelineEnd !== undefined && !Number.isFinite(options.timelineEnd)) {
+        throw new Error(`Video extraction timelineEnd must be finite; got ${String(options.timelineEnd)}`);
+    }
+    const configuredFps = toFps(options.fps);
+    const fps = fpsToNumber(configuredFps);
+    const fpsKey = fpsToFfmpegArg(configuredFps);
     const startTime = Date.now();
     const extracted = [];
     const errors = [];
@@ -645,6 +890,8 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     for (const video of videos) {
         if (signal?.aborted)
             break;
+        if (options.timelineEnd !== undefined && video.start >= options.timelineEnd)
+            continue;
         try {
             let videoPath = video.src;
             if (!isHttpUrl(videoPath)) {
@@ -689,10 +936,11 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     }
     breakdown.resolveMs = Date.now() - phase1Start;
     // Snapshot the pre-preflight key inputs so the extraction cache keys on the
-    // user-visible source (original path, original mediaStart, original segment
-    // bounds) rather than the workDir-local normalized file produced by the
+    // user-visible source path rather than the
+    // workDir-local normalized file produced by the
     // HDR preflight. Without this, every render would write a new
     // normalized file with a fresh mtime → fresh cache key → perpetual misses.
+    // Phase 3 updates mediaStart after trimming any invisible negative preroll.
     const cacheKeyInputs = resolvedVideos.map(({ video, videoPath }) => {
         const stat = readKeyStat(videoPath);
         // Missing files return null — skip the cache path for that entry. The
@@ -706,8 +954,6 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             mtimeMs: stat.mtimeMs,
             size: stat.size,
             mediaStart: video.mediaStart,
-            start: video.start,
-            end: video.end,
         };
     });
     // Phase 2: Probe color spaces and normalize if mixed HDR/SDR
@@ -783,12 +1029,13 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 // Guard against mediaStart past EOF — FFmpeg's `-ss` silently produces
                 // a 0-byte file when seeking beyond the source duration, and the
                 // downstream extractor then points at a broken input.
-                if (entry.video.mediaStart >= metadata.durationSeconds) {
+                const playableDuration = resolvePlayableVideoDuration(metadata);
+                if (entry.video.mediaStart >= playableDuration) {
                     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)`,
+                        error: `SDR→HDR conversion skipped: mediaStart (${entry.video.mediaStart}s) ≥ playable video duration (${playableDuration}s)`,
                     });
                     hdrSkippedIndices.add(i);
                     continue;
@@ -851,13 +1098,18 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         };
     }
     function scopedExtractionOptions(work) {
-        return { ...options, format: work.format, sdrToHdrTransfer: work.sdrToHdrTransfer };
+        return {
+            ...options,
+            format: work.format,
+            sdrToHdrTransfer: work.sdrToHdrTransfer,
+            finalFrameOnly: work.finalFrameOnly,
+        };
     }
     function rehydratePublishedCache(work, target) {
         const rehydrated = rehydrateCacheEntry(target.entry, {
             videoId: work.video.id,
             srcPath: target.srcPath,
-            fps: options.fps,
+            fps,
             format: work.format,
             metadata: work.metadata,
         });
@@ -869,17 +1121,18 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         const keyInput = cacheKeyInputs[work.index];
         if (!keyInput)
             return { work };
-        const transform = work.sdrToHdrTransfer
-            ? sdrToHdrTransformKey(work.sdrToHdrTransfer)
-            : undefined;
-        const keyDuration = resolveSegmentDuration(keyInput.end - keyInput.start, keyInput.mediaStart, work.metadata);
+        const transformParts = [
+            work.sdrToHdrTransfer ? sdrToHdrTransformKey(work.sdrToHdrTransfer) : undefined,
+            work.finalFrameOnly ? "final-frame" : undefined,
+        ].filter((part) => part !== undefined);
+        const transform = transformParts.length > 0 ? transformParts.join("+") : undefined;
         const lookup = lookupCacheEntry(cacheRootDir, {
             videoPath: keyInput.videoPath,
             mtimeMs: keyInput.mtimeMs,
             size: keyInput.size,
             mediaStart: keyInput.mediaStart,
-            duration: keyDuration,
-            fps: options.fps,
+            duration: work.videoDuration,
+            fps: fpsKey,
             format: work.format,
             transform,
         });
@@ -897,7 +1150,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         const { work, cacheTarget } = miss;
         if (!cacheTarget) {
             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), {
+            const attempted = await runVideoExtractionWithRetry(() => extractVideoFramesRange(work.videoPath, work.video.id, work.extractionMediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config), {
                 signal,
                 maxTransientRetries,
                 onRetry: () => {
@@ -910,7 +1163,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         const partialDir = partialCacheEntryDir(cacheTarget.entry);
         rmSync(partialDir, { recursive: true, force: true });
         mkdirSync(partialDir, { recursive: true });
-        const attempted = await runVideoExtractionWithRetry(() => 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.extractionMediaStart, work.videoDuration, scopedExtractionOptions(work), signal, config, partialDir), {
             signal,
             maxTransientRetries,
             onRetry: () => {
@@ -939,10 +1192,10 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         const { miss } = member;
         const { work, cacheTarget } = miss;
         if (!cacheTarget) {
-            return sliceSupersetMember(member, superset, join(options.outputDir, work.video.id), options.fps);
+            return sliceSupersetMember(member, superset, join(options.outputDir, work.video.id), fps, configuredFps);
         }
         const partialDir = partialCacheEntryDir(cacheTarget.entry);
-        const sliced = sliceSupersetMember(member, superset, partialDir, options.fps);
+        const sliced = sliceSupersetMember(member, superset, partialDir, fps, configuredFps);
         const published = publishCacheEntry(cacheTarget.entry, partialDir);
         if (!published.published) {
             breakdown.cachePublishFailures += 1;
@@ -1003,13 +1256,27 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         }
         try {
             const metadata = videoMetadata[index] ?? (await extractMediaMetadata(videoPath));
-            const videoDuration = resolveSegmentDuration(video.end - video.start, video.mediaStart, metadata);
-            if (video.end - video.start !== videoDuration) {
-                video.end = video.start + videoDuration;
+            const initialWindow = resolveVideoExtractionWindow(video, metadata, options.timelineEnd);
+            const window = await resolveFinalFrameExtractionWindow(videoPath, video, metadata, initialWindow, signal);
+            const videoDuration = window.durationSeconds;
+            if (videoDuration <= 0) {
+                return { skipped: true };
             }
+            if (!window.preserveTimelinePhase) {
+                video.start = window.compositionStart;
+                if (!window.preserveTimelineEnd) {
+                    video.end = window.compositionStart + videoDuration;
+                }
+                video.mediaStart = window.mediaStart;
+            }
+            const keyInput = cacheKeyInputs[index];
+            const extractionMediaStart = window.extractionMediaStart ?? window.mediaStart;
+            if (keyInput)
+                keyInput.mediaStart = extractionMediaStart;
             const format = resolveFrameFormat(metadata, options.format);
             const sdrToHdrTransfer = sdrToHdrTransfers[index];
-            const dedupeKey = `${videoPath}\0${video.mediaStart}\0${videoDuration}\0${options.fps}\0${format}\0${sdrToHdrTransfer ?? ""}`;
+            const finalFrameOnly = window.finalFrameOnly === true;
+            const dedupeKey = `${videoPath}\0${extractionMediaStart}\0${videoDuration}\0${fpsKey}\0${format}\0${sdrToHdrTransfer ?? ""}\0${finalFrameOnly ? "final" : "range"}`;
             return {
                 work: {
                     video,
@@ -1017,6 +1284,8 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                     index,
                     metadata,
                     videoDuration,
+                    extractionMediaStart,
+                    finalFrameOnly,
                     format,
                     sdrToHdrTransfer,
                     dedupeKey,
@@ -1044,7 +1313,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             uniqueOutcomes.set(work.dedupeKey, lookup);
         }
     }
-    const supersetPlan = planSupersetGroups(cacheMisses, options.fps);
+    const supersetPlan = planSupersetGroups(cacheMisses, fps);
     const directOutcomes = await Promise.all(supersetPlan.direct.map(async (miss) => [miss.work.dedupeKey, await executeDirectMiss(miss)]));
     for (const [key, outcome] of directOutcomes)
         uniqueOutcomes.set(key, outcome);
@@ -1053,12 +1322,21 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         for (const [key, outcome] of groupOutcomes)
             uniqueOutcomes.set(key, outcome);
     }
-    const results = preparedExtractions.map((prepared) => {
-        if ("error" in prepared)
-            return prepared;
+    const results = [];
+    for (const prepared of preparedExtractions) {
+        if ("skipped" in prepared)
+            continue;
+        if ("error" in prepared) {
+            results.push(prepared);
+            continue;
+        }
         const outcome = uniqueOutcomes.get(prepared.work.dedupeKey);
-        if (!outcome)
-            return { error: extractionError(prepared.work.video.id, "missing extraction result") };
+        if (!outcome) {
+            results.push({
+                error: extractionError(prepared.work.video.id, "missing extraction result"),
+            });
+            continue;
+        }
         if ("error" in outcome) {
             // A shared (deduped/superset) failure fans out to every element with the
             // same key; annotate followers with the leader's videoId so N copies of
@@ -1067,17 +1345,18 @@ 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 {
+            results.push({
                 error: {
                     videoId: prepared.work.video.id,
                     kind: outcome.error.kind,
                     retryable: outcome.error.retryable,
                     error: message,
                 },
-            };
+            });
+            continue;
         }
-        return { result: { ...outcome.result, videoId: prepared.work.video.id } };
-    });
+        results.push({ result: { ...outcome.result, videoId: prepared.work.video.id } });
+    }
     breakdown.extractMs = Date.now() - phase3Start;
     // Collect results and errors
     for (const item of results) {
@@ -1115,7 +1394,7 @@ function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, me
     let localTime = globalTime - videoStart;
     if (localTime < 0)
         return null;
-    const loopDuration = Math.max(0, extracted.metadata.durationSeconds - mediaStart);
+    const loopDuration = Math.max(0, resolvePlayableVideoDuration(extracted.metadata) - mediaStart);
     if (loop && loopDuration > 0 && localTime >= loopDuration) {
         localTime %= loopDuration;
     }