@hyperframes/engine 0.7.88 → 0.7.90

package/dist/services/videoFrameExtractor.js

@@ -10,7 +10,7 @@ import { isAbsolute, join, posix, resolve, sep } from "path";
 import { parseHTML } from "linkedom";
 import { decodeUrlPathVariants, MEDIA_DURATION_CLAMP_EPSILON_SECONDS } 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";
@@ -180,7 +180,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);
@@ -258,11 +261,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,13 +293,22 @@ 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) {
+    if (!options.finalFrameOnly && !metadata.isVFR) {
         vfFilters.push(`fps=${fps}`);
     }
     if (options.sdrToHdrTransfer) {
@@ -310,8 +323,9 @@ outputDirOverride) {
     }
     if (vfFilters.length > 0)
         args.push("-vf", vfFilters.join(","));
-    if (metadata.isVFR)
+    if (!options.finalFrameOnly && metadata.isVFR) {
         args.push("-fps_mode", "cfr", "-r", String(fps));
+    }
     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 +398,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 +604,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 +625,8 @@ function windowsOverlapOrTouch(misses, baseStart) {
 function buildSupersetGroup(groupId, misses, fps) {
     if (misses.length < 2)
         return null;
+    if (misses.some(({ work }) => work.finalFrameOnly))
+        return null;
     const baseStart = Math.min(...misses.map(({ work }) => work.video.mediaStart));
     if (!misses.every(({ work }) => isIntegralFrameOffset(work.video.mediaStart - baseStart, fps))) {
         return null;
@@ -612,6 +772,9 @@ 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 startTime = Date.now();
     const extracted = [];
     const errors = [];
@@ -645,6 +808,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 +854,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 +872,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 +947,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,7 +1016,12 @@ 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, {
@@ -869,16 +1039,17 @@ 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,
+            duration: work.videoDuration,
             fps: options.fps,
             format: work.format,
             transform,
@@ -897,7 +1068,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 +1081,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: () => {
@@ -1003,13 +1174,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${options.fps}\0${format}\0${sdrToHdrTransfer ?? ""}\0${finalFrameOnly ? "final" : "range"}`;
             return {
                 work: {
                     video,
@@ -1017,6 +1202,8 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                     index,
                     metadata,
                     videoDuration,
+                    extractionMediaStart,
+                    finalFrameOnly,
                     format,
                     sdrToHdrTransfer,
                     dedupeKey,
@@ -1053,12 +1240,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 +1263,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 +1312,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;
     }