Files
hyperframes/docs/packages/player.mdx
T
3ee095bdec fix(player): keep the video playing when you jump to another moment (#7719)
Clicking or dragging the scrubber while a film played left it paused at
the new spot, and `paused` turned true without a `pause` event. The
controls now hold a playing film during the press and play on from where
it is released, like a <video>'s own controls; a paused film stays
paused. A touch scrub no longer replays as mouse events.

seek() gains an opt-in { keepPlaying: true } for hosts (keyboard seeks,
chapter jumps). A plain seek(t), and setting currentTime, still land
paused, so existing callers keep their behavior.

The packed player tarball grows 339 bytes (158705 to 159044, packed with
pnpm 10.17.1 as CI does). main sat 11 bytes under the 1% gate, so the
packed budget moves to 159100; the unpacked size stays within budget.

Co-authored-by: robinebers <16515780+robinebers@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-18 05:21:17 +00:00

233 lines
12 KiB
Plaintext

---
title: "@hyperframes/player"
description: "Embeddable web component for playing HyperFrames compositions in any web page."
---
The player package provides a `<hyperframes-player>` custom element that embeds a
HyperFrames composition in plain HTML or a framework application.
```bash
npm install @hyperframes/player
```
Use Player when an application needs to play and seek an HTML composition. Use
[Studio](/packages/studio) to edit it or the [CLI](/packages/cli) and
[Producer](/packages/producer) to render a video file.
## Embed a composition
### Via CDN
```html title="index.html"
<script type="module" src="https://cdn.jsdelivr.net/npm/@hyperframes/player"></script>
<hyperframes-player
src="./my-composition/index.html"
controls
style="width: 100%; max-width: 800px; aspect-ratio: 16/9"
></hyperframes-player>
```
With a package manager:
```js
import "@hyperframes/player";
```
```html title="index.html"
<hyperframes-player
src="/compositions/intro.html"
controls
></hyperframes-player>
```
Set `autoplay muted` only when playback should start without a user gesture.
Add or remove `controls` at any time. When shown, the controls reflect the current
playback state, position and speed. Clicking or dragging the scrubber keeps a
playing film playing from the new spot, as a `<video>`'s own controls do, and
leaves a paused film paused.
## Attributes
| Attribute | Type | Default | Description |
| --------------- | ------- | ------- | --------------------------------------------------------- |
| `src` | string | — | URL or relative path to composition HTML, or to a video file with `type` |
| `type` | string | — | A `video/...` type (e.g. `video/mp4`) plays `src` as a video file |
| `srcdoc` | string | — | Composition HTML already available as a string |
| `width` | number | 1920 | Native composition width used for aspect ratio |
| `height` | number | 1080 | Native composition height used for aspect ratio |
| `controls` | boolean | false | Show playback, scrub, speed, time, volume, and fullscreen controls |
| `autoplay` | boolean | false | Start when the composition is ready |
| `loop` | boolean | false | Restart at the end |
| `muted` | boolean | false | Mute audio |
| `volume` | number | 1 | Playback volume from 0 to 1 |
| `poster` | string | — | Image URL to show before first play |
| `playback-rate` | number | 1 | Playback speed multiplier |
| `audio-src` | string | — | Optional primary audio URL to preload in the parent frame |
| `audio-locked` | boolean | false | Force muted playback and hide volume controls |
| `assets-loading-ui` | `player` or `none` | `player` | `none` hides the loading-assets card; asset events still fire |
| `low-power-idle` | boolean | false | While paused, check in once a second, not every 80 ms (many-player pages) |
| `disable-click-to-play` | boolean | false | A click on the player no longer plays or pauses, so the page can handle it |
| `disable-fullscreen` | boolean | false | Hide the fullscreen button in the controls (`disableFullscreen`) |
| `no-load-timeout` | boolean | false | A slow load never fails at 8 s, so the page owns the deadline; script and runtime errors still fail at once |
| `range-start` | number | — | Film second where playback starts, loops back to and parks when paused (`rangeStart`) |
| `range-end` | number | — | Film second the range ends before: it stops or loops on the frame before it (`rangeEnd`) |
`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`.
The fullscreen button fills the screen with the whole player, controls included. It appears only where the page can go fullscreen, so not on iPhone Safari and not inside a cross-origin iframe without `allow="fullscreen"`. It follows every exit, including Esc. Set `disable-fullscreen` to hide it. A refused request fires the browser's `fullscreenerror` on the player.
Player also accepts `shader-capture-scale` and `shader-loading` for previewing
projects that use shader transitions. These are preview controls, not composition
authoring attributes.
With a `video/...` `type`, `src` plays in a `<video>` behind the same playback API and
events. `scenes`, `setRuntimeData()`, `setColorGrading()`, `iframeElement` and `stopMedia()`
are composition-only, and `srcdoc` wins over a video `src`, as it does in an iframe.
Removing a video player's `src` attribute or setting it to an empty string unloads the film and resets playback to paused at 0:00. Set a new `src` to load another video.
## JavaScript API
The main API follows familiar media-player behavior:
```js
const player = document.querySelector("hyperframes-player");
player.play();
player.pause();
player.seek(2.5);
player.seek(2.5, { keepPlaying: true });
player.currentTime = 5;
player.playbackRate = 1.5;
player.muted = true;
console.log(player.duration, player.paused, player.ready);
console.log(player.compositionWidth, player.compositionHeight);
```
`seek()` and setting `currentTime` pause at the new time. Pass `{ keepPlaying: true }`
to keep a playing film playing from there, as setting a `<video>`'s `currentTime`
does; a paused film stays paused.
In Studio previews, scrubbing keeps the last complete picture visible while video
layers decode at the requested time. Rapid seeks keep only the latest queued
destination, and the captions and video layers appear together once it is ready.
Complete intermediate pictures can appear during a drag. Jumping to a different
clip supersedes an earlier pending seek; failed sources do not hold up the preview.
## Events
```js
const player = document.querySelector("hyperframes-player");
player.addEventListener("ready", (event) => {
console.log("Duration:", event.detail.duration);
});
player.addEventListener("timeupdate", (event) => {
console.log("Time:", event.detail.currentTime);
});
```
| Event | Detail | Description |
| -------------- | ----------------- | ------------------------------------------------------------ |
| `ready` | `{ duration, compositionWidth, compositionHeight }` | Composition loaded and timeline discovered |
| `durationchange` | `{ duration }` | The duration changed after `ready` |
| `resize` | `{ compositionWidth, compositionHeight }` | The composition's size changed |
| `timeupdate` | `{ currentTime }` | Playback position changed, approximately 10 times per second |
| `play` | — | Playback started |
| `pause` | — | Playback paused |
| `ended` | — | Playback reached end |
| `rangeclamped` | `{ rangeStart, rangeEnd, duration }` | A range past the film was cut to its end, or an empty one ignored (nulls) |
| `ratechange` | — | Playback rate changed |
| `volumechange` | — | Volume or muted state changed |
| `scenes` | `{ scenes }` | The runtime reported its scene list |
| `error` | `{ message }` | Load or runtime error; a video adds its `MediaError` `code` |
| `playbackerror` | `{ source, error }` | The browser blocked playback, for example unmuted autoplay |
## Custom icons and loading mark
Put an element with a `slot` attribute inside the player to replace a control glyph or the loading mark. Anything you leave out keeps the default.
| Slot | Shown when | Default size |
| ------------------- | ----------------------------------------------------------- | ------------ |
| `play-icon` | Paused | 24 px |
| `pause-icon` | Playing | 24 px |
| `volume-high-icon` | Unmuted, volume 0.5 or higher | 20 px |
| `volume-low-icon` | Unmuted, volume below 0.5 | 20 px |
| `volume-muted-icon` | Muted | 20 px |
| `loading-mark` | Preparing shader transitions, loading assets, and buffering | 78 px |
```html title="index.html"
<hyperframes-player src="/compositions/intro.html" controls>
<svg slot="play-icon" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
<path d="M8 5v14l11-7z" />
</svg>
<svg slot="pause-icon" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
<path d="M6 5h4v14H6zM14 5h4v14h-4z" />
</svg>
<img slot="loading-mark" src="/brand-mark.svg" width="78" height="78" alt="" />
</hyperframes-player>
```
Glyphs take the control bar's color through `currentColor`, and you set their size. Put `slot` on the `<svg>` or `<img>` itself, as a direct child of the player; a wrapper element needs `display: contents` to keep the glyph centered. A custom mark replaces the HyperFrames light sweep and glow, so add your own CSS animation if you want motion.
Until the element is defined, its children show as plain content. Hide them:
```css title="styles.css"
hyperframes-player:not(:defined) > [slot] {
display: none;
}
```
## Advanced: iframe access
The composition runs inside an `<iframe>` in the player's Shadow DOM. For most
uses, the JavaScript API and events above are enough. The `iframeElement` getter
exists for same-origin tools that must inspect the composition DOM or connect a
custom editing surface:
```js
const player = document.querySelector("hyperframes-player");
const iframe = player.iframeElement;
// Reach into the composition's DOM
iframe.contentDocument.querySelectorAll("[data-composition-id]");
// Read the runtime (GSAP timelines, element registry, etc.)
iframe.contentWindow.__timelines;
```
Direct DOM access works only when the composition and the host page are
same-origin. Cross-origin embeds must use the Player API and events.
[`@hyperframes/studio`](/packages/studio) exports `resolveIframe` for consumers
that need to pass the inner iframe to Studio's timeline hooks:
```ts
import { resolveIframe, useTimelinePlayer } from "@hyperframes/studio";
const { iframeRef } = useTimelinePlayer();
const player = document.createElement("hyperframes-player");
player.setAttribute("src", src);
container.appendChild(player);
// Forward the inner iframe so useTimelinePlayer can drive play/pause/seek.
iframeRef.current = resolveIframe(player);
```
## How it works
The composition runs in a sandboxed iframe inside the player's Shadow DOM. This
isolates its styles, scales it to the player container, and lets the player
communicate with the HyperFrames runtime through `postMessage`.
## Related topics
- [Edit the same composition with the SDK](/sdk/quickstart)
- [Use the complete Studio interface](/studio)
- [Understand the composition contract](/reference/html-schema)