Skip to content

Commit 09aadd8

Browse files
feat(core): video, audio and image length come from one shared resolver (#4166)
A new resolver in @hyperframes/parsers decides how long a video, audio or image occupies the timeline. The core runtime start resolver, clip manifest and clip tree now read length through it. An image with data-start and no data-duration gets the dropped-image default of 3 seconds; a bare image stays a static layer. Video and audio take their length from the file until an authored duration trims it. The playback rate bound (0.1 to 10) now lives in parsers, and core re-exports it. A rate lane keeps its own arithmetic in core. The lint rule that asked images for data-duration is removed, and the docs no longer say an image requires it.
1 parent bdecae0 commit 09aadd8

23 files changed

Lines changed: 619 additions & 107 deletions

‎docs/reference/html-schema.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ unbounded animation, and timeline-free compositions need an explicit duration.
9696
| --- | --- | --- |
9797
| `id` | Yes | Stable identifier for timing, editing, and animation |
9898
| `data-start` | Yes | Start in seconds or a relative timing expression |
99-
| `data-duration` | Yes for DOM, image, and nested-composition clips | Visible slot length in seconds |
99+
| `data-duration` | Yes for DOM and nested-composition clips; optional for image (3 s default), video and audio (source length) | Visible slot length in seconds |
100100
| `data-track-index` | No | Studio timeline lane, display only. The render never reads it and it does not prevent overlap |
101101
| `class="clip"` | Recommended for authored timed DOM and image elements | Layout and tooling convention. Visibility is keyed off `data-start`, but the shared `.clip` rule supplies the full-frame box |
102102

‎packages/core/docs/core.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ A clip is any discrete block on the timeline. We represent clips as HTML element
183183

184184
- `id` — Unique identifier (e.g., "el-1")
185185
- `data-start` — Start time in seconds, or a clip `id` reference. See [Relative Timing](#relative-timing).
186-
- `data-duration` — Duration in seconds. Required for `<img>` clips. Optional for `<video>` and `<audio>` (defaults to the source media's full duration). Not used on compositions.
186+
- `data-duration` — Duration in seconds. Optional for `<img>` (defaults to 3 seconds), `<video>` and `<audio>` (default to the source media's length, less any playback offset, over the playback rate; an authored value trims). Not used on compositions.
187187
- `data-track-index` — Timeline track number. Tracks serve two purposes: they determine visual layering (higher tracks render in front) and they group clips into rows on the timeline. Clips on the same track **cannot overlap in time**.
188188

189189
### Media Clips (video, audio)
Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
1-
/** The one clamp for a playback rate: the constant attribute and the rate lane alike. */
2-
export const MIN_PLAYBACK_RATE = 0.1;
3-
export const MAX_PLAYBACK_RATE = 10;
1+
export { MIN_PLAYBACK_RATE, MAX_PLAYBACK_RATE } from "@hyperframes/parsers/media-duration";

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,17 @@ describe("createClipTree", () => {
5959
expect(child!.parentId).toBe("scene");
6060
});
6161

62+
it("keeps a timed image that starts at the end of the root, since it has its own default length", () => {
63+
document.body.innerHTML = `
64+
<div data-composition-id="root" data-duration="10" data-start="0" id="root">
65+
<img id="late" data-start="10" />
66+
</div>`;
67+
const late = { resolveStartForElement: () => 10 };
68+
expect(createClipTree({ ...params, startResolver: late }).roots.map((n) => n.id)).toContain(
69+
"late",
70+
);
71+
});
72+
6273
it.each([10, 11])(
6374
"does not replace a known zero media span with root duration (start=%s)",
6475
(start) => {

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

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,11 @@
1111
*/
1212

1313
import type { RuntimeTimelineLike } from "./types";
14-
import { parseStrictFiniteTimingNumber, resolveNaturalMediaTimelineDuration } from "./playbackRate";
14+
import {
15+
parseStrictFiniteTimingNumber,
16+
resolveNaturalMediaTimelineDuration,
17+
resolveTimedImageDurationSeconds,
18+
} from "./playbackRate";
1519
import { isMediaElement } from "./domRealm";
1620

1721
export interface ClipNode {
@@ -67,8 +71,12 @@ function durationFromTimeline(
6771
}
6872

6973
function durationFromMedia(el: Element): number | null {
70-
if (!isMediaElement(el) || !Number.isFinite(el.duration)) return null;
71-
return resolveNaturalMediaTimelineDuration(el, el.duration);
74+
if (isMediaElement(el)) {
75+
return Number.isFinite(el.duration)
76+
? resolveNaturalMediaTimelineDuration(el, el.duration)
77+
: null;
78+
}
79+
return resolveTimedImageDurationSeconds(el);
7280
}
7381

7482
// Used only to filter out zero-duration (decorative) elements at build time.

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
import { describe, expect, it } from "vitest";
2+
import * as parsersBounds from "@hyperframes/parsers/media-duration";
3+
import { MEDIA_DURATION_FIXTURES } from "@hyperframes/parsers/media-duration-fixtures";
24
import {
5+
resolveMediaElementDurationSeconds,
36
resolveNaturalMediaTimelineDuration,
47
resolveNaturalMediaTimelineDurationFromValues,
8+
resolveTimedImageDurationSeconds,
59
} from "./playbackRate";
10+
import * as coreBounds from "../playbackRateBounds";
611

712
function elementWith(attributes: Record<string, string>): Pick<Element, "getAttribute"> {
813
return {
@@ -51,4 +56,71 @@ describe("rate lane duration", () => {
5156
2,
5257
);
5358
});
59+
60+
it("keeps a rate lane's arithmetic when the shared resolver reports a media length", () => {
61+
const el = {
62+
...elementWith({
63+
"data-automation": JSON.stringify({
64+
version: 1,
65+
lanes: [
66+
{
67+
target: "rate",
68+
points: [
69+
{ t: 0, v: 1 },
70+
{ t: 2, v: 3 },
71+
],
72+
},
73+
],
74+
}),
75+
}),
76+
duration: 10,
77+
};
78+
expect(resolveMediaElementDurationSeconds(el)).toBeCloseTo(2 + (10 - 3.641) / 3, 2);
79+
});
80+
});
81+
82+
describe("resolveMediaElementDurationSeconds over the shared media-duration fixtures", () => {
83+
// The runtime reader only sees video and audio; an image has no source to probe.
84+
for (const fixture of MEDIA_DURATION_FIXTURES.filter((f) => f.tag !== "img")) {
85+
it(fixture.name, () => {
86+
const el = {
87+
...elementWith(fixture.attrs),
88+
duration: fixture.sourceDurationSeconds ?? Number.NaN,
89+
};
90+
expect(resolveMediaElementDurationSeconds(el)).toBe(fixture.expected.seconds);
91+
});
92+
}
93+
});
94+
95+
describe("resolveTimedImageDurationSeconds over the shared media-duration fixtures", () => {
96+
const imgWith = (attrs: Readonly<Record<string, string>>) => {
97+
const img = document.createElement("img");
98+
for (const [name, value] of Object.entries(attrs)) img.setAttribute(name, value);
99+
return img;
100+
};
101+
102+
for (const fixture of MEDIA_DURATION_FIXTURES.filter((f) => f.tag === "img")) {
103+
it(fixture.name, () => {
104+
expect(resolveTimedImageDurationSeconds(imgWith(fixture.attrs))).toBe(
105+
fixture.expected.seconds,
106+
);
107+
});
108+
}
109+
110+
it("leaves a bare image, with no timing attribute, as a static layer", () => {
111+
expect(resolveTimedImageDurationSeconds(imgWith({}))).toBeNull();
112+
});
113+
114+
it("does not time anything that is not an image", () => {
115+
expect(resolveTimedImageDurationSeconds(document.createElement("div"))).toBeNull();
116+
});
117+
});
118+
119+
describe("the playback rate bound", () => {
120+
it("has one owner: core's bounds are the parsers bounds", () => {
121+
expect([coreBounds.MIN_PLAYBACK_RATE, coreBounds.MAX_PLAYBACK_RATE]).toEqual([
122+
parsersBounds.MIN_PLAYBACK_RATE,
123+
parsersBounds.MAX_PLAYBACK_RATE,
124+
]);
125+
});
54126
});

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

Lines changed: 54 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,28 @@
1-
import { MAX_PLAYBACK_RATE, MIN_PLAYBACK_RATE } from "../playbackRateBounds";
1+
import {
2+
clampPlaybackRate,
3+
readAuthoredDurationSeconds,
4+
readDataDurationSeconds,
5+
readMediaOffsetSeconds,
6+
readPlaybackRate,
7+
resolveMediaDuration,
8+
resolveNaturalDurationSeconds,
9+
} from "@hyperframes/parsers/media-duration";
210
import { resolveRateSpec, timeAtSourceTime, type RateSpec } from "../speedRamp";
3-
import { isMediaElement } from "./domRealm";
11+
import { isImageElement, isMediaElement } from "./domRealm";
12+
import { parseNumeric } from "./startExpression";
413

5-
export function normalizePlaybackRate(raw: number): number {
6-
return Number.isFinite(raw) && raw > 0
7-
? Math.max(MIN_PLAYBACK_RATE, Math.min(MAX_PLAYBACK_RATE, raw))
8-
: 1;
9-
}
14+
export const normalizePlaybackRate = clampPlaybackRate;
1015

1116
/** Parse a literal numeric timing attribute without accepting trailing units or garbage. */
1217
export function parseStrictFiniteTimingNumber(raw: string | null | undefined): number | null {
1318
return parseNumeric(raw);
1419
}
1520

1621
export function readElementPlaybackRate(el: Pick<Element, "getAttribute">): number {
17-
const authored = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
18-
const raw =
19-
Number.isFinite(authored) && authored > 0
20-
? authored
21-
: isMediaElement(el)
22-
? el.defaultPlaybackRate
23-
: 1;
24-
return normalizePlaybackRate(raw);
22+
return readPlaybackRate(
23+
(name) => el.getAttribute(name),
24+
isMediaElement(el) ? el.defaultPlaybackRate : 1,
25+
);
2526
}
2627

2728
/** A constant rate clamped to the shared range; a lane is already normalised by its parser. */
@@ -35,15 +36,9 @@ export function readElementRateSpec(el: Pick<Element, "getAttribute">): RateSpec
3536
}
3637

3738
export function readMediaStart(el: Pick<Element, "getAttribute">): number {
38-
const parse = (raw: string | null): number | null => {
39-
const value = parseStrictFiniteTimingNumber(raw);
40-
if (value == null) return null;
41-
return Number.isFinite(value) && value >= 0 ? value : null;
42-
};
43-
return (
44-
parse(el.getAttribute("data-playback-start")) ?? parse(el.getAttribute("data-media-start")) ?? 0
45-
);
39+
return readMediaOffsetSeconds((name) => el.getAttribute(name));
4640
}
41+
4742
export function resolveNaturalMediaTimelineDuration(
4843
el: Pick<Element, "getAttribute">,
4944
sourceDuration: number,
@@ -56,32 +51,52 @@ export function resolveNaturalMediaTimelineDuration(
5651
}
5752

5853
/**
59-
* How long a media element occupies the timeline: an explicit `data-duration`
60-
* trim if authored, otherwise the natural source length adjusted for playback
61-
* start and rate. `null` when the source has not reported a duration yet.
62-
*
63-
* Single owner for the media-window scan run by BOTH the runtime's duration
64-
* floor and the clip manifest.
54+
* How long a media element occupies the timeline: an authored `data-duration` trim, otherwise
55+
* the source's natural length adjusted for playback start and rate (lane-aware). `null` while
56+
* the source has not reported a duration yet. The authored/pending decision is the shared
57+
* parsers resolver's; only a `rate` lane's arithmetic stays here, because lanes live in core.
6558
*/
6659
export function resolveMediaElementDurationSeconds(
6760
el: Pick<Element, "getAttribute"> & { duration: number },
6861
): number | null {
69-
const declaredDuration = parseStrictFiniteTimingNumber(el.getAttribute("data-duration"));
70-
if (declaredDuration != null && declaredDuration > 0) return declaredDuration;
71-
if (Number.isFinite(el.duration)) return resolveNaturalMediaTimelineDuration(el, el.duration);
72-
return null;
62+
const resolved = resolveMediaDuration({
63+
tag: "video", // video and audio resolve identically
64+
authoredDurationSeconds: readDataDurationSeconds((name) => el.getAttribute(name)),
65+
sourceDurationSeconds: Number.isFinite(el.duration) ? el.duration : null,
66+
mediaStartSeconds: readMediaStart(el),
67+
playbackRate: readElementPlaybackRate(el),
68+
});
69+
return resolved.source === "media"
70+
? resolveNaturalMediaTimelineDuration(el, el.duration)
71+
: resolved.seconds;
7372
}
7473

74+
/** A timed `<img>` (`data-start` or `data-track-index`) gets the dropped-image default unless
75+
* trimmed by `data-duration` or `data-end`; a bare `<img>` is a static layer. `null` otherwise. */
76+
export function resolveTimedImageDurationSeconds(el: Element, startSeconds = 0): number | null {
77+
if (!isImageElement(el)) return null;
78+
if (!el.hasAttribute("data-start") && !el.hasAttribute("data-track-index")) return null;
79+
return resolveMediaDuration({
80+
tag: "img",
81+
authoredDurationSeconds: readAuthoredDurationSeconds(
82+
(name) => el.getAttribute(name),
83+
startSeconds,
84+
),
85+
sourceDurationSeconds: null,
86+
mediaStartSeconds: 0,
87+
playbackRate: 1,
88+
}).seconds;
89+
}
90+
91+
/** A constant rate goes through the shared arithmetic; a `rate` lane integrates over its points. */
7592
export function resolveNaturalMediaTimelineDurationFromValues(
7693
sourceDuration: number,
7794
mediaStart: number,
7895
playbackRate: RateSpec,
7996
): number | null {
97+
if (typeof playbackRate === "number") {
98+
return resolveNaturalDurationSeconds(sourceDuration, mediaStart, playbackRate);
99+
}
80100
if (!Number.isFinite(sourceDuration)) return null;
81-
const remaining = Math.max(0, sourceDuration - mediaStart);
82-
return timeAtSourceTime(
83-
typeof playbackRate === "number" ? normalizePlaybackRate(playbackRate) : playbackRate,
84-
remaining,
85-
);
101+
return timeAtSourceTime(playbackRate, Math.max(0, sourceDuration - mediaStart));
86102
}
87-
import { parseNumeric } from "./startExpression";

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { describe, it, expect, afterEach, beforeAll } from "vitest";
2+
import { DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS } from "@hyperframes/parsers/media-duration";
23
import { createRuntimeStartTimeResolver } from "./startResolver";
34

45
// jsdom doesn't provide CSS.escape — polyfill it
@@ -316,6 +317,26 @@ describe("createRuntimeStartTimeResolver", () => {
316317
expect(resolver.resolveDurationForElement(el)).toBe(6);
317318
});
318319

320+
it.each([["data-start"], ["data-track-index"]])(
321+
"gives an img with only %s the dropped-image default",
322+
(attr) => {
323+
const el = document.createElement("img");
324+
el.setAttribute(attr, "1");
325+
document.body.appendChild(el);
326+
const resolver = createRuntimeStartTimeResolver({});
327+
expect(resolver.resolveDurationForElement(el)).toBe(
328+
DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS,
329+
);
330+
},
331+
);
332+
333+
it("leaves a bare img with no length", () => {
334+
const el = document.createElement("img");
335+
document.body.appendChild(el);
336+
const resolver = createRuntimeStartTimeResolver({});
337+
expect(resolver.resolveDurationForElement(el)).toBeNull();
338+
});
339+
319340
it("returns null when no duration info available", () => {
320341
const el = document.createElement("div");
321342
document.body.appendChild(el);

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

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,8 @@ import { resolveAuthoredTimingWindow } from "./authoredTiming";
66
// would be an import cycle.
77
import {
88
parseStrictFiniteTimingNumber,
9-
readElementRateSpec,
10-
readMediaStart,
11-
resolveNaturalMediaTimelineDurationFromValues,
9+
resolveNaturalMediaTimelineDuration,
10+
resolveTimedImageDurationSeconds,
1211
} from "./playbackRate";
1312
import { isMediaElement } from "./domRealm";
1413
import { parseStartExpression } from "./startExpression";
@@ -72,16 +71,9 @@ export function createRuntimeStartTimeResolver(params: {
7271
}
7372
}
7473
if ((resolved == null || resolved <= 0) && isMediaElement(element)) {
75-
const playbackStart = readMediaStart(element);
76-
if (Number.isFinite(element.duration) && element.duration > playbackStart) {
77-
resolved =
78-
resolveNaturalMediaTimelineDurationFromValues(
79-
element.duration,
80-
playbackStart,
81-
readElementRateSpec(element),
82-
) ?? 0;
83-
}
74+
resolved = resolveNaturalMediaTimelineDuration(element, element.duration);
8475
}
76+
if (resolved == null || resolved <= 0) resolved = resolveTimedImageDurationSeconds(element);
8577
if (resolved == null || resolved <= 0) {
8678
const compositionId = element.getAttribute("data-composition-id");
8779
if (compositionId) {

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS } from "@hyperframes/parsers/media-duration";
12
import { describe, it, expect, afterEach } from "vitest";
23
import { collectRuntimeTimelinePayload } from "./timeline";
34

@@ -326,6 +327,41 @@ describe("collectRuntimeTimelinePayload", () => {
326327
expect(result.clips[0].kind).toBe("image");
327328
});
328329

330+
it("gives a timed image with no data-duration the dropped-image default, not the composition remainder", () => {
331+
const root = document.createElement("div");
332+
root.setAttribute("data-composition-id", "main");
333+
root.setAttribute("data-duration", "10");
334+
document.body.appendChild(root);
335+
336+
const timed = document.createElement("img");
337+
timed.id = "timed";
338+
timed.setAttribute("data-start", "2");
339+
root.appendChild(timed);
340+
341+
const timedClip = collectRuntimeTimelinePayload(defaultParams).clips.find(
342+
(c) => c.id === "timed",
343+
);
344+
expect([timedClip?.start, timedClip?.duration]).toEqual([
345+
2,
346+
DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS,
347+
]);
348+
});
349+
350+
it("trims a timed image with data-end and no data-duration to end minus start", () => {
351+
const root = document.createElement("div");
352+
root.setAttribute("data-composition-id", "main");
353+
root.setAttribute("data-duration", "10");
354+
document.body.appendChild(root);
355+
const img = document.createElement("img");
356+
img.id = "trimmed";
357+
img.setAttribute("data-start", "2");
358+
img.setAttribute("data-end", "6");
359+
root.appendChild(img);
360+
361+
const clip = collectRuntimeTimelinePayload(defaultParams).clips.find((c) => c.id === "trimmed");
362+
expect([clip?.start, clip?.duration]).toEqual([2, 4]);
363+
});
364+
329365
it("identifies composition clips", () => {
330366
const root = document.createElement("div");
331367
root.setAttribute("data-composition-id", "main");

0 commit comments

Comments
 (0)