Helios Player

The <helios-player> web component provides a drop-in UI for reviewing and exporting Helios compositions. It implements a subset of the HTMLMediaElement interface for familiar programmatic control.

Installation

npm install @helios-project/player

Usage

Basic setup

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 must connect to the parent window. Using @helios-project/core:

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

const helios = new Helios({ /* config */ });

// Initialize the bridge
connectToParent(helios);

Legacy mode (same-origin only): The player will automatically access window.helios on the iframe’s content window if available. However, connectToParent is recommended for cross-origin support and sandboxing.

Attributes

Attribute	Description	Default
`src`	URL of the composition page to load	(Required)
`width`	Width for aspect ratio calculation	-
`height`	Height for aspect ratio calculation	-
`autoplay`	Auto-start playback when connected	`false`
`loop`	Loop playback at the end	`false`
`controls`	Show UI controls overlay	`false`
`export-mode`	Export strategy: `auto`, `canvas`, or `dom`	`auto`
`canvas-selector`	CSS selector for canvas element	`canvas`
`export-format`	Output format: `mp4`, `webm`, `png`, `jpeg`	`mp4`
`poster`	Image URL to display before playback	-
`preload`	`auto` or `none` (defers iframe loading)	`auto`
`input-props`	JSON string of composition properties	-
`interactive`	Enable direct composition interaction	`false`
`controlslist`	Disable features: `nodownload`, `nofullscreen`	-
`sandbox`	Security flags for the iframe	`allow-scripts allow-same-origin`
`export-width`	Target width for export	-
`export-height`	Target height for export	-
`export-bitrate`	Target bitrate for export (bps)	-
`export-filename`	Filename for export (no extension)	`video`
`export-caption-mode`	Caption strategy: `burn-in` or `file`	`burn-in`
`disablepictureinpicture`	Hide Picture-in-Picture button	`false`
`media-title`	Title for OS Media Session	-
`media-artist`	Artist name for OS Media Session	-
`media-album`	Album name for OS Media Session	-
`media-artwork`	Artwork URL for OS Media Session	-

User interface

The player includes comprehensive controls:

Playback - Play/Pause, scrubber, time display
Audio - Volume, mute, and track menu for individual track control
Settings menu (gear icon):
- Speed adjustment (0.25x - 2x)
- Loop toggle
- Playback range (In/Out points)
- Diagnostics (WebCodecs support)
- Shortcuts reference
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
`Shift` + `D`	Toggle Diagnostics
`0-9`	Seek to 0-90%

API reference

The <helios-player> element implements a subset of the HTMLMediaElement interface.

Methods

`play(): Promise<void>`

Starts playback.

const player = document.querySelector('helios-player');
await player.play();

`pause(): void`

Pauses playback.

`load(): void`

Reloads the iframe (useful if src changed or to retry connection).

`export(options?: HeliosExportOptions): Promise<void>`

Programmatically trigger client-side export.

await player.export({
  format: 'webm',
  filename: 'my-video',
  mode: 'dom',
  width: 1920,
  height: 1080
});

`diagnose(): Promise<DiagnosticReport>`

Runs environment diagnostics (WebCodecs, WebGL) and returns a report.

`requestPictureInPicture(): Promise<PictureInPictureWindow>`

Requests Picture-in-Picture mode for the player.

`addTextTrack(kind: string, label?: string, language?: string): TextTrack`

Adds a new text track to the media element.

`fastSeek(time: number): void`

Seeks to the specified time as fast as possible (currently equivalent to setting currentTime).

Properties

Property	Type	Description
`currentTime`	`number`	Current playback position (seconds)
`duration`	`number` (read-only)	Total duration (seconds)
`paused`	`boolean` (read-only)	Whether playback is paused
`ended`	`boolean` (read-only)	Whether playback has ended
`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)	Intrinsic video width
`videoHeight`	`number` (read-only)	Intrinsic video height
`buffered`	`TimeRanges` (read-only)	Buffered content (always 0-duration)
`seekable`	`TimeRanges` (read-only)	Seekable content (always 0-duration)
`seeking`	`boolean` (read-only)	Whether currently seeking/scrubbing
`readyState`	`number` (read-only)	Readiness state (0-4)
`networkState`	`number` (read-only)	Network state (0-3)
`fps`	`number` (read-only)	Frames per second
`currentFrame`	`number`	Current frame index
`inputProps`	`object`	Composition input properties
`playsInline`	`boolean`	Reflected playsinline attribute
`disablePictureInPicture`	`boolean`	Hide PiP button
`textTracks`	`TextTrackList` (read-only)	Text tracks

Events

The element dispatches standard media events:

play - Playback starts
pause - Playback paused
ended - Playback completed
timeupdate - Current time/frame changed
volumechange - Volume or mute state changed
ratechange - Playback rate changed
durationchange - Duration changed
loadstart - Browser begins looking for media
loadedmetadata - Duration and dimensions determined
loadeddata - Data for current frame available
canplay - Browser can resume playback
canplaythrough - Browser can play through without buffering

Controllers

The player uses two controller patterns for managing compositions:

DirectController

For same-origin compositions with direct access to the Helios instance. See /home/daytona/workspace/source/packages/player/src/controllers.ts:38

BridgeController

For cross-origin or sandboxed compositions using postMessage communication. See /home/daytona/workspace/source/packages/player/src/controllers.ts:245

Client-side export

The player supports browser-based export to video (MP4/WebM) or image snapshots (PNG/JPEG) using WebCodecs.

Export modes

canvas - Captures frames from a <canvas> element. Fast and efficient.
dom - Captures the entire DOM using foreignObject SVG serialization. For compositions using DOM elements.
auto - Automatically detects the best strategy.

Configuration example

<helios-player
  src="composition.html"
  export-mode="dom"
  export-format="webm"
  export-width="1920"
  export-height="1080"
></helios-player>

Image snapshots

Set export-format="png" or export-format="jpeg" to capture a single frame instead of rendering video.

Audio fades

Apply audio fades during export by adding data-helios-fade-in and data-helios-fade-out attributes to audio elements:

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

Values are in seconds.

CSS variables

Customize the player controls with CSS variables:

Variable	Default	Description
`--helios-controls-bg`	`rgba(0, 0, 0, 0.6)`	Controls bar background
`--helios-text-color`	`white`	Text and icon color
`--helios-accent-color`	`#007bff`	Accent for active elements
`--helios-range-track-color`	`#555`	Scrubber track background
`--helios-font-family`	`sans-serif`	UI font family

Verification

Run the E2E verification suite:

npx tsx tests/e2e/verify-player.ts

This uses Playwright to verify core functionality (playback, scrubber, menus, volume) with a dependency-free mock composition.

Get Started

Core Concepts

Framework Guides

Features

Rendering

Tools

Component Registry

Advanced

Installation

Usage

Basic setup

Connecting the composition

Attributes

User interface

Keyboard shortcuts

API reference

Methods

`play(): Promise<void>`

`pause(): void`

`load(): void`

`export(options?: HeliosExportOptions): Promise<void>`

`diagnose(): Promise<DiagnosticReport>`

`requestPictureInPicture(): Promise<PictureInPictureWindow>`

`addTextTrack(kind: string, label?: string, language?: string): TextTrack`

`fastSeek(time: number): void`

Properties

Events

Controllers

DirectController

BridgeController

Client-side export

Export modes

Configuration example

Image snapshots

Audio fades

CSS variables

Verification

Build docs developers (and LLMs) love

Get Started

Core Concepts

Framework Guides

Features

Rendering

Tools

Component Registry

Advanced

​Installation

​Usage

​Basic setup

​Connecting the composition

​Attributes

​User interface

​Keyboard shortcuts

​API reference

​Methods

​play(): Promise<void>

​pause(): void

​load(): void

​export(options?: HeliosExportOptions): Promise<void>

​diagnose(): Promise<DiagnosticReport>

​requestPictureInPicture(): Promise<PictureInPictureWindow>

​addTextTrack(kind: string, label?: string, language?: string): TextTrack

​fastSeek(time: number): void

​Properties

​Events

​Controllers

​DirectController

​BridgeController

​Client-side export

​Export modes

​Configuration example

​Image snapshots

​Audio fades

​CSS variables

​Verification

Build docs developers (and LLMs) love

Installation

Usage

Basic setup

Connecting the composition

Attributes

User interface

Keyboard shortcuts

API reference

Methods

`play(): Promise<void>`

`pause(): void`

`load(): void`

`export(options?: HeliosExportOptions): Promise<void>`

`diagnose(): Promise<DiagnosticReport>`

`requestPictureInPicture(): Promise<PictureInPictureWindow>`

`addTextTrack(kind: string, label?: string, language?: string): TextTrack`

`fastSeek(time: number): void`

Properties

Events

Controllers

DirectController

BridgeController

Client-side export

Export modes

Configuration example

Image snapshots

Audio fades

CSS variables

Verification