@hyperframes/player

The player package provides a <hyperframes-player> custom element that embeds a HyperFrames composition in plain HTML or a framework application.

npm install @hyperframes/player

Use Player when an application needs to play and seek an HTML composition. Use Studio to edit it or the CLI and Producer to render a video file.

Embed a composition

Via CDN

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:

import "@hyperframes/player";

index.html

<hyperframes-player
  src="/compositions/intro.html"
  controls
></hyperframes-player>

Set autoplay muted only when playback should start without a user gesture.

Attributes

Attribute	Type	Default	Description
`src`	string	—	URL or relative path to composition HTML
`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, and volume 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

Player also accepts shader-capture-scale and shader-loading for previewing projects that use shader transitions. These are preview controls, not composition authoring attributes.

JavaScript API

The main API follows familiar media-player behavior:

const player = document.querySelector("hyperframes-player");

player.play();
player.pause();
player.seek(2.5);

player.currentTime = 5;
player.playbackRate = 1.5;
player.muted = true;

console.log(player.duration, player.paused, player.ready);

Events

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 }`	Composition loaded and timeline discovered
`timeupdate`	`{ currentTime }`	Playback position changed, approximately 10 times per second
`play`	—	Playback started
`pause`	—	Playback paused
`ended`	—	Playback reached end
`ratechange`	—	Playback rate changed
`volumechange`	—	Volume or muted state changed
`scenes`	`{ scenes }`	The runtime reported its scene list
`error`	`{ message }`	Load or runtime error

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:

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 exports resolveIframe for consumers that need to pass the inner iframe to Studio’s timeline hooks:

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.

Start here

Command line

SDK guides

SDK reference

Composition, design & animation

Composition reference

Rendering paths

Cloud infrastructure

Advanced rendering

Packages

Agent setup

Contributing & community

Embed a composition

Via CDN

Attributes

JavaScript API

Events

Advanced: iframe access

How it works

​Embed a composition

​Via CDN

​Attributes

​JavaScript API

​Events

​Advanced: iframe access

​How it works

​Related topics

Embed a composition

Via CDN

Attributes

JavaScript API

Events

Advanced: iframe access

How it works

Related topics