Skip to content

Commit 840f657

Browse files
feat(player): play and loop a range of a film with range-start and range-end (#4688)
* feat(player): play and loop a range of the film with range-start and range-end The runtime takes a set-play-range control and stops on the range end frame itself. The player wraps to range-start with loop, fires ended without it, and reports a range cut to the film with rangeclamped. Video and __timelines players check it per tick. * fix(player): hold a range on its last frame and let the runtime own range jumps A runtime with the play-range capability jumps to range-start itself when a new range leaves the playhead outside, so a stale state no longer ends the film; older runtimes keep the player fallback, guarded until a state lands inside. Every range stop shows the last frame before range-end; a paused playhead re-parks only when it falls outside the new range. * fix(player): stop a range a check early and enforce its end on a video in a background tab * test(player): share the range video setup * fix(player): a slow frame no longer cuts a range short; a video without a range is unchanged * fix(player): a range still stops early where video time moves once per frame * refactor(player): cut the range look-ahead comment to one line * fix(player): a per-frame video time rounded down still stops a range early * test(player): pin no rounding tolerance at a film's own end * test(studio): expect the play-range capability on control messages
1 parent dc61ce1 commit 840f657

18 files changed

Lines changed: 974 additions & 38 deletions

‎docs/packages/player.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ Set `autoplay muted` only when playback should start without a user gesture.
6464
| `assets-loading-ui` | `player` or `none` | `player` | `none` hides the loading-assets card; asset events still fire |
6565
| `low-power-idle` | boolean | false | While paused, check in once a second, not every 80 ms (many-player pages) |
6666
| `disable-click-to-play` | boolean | false | A click on the player no longer plays or pauses, so the page can handle it |
67+
| `range-start` | number | — | Film second where playback starts, loops back to and parks when paused (`rangeStart`) |
68+
| `range-end` | number | — | Film second the range ends before: it stops or loops on the frame before it (`rangeEnd`) |
69+
70+
`range-start` and `range-end` play the moment [start, end) of the film. The player parks on `range-start` at `ready`, and again when a paused playhead falls outside a new range; `play()` from outside the range starts there. At the end it holds the last frame before `range-end` and fires `ended`, or wraps to `range-start` with `loop`. `currentTime` at `ended` is then inside that frame, not `range-end` itself, so listen for `ended` rather than comparing times. A current runtime stops on that frame itself; video and `__timelines` players stop one clock tick early, predicted from the smaller of their last two steps, and a video in a background tab checks on its own `timeupdate`; an older runtime stops when the player sees its time pass the end. `currentTime` and `duration` stay in film time. A range past the film is cut to its end and an empty or negative one is ignored; both fire `rangeclamped`.
6771

6872
Player also accepts `shader-capture-scale` and `shader-loading` for previewing
6973
projects that use shader transitions. These are preview controls, not composition
@@ -115,6 +119,7 @@ player.addEventListener("timeupdate", (event) => {
115119
| `play` | — | Playback started |
116120
| `pause` | — | Playback paused |
117121
| `ended` | — | Playback reached end |
122+
| `rangeclamped` | `{ rangeStart, rangeEnd, duration }` | A range past the film was cut to its end, or an empty one ignored (nulls) |
118123
| `ratechange` | — | Playback rate changed |
119124
| `volumechange` | — | Volume or muted state changed |
120125
| `scenes` | `{ scenes }` | The runtime reported its scene list |

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ function createMockDeps() {
1818
onSetColorGrading: vi.fn(),
1919
onSetColorGradingCompare: vi.fn(),
2020
onSetRootDuration: vi.fn(),
21+
onSetPlayRange: vi.fn(),
2122
onEnablePickMode: vi.fn(),
2223
onDisablePickMode: vi.fn(),
2324
onSetRuntimeData: vi.fn(),
@@ -258,6 +259,17 @@ describe("installRuntimeControlBridge", () => {
258259
expect(deps.onSetRootDuration).toHaveBeenCalledWith(18.5);
259260
});
260261

262+
it("dispatches set-play-range with numeric seconds, and null for an open end", () => {
263+
const deps = createMockDeps();
264+
const handler = installRuntimeControlBridge(deps);
265+
handler(makeControlMessage("set-play-range", { startSeconds: "2", endSeconds: 3.5 }));
266+
handler(makeControlMessage("set-play-range", { startSeconds: null, endSeconds: null }));
267+
expect(deps.onSetPlayRange.mock.calls).toEqual([
268+
[2, 3.5],
269+
[0, null],
270+
]);
271+
});
272+
261273
it("dispatches set-color-grading command with target and grading payload", () => {
262274
const deps = createMockDeps();
263275
const handler = installRuntimeControlBridge(deps);

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ type BridgeDeps = {
2222
onSetPlaybackRate: (rate: number) => void;
2323
onSetIdleHeartbeat: (slow: boolean) => void;
2424
onSetRootDuration: (durationSeconds: number) => void;
25+
onSetPlayRange: (startSeconds: number, endSeconds: number | null) => void;
2526
onSetColorGrading: (target: HfColorGradingTarget | string | null, grading: unknown) => void;
2627
onSetColorGradingCompare: (
2728
target: HfColorGradingTarget | string | null,
@@ -74,6 +75,11 @@ const CONTROL_HANDLERS = new Map<string, ControlHandler>(
7475
"set-playback-rate": (data, deps) => deps.onSetPlaybackRate(Number(data.playbackRate ?? 1)),
7576
"set-idle-heartbeat": (data, deps) => deps.onSetIdleHeartbeat(Boolean(data.slow)),
7677
"set-root-duration": (data, deps) => deps.onSetRootDuration(Number(data.durationSeconds ?? 0)),
78+
"set-play-range": (data, deps) =>
79+
deps.onSetPlayRange(
80+
Number(data.startSeconds ?? 0),
81+
data.endSeconds == null ? null : Number(data.endSeconds),
82+
),
7783
"set-color-grading": (data, deps) =>
7884
deps.onSetColorGrading(data.target ?? null, data.grading ?? null),
7985
"set-color-grading-compare": (data, deps) =>

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,28 @@ describe("TransportClock", () => {
199199
expect(clock.getDuration()).toBe(Infinity);
200200
});
201201

202+
it("plays to a range's end, stops on its last frame, and runs to the film end once cleared", () => {
203+
const { clock, advance } = createClock({ duration: 6 });
204+
clock.setPlayRange(2, 3, 30);
205+
clock.seek(2);
206+
clock.play();
207+
advance(1500);
208+
expect(clock.now()).toBe(3);
209+
expect(clock.reachedEnd()).toBe(true);
210+
expect(clock.getStopTime()).toBeCloseTo(89 / 30, 9);
211+
clock.pause();
212+
clock.seek(clock.getStopTime());
213+
expect(clock.reachedEnd()).toBe(true);
214+
expect(clock.getDuration()).toBe(6);
215+
expect(clock.getPlayStart()).toBe(2);
216+
clock.setPlayRange(0, null, 30);
217+
expect(clock.reachedEnd()).toBe(false);
218+
expect(clock.getStopTime()).toBe(6);
219+
clock.play();
220+
advance(5000);
221+
expect(clock.now()).toBe(6);
222+
});
223+
202224
it("reachedEnd returns false when no duration set", () => {
203225
const { clock, advance } = createClock();
204226
clock.play();

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

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { timeAtSourceTime, type RateSpec } from "../speedRamp.js";
22
import { MEDIA_HARD_SYNC_SECONDS } from "./media.js";
3+
import { playRangeHoldTime } from "./protocol.js";
34

45
export type TransportClockSnapshot = {
56
time: number;
@@ -31,6 +32,9 @@ export class TransportClock {
3132
private _playStartMs: number | null = null;
3233
private _rate = 1;
3334
private _duration = Infinity;
35+
private _playStart = 0;
36+
private _playEnd = Infinity;
37+
private _playHold = Infinity;
3438
private _nowMs: () => number;
3539
private _audioSource: AudioClockSource | null = null;
3640
/** Wall-clock time of the last `now()` read while playing; null while paused. */
@@ -64,7 +68,7 @@ export class TransportClock {
6468
audioTime = this._elementTimeNeverBehind(this._audioSource);
6569
}
6670
if (audioTime !== null) {
67-
const t = Number.isFinite(this._duration) ? Math.min(audioTime, this._duration) : audioTime;
71+
const t = Math.min(audioTime, this.getEnd());
6872
this._baseTime = Math.max(0, t);
6973
this._playStartMs = this._nowMs();
7074
this._lastReadMs = null;
@@ -77,7 +81,7 @@ export class TransportClock {
7781
this._applyStallCorrection();
7882
const elapsed = (this._nowMs() - this._playStartMs) / 1000;
7983
const t = this._baseTime + elapsed * this._rate;
80-
this._lastNow = Math.max(0, Number.isFinite(this._duration) ? Math.min(t, this._duration) : t);
84+
this._lastNow = Math.max(0, Math.min(t, this.getEnd()));
8185
return this._lastNow;
8286
}
8387

@@ -113,7 +117,7 @@ export class TransportClock {
113117

114118
play(): boolean {
115119
if (this._playStartMs !== null) return false;
116-
if (Number.isFinite(this._duration) && this._baseTime >= this._duration) return false;
120+
if (this._baseTime >= this.getEnd()) return false;
117121
this._playStartMs = this._nowMs();
118122
this._lastNow = this._baseTime;
119123
// Not a stall: the gap since the clock was last read (possibly a long
@@ -174,6 +178,25 @@ export class TransportClock {
174178
return this._duration;
175179
}
176180

181+
setPlayRange(start: number, end: number | null, fps: number): void {
182+
this._playStart = Number.isFinite(start) && start > 0 ? start : 0;
183+
this._playEnd = end !== null && Number.isFinite(end) && end > this._playStart ? end : Infinity;
184+
this._playHold = playRangeHoldTime(this._playStart, this._playEnd, fps);
185+
}
186+
187+
getPlayStart(): number {
188+
return this._playStart;
189+
}
190+
191+
getEnd(): number {
192+
return Math.min(this._duration, this._playEnd);
193+
}
194+
195+
/** Where a stop parks: the film's end, or a range's last frame, since the moment is [start, end). */
196+
getStopTime(): number {
197+
return this._playEnd < this._duration ? this._playHold : this.getEnd();
198+
}
199+
177200
attachAudioSource(source: AudioClockSource): void {
178201
this._audioSource = source;
179202
}
@@ -218,6 +241,7 @@ export class TransportClock {
218241
}
219242

220243
reachedEnd(): boolean {
221-
return Number.isFinite(this._duration) && this.now() >= this._duration;
244+
const time = this.now();
245+
return time >= this.getEnd() || (this._playStartMs === null && time >= this.getStopTime());
222246
}
223247
}

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

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3710,9 +3710,10 @@ export function initSandboxRuntimeModular(): void {
37103710
if (dur > 0) {
37113711
clock.setDuration(dur);
37123712
if (clock.reachedEnd()) {
3713-
clock.seek(0);
3714-
state.currentTime = 0;
3715-
seekTimelineAndAdapters(0);
3713+
const start = clock.getPlayStart();
3714+
clock.seek(start);
3715+
state.currentTime = start;
3716+
seekTimelineAndAdapters(start);
37163717
}
37173718
} else {
37183719
const rootEl = resolveRootCompositionElement();
@@ -4594,21 +4595,19 @@ export function initSandboxRuntimeModular(): void {
45944595
colorGrading.redrawAnimated();
45954596
}
45964597

4597-
// Looping is handled at the player layer (<hyperframes-player>),
4598-
// not the runtime. The clock pauses at duration; GSAP's repeat:-1
4599-
// is bypassed because we drive tl.totalTime(t) directly. The
4600-
// parent observes isPlaying=false at end and re-issues seek(0)+play()
4601-
// if its loop attribute is set.
4598+
// The clock stops at its end (GSAP's repeat:-1 is bypassed: we drive
4599+
// tl.totalTime(t) directly); the parent loops by seeking to its range
4600+
// start, or 0, and playing again.
46024601
if (clock.isPlaying() && clock.reachedEnd()) {
46034602
webAudio.stopAll();
46044603
clock.detachAudioSource();
46054604
clock.pause();
46064605
state.isPlaying = false;
4607-
const dur = clock.getDuration();
4608-
if (Number.isFinite(dur)) {
4609-
clock.seek(dur);
4610-
state.currentTime = dur;
4611-
seekTimelineAndAdapters(dur);
4606+
const stop = clock.getStopTime();
4607+
if (Number.isFinite(stop)) {
4608+
clock.seek(stop);
4609+
state.currentTime = stop;
4610+
seekTimelineAndAdapters(stop);
46124611
}
46134612
runAdapters("pause");
46144613
syncMediaForCurrentState(timingRevision);
@@ -4890,6 +4889,15 @@ export function initSandboxRuntimeModular(): void {
48904889
wakeTransport();
48914890
},
48924891
onSetRootDuration: growRootDurationLive,
4892+
onSetPlayRange: (startSeconds, endSeconds) => {
4893+
clock.setPlayRange(startSeconds, endSeconds, state.canonicalFps);
4894+
const start = clock.getPlayStart();
4895+
if (clock.isPlaying() && (clock.now() < start || clock.reachedEnd())) {
4896+
transport.seek(start, { keepPlaying: true });
4897+
return;
4898+
}
4899+
postState(true);
4900+
},
48934901
onSetColorGrading: (target, grading) => {
48944902
colorGrading.setGrading(target, grading);
48954903
},
@@ -4906,11 +4914,11 @@ export function initSandboxRuntimeModular(): void {
49064914
clock.detachAudioSource();
49074915
clock.pause();
49084916
state.isPlaying = false;
4909-
const dur = clock.getDuration();
4910-
if (Number.isFinite(dur)) {
4911-
clock.seek(dur);
4912-
state.currentTime = dur;
4913-
seekTimelineAndAdapters(dur);
4917+
const stop = clock.getStopTime();
4918+
if (Number.isFinite(stop)) {
4919+
clock.seek(stop);
4920+
state.currentTime = stop;
4921+
seekTimelineAndAdapters(stop);
49144922
}
49154923
runAdapters("pause");
49164924
syncMediaForCurrentState();

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ export const RUNTIME_PROTOCOL_CAPABILITIES = [
66
"seek-keep-playing",
77
"composition-manifest-v1",
88
"runtime-data",
9+
"play-range",
910
] as const;
1011

1112
export type RuntimeProtocolFps = {
@@ -47,6 +48,10 @@ export function runtimeProtocolFpsFromNumber(value: number): RuntimeProtocolFps
4748
return { numerator: numerator / divisor, denominator: denominator / divisor };
4849
}
4950

51+
export function playRangeHoldTime(start: number, end: number, fps: number): number {
52+
return Math.max(start, (Math.ceil(end * fps - 1e-6) - 1) / fps);
53+
}
54+
5055
export function runtimeProtocolFpsToNumber(value: unknown): number | null {
5156
if (typeof value !== "object" || value === null) return null;
5257
const fps = value as Partial<RuntimeProtocolFps>;

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,88 @@ describe("parked transport loop", () => {
206206
expect(states.at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 149 });
207207
});
208208

209+
const setPlayRange = (startSeconds: number | null, endSeconds: number | null) =>
210+
window.dispatchEvent(
211+
new MessageEvent("message", {
212+
source: window.parent,
213+
data: {
214+
source: "hf-parent",
215+
type: "control",
216+
action: "set-play-range",
217+
startSeconds,
218+
endSeconds,
219+
},
220+
}),
221+
);
222+
const stateMessages = () => posted.filter((m) => m["type"] === "state");
223+
224+
/** Mounts a 5 s film with clips a [0, 3) and b [3, 5), driven by a mocked clock. */
225+
const mountRangeFilm = () => {
226+
let nowMs = 1000;
227+
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
228+
mount(
229+
`<div id="a" data-start="0" data-duration="3"></div><div id="b" data-start="3" data-duration="2"></div>`,
230+
);
231+
const timeline = window.__timelines!.main!;
232+
initSandboxRuntimeModular();
233+
quiesce();
234+
const frames: Array<{ time: number; b: string }> = [];
235+
const step = () => {
236+
nowMs += 7;
237+
raf.step(7);
238+
frames.push({ time: timeline.time(), b: document.getElementById("b")!.style.visibility });
239+
};
240+
const playOut = () => {
241+
window.__player!.play();
242+
for (let n = 0; n < 1000 && window.__player!.isPlaying(); n += 1) step();
243+
};
244+
return { timeline, frames, step, playOut };
245+
};
246+
247+
it("stops on a play range's last frame, says it ended, and restarts at the range start only while it is set", () => {
248+
const { timeline, frames, playOut } = mountRangeFilm();
249+
250+
setPlayRange(2, 3);
251+
window.__player!.seek(2);
252+
for (let wrap = 0; wrap < 3; wrap += 1) playOut();
253+
expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 89 });
254+
expect(stateMessages().at(-1)?.["currentTime"]).toBeCloseTo(89 / 30, 9);
255+
expect(timeline.time()).toBeCloseTo(89 / 30, 9);
256+
expect(Math.max(...frames.map((f) => f.time))).toBeLessThan(3);
257+
expect(frames.every((f) => f.b === "hidden")).toBe(true);
258+
expect(document.getElementById("a")!.style.visibility).not.toBe("hidden");
259+
expect(window.__player!.getDuration()).toBe(5);
260+
261+
const before = stateMessages().length;
262+
window.__player!.play();
263+
expect(stateMessages()[before]).toMatchObject({ isPlaying: true, frame: 60 });
264+
window.__player!.pause();
265+
266+
setPlayRange(null, null);
267+
playOut();
268+
expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 150 });
269+
const atFilmEnd = stateMessages().length;
270+
window.__player!.play();
271+
expect(stateMessages()[atFilmEnd]).toMatchObject({ isPlaying: true, frame: 0 });
272+
});
273+
274+
it("jumps to the range start and keeps playing when a new range leaves the playhead outside", () => {
275+
const { step } = mountRangeFilm();
276+
setPlayRange(2, 3);
277+
window.__player!.seek(2.5);
278+
window.__player!.play();
279+
step();
280+
const before = stateMessages().length;
281+
282+
setPlayRange(2, 2.4);
283+
284+
const after = stateMessages().slice(before);
285+
expect(after.some((m) => m["ended"] === true)).toBe(false);
286+
expect(after.at(-1)).toMatchObject({ isPlaying: true, currentTime: 2 });
287+
expect(after.at(-1)?.["capabilities"]).toContain("play-range");
288+
expect(window.__player!.isPlaying()).toBe(true);
289+
});
290+
209291
// The render stops at the root's declared length too; a longer animation is cut off.
210292
it.each([
211293
["3 s, shorter than its animation", "3", 90],

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ type RuntimeBridgeControlActionBase =
2222
| "set-web-audio-media-disabled"
2323
| "set-idle-heartbeat"
2424
| "set-root-duration"
25+
| "set-play-range"
2526
| "stop-media"
2627
| "flash-elements";
2728

@@ -34,6 +35,8 @@ type RuntimeBridgeControlMessageBase = {
3435
muted?: boolean;
3536
volume?: number;
3637
durationSeconds?: number;
38+
startSeconds?: number | null;
39+
endSeconds?: number | null;
3740
disabled?: boolean;
3841
slow?: boolean;
3942
playbackRate?: number;

0 commit comments

Comments
 (0)