Player element

The <helios-player> element is a custom web component that provides a video-like interface for playing Helios compositions. It implements the HTMLMediaElement API for standard video compatibility.

Basic usage

<helios-player
  src="https://example.com/composition.html"
  controls
  autoplay
  loop
></helios-player>

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

Attributes

src

string

URL to the Helios composition HTML file. The composition will be loaded in an iframe.

controls

boolean

Shows playback controls including play/pause, scrubber, volume, fullscreen, and export buttons.

autoplay

boolean

Automatically starts playback when the composition loads. Follows browser autoplay policies.

loop

boolean

Restarts playback from the beginning when the composition ends.

muted

boolean

Mutes all audio output. Can be toggled at runtime via the muted property.

poster

string

URL to a poster image displayed before the first play. Shown with a large play button overlay.

width

number

Width of the player in pixels. Also accessible via the width property.

height

number

Height of the player in pixels. Also accessible via the height property.

interactive

boolean

Enables pointer events to pass through to the composition iframe, allowing interactive content.

playsinline

boolean

Enables inline playback on mobile devices (iOS). Prevents fullscreen takeover.

disablepictureinpicture

boolean

Disables the picture-in-picture button and functionality.

preload

string

default:"auto"

Hint for how the player should load. Values: "none", "metadata", "auto".

sandbox

string

default:"allow-scripts allow-same-origin"

Sandbox flags for the composition iframe. Controls security restrictions.

canvas-selector

string

default:"canvas"

CSS selector for the canvas element inside the composition to use for rendering and export.

input-props

string

JSON string of input properties to pass to the composition schema. Alternative to setting via JavaScript.

export-format

string

default:"mp4"

Default export format. Values: "mp4", "webm", "png", "jpeg".

export-mode

string

default:"auto"

Export capture mode. Values: "auto", "canvas", "dom". Auto attempts canvas first, falls back to DOM.

export-width

number

Custom width for exported video. Defaults to composition dimensions.

export-height

number

Custom height for exported video. Defaults to composition dimensions.

export-bitrate

number

default:"5000000"

Video bitrate for export in bits per second.

export-filename

string

default:"video"

Default filename (without extension) for exported files.

export-caption-mode

string

Controls caption rendering in exports. Values: "burn" (render into video), "sidecar" (separate file).

media-title

string

Title for Media Session API integration (system media controls).

media-artist

string

Artist name for Media Session API.

media-album

string

Album name for Media Session API.

media-artwork

string

URL to artwork image for Media Session API.

Properties

Playback state

currentTime

number

Current playback position in seconds. Reading returns the current time, writing seeks to that position.

currentFrame

number

Current frame number. Alternative to currentTime for frame-accurate control.

duration

number

Total duration of the composition in seconds.

paused

boolean

Whether playback is currently paused.

ended

boolean

Whether playback has reached the end.

seeking

boolean

Whether a seek operation is in progress.

playbackRate

number

Playback speed multiplier. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed.

fps

number

Frame rate of the composition.

Audio

volume

number

Master volume level from 0.0 (silent) to 1.0 (full volume).

muted

boolean

Whether audio is muted. Independent of volume level.

audioTracks

HeliosAudioTrackList

List of available audio tracks. See audio tracks API.

Video

videoWidth

number

Intrinsic width of the composition video in pixels.

videoHeight

number

Intrinsic height of the composition video in pixels.

videoTracks

HeliosVideoTrackList

List of available video tracks.

Text tracks

textTracks

HeliosTextTrackList

List of text tracks (captions/subtitles). See text tracks API.

Ready state

readyState

number

Current ready state. Values: HAVE_NOTHING (0), HAVE_METADATA (1), HAVE_CURRENT_DATA (2), HAVE_FUTURE_DATA (3), HAVE_ENOUGH_DATA (4).

networkState

number

Current network state. Values: NETWORK_EMPTY (0), NETWORK_IDLE (1), NETWORK_LOADING (2), NETWORK_NO_SOURCE (3).

error

MediaError | null

Most recent error, or null if no error occurred.

Other properties

buffered

TimeRanges

Time ranges that have been buffered. For Helios, this is typically the full duration.

seekable

TimeRanges

Time ranges that can be seeked to. For Helios, this is typically the full duration.

played

TimeRanges

Time ranges that have been played.

currentSrc

string

Current source URL (same as src).

preservesPitch

boolean

Whether audio pitch is preserved during rate changes. Default is true.

defaultPlaybackRate

number

Default playback rate to use when resetting. Default is 1.0.

defaultMuted

boolean

Default muted state (reflects the muted attribute).

Methods

play()

Starts or resumes playback.

await player.play();

Returns: Promise<void> - Resolves when playback starts.

pause()

Pauses playback.

player.pause();

load()

Loads or reloads the composition from the src attribute.

player.load();

fastSeek(time)

Seeks to the specified time. Identical to setting currentTime.

player.fastSeek(10.5); // Seek to 10.5 seconds

Parameters:

time (number) - Time in seconds

canPlayType(type)

Returns whether the player can play the given MIME type. Always returns empty string since Helios only plays compositions.

player.canPlayType('video/mp4'); // Returns ""

Parameters:

type (string) - MIME type to check

Returns: "" | "maybe" | "probably"

requestPictureInPicture()

Requests picture-in-picture mode.

try {
  await player.requestPictureInPicture();
} catch (err) {
  console.error('PiP not supported:', err);
}

Returns: Promise<PictureInPictureWindow>

addTextTrack(kind, label, language)

Adds a new text track to the player.

const track = player.addTextTrack('subtitles', 'English', 'en');
track.mode = 'showing';

Parameters:

kind (string) - Track kind: "subtitles", "captions", "descriptions", etc.
label (string) - Human-readable label
language (string) - BCP 47 language code

Returns: HeliosTextTrack

getDiagnostics()

Returns diagnostic information about the composition and player state.

const diagnostics = await player.getDiagnostics();
console.log(diagnostics);

Returns: Promise<DiagnosticReport>

Events

Playback events

play

Event

Fired when playback starts.

pause

Event

Fired when playback pauses.

ended

Event

Fired when playback reaches the end.

timeupdate

Event

Fired periodically as currentTime updates during playback.

seeking

Event

Fired when a seek operation begins.

seeked

Event

Fired when a seek operation completes.

ratechange

Event

Fired when playbackRate changes.

Loading events

loadstart

Event

Fired when loading begins.

loadedmetadata

Event

Fired when metadata (duration, dimensions) is loaded.

loadeddata

Event

Fired when the first frame is loaded.

canplay

Event

Fired when enough data is available to start playing.

canplaythrough

Event

Fired when playback can likely play through without buffering.

durationchange

Event

Fired when duration changes.

Audio events

volumechange

Event

Fired when volume or muted state changes.

Display events

resize

Event

Fired when the player dimensions change.

enterpictureinpicture

Event

Fired when entering picture-in-picture mode.

leavepictureinpicture

Event

Fired when leaving picture-in-picture mode.

Error events

error

ErrorEvent

Fired when an error occurs.

Event handler properties

All events can be listened to via addEventListener() or by setting the corresponding on* property:

// Using addEventListener
player.addEventListener('play', () => console.log('Playing'));

// Using property
player.onplay = () => console.log('Playing');

Available handler properties: onplay, onpause, onended, ontimeupdate, onseeking, onseeked, onvolumechange, onratechange, ondurationchange, onresize, onloadstart, onloadedmetadata, onloadeddata, oncanplay, oncanplaythrough, onerror, onenterpictureinpicture, onleavepictureinpicture.

CSS custom properties

The player supports extensive theming via CSS custom properties:

helios-player {
  --helios-controls-bg: rgba(0, 0, 0, 0.8);
  --helios-text-color: white;
  --helios-accent-color: #007bff;
  --helios-range-track-color: #555;
  --helios-font-family: 'Inter', sans-serif;
  --helios-caption-scale: 0.05;
  --helios-caption-bg: rgba(0, 0, 0, 0.7);
  --helios-caption-color: white;
  --helios-caption-font-family: sans-serif;
}

--helios-controls-bg

color

default:"rgba(0, 0, 0, 0.6)"

Background color for the controls bar.

--helios-text-color

color

default:"white"

Text and icon color in controls.

--helios-accent-color

color

default:"#007bff"

Accent color for interactive elements and highlights.

--helios-range-track-color

color

default:"#555"

Background color for range sliders.

--helios-font-family

string

default:"sans-serif"

Font family for UI text.

--helios-caption-scale

number

default:"0.05"

Caption font size as a fraction of video height.

--helios-caption-bg

color

default:"rgba(0, 0, 0, 0.7)"

Caption background color.

--helios-caption-color

color

default:"white"

Caption text color.

--helios-caption-font-family

string

default:"sans-serif"

Font family for captions.

CSS parts

The player exposes Shadow DOM parts for advanced styling:

helios-player::part(controls) {
  padding: 16px;
}

helios-player::part(play-pause-button) {
  color: lime;
}

Available parts: iframe, controls, play-pause-button, volume-control, volume-button, volume-slider, scrubber-wrapper, scrubber, time-display, fullscreen-button, pip-button, cc-button, export-button, audio-button, settings-button, poster, poster-image, big-play-button, captions, overlay, markers, tooltip.

Example: Full player setup

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import '@helios-project/player';
  </script>
  <style>
    helios-player {
      width: 100%;
      max-width: 1200px;
      --helios-accent-color: #ff6b6b;
    }
  </style>
</head>
<body>
  <helios-player
    id="player"
    src="./composition.html"
    controls
    poster="./thumbnail.jpg"
    media-title="My Composition"
  ></helios-player>

  <script>
    const player = document.getElementById('player');
    
    // Add event listeners
    player.addEventListener('loadedmetadata', () => {
      console.log('Duration:', player.duration);
      console.log('FPS:', player.fps);
    });
    
    player.addEventListener('play', () => {
      console.log('Playback started');
    });
    
    // Add captions
    const track = player.addTextTrack('subtitles', 'English', 'en');
    track.addCue(new VTTCue(0, 5, 'Hello world'));
    track.mode = 'showing';
    
    // Control playback
    player.play();
  </script>
</body>
</html>

Core

Renderer

Player

CLI

Types

Player element

Basic usage

Attributes

Properties

Playback state

Audio

Video

Text tracks

Ready state

Other properties

Methods

play()

pause()

load()

fastSeek(time)

canPlayType(type)

requestPictureInPicture()

addTextTrack(kind, label, language)

getDiagnostics()

Events

Playback events

Loading events

Audio events

Display events

Error events

Event handler properties

CSS custom properties

CSS parts

Example: Full player setup

Build docs developers (and LLMs) love

Core

Renderer

Player

CLI

Types

​Basic usage

​Attributes

​Properties

​Playback state

​Audio

​Video

​Text tracks

​Ready state

​Other properties

​Methods

​play()

​pause()

​load()

​fastSeek(time)

​canPlayType(type)

​requestPictureInPicture()

​addTextTrack(kind, label, language)

​getDiagnostics()

​Events

​Playback events

​Loading events

​Audio events

​Display events

​Error events

​Event handler properties

​CSS custom properties

​CSS parts

​Example: Full player setup

Build docs developers (and LLMs) love

Basic usage

Attributes

Properties

Playback state

Audio

Video

Text tracks

Ready state

Other properties

Methods

play()

pause()

load()

fastSeek(time)

canPlayType(type)

requestPictureInPicture()

addTextTrack(kind, label, language)

getDiagnostics()

Events

Playback events

Loading events

Audio events

Display events

Error events

Event handler properties

CSS custom properties

CSS parts

Example: Full player setup