fix: preserve negative-start loop and held tails

Author: jrusso1020

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

@@ -101,6 +101,46 @@ describe("resolveVideoExtractionDuration", () => {
     );
   });
 
+  it("preserves a short source cycle when negative preroll crosses a loop boundary", () => {
+    expect(
+      resolveVideoExtractionWindow(
+        video({ start: -5, end: 10, mediaStart: 0, loop: true }),
+        metadata(3),
+        2,
+      ),
+    ).toEqual({
+      compositionStart: -5,
+      mediaStart: 0,
+      durationSeconds: 3,
+      preserveTimelinePhase: true,
+    });
+  });
+
+  it("preserves source frames needed to hold a non-loop final frame", () => {
+    expect(
+      resolveVideoExtractionWindow(
+        video({ start: -5, end: 10, mediaStart: 0, loop: false }),
+        metadata(3),
+        2,
+      ),
+    ).toEqual({
+      compositionStart: -5,
+      mediaStart: 0,
+      durationSeconds: 3,
+      preserveTimelinePhase: true,
+    });
+  });
+
+  it("rebases a loop phase when the visible window stays within one cycle", () => {
+    expect(
+      resolveVideoExtractionWindow(
+        video({ start: -5, end: 10, mediaStart: 0, loop: true }),
+        metadata(3),
+        0.5,
+      ),
+    ).toEqual({ compositionStart: 0, mediaStart: 2, durationSeconds: 0.5 });
+  });
+
   it("retains legacy behavior when no timeline end is supplied", () => {
     expect(resolveVideoExtractionDuration(video(), metadata(60))).toBe(60);
   });
@@ -1100,6 +1140,64 @@ describe.skipIf(!HAS_FFMPEG)("extractAllVideoFrames on a VFR source", () => {
     expect(result).toMatchObject({ success: true, extracted: [], errors: [] });
   });
 
+  it("preserves loop phase when negative preroll crosses the source boundary", async () => {
+    const outputDir = join(FIXTURE_DIR, "out-negative-loop");
+    mkdirSync(outputDir, { recursive: true });
+    const video: VideoElement = {
+      id: "negative-loop",
+      src: VFR_FIXTURE,
+      start: -19,
+      end: 5,
+      mediaStart: 0,
+      loop: true,
+      hasAudio: false,
+    };
+
+    const result = await extractAllVideoFrames([video], FIXTURE_DIR, {
+      fps: 1,
+      outputDir,
+      timelineEnd: 2,
+    });
+
+    expect(result.errors).toEqual([]);
+    const extracted = result.extracted[0];
+    if (!extracted) throw new Error("expected loop source frames");
+    const lookup = createFrameLookupTable([video], result.extracted);
+    expect(video).toMatchObject({ start: -19, mediaStart: 0, loop: true });
+    expect(lookup.getFrame("negative-loop", 0)).toBe(
+      extracted.framePaths.get(extracted.totalFrames - 1),
+    );
+  }, 30_000);
+
+  it("preserves the held final frame after negative preroll exhausts a source", async () => {
+    const outputDir = join(FIXTURE_DIR, "out-negative-held-tail");
+    mkdirSync(outputDir, { recursive: true });
+    const video: VideoElement = {
+      id: "negative-held-tail",
+      src: VFR_FIXTURE,
+      start: -15,
+      end: 5,
+      mediaStart: 0,
+      loop: false,
+      hasAudio: false,
+    };
+
+    const result = await extractAllVideoFrames([video], FIXTURE_DIR, {
+      fps: 1,
+      outputDir,
+      timelineEnd: 2,
+    });
+
+    expect(result.errors).toEqual([]);
+    const extracted = result.extracted[0];
+    if (!extracted) throw new Error("expected held-tail source frames");
+    const lookup = createFrameLookupTable([video], result.extracted);
+    expect(video).toMatchObject({ start: -15, mediaStart: 0, loop: false });
+    expect(lookup.getFrame("negative-held-tail", 0)).toBe(
+      extracted.framePaths.get(extracted.totalFrames - 1),
+    );
+  }, 30_000);
+
   it("detects the synthesized fixture as VFR", async () => {
     const md = await extractVideoMetadata(VFR_FIXTURE);
     expect(md.isVFR).toBe(true);

packages/engine/src/services/videoFrameExtractor.ts

@@ -738,13 +738,24 @@ export interface TimelineExtractionWindow {
   compositionStart: number;
   mediaStart: number;
   durationSeconds: number;
+  /**
+   * Preserve the authored timeline origin and mediaStart for lookup. This is
+   * required when a negative preroll crosses a source boundary: looped media
+   * still needs its modulo phase, while a non-looping authored slot still
+   * needs the extracted final frame for held-tail playback.
+   */
+  preserveTimelinePhase?: boolean;
 }
 
+type TimelineWindowVideo = Pick<VideoElement, "start" | "end" | "mediaStart"> &
+  Partial<Pick<VideoElement, "loop">>;
+
 /** Intersect a resolved source interval with the render timeline. */
 export function resolveTimelineExtractionWindow(
-  video: Pick<VideoElement, "start" | "end" | "mediaStart">,
+  video: TimelineWindowVideo,
   resolvedDuration: number,
   timelineEnd?: number,
+  sourceDuration?: number,
 ): TimelineExtractionWindow {
   if (timelineEnd === undefined) {
     return {
@@ -762,16 +773,41 @@ export function resolveTimelineExtractionWindow(
     0,
     Math.min(resolvedDuration - trimmedPreroll, timelineEnd - compositionStart),
   );
+  let mediaStart = video.mediaStart + trimmedPreroll;
+  if (durationSeconds > 0 && sourceDuration !== undefined) {
+    const sourceRemaining = Math.max(0, sourceDuration - video.mediaStart);
+    const prerollCrossesSourceEnd = trimmedPreroll >= sourceRemaining;
+    if (sourceRemaining > 0 && video.loop && trimmedPreroll > 0) {
+      const phaseOffset = trimmedPreroll % sourceRemaining;
+      const phaseRemaining = sourceRemaining - phaseOffset;
+      if (durationSeconds > phaseRemaining) {
+        return {
+          compositionStart: video.start,
+          mediaStart: video.mediaStart,
+          durationSeconds: sourceRemaining,
+          preserveTimelinePhase: true,
+        };
+      }
+      mediaStart = video.mediaStart + phaseOffset;
+    } else if (sourceRemaining > 0 && prerollCrossesSourceEnd) {
+      return {
+        compositionStart: video.start,
+        mediaStart: video.mediaStart,
+        durationSeconds: sourceRemaining,
+        preserveTimelinePhase: true,
+      };
+    }
+  }
   return {
     compositionStart,
-    mediaStart: video.mediaStart + trimmedPreroll,
+    mediaStart,
     durationSeconds,
   };
 }
 
 /** Resolve source duration first, then intersect it with the render timeline. */
 export function resolveVideoExtractionWindow(
-  video: Pick<VideoElement, "start" | "end" | "mediaStart">,
+  video: TimelineWindowVideo,
   metadata: VideoMetadata,
   timelineEnd?: number,
 ): TimelineExtractionWindow {
@@ -780,11 +816,16 @@ export function resolveVideoExtractionWindow(
     video.mediaStart,
     metadata,
   );
-  return resolveTimelineExtractionWindow(video, resolvedDuration, timelineEnd);
+  return resolveTimelineExtractionWindow(
+    video,
+    resolvedDuration,
+    timelineEnd,
+    metadata.durationSeconds,
+  );
 }
 
 export function resolveVideoExtractionDuration(
-  video: Pick<VideoElement, "start" | "end" | "mediaStart">,
+  video: TimelineWindowVideo,
   metadata: VideoMetadata,
   timelineEnd?: number,
 ): number {
@@ -1590,9 +1631,11 @@ export async function extractAllVideoFrames(
         if (videoDuration <= 0) {
           return { skipped: true };
         }
-        video.start = window.compositionStart;
-        video.end = window.compositionStart + videoDuration;
-        video.mediaStart = window.mediaStart;
+        if (!window.preserveTimelinePhase) {
+          video.start = window.compositionStart;
+          video.end = window.compositionStart + videoDuration;
+          video.mediaStart = window.mediaStart;
+        }
         const keyInput = cacheKeyInputs[index];
         if (keyInput) keyInput.mediaStart = window.mediaStart;
 

packages/producer/src/services/hdrCompositor.ts

@@ -139,6 +139,8 @@ export interface HdrVideoFrameSource {
   frameSize: number;
   frameCount: number;
   scratch: Buffer;
+  /** The raw file contains one playable source cycle and must wrap at EOF. */
+  loop?: boolean;
 }
 
 export function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: ProducerLogger): void {
@@ -152,6 +154,18 @@ export function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: Prod
   }
 }
 
+export function resolveHdrVideoFrameIndex(
+  time: number,
+  startTime: number,
+  fps: number,
+  frameCount: number,
+  loop = false,
+): number | null {
+  const frameIndex = Math.round((time - startTime) * fps);
+  if (frameIndex < 0 || frameCount < 1) return null;
+  return loop ? frameIndex % frameCount : Math.min(frameIndex, frameCount - 1);
+}
+
 // fallow-ignore-next-line complexity
 export function blitHdrVideoLayer(
   canvas: Buffer,
@@ -173,14 +187,18 @@ export function blitHdrVideoLayer(
     return;
   }
 
-  // Frame index within the video. Clamp to the extracted raw frame count so
-  // a composition that outlives the source clip freezes on the last frame,
-  // matching Chrome's <video> behavior.
-  const videoFrameIndex = Math.round((time - startTime) * fps) + 1;
-  if (videoFrameIndex < 1) return;
-  const effectiveIndex = Math.min(videoFrameIndex, frameSource.frameCount);
-  if (effectiveIndex < 1) return;
-  const frameOffset = (effectiveIndex - 1) * frameSource.frameSize;
+  // Frame index within the extracted playable source range. Loops wrap one
+  // extracted cycle; non-loops clamp to its final frame, matching Chrome's
+  // held-tail behavior for authored slots that outlive the source.
+  const effectiveIndex = resolveHdrVideoFrameIndex(
+    time,
+    startTime,
+    fps,
+    frameSource.frameCount,
+    frameSource.loop,
+  );
+  if (effectiveIndex === null) return;
+  const frameOffset = effectiveIndex * frameSource.frameSize;
 
   try {
     if (hdrPerf) hdrPerf.hdrVideoLayerBlits += 1;