fix(producer): drop clips outside the timeline before extraction, cloud renders included

The previous commit marked such a clip with end = start, but the window
resolver reads a zero-length slot as "use the source's natural length", and
the distributed plan still required an extracted entry for every declared
clip. Instead, the extract stage (shared by in-process and distributed
renders) removes clips that lie entirely outside [0, duration) from the
composition before probing and extraction, using one engine predicate that
the extractor's own early skip also uses, so a clip ending before 0 is no
longer downloaded or probed either.

Author: miguel-heygen

packages/engine/src/index.ts

@@ -204,6 +204,7 @@ export {
   parseImageElements,
   extractVideoFramesRange,
   extractAllVideoFrames,
+  isVideoOutsideTimeline,
   resolveTimelineExtractionWindow,
   resolveVideoExtractionWindow,
   resolveFinalFrameExtractionWindow,

packages/engine/src/services/videoFrameExtractor.test.ts

@@ -2286,31 +2286,28 @@ describe.skipIf(!HAS_FFMPEG)("extractAllVideoFrames on a VFR source", () => {
     });
 
     expect(result).toMatchObject({ success: true, extracted: [], errors: [] });
-    // Frame coverage reads this window; a clip never on screen owes no frames.
-    expect(video).toMatchObject({ start: -2, end: -2 });
   });
 
-  it("gives a clip starting after the timeline end an empty window, not an error", async () => {
-    const outputDir = join(FIXTURE_DIR, "out-after-timeline");
+  it("never opens the source of a clip outside the timeline", async () => {
+    const outputDir = join(FIXTURE_DIR, "out-outside-missing");
     mkdirSync(outputDir, { recursive: true });
-    const video: VideoElement = {
-      id: "after-timeline",
-      src: VFR_FIXTURE,
-      start: 4,
-      end: 6,
+    const outside = (id: string, start: number, end: number): VideoElement => ({
+      id,
+      src: "missing-source.mp4",
+      start,
+      end,
       mediaStart: 0,
       loop: false,
       hasAudio: false,
-    };
-
-    const result = await extractAllVideoFrames([video], FIXTURE_DIR, {
-      fps: 1,
-      outputDir,
-      timelineEnd: 3,
     });
 
+    const result = await extractAllVideoFrames(
+      [outside("before-zero", -2, -1), outside("after-end", 4, 6)],
+      FIXTURE_DIR,
+      { fps: 1, outputDir, timelineEnd: 3 },
+    );
+
     expect(result).toMatchObject({ success: true, extracted: [], errors: [] });
-    expect(video).toMatchObject({ start: 4, end: 4 });
   });
 
   it("preserves loop phase when negative preroll crosses the source boundary", async () => {

packages/engine/src/services/videoFrameExtractor.ts

@@ -1348,11 +1348,6 @@ function canHoldFinalFramePastEof(video: TimelineWindowVideo): boolean {
 // one frame, while FFmpeg seeks to the separately probed real frame timestamp.
 const FINAL_FRAME_LOGICAL_DURATION_SECONDS = 1e-6;
 
-/** A clip entirely outside the render timeline is never on screen, so it owes no frames. */
-function clearVideoWindow(video: VideoElement): void {
-  video.end = video.start;
-}
-
 /** Move a clip to its extraction window; a rate lane is shifted so it keeps integrating from the new origin. */
 export function rebaseVideoToWindow(video: VideoElement, window: TimelineExtractionWindow): void {
   if (window.preserveTimelinePhase) return;
@@ -1376,6 +1371,13 @@ export function rebaseVideoToWindow(video: VideoElement, window: TimelineExtract
  * timeline origin separate from the extracted range is what makes both
  * behaviours survive the source-duration cap.
  */
+export function isVideoOutsideTimeline(
+  video: Pick<VideoElement, "start" | "end">,
+  timelineEnd: number,
+): boolean {
+  return video.start >= timelineEnd || video.end <= 0;
+}
+
 export function resolveTimelineExtractionWindow(
   video: TimelineWindowVideo,
   resolvedDuration: number,
@@ -1873,8 +1875,7 @@ export async function extractAllVideoFrames(
   const warnedSrcs = new Set<string>();
   for (const video of videos) {
     if (signal?.aborted) break;
-    if (options.timelineEnd !== undefined && video.start >= options.timelineEnd) {
-      clearVideoWindow(video);
+    if (options.timelineEnd !== undefined && isVideoOutsideTimeline(video, options.timelineEnd)) {
       continue;
     }
     try {
@@ -2460,7 +2461,6 @@ export async function extractAllVideoFrames(
         );
         const videoDuration = window.durationSeconds;
         if (videoDuration <= 0) {
-          clearVideoWindow(video);
           return { skipped: true };
         }
         rebaseVideoToWindow(video, window);

packages/producer/src/services/render/stages/extractVideosStage.timelineBound.test.ts

@@ -12,6 +12,7 @@ const extractionCalls = vi.hoisted(
 );
 const toneMapHdrToSdrCalls = vi.hoisted(() => new Array<boolean | undefined>());
 const contentKeyedDirsCalls = vi.hoisted(() => new Array<readonly string[] | undefined>());
+const requestedVideoIds = vi.hoisted(() => new Array<string[]>());
 const fixtureState = vi.hoisted(() => ({ sourceDurationSeconds: 60 }));
 
 vi.mock("@hyperframes/engine", async (importOriginal) => {
@@ -27,6 +28,7 @@ vi.mock("@hyperframes/engine", async (importOriginal) => {
         contentKeyedDirs?: readonly string[];
       },
     ): Promise<ExtractionResult> => {
+      requestedVideoIds.push(videos.map((v) => v.id));
       const sourceDurationSeconds = fixtureState.sourceDurationSeconds;
       const video = videos[0];
       if (!video) throw new Error("timeline-bound fixture requires one video");
@@ -80,8 +82,8 @@ import { runExtractVideosStage } from "./extractVideosStage.js";
 async function runStage(
   compositionDuration: number,
   materializeSymlinks: boolean,
-  options: { source?: string; log?: ProducerLogger } = {},
-): Promise<void> {
+  options: { source?: string; log?: ProducerLogger; extraVideos?: VideoElement[] } = {},
+): Promise<VideoElement[]> {
   const composition = {
     duration: compositionDuration,
     videos: [
@@ -94,6 +96,7 @@ async function runStage(
         loop: false,
         hasAudio: false,
       },
+      ...(options.extraVideos ?? []),
     ],
     audios: [],
     images: [],
@@ -115,6 +118,7 @@ async function runStage(
     assertNotAborted: () => {},
     materializeSymlinks,
   });
+  return composition.videos;
 }
 
 describe.each([
@@ -150,6 +154,26 @@ describe.each([
     expect(toneMapHdrToSdrCalls).toEqual([true]);
   });
 
+  it("drops clips outside the timeline before extraction", async () => {
+    requestedVideoIds.splice(0);
+    const outside = (id: string, start: number, end: number): VideoElement => ({
+      id,
+      src: "outside.mp4",
+      start,
+      end,
+      mediaStart: 0,
+      loop: false,
+      hasAudio: false,
+    });
+
+    const videos = await runStage(2, materializeSymlinks, {
+      extraVideos: [outside("after-end", 2, 4), outside("before-zero", -3, -1)],
+    });
+
+    expect(requestedVideoIds).toEqual([["root-video"]]);
+    expect(videos.map((v) => v.id)).toEqual(["root-video"]);
+  });
+
   it("caches the compiled remote-media copies by content", async () => {
     contentKeyedDirsCalls.splice(0);
 

packages/producer/src/services/render/stages/extractVideosStage.ts

@@ -45,6 +45,7 @@ import {
   detectTransfer,
   extractAllVideoFrames,
   extractMediaMetadata,
+  isVideoOutsideTimeline,
   isHdrColorSpace,
   resolveProjectRelativeSrc,
   runVideoExtractionWithRetry,
@@ -389,6 +390,9 @@ export async function runExtractVideosStage(
 
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
+  composition.videos = composition.videos.filter(
+    (video) => !isVideoOutsideTimeline(video, composition.duration),
+  );
 
   let frameLookup: FrameLookupTable | null = null;
   let extractionResult: Awaited<ReturnType<typeof extractAllVideoFrames>> | null = null;