Player element

Complete API reference for the <helios-player> web component

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>