Skip to content

Commit 2e8f871

Browse files
committed
fix(video): hold final frame through composition
1 parent 71d7be7 commit 2e8f871

15 files changed

Lines changed: 352 additions & 90 deletions

File tree

‎packages/cli/src/commands/validate.test.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import {
1111
runAndParseJsonEnvelope,
1212
} from "./deprecationTestHarness.js";
1313
import {
14+
auditClipDurations,
1415
extractCompositionErrorsFromLint,
1516
navigationTimeoutHint,
1617
raceMediaReady,
@@ -49,6 +50,58 @@ vi.mock("../utils/producer.js", () => ({
4950
vi.mock("../utils/project.js", () => resolveProjectMock());
5051
vi.mock("../utils/lintProject.js", () => lintProjectFailureMock());
5152

53+
describe("auditClipDurations", () => {
54+
it("audits audio only because explicit video slots hold their final frame", async () => {
55+
let selector = "";
56+
const originalDocument = globalThis.document;
57+
const audio = {
58+
duration: 1,
59+
id: "voice",
60+
loop: false,
61+
tagName: "AUDIO",
62+
getAttribute: (name: string) =>
63+
name === "data-duration" ? "5" : name === "data-media-start" ? "0" : null,
64+
};
65+
const page = {
66+
evaluate: async (fn: (waitMs: number) => unknown, waitMs: number) => {
67+
Object.defineProperty(globalThis, "document", {
68+
configurable: true,
69+
value: {
70+
querySelectorAll: (query: string) => {
71+
selector = query;
72+
return [audio];
73+
},
74+
},
75+
});
76+
return fn(waitMs);
77+
},
78+
};
79+
80+
try {
81+
const warnings = await auditClipDurations(
82+
page as never,
83+
({ slotSeconds, mediaSeconds }) => ({
84+
shortfallSeconds: slotSeconds - mediaSeconds,
85+
toleranceSeconds: 0.05,
86+
}),
87+
10,
88+
);
89+
expect(selector).toBe("audio[data-duration]");
90+
expect(warnings).toHaveLength(1);
91+
expect(warnings[0]?.text).toContain('Audio "voice"');
92+
} finally {
93+
if (originalDocument === undefined) {
94+
Reflect.deleteProperty(globalThis, "document");
95+
} else {
96+
Object.defineProperty(globalThis, "document", {
97+
configurable: true,
98+
value: originalDocument,
99+
});
100+
}
101+
}
102+
});
103+
});
104+
52105
// Regression for the validate audio-duration-probe timeout: a slow-loading
53106
// media element's duration was snapshotted once, at a fixed point in time,
54107
// and any element still mid-load was permanently misreported as unreadable.

‎packages/cli/src/commands/validate.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -127,8 +127,9 @@ export function raceMediaReady(
127127
}
128128

129129
/**
130-
* Flag `<video>`/`<audio>` clips whose source is meaningfully shorter than their
131-
* `data-duration` slot (the slot gets silently shortened in renders). Runs in
130+
* Flag `<audio>` clips whose source is meaningfully shorter than their
131+
* `data-duration` slot (the slot gets silently shortened in renders). Videos
132+
* intentionally hold their final frame through an explicit longer slot. Runs in
132133
* the live page to read each element's intrinsic `.duration`, which static lint
133134
* can't see.
134135
*/
@@ -140,7 +141,7 @@ export async function auditClipDurations(
140141
// fallow-ignore-next-line complexity
141142
const clips = await page.evaluate(async (maxWaitMs: number) => {
142143
const nodes = Array.from(
143-
document.querySelectorAll("video[data-duration], audio[data-duration]"),
144+
document.querySelectorAll("audio[data-duration]"),
144145
) as HTMLMediaElement[];
145146

146147
// The caller's page-settle sleep is a flat, unconditional wait shared with

‎packages/core/src/compiler/htmlCompiler.test.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,39 @@ describe("compileHtml", () => {
1212
expect(compiled).toContain('data-end="4"');
1313
});
1414

15-
it("still clamps non-looping media durations to source duration", async () => {
15+
it("preserves an explicit non-looping video slot past source end", async () => {
1616
const html = '<video id="hero" src="hero.webm" data-start="0" data-duration="4" data-end="4">';
1717

1818
const compiled = await compileHtml(html, "/project", async () => 3.125);
1919

20+
expect(compiled).toContain('data-duration="4"');
21+
expect(compiled).toContain('data-end="4"');
22+
});
23+
24+
it("uses natural duration for a video without an explicit slot inside a composition", async () => {
25+
const html =
26+
'<div data-composition-id="root" data-start="0" data-duration="5">' +
27+
'<video id="hero" src="hero.webm" data-start="0">' +
28+
"</div>";
29+
30+
const compiled = await compileHtml(html, "/project", async () => 1);
31+
32+
expect(compiled).toContain('data-duration="1"');
33+
expect(compiled).toContain('data-end="1"');
34+
});
35+
36+
it("uses natural duration for a standalone video without a composition window", async () => {
37+
const html = '<video id="hero" src="hero.webm" data-start="0">';
38+
const compiled = await compileHtml(html, "/project", async () => 1);
39+
expect(compiled).toContain('data-duration="1"');
40+
expect(compiled).toContain('data-end="1"');
41+
});
42+
43+
it("still clamps non-looping audio durations to source duration", async () => {
44+
const html = '<audio id="voice" src="voice.wav" data-start="0" data-duration="4" data-end="4">';
45+
46+
const compiled = await compileHtml(html, "/project", async () => 3.125);
47+
2048
expect(compiled).toContain('data-duration="3.125"');
2149
expect(compiled).toContain('data-end="3.125"');
2250
});

‎packages/core/src/compiler/htmlCompiler.ts‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import {
44
injectDurations,
55
extractResolvedMedia,
66
clampDurations,
7-
shouldClampMediaDuration,
7+
shouldClampResolvedMediaDuration,
88
type ResolvedDuration,
99
} from "./timingCompiler";
1010

@@ -23,7 +23,8 @@ function resolveMediaSrc(src: string, projectDir: string): string {
2323
*
2424
* 1. Static pass: compileTimingAttrs() adds data-end where data-duration exists
2525
* 2. For unresolved video/audio (no data-duration): probe via probeMediaDuration, inject durations
26-
* 3. For pre-resolved video/audio: validate data-duration against actual source, clamp if needed
26+
* 3. For pre-resolved audio: clamp data-duration to playable source when needed.
27+
* Explicit video slots are preserved and hold their final frame.
2728
*
2829
* @param rawHtml - The raw HTML string
2930
* @param projectDir - The project directory for resolving relative paths
@@ -54,18 +55,17 @@ export async function compileHtml(
5455
if (fileDuration <= 0) continue;
5556

5657
const effectiveDuration = fileDuration - el.mediaStart;
57-
resolutions.push({
58-
id: el.id,
59-
duration: effectiveDuration > 0 ? effectiveDuration : fileDuration,
60-
});
58+
const sourceDuration = effectiveDuration > 0 ? effectiveDuration : fileDuration;
59+
resolutions.push({ id: el.id, duration: sourceDuration });
6160
}
6261

6362
if (resolutions.length > 0) {
6463
html = injectDurations(html, resolutions);
6564
}
6665
}
6766

68-
// Phase 2: Validate pre-resolved media — clamp data-duration to actual source duration
67+
// Phase 2: Bound authored audio to playable source. Explicit video slots may
68+
// outlive their source and render by holding the final frame.
6969
const preResolved = extractResolvedMedia(html);
7070
const clampList: ResolvedDuration[] = [];
7171

@@ -77,7 +77,7 @@ export async function compileHtml(
7777
if (fileDuration <= 0) continue;
7878

7979
const maxDuration = fileDuration - el.mediaStart;
80-
if (maxDuration > 0 && shouldClampMediaDuration(el.duration, maxDuration)) {
80+
if (maxDuration > 0 && shouldClampResolvedMediaDuration(el.tagName, el.duration, maxDuration)) {
8181
clampList.push({ id: el.id, duration: maxDuration });
8282
}
8383
}

‎packages/core/src/compiler/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ export {
1717
extractResolvedMedia,
1818
clampDurations,
1919
shouldClampMediaDuration,
20+
shouldClampResolvedMediaDuration,
2021
type UnresolvedElement,
2122
type ResolvedDuration,
2223
type ResolvedMediaElement,

‎packages/core/src/compiler/timingCompiler.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
injectDurations,
77
extractResolvedMedia,
88
clampDurations,
9+
shouldClampResolvedMediaDuration,
910
} from "./timingCompiler.js";
1011

1112
// Raw 0x00 bytes in the HFMASK delimiters shipped once and broke every render
@@ -264,3 +265,10 @@ describe("clampDurations", () => {
264265
expect(result).toContain('data-end="7"');
265266
});
266267
});
268+
269+
describe("shouldClampResolvedMediaDuration", () => {
270+
it("preserves an explicit video slot but keeps audio source-bounded", () => {
271+
expect(shouldClampResolvedMediaDuration("video", 5, 1)).toBe(false);
272+
expect(shouldClampResolvedMediaDuration("audio", 5, 1)).toBe(true);
273+
});
274+
});

‎packages/core/src/compiler/timingCompiler.ts‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,15 +48,29 @@ export interface CompilationResult {
4848
unresolved: UnresolvedElement[];
4949
}
5050

51-
// ffprobe precision can differ slightly across local and CI media stacks. Also
52-
// the floor for the engine's hold-last-frame tolerance (a slot left unclamped is
53-
// short by at most this), so they must move together.
51+
// ffprobe precision can differ slightly across local and CI media stacks, so
52+
// avoid shortening authored audio for insignificant probe drift.
5453
export const MEDIA_DURATION_CLAMP_EPSILON_SECONDS = 0.05;
5554

5655
export function shouldClampMediaDuration(declaredDuration: number, maxDuration: number): boolean {
5756
return declaredDuration > maxDuration + MEDIA_DURATION_CLAMP_EPSILON_SECONDS;
5857
}
5958

59+
/**
60+
* Whether compilation should shorten an authored media slot to its source.
61+
*
62+
* Non-looping video intentionally keeps an explicit longer slot: browsers and
63+
* the render frame injector hold its final frame until that authored slot ends.
64+
* Audio has no frame to hold, so its slot remains bounded by playable source.
65+
*/
66+
export function shouldClampResolvedMediaDuration(
67+
tagName: ResolvedMediaElement["tagName"],
68+
declaredDuration: number,
69+
maxDuration: number,
70+
): boolean {
71+
return tagName === "audio" && shouldClampMediaDuration(declaredDuration, maxDuration);
72+
}
73+
6074
// ── Helpers ──────────────────────────────────────────────────────────────
6175

6276
function getAttr(tag: string, attr: string): string | null {

‎packages/core/src/index.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ describe("@hyperframes/core public API exports", () => {
124124
expect(typeof core.extractResolvedMedia).toBe("function");
125125
expect(typeof core.clampDurations).toBe("function");
126126
expect(typeof core.shouldClampMediaDuration).toBe("function");
127+
expect(typeof core.shouldClampResolvedMediaDuration).toBe("function");
127128
});
128129
});
129130

‎packages/core/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,7 @@ export {
138138
extractResolvedMedia,
139139
clampDurations,
140140
shouldClampMediaDuration,
141+
shouldClampResolvedMediaDuration,
141142
MEDIA_DURATION_CLAMP_EPSILON_SECONDS,
142143
} from "./compiler/timingCompiler";
143144

‎packages/core/src/runtime/init.ts‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,11 @@ import {
1919
} from "./adapters/video-texture-compat";
2020
import { forceDispatchSeekEvent } from "./adapters/seek-dispatch";
2121
import { createWaapiAdapter } from "./adapters/waapi";
22-
import { refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
22+
import {
23+
refreshRuntimeMediaCache,
24+
resolveRuntimeMediaClipDuration,
25+
syncRuntimeMedia,
26+
} from "./media";
2327
import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
2428
import { createPickerModule } from "./picker";
2529
import { createRuntimePlayer, type RuntimePlayerTransport } from "./player";
@@ -1807,10 +1811,12 @@ export function initSandboxRuntimeModular(): void {
18071811
const ownDuration = Number.parseFloat(element.dataset.duration ?? "");
18081812
const explicitDuration =
18091813
Number.isFinite(ownDuration) && ownDuration > 0 ? ownDuration : null;
1810-
const candidates = [sourceDuration, hostRemaining, explicitDuration].filter(
1811-
(value): value is number => value != null,
1812-
);
1813-
return candidates.length > 0 ? Math.min(...candidates) : null;
1814+
return resolveRuntimeMediaClipDuration({
1815+
isVideo: element.tagName === "VIDEO",
1816+
sourceDuration,
1817+
hostRemaining,
1818+
explicitDuration,
1819+
});
18141820
},
18151821
});
18161822
// Attach probed volume keyframes to clips so syncRuntimeMedia can use the

0 commit comments

Comments
 (0)