Skip to content

Commit 01744f2

Browse files
fix(media): unify nested start coordinate mapping (#3732)
1 parent e5a6023 commit 01744f2

11 files changed

Lines changed: 187 additions & 17 deletions

File tree

‎docs/concepts/compositions.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,12 @@ Use a separate file when you want to reuse it.
108108
It defaults to `0`. Trimming or splitting from the left pushes this offset
109109
forward by the time elapsed multiplied by `data-playback-rate`, so the
110110
nested animation keeps going instead of jumping back to its beginning.
111+
112+
Timing inside the child file is local to that composition. If this host
113+
starts at `10` and a child video starts at `2`, the video starts at `12` on
114+
the root timeline. Legacy projects that authored a media start in root time
115+
can preserve it explicitly with `data-hf-media-start-basis="global"`; new
116+
compositions should use local timing.
111117
</Tab>
112118
<Tab title="Inline">
113119
Write the nested composition straight into the parent. Simpler for

‎packages/core/package-subpaths.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,12 @@
5050
"types": "./dist/compositionContract.d.ts",
5151
"environments": ["browser", "bun", "node"]
5252
},
53+
"./media-timing": {
54+
"source": "./src/mediaTiming.ts",
55+
"runtime": "./dist/mediaTiming.js",
56+
"types": "./dist/mediaTiming.d.ts",
57+
"environments": ["browser", "bun", "node"]
58+
},
5359
"./editing": {
5460
"source": "./src/editing/affordances.ts",
5561
"runtime": "./dist/editing/affordances.js",

‎packages/core/package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,12 @@
6464
"import": "./src/compositionContract.ts",
6565
"types": "./src/compositionContract.ts"
6666
},
67+
"./media-timing": {
68+
"bun": "./src/mediaTiming.ts",
69+
"node": "./dist/mediaTiming.js",
70+
"import": "./src/mediaTiming.ts",
71+
"types": "./src/mediaTiming.ts"
72+
},
6773
"./editing": {
6874
"bun": "./src/editing/affordances.ts",
6975
"node": "./dist/editing/affordances.js",
@@ -424,6 +430,10 @@
424430
"import": "./dist/compositionContract.js",
425431
"types": "./dist/compositionContract.d.ts"
426432
},
433+
"./media-timing": {
434+
"import": "./dist/mediaTiming.js",
435+
"types": "./dist/mediaTiming.d.ts"
436+
},
427437
"./editing": {
428438
"import": "./dist/editing/affordances.js",
429439
"types": "./dist/editing/affordances.d.ts"

‎packages/core/src/mediaTiming.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
export const MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
2+
3+
export type MediaStartBasis = "local" | "global";
4+
5+
export function readMediaStartBasis(value: string | null | undefined): MediaStartBasis {
6+
return value?.trim().toLowerCase() === "global" ? "global" : "local";
7+
}
8+
9+
/** Resolve authored media time onto the root timeline. Nested media is local
10+
* by default; only an explicit compatibility marker preserves a legacy
11+
* root-global value. */
12+
export function resolveAbsoluteMediaStartSeconds(input: {
13+
authoredStart: number;
14+
hostStart: number;
15+
basis?: string | null;
16+
}): number {
17+
return readMediaStartBasis(input.basis) === "global"
18+
? input.authoredStart
19+
: input.hostStart + input.authoredStart;
20+
}

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

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1228,6 +1228,40 @@ describe("initSandboxRuntimeModular", () => {
12281228
expect(video.style.visibility).toBe("visible");
12291229
});
12301230

1231+
it("keeps an overlapping numeric media start local to its delayed host", () => {
1232+
const root = document.createElement("div");
1233+
root.setAttribute("data-composition-id", "main");
1234+
root.setAttribute("data-root", "true");
1235+
root.setAttribute("data-duration", "10");
1236+
document.body.appendChild(root);
1237+
1238+
const host = document.createElement("div");
1239+
host.setAttribute("data-composition-id", "nested");
1240+
host.setAttribute("data-composition-file", "nested.html");
1241+
host.setAttribute("data-start", "2");
1242+
host.setAttribute("data-duration", "6");
1243+
root.appendChild(host);
1244+
1245+
const video = document.createElement("video");
1246+
video.setAttribute("data-start", "2");
1247+
video.setAttribute("data-duration", "2");
1248+
video.load = () => {};
1249+
host.appendChild(video);
1250+
1251+
window.__timelines = {
1252+
main: createMockTimeline(10),
1253+
nested: createMockTimeline(6),
1254+
};
1255+
1256+
initSandboxRuntimeModular();
1257+
1258+
expect(window.__hfResolveMediaStartSeconds?.(video)).toBe(4);
1259+
window.__player?.renderSeek(2.5);
1260+
expect(video.style.visibility).toBe("hidden");
1261+
window.__player?.renderSeek(4.5);
1262+
expect(video.style.visibility).toBe("visible");
1263+
});
1264+
12311265
it("keeps a long video starting at zero local to its delayed composition host", () => {
12321266
const root = document.createElement("div");
12331267
root.setAttribute("data-composition-id", "main");
@@ -2015,6 +2049,7 @@ describe("initSandboxRuntimeModular", () => {
20152049
// pip-wired video: data-start is authored in global time (same value as host)
20162050
const pipVideo = document.createElement("video");
20172051
pipVideo.setAttribute("data-start", "45.40");
2052+
pipVideo.setAttribute("data-hf-media-start-basis", "global");
20182053
pipVideo.setAttribute("data-duration", "7.06");
20192054
Object.defineProperty(pipVideo, "paused", { value: true, configurable: true });
20202055
Object.defineProperty(pipVideo, "readyState", { value: 0, configurable: true });

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

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ import { shouldAttemptPeriodicTimelineBind } from "./timelineRebindPolicy";
6767
import { installStudioCustomEase } from "./customEase";
6868
import { parseNumeric } from "./startExpression";
6969
import { parseStrictFiniteTimingNumber } from "./playbackRate";
70+
import {
71+
MEDIA_START_BASIS_ATTR,
72+
resolveAbsoluteMediaStartSeconds as resolveAuthoredMediaStartSeconds,
73+
} from "../mediaTiming";
7074
import {
7175
clearRuntimeData,
7276
setRuntimeData,
@@ -691,18 +695,11 @@ export function initSandboxRuntimeModular(): void {
691695
return resolveStartForElement(element, inheritedStart);
692696
}
693697

694-
// Both timing conventions exist in shipped projects:
695-
// - composition-local media, e.g. host@20 + video@0 => root@20
696-
// - legacy root-global PIP media, e.g. [email protected] + [email protected] => [email protected]
697-
// Preserve the global value when its authored start already falls inside
698-
// the host's absolute window. A long local clip can overlap that window
699-
// even when its start is local ([email protected] + video@0/duration=80), so the
700-
// duration cannot disambiguate the timing convention.
701-
const hostDuration = context.inheritedDuration;
702-
const hostEnd = hostDuration != null && hostDuration > 0 ? inheritedStart + hostDuration : null;
703-
const startsInsideHostWindow =
704-
authoredStart >= inheritedStart && (hostEnd == null || authoredStart < hostEnd);
705-
return startsInsideHostWindow ? authoredStart : inheritedStart + authoredStart;
698+
return resolveAuthoredMediaStartSeconds({
699+
authoredStart,
700+
hostStart: inheritedStart,
701+
basis: element.getAttribute(MEDIA_START_BASIS_ATTR),
702+
});
706703
};
707704

708705
window.__hfResolveMediaStartSeconds = resolveAbsoluteMediaStartSeconds;

‎packages/lint/src/rules/media.test.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,39 @@ describe("media rules", () => {
466466
expect(finding).toBeUndefined();
467467
});
468468

469+
it("warns that an unmarked nonzero nested media start is local", async () => {
470+
const html = `<template>
471+
<div data-composition-id="scene" data-width="1920" data-height="1080">
472+
<video id="clip" src="clip.mp4" data-start="2" data-duration="2" muted></video>
473+
</div>
474+
</template>`;
475+
const result = await lintHyperframeHtml(html, { isSubComposition: true });
476+
const finding = result.findings.find(
477+
(item) => item.code === "nested_media_start_basis_ambiguous",
478+
);
479+
480+
expect(finding?.severity).toBe("warning");
481+
expect(finding?.message).toContain("local to its composition");
482+
expect(finding?.fixHint).toContain('data-hf-media-start-basis="global"');
483+
});
484+
485+
it.each([
486+
['data-start="0"', "zero local start"],
487+
['data-start="2" data-hf-media-start-basis="local"', "explicit local start"],
488+
['data-start="2" data-hf-media-start-basis="global"', "explicit legacy-global start"],
489+
])("does not warn for %s (%s)", async (attrs) => {
490+
const html = `<template>
491+
<div data-composition-id="scene" data-width="1920" data-height="1080">
492+
<audio id="clip" src="clip.wav" ${attrs} data-duration="2"></audio>
493+
</div>
494+
</template>`;
495+
const result = await lintHyperframeHtml(html, { isSubComposition: true });
496+
497+
expect(result.findings.some((item) => item.code === "nested_media_start_basis_ambiguous")).toBe(
498+
false,
499+
);
500+
});
501+
469502
it("reports error for media with crossorigin (breaks preview when host omits CORS)", async () => {
470503
const html = `
471504
<html><body>

‎packages/lint/src/rules/media.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,29 @@ function findMediaSrcKindMismatchFindings(ctx: LintContext): HyperframeLintFindi
138138
return findings;
139139
}
140140

141+
function findNestedMediaStartBasisFindings(ctx: LintContext): HyperframeLintFinding[] {
142+
if (!ctx.options.isSubComposition) return [];
143+
const findings: HyperframeLintFinding[] = [];
144+
for (const tag of ctx.tags) {
145+
if (tag.name !== "video" && tag.name !== "audio") continue;
146+
const rawStart = readAttr(tag.raw, "data-start");
147+
const start = rawStart == null || rawStart.trim() === "" ? NaN : Number(rawStart);
148+
if (!Number.isFinite(start) || start <= 0) continue;
149+
const basis = readAttr(tag.raw, "data-hf-media-start-basis");
150+
if (basis === "local" || basis === "global") continue;
151+
const elementId = readAttr(tag.raw, "id") || undefined;
152+
findings.push({
153+
code: "nested_media_start_basis_ambiguous",
154+
severity: "warning",
155+
message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start="${rawStart}" inside a sub-composition. Nested media timing is local to its composition by default; a nonzero value can be confused with a legacy root-global timestamp.`,
156+
elementId,
157+
fixHint: `Keep data-start="${rawStart}" if it is composition-local. If this is a legacy root-global timestamp, add data-hf-media-start-basis="global"; otherwise convert it to local time by subtracting the host start.`,
158+
snippet: truncateSnippet(tag.raw),
159+
});
160+
}
161+
return findings;
162+
}
163+
141164
/** Parent `src`, else a descendant `<source src>` (matches engine resolveMediaElementSrc). */
142165
function mediaHasResolvableSrc(tag: OpenTag, tags: readonly OpenTag[]): boolean {
143166
if (readAttr(tag.raw, "src")) return true;
@@ -376,6 +399,7 @@ function findRuntimeMediaSrcMutationFindings(ctx: LintContext): HyperframeLintFi
376399
}
377400

378401
export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
402+
findNestedMediaStartBasisFindings,
379403
// duplicate_media_id + duplicate_media_discovery_risk
380404
({ tags }) => {
381405
const findings: HyperframeLintFinding[] = [];

‎packages/producer/src/services/renderMediaCollector.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,18 @@ describe("collectRenderMedia host windows", () => {
1616
expect(videos.find((v) => v.id === "red")).toMatchObject({ start: 0, end: 2 });
1717
expect(videos.find((v) => v.id === "blue")).toMatchObject({ start: 2, end: 4 });
1818
});
19+
20+
it("preserves an explicitly marked legacy-global media window", () => {
21+
const html =
22+
`<div data-composition-file="scene.html" data-composition-id="scene" data-start="2" data-duration="6">` +
23+
`<video ${MEDIA_RENDER_ID_ATTR}="local" id="local" src="local.mp4" data-start="2" data-duration="2" data-has-audio="true"></video>` +
24+
`<video ${MEDIA_RENDER_ID_ATTR}="global" id="global" src="global.mp4" data-start="2" data-duration="2" data-hf-media-start-basis="global" data-has-audio="true"></video>` +
25+
`</div>`;
26+
27+
const { videos, audios } = collectRenderMedia(html);
28+
expect(videos.find((video) => video.id === "local")).toMatchObject({ start: 4, end: 6 });
29+
expect(videos.find((video) => video.id === "global")).toMatchObject({ start: 2, end: 4 });
30+
expect(audios.find((audio) => audio.id === "local-audio")).toMatchObject({ start: 4, end: 0 });
31+
expect(audios.find((audio) => audio.id === "global-audio")).toMatchObject({ start: 2, end: 0 });
32+
});
1933
});

‎packages/producer/src/services/renderMediaCollector.ts‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@
1616

1717
import { parseHTML } from "linkedom";
1818
import { MEDIA_RENDER_ID_ATTR } from "@hyperframes/core";
19+
import {
20+
MEDIA_START_BASIS_ATTR,
21+
readMediaStartBasis,
22+
resolveAbsoluteMediaStartSeconds,
23+
type MediaStartBasis,
24+
} from "@hyperframes/core/media-timing";
1925
import {
2026
parseVideoElements,
2127
parseImageElements,
@@ -40,9 +46,11 @@ interface HostWindow {
4046
offset: number;
4147
/** Absolute time past which a descendant is outside its host, or Infinity. */
4248
limit: number;
49+
/** Whether authored media time is composition-local or legacy root-global. */
50+
basis: MediaStartBasis;
4351
}
4452

45-
const ROOT_WINDOW: HostWindow = { offset: 0, limit: Infinity };
53+
const ROOT_WINDOW: HostWindow = { offset: 0, limit: Infinity, basis: "local" };
4654

4755
function parseNumeric(value: string | null): number | null {
4856
if (value == null || value === "") return null;
@@ -80,7 +88,16 @@ function resolveHostWindow(
8088
if (hostEnd != null) limit = Math.min(limit, offset + hostEnd);
8189
offset += hostStart;
8290
}
83-
return { offset, limit };
91+
const tag = element.tagName.toLowerCase();
92+
const basis =
93+
tag === "video" || tag === "audio"
94+
? readMediaStartBasis(element.getAttribute(MEDIA_START_BASIS_ATTR))
95+
: "local";
96+
return {
97+
offset,
98+
limit,
99+
basis,
100+
};
84101
}
85102

86103
/**
@@ -114,9 +131,17 @@ function toAbsoluteWindow(
114131
end: number,
115132
window: HostWindow,
116133
): { start: number; end: number } | null {
117-
const absoluteStart = start + window.offset;
134+
const absoluteStart = resolveAbsoluteMediaStartSeconds({
135+
authoredStart: start,
136+
hostStart: window.offset,
137+
basis: window.basis,
138+
});
118139
if (absoluteStart >= window.limit) return null;
119-
const absoluteEnd = end + window.offset;
140+
const absoluteEnd = resolveAbsoluteMediaStartSeconds({
141+
authoredStart: end,
142+
hostStart: window.offset,
143+
basis: window.basis,
144+
});
120145
return { start: absoluteStart, end: Math.min(absoluteEnd, window.limit) };
121146
}
122147

0 commit comments

Comments
 (0)