Helios Player

The @helios-project/player package provides the <helios-player> Web Component, a drop-in UI for reviewing and exporting Helios compositions.

Installation

npm install @helios-project/player

Usage

Host Page

Import the player and use the custom element in your HTML.

<script type="module">
  import "@helios-project/player";
</script>

<helios-player
  src="path/to/composition.html"
  width="1920"
  height="1080"
  controls
  autoplay
></helios-player>

Connecting the Composition

For the player to control your composition, the composition page (inside the iframe) must connect to the parent window.

If you are using packages/core directly:

import { Helios } from "@helios-project/core";
import { connectToParent } from "@helios-project/player/bridge";

const helios = new Helios({ ... });

// Initialize the bridge
connectToParent(helios);

If you are using window.helios (Legacy/Direct Mode):

The player will automatically attempt to access window.helios on the iframe's content window if it's on the same origin. However, connectToParent is the recommended approach for cross-origin support and sandboxing.

Attributes

| Attribute | Description | Default | |---|---|---| | src | URL of the composition page to load in the iframe. | (Required) | | width | Width of the player (aspect ratio calculation). | - | | height | Height of the player (aspect ratio calculation). | - | | autoplay | Automatically start playback when connected. | false | | loop | Loop playback when the end is reached. | false | | controls | Show the UI controls overlay. | false | | export-mode | Strategy for client-side export: auto, canvas, or dom. | auto | | canvas-selector | CSS selector for the canvas element (used in canvas export mode). | canvas | | export-format | Output format: mp4, webm, png, or jpeg. | mp4 | | poster | URL of an image to display before playback starts. | - | | preload | auto or none. If none, defers loading the iframe until interaction. | auto | | input-props | JSON string of properties to pass to the composition. | - | | interactive | Enable direct interaction with the composition (disables click-to-pause). | false | | controlslist | Space-separated list of features to disable: nodownload, nofullscreen. | - | | sandbox | Security flags for the iframe. | allow-scripts allow-same-origin | | export-width | Target width for client-side export. | - | | export-height | Target height for client-side export. | - | | muted | Automatically mute the player's audio upon loading. | false | | playsinline | Indicates that the video is to be played "inline", that is within the element's playback area. | false | | export-bitrate | Target bitrate for client-side export (bps). | - | | export-filename | Filename for client-side export (without extension). | video | | export-caption-mode | Strategy for caption export: burn-in or file. | burn-in | | disablepictureinpicture | Hides the Picture-in-Picture button. | false | | media-title | Title of the composition for OS Media Session. | - | | media-artist | Artist name for OS Media Session. | - | | media-album | Album name for OS Media Session. | - | | media-artwork | URL of artwork for OS Media Session (defaults to poster). | - | | crossorigin | CORS setting for this media element (anonymous or use-credentials). | - |

User Interface

The player includes a comprehensive set of controls:

• Playback: Play/Pause, Scrubber, Time Display.
• Audio: Volume, Mute, and a Track Menu for individual track control.
• Settings Menu (Gear Icon):
  • Speed: Adjust playback rate (0.25x - 2x).
  • Loop: Toggle playback looping.
  • Playback Range: Set In/Out points to loop a specific section.
  • Diagnostics: View environment capabilities (WebCodecs support).
  • Shortcuts: View keyboard shortcuts.
• Tools: Fullscreen, Picture-in-Picture, Captions (CC), Export.

Keyboard Shortcuts

| Key | Action | |-----|--------| | Space / K | Play / Pause | | F | Toggle Fullscreen | | M | Mute / Unmute | | C | Toggle Captions | | ? | Show Shortcuts Help | | ← / → | Seek 1 frame | | Shift + ← / → | Seek 10 frames | | Home | Go to Start | | End | Go to End | | I | Set In Point | | O | Set Out Point | | X | Clear Playback Range | | J | Seek backward 10 seconds | | L | Seek forward 10 seconds | | , | Seek backward 1 frame | | . | Seek forward 1 frame | | Shift + D | Toggle Diagnostics | | 0-9 | Seek to 0-90% |

CSS Variables

The player exposes several CSS variables to allow theming of the controls:

| Variable | Default | Description | |---|---|---| | --helios-controls-bg | rgba(0, 0, 0, 0.6) | Background color of the controls bar. | | --helios-text-color | white | Text and icon color. | | --helios-accent-color | #007bff | Accent color for active elements (scrubber, buttons). | | --helios-range-track-color | #555 | Background color of the scrubber track. | | --helios-font-family | sans-serif | Font family for the player UI. |

Standard Media API

The <helios-player> element implements a subset of the HTMLMediaElement interface, allowing you to control playback programmatically.

HTMLMediaElement Constants

Both class-level and instance-level properties are provided for standard media states:

• HAVE_NOTHING (0): No media data available.
• HAVE_METADATA (1): Media metadata available.
• HAVE_CURRENT_DATA (2): Data for current playback position available.
• HAVE_FUTURE_DATA (3): Data for current and future playback position available.
• HAVE_ENOUGH_DATA (4): Enough data available to play through.
• NETWORK_EMPTY (0): Uninitialized network state.
• NETWORK_IDLE (1): Idle network state.
• NETWORK_LOADING (2): Loading network state.
• NETWORK_NO_SOURCE (3): No source network state.

Methods

• setDuration(seconds: number): void - Updates the composition duration dynamically.

• setFps(fps: number): void - Updates the composition framerate dynamically.

• setSize(width: number, height: number): void - Updates the composition dimensions dynamically.

• setMarkers(markers: Marker[]): void - Updates the timeline markers dynamically.

• setSinkId(sinkId: string): Promise<void> - Sets the audio sink id.

• play(): Promise<void> - Starts playback.

• getController(): HeliosController | null - Retrieves the underlying HeliosController instance, if connected.

• getSchema(): Promise<HeliosSchema | undefined> - Retrieves the input properties schema from the composition.

• pause(): void - Pauses playback.

• setPlaybackRange(startFrame: number, endFrame: number): void - Sets the playback range to a specific start and end frame.

• clearPlaybackRange(): void - Clears the playback range.

• load(): void - Reloads the iframe (useful if src changed or to retry connection).

• addTextTrack(kind: string, label?: string, language?: string): TextTrack - Adds a new text track to the media element.

• diagnose(): Promise<DiagnosticReport> - Runs environment diagnostics (WebCodecs, WebGL) and returns a report.

• requestPictureInPicture(): Promise<PictureInPictureWindow> - Requests Picture-in-Picture mode for the player.

• export(options?: HeliosExportOptions): Promise<void> - Programmatically trigger client-side export.

• fastSeek(time: number): void - Seeks to the specified time as fast as possible (currently equivalent to setting currentTime).

• getStartDate(): number - Returns NaN since the player does not support a specific start date timeline.

• canPlayType(type: string): CanPlayTypeResult - Returns whether the player can play the specified media type (e.g., 'probably', 'maybe', or '').

• captureStream(): Promise<MediaStream> - Returns a MediaStream capturing the player's canvas (if same-origin).

• startAudioMetering(): void - Starts audio metering calculation.

• stopAudioMetering(): void - Stops audio metering calculation.

• getVideoPlaybackQuality(): VideoPlaybackQuality - Returns an object containing the video playback quality metrics.

• requestVideoFrameCallback(callback: VideoFrameRequestCallback): number - Registers a callback to be fired when a new frame is rendered.

• cancelVideoFrameCallback(handle: number): void - Cancels a previously registered video frame callback.

Properties

• disableRemotePlayback (boolean): Reflected disableremoteplayback attribute.

• remote (RemotePlayback): Returns a mock RemotePlayback object to complete HTMLMediaElement parity.

• mediaGroup (string): Reflected mediagroup attribute.

• sinkId (string, read-only): Returns the current audio sink id.

• src (string): URL of the composition page to load in the iframe.

• autoplay (boolean): Reflected autoplay attribute.

• loop (boolean): Reflected loop attribute.

• controls (boolean): Reflected controls attribute.

• poster (string): Reflected poster attribute.

• preload (string): Reflected preload attribute.

• sandbox (string): Reflected sandbox attribute.

• interactive (boolean): Reflected interactive attribute.

• textTracks (TextTrackList, read-only): The text tracks associated with the media element.

• audioTracks (AudioTrackList, read-only): The audio tracks associated with the media element.

• videoTracks (VideoTrackList, read-only): The video tracks associated with the media element.

• currentTime (number): Current playback position in seconds.

• duration (number, read-only): Total duration in seconds.

• paused (boolean, read-only): Whether playback is paused.

• ended (boolean, read-only): Whether playback has reached the end.

• volume (number): Audio volume (0.0 to 1.0).

• muted (boolean): Audio mute state.

• playbackRate (number): Playback speed (default 1.0).

• width (number): Reflected width attribute.

• height (number): Reflected height attribute.

• videoWidth (number, read-only): The intrinsic width of the video (from controller state or attributes).

• videoHeight (number, read-only): The intrinsic height of the video (from controller state or attributes).

• buffered (TimeRanges, read-only): Returns a TimeRanges object representing buffered content (always 0-duration).

• seekable (TimeRanges, read-only): Returns a TimeRanges object representing seekable content (always 0-duration).

• seeking (boolean, read-only): Whether the player is currently seeking (scrubbing).

• readyState (number, read-only): The current readiness state of the media (0-4).

• networkState (number, read-only): The current network state (0-3).

• fps (number, read-only): Frames per second of the composition.

• currentFrame (number): Current frame index.

• inputProps (object): Get or set the input properties passed to the composition.

• playsInline (boolean): Reflected playsinline attribute.

• disablePictureInPicture (boolean): Hides the Picture-in-Picture button.

• autoPictureInPicture (boolean): If true, automatically enters Picture-in-Picture when the user switches tabs or apps.

• error (MediaError | null, read-only): The current media error, or null if no error occurred.

• currentSrc (string, read-only): The absolute URL of the chosen media resource.

• played (TimeRanges, read-only): The ranges of the media source that the browser has played.

• defaultMuted (boolean): Reflected defaultMuted attribute.

• defaultPlaybackRate (number): The default rate of playback.

• srcObject (MediaProvider | null): The media provider object assigned to the player.

• crossOrigin (string | null): The CORS setting for this media element.

• exportMode (string): Reflected export-mode attribute.

• exportFormat (string): Reflected export-format attribute.

• exportFilename (string): Reflected export-filename attribute.

• exportWidth (number | null): Reflected export-width attribute.

• exportHeight (number | null): Reflected export-height attribute.

• exportBitrate (number | null): Reflected export-bitrate attribute.

• exportCaptionMode (string): Reflected export-caption-mode attribute.

• canvasSelector (string): Reflected canvas-selector attribute.

• controlsList (string): Reflected controlslist attribute.

• mediaTitle (string): Reflected media-title attribute.

• mediaArtist (string): Reflected media-artist attribute.

• mediaAlbum (string): Reflected media-album attribute.

• mediaArtwork (string): Reflected media-artwork attribute.

Event Handlers

• onplay (function | null): Event handler for the play event.
• onplaying (function | null): Event handler for the playing event.
• onpause (function | null): Event handler for the pause event.
• onended (function | null): Event handler for the ended event.
• ontimeupdate (function | null): Event handler for the timeupdate event.
• onvolumechange (function | null): Event handler for the volumechange event.
• onratechange (function | null): Event handler for the ratechange event.
• ondurationchange (function | null): Event handler for the durationchange event.
• onseeking (function | null): Event handler for the seeking event.
• onseeked (function | null): Event handler for the seeked event.
• onresize (function | null): Event handler for the resize event.
• onloadstart (function | null): Event handler for the loadstart event.
• onloadedmetadata (function | null): Event handler for the loadedmetadata event.
• onloadeddata (function | null): Event handler for the loadeddata event.
• oncanplay (function | null): Event handler for the canplay event.
• oncanplaythrough (function | null): Event handler for the canplaythrough event.
• onsuspend (function | null): Event handler for the suspend event.
• onstalled (function | null): Event handler for the stalled event.
• onwaiting (function | null): Event handler for the waiting event.
• onerror (function | null): Event handler for the error event.
• onenterpictureinpicture (function | null): Event handler for the enterpictureinpicture event.
• onleavepictureinpicture (function | null): Event handler for the leavepictureinpicture event.
• onaudiometering (function | null): Event handler for the audiometering event.
• onabort (function | null): Event handler for the abort event.
• onemptied (function | null): Event handler for the emptied event.
• onprogress (function | null): Event handler for the progress event.

Events

The element dispatches the following custom events:

• error: Fired when an error occurs during media loading or playback.
• audiometering: Fired during playback to report stereo RMS and Peak audio levels.
• playing: Fired when playback is ready to start after having been paused or delayed due to lack of data.
• suspend: Fired when media data loading has been suspended.
• stalled: Fired when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
• waiting: Fired when playback has stopped because of a temporary lack of data.
• play: Fired when playback starts.
• pause: Fired when playback is paused.
• seeking: Fired when a seek operation starts.
• seeked: Fired when a seek operation completes.
• ended: Fired when playback completes.
• timeupdate: Fired when the current time/frame changes.
• volumechange: Fired when volume or mute state changes.
• ratechange: Fired when playback rate changes.
• durationchange: Fired when the duration of the composition changes.
• loadstart: Fired when the browser begins looking for media data.
• loadedmetadata: Fired when the duration and dimensions of the media have been determined.
• loadeddata: Fired when data for the current frame is available.
• canplay: Fired when the browser can resume playback of the media.
• canplaythrough: Fired when the browser estimates it can play through the media without buffering.
• abort: Fired when the loading of the media has been aborted.
• emptied: Fired when the media has become empty.
• progress: Fired periodically as the browser loads a resource.
• resize: Fired when the player dimensions change.
• enterpictureinpicture: Fired when the player enters Picture-in-Picture mode.
• leavepictureinpicture: Fired when the player leaves Picture-in-Picture mode.

Client-Side Export

The player supports exporting the composition to video (MP4/WebM) or image snapshots (PNG/JPEG) directly in the browser using WebCodecs.

• export-mode="canvas": captures frames from a <canvas> element. Fast and efficient.
• export-mode="dom": captures the entire DOM using foreignObject SVG serialization. Useful for compositions using DOM elements (divs, text, css).
• export-mode="auto": attempts to detect the best strategy.

Configuration:

<helios-player
  src="..."
  export-mode="dom"
  export-format="webm"
></helios-player>

To take a snapshot (PNG) instead of a video, set export-format="png".

Audio Fades

To apply audio fades during client-side export, add data-helios-fade-in and/or data-helios-fade-out attributes to your audio elements within the composition. The value should be the duration in seconds.

<audio src="music.mp3" data-helios-fade-in="2" data-helios-fade-out="3"></audio>

Verification

To run the End-to-End (E2E) verification suite:

npx tsx tests/e2e/verify-player.ts

This script starts a local server and uses Playwright to verify the player's core functionality (playback, scrubber, menus, volume) using a dependency-free mock composition.