Skip to content

Commit f0c2c7d

Browse files
committed
fix(producer): align frame coverage with extraction rounding
1 parent f500a42 commit f0c2c7d

2 files changed

Lines changed: 97 additions & 24 deletions

File tree

‎packages/producer/src/services/render/videoFrameCoverage.test.ts‎

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// fallow-ignore-file code-duplication
2+
13
import type { ExtractedFrames, VideoElement, VideoMetadata } from "@hyperframes/engine";
24
import { describe, expect, it } from "vitest";
35
import {
@@ -35,9 +37,9 @@ function makeVideo(overrides: Partial<VideoElement> & { id: string }): VideoElem
3537
function makeExtracted(
3638
videoId: string,
3739
delivered: number,
38-
options: { fps?: number; durationSeconds?: number } = {},
40+
options: { fps?: number; durationSeconds?: number; isVFR?: boolean } = {},
3941
): ExtractedFrames {
40-
const { fps = 30, durationSeconds = Number.POSITIVE_INFINITY } = options;
42+
const { fps = 30, durationSeconds = Number.POSITIVE_INFINITY, isVFR = false } = options;
4143
const framePaths = new Map<number, string>();
4244
for (let i = 0; i < delivered; i += 1) framePaths.set(i, `/tmp/${videoId}/${i}.jpg`);
4345
const metadata: VideoMetadata = {
@@ -48,7 +50,7 @@ function makeExtracted(
4850
fps,
4951
videoCodec: "h264",
5052
hasAudio: false,
51-
isVFR: false,
53+
isVFR,
5254
hasAlpha: false,
5355
colorSpace: null,
5456
};
@@ -72,9 +74,23 @@ describe("expectedFramesForClip", () => {
7274
expect(expectedFramesForClip(2, 1, 30)).toBe(0); // negative window collapses to 0
7375
});
7476

75-
it("ceils fractional-fps windows so a 29.97fps 1s clip demands 30 frames", () => {
77+
it("defaults to fail-closed ceil rounding", () => {
7678
expect(expectedFramesForClip(0, 1, 29.97)).toBe(30);
7779
expect(expectedFramesForClip(0, 5, 30)).toBe(150);
80+
expect(expectedFramesForClip(0, 0.616666, 30)).toBe(19);
81+
expect(expectedFramesForClip(0, 0.316666, 30)).toBe(10);
82+
});
83+
84+
it("matches the CFR fps filter's nearest-boundary rounding when requested", () => {
85+
expect(expectedFramesForClip(0, 0.616666, 30, "nearest")).toBe(18);
86+
expect(expectedFramesForClip(0, 0.316666, 30, "nearest")).toBe(9);
87+
expect(expectedFramesForClip(0, 0.633333, 30, "nearest")).toBe(19);
88+
});
89+
90+
it("requires one frame for every positive sub-frame clip", () => {
91+
expect(expectedFramesForClip(0, 0.001, 30)).toBe(1);
92+
expect(expectedFramesForClip(0, 0.001, 30, "nearest")).toBe(1);
93+
expect(expectedFramesForClip(1, 1, 30)).toBe(0);
7894
});
7995
});
8096

@@ -123,6 +139,43 @@ describe("computeVideoFrameCoverage", () => {
123139
});
124140
});
125141

142+
it("reports full coverage for a short CFR clip matching FFmpeg boundary rounding", () => {
143+
const videos = [makeVideo({ id: "short", start: 0, end: 0.616666 })];
144+
const reports = computeVideoFrameCoverage(videos, [makeExtracted("short", 18)], 30);
145+
expect(reports[0]).toMatchObject({
146+
expectedFrames: 18,
147+
capturedFrames: 18,
148+
ratio: 1,
149+
});
150+
expect(() => assertVideoFrameCoverage(reports, 0.95)).not.toThrow();
151+
});
152+
153+
it("keeps ceil coverage for the VFR extraction branch", () => {
154+
const videos = [makeVideo({ id: "short-vfr", start: 0, end: 0.616666 })];
155+
const reports = computeVideoFrameCoverage(
156+
videos,
157+
[makeExtracted("short-vfr", 18, { isVFR: true })],
158+
30,
159+
);
160+
expect(reports[0]).toMatchObject({
161+
expectedFrames: 19,
162+
capturedFrames: 18,
163+
ratio: 18 / 19,
164+
});
165+
expect(() => assertVideoFrameCoverage(reports, 0.95)).toThrow(VideoFrameCoverageError);
166+
});
167+
168+
it("still fails closed when a positive sub-frame clip captured zero frames", () => {
169+
const videos = [makeVideo({ id: "blank-sub-frame", start: 0, end: 0.001 })];
170+
const reports = computeVideoFrameCoverage(videos, [makeExtracted("blank-sub-frame", 0)], 30);
171+
expect(reports[0]).toMatchObject({
172+
expectedFrames: 1,
173+
capturedFrames: 0,
174+
ratio: 0,
175+
});
176+
expect(() => assertVideoFrameCoverage(reports, 0.95)).toThrow(VideoFrameCoverageError);
177+
});
178+
126179
it("reports 0 capturedFrames when a video was never extracted (injection failure)", () => {
127180
// Field signal ts=1784139267: later-injected video clips silently drop
128181
// out of the extractor under injection-count saturation.

‎packages/producer/src/services/render/videoFrameCoverage.ts‎

Lines changed: 40 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ export interface VideoFrameCoverageErrorDetails {
7171
}
7272

7373
export class VideoFrameCoverageError extends Error {
74+
// Read structurally by isVideoFrameCoverageError and cross-module callers.
75+
// fallow-ignore-next-line unused-class-member
7476
readonly hyperframesVideoFrameCoverageError = true as const;
7577
readonly threshold: number;
7678
readonly worst: VideoFrameCoverageReport;
@@ -117,16 +119,47 @@ export function resolveVideoCoverageThreshold(
117119
}
118120

119121
/**
120-
* Ceil the clip's authored `[start,end)` window at `fps` — the number of
121-
* captured render frames whose center-time falls inside the window. Kept
122-
* separate so a caller (or a test) can override it if a composition uses
123-
* a non-integer fps whose sampling makes the naive count off by one.
122+
* Count frames in a clip's authored `[start,end)` window. CFR extraction uses
123+
* FFmpeg's `-vf fps=<fps>` and rounds to the nearest output-frame boundary;
124+
* VFR extraction uses `-fps_mode cfr -r <fps>` and rounds up. Missing entries
125+
* retain the fail-closed `ceil` default. Positive sub-frame clips emit one.
124126
*/
125-
export function expectedFramesForClip(start: number, end: number, fps: number): number {
127+
export function expectedFramesForClip(
128+
start: number,
129+
end: number,
130+
fps: number,
131+
rounding: "ceil" | "nearest" = "ceil",
132+
): number {
126133
if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(fps)) return 0;
127134
if (fps <= 0) return 0;
128135
const duration = Math.max(0, end - start);
129-
return Math.ceil(duration * fps);
136+
if (duration === 0) return 0;
137+
const frameCount =
138+
rounding === "nearest" ? Math.round(duration * fps) : Math.ceil(duration * fps);
139+
return Math.max(1, frameCount);
140+
}
141+
142+
function expectedFramesForVideo(
143+
video: VideoElement,
144+
entry: ExtractedFrames | undefined,
145+
fps: number,
146+
): number {
147+
const rounding = entry && !entry.metadata.isVFR ? "nearest" : "ceil";
148+
const slotFrames = expectedFramesForClip(video.start, video.end, fps, rounding);
149+
if (!entry) return slotFrames;
150+
151+
// A short source in a longer slot has a legitimate delivery ceiling of
152+
// the source portion, not the full slot: a non-looping clip holds its
153+
// final decoded frame across the tail (#2516/#2606), and a looping clip
154+
// reuses its full source frame set per repeat (#2665). In both cases the
155+
// full source *has* been delivered — the same 90 unique source frames
156+
// cover the 300-frame slot — so coverage must measure source-source, not
157+
// slot-source.
158+
const sourceDuration = entry.metadata.durationSeconds - video.mediaStart;
159+
if (!Number.isFinite(sourceDuration) || sourceDuration <= 0) return slotFrames;
160+
161+
const sourceFrames = expectedFramesForClip(0, sourceDuration, fps, rounding);
162+
return Math.min(slotFrames, sourceFrames);
130163
}
131164

132165
export function computeVideoFrameCoverage(
@@ -140,20 +173,7 @@ export function computeVideoFrameCoverage(
140173
const reports: VideoFrameCoverageReport[] = [];
141174
for (const video of videos) {
142175
const entry = byId.get(video.id);
143-
const slotFrames = expectedFramesForClip(video.start, video.end, fps);
144-
// A short source in a longer slot has a legitimate delivery ceiling of
145-
// the source portion, not the full slot: a non-looping clip holds its
146-
// final decoded frame across the tail (#2516/#2606), and a looping clip
147-
// reuses its full source frame set per repeat (#2665). In both cases the
148-
// full source *has* been delivered — the same 90 unique source frames
149-
// cover the 300-frame slot — so coverage must measure source-source, not
150-
// slot-source. A missing extraction (no `entry`) still requires the full
151-
// slot; there's no delivered set to credit.
152-
const sourceDuration = entry ? entry.metadata.durationSeconds - video.mediaStart : NaN;
153-
const hasUsableSourceDuration = Number.isFinite(sourceDuration) && sourceDuration > 0;
154-
const sourceFrames =
155-
entry && hasUsableSourceDuration ? expectedFramesForClip(0, sourceDuration, fps) : slotFrames;
156-
const expectedFrames = entry ? Math.min(slotFrames, sourceFrames) : slotFrames;
176+
const expectedFrames = expectedFramesForVideo(video, entry, fps);
157177
// framePaths is a Map — `size` is the number of distinct captured frames
158178
// delivered to the runtime injector, which is the load-bearing count
159179
// (some extractors report a total that includes cache-hit-skipped frames

0 commit comments

Comments
 (0)