Helios Player

Web component for previewing and exporting Helios compositions

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.