> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```html theme={null}
<helios-player
  src="https://example.com/composition.html"
  controls
  autoplay
  loop
></helios-player>
```

```javascript theme={null}
const player = document.querySelector('helios-player');
player.play();
player.currentTime = 5.0;
```

## Attributes

<ParamField path="src" type="string">
  URL to the Helios composition HTML file. The composition will be loaded in an iframe.
</ParamField>

<ParamField path="controls" type="boolean">
  Shows playback controls including play/pause, scrubber, volume, fullscreen, and export buttons.
</ParamField>

<ParamField path="autoplay" type="boolean">
  Automatically starts playback when the composition loads. Follows browser autoplay policies.
</ParamField>

<ParamField path="loop" type="boolean">
  Restarts playback from the beginning when the composition ends.
</ParamField>

<ParamField path="muted" type="boolean">
  Mutes all audio output. Can be toggled at runtime via the `muted` property.
</ParamField>

<ParamField path="poster" type="string">
  URL to a poster image displayed before the first play. Shown with a large play button overlay.
</ParamField>

<ParamField path="width" type="number">
  Width of the player in pixels. Also accessible via the `width` property.
</ParamField>

<ParamField path="height" type="number">
  Height of the player in pixels. Also accessible via the `height` property.
</ParamField>

<ParamField path="interactive" type="boolean">
  Enables pointer events to pass through to the composition iframe, allowing interactive content.
</ParamField>

<ParamField path="playsinline" type="boolean">
  Enables inline playback on mobile devices (iOS). Prevents fullscreen takeover.
</ParamField>

<ParamField path="disablepictureinpicture" type="boolean">
  Disables the picture-in-picture button and functionality.
</ParamField>

<ParamField path="preload" type="string" default="auto">
  Hint for how the player should load. Values: `"none"`, `"metadata"`, `"auto"`.
</ParamField>

<ParamField path="sandbox" type="string" default="allow-scripts allow-same-origin">
  Sandbox flags for the composition iframe. Controls security restrictions.
</ParamField>

<ParamField path="canvas-selector" type="string" default="canvas">
  CSS selector for the canvas element inside the composition to use for rendering and export.
</ParamField>

<ParamField path="input-props" type="string">
  JSON string of input properties to pass to the composition schema. Alternative to setting via JavaScript.
</ParamField>

<ParamField path="export-format" type="string" default="mp4">
  Default export format. Values: `"mp4"`, `"webm"`, `"png"`, `"jpeg"`.
</ParamField>

<ParamField path="export-mode" type="string" default="auto">
  Export capture mode. Values: `"auto"`, `"canvas"`, `"dom"`. Auto attempts canvas first, falls back to DOM.
</ParamField>

<ParamField path="export-width" type="number">
  Custom width for exported video. Defaults to composition dimensions.
</ParamField>

<ParamField path="export-height" type="number">
  Custom height for exported video. Defaults to composition dimensions.
</ParamField>

<ParamField path="export-bitrate" type="number" default="5000000">
  Video bitrate for export in bits per second.
</ParamField>

<ParamField path="export-filename" type="string" default="video">
  Default filename (without extension) for exported files.
</ParamField>

<ParamField path="export-caption-mode" type="string">
  Controls caption rendering in exports. Values: `"burn"` (render into video), `"sidecar"` (separate file).
</ParamField>

<ParamField path="media-title" type="string">
  Title for Media Session API integration (system media controls).
</ParamField>

<ParamField path="media-artist" type="string">
  Artist name for Media Session API.
</ParamField>

<ParamField path="media-album" type="string">
  Album name for Media Session API.
</ParamField>

<ParamField path="media-artwork" type="string">
  URL to artwork image for Media Session API.
</ParamField>

## Properties

### Playback state

<ParamField path="currentTime" type="number">
  Current playback position in seconds. Reading returns the current time, writing seeks to that position.
</ParamField>

<ParamField path="currentFrame" type="number">
  Current frame number. Alternative to `currentTime` for frame-accurate control.
</ParamField>

<ParamField path="duration" type="number" readonly>
  Total duration of the composition in seconds.
</ParamField>

<ParamField path="paused" type="boolean" readonly>
  Whether playback is currently paused.
</ParamField>

<ParamField path="ended" type="boolean" readonly>
  Whether playback has reached the end.
</ParamField>

<ParamField path="seeking" type="boolean" readonly>
  Whether a seek operation is in progress.
</ParamField>

<ParamField path="playbackRate" type="number">
  Playback speed multiplier. `1.0` is normal speed, `2.0` is double speed, `0.5` is half speed.
</ParamField>

<ParamField path="fps" type="number" readonly>
  Frame rate of the composition.
</ParamField>

### Audio

<ParamField path="volume" type="number">
  Master volume level from `0.0` (silent) to `1.0` (full volume).
</ParamField>

<ParamField path="muted" type="boolean">
  Whether audio is muted. Independent of volume level.
</ParamField>

<ParamField path="audioTracks" type="HeliosAudioTrackList" readonly>
  List of available audio tracks. See audio tracks API.
</ParamField>

### Video

<ParamField path="videoWidth" type="number" readonly>
  Intrinsic width of the composition video in pixels.
</ParamField>

<ParamField path="videoHeight" type="number" readonly>
  Intrinsic height of the composition video in pixels.
</ParamField>

<ParamField path="videoTracks" type="HeliosVideoTrackList" readonly>
  List of available video tracks.
</ParamField>

### Text tracks

<ParamField path="textTracks" type="HeliosTextTrackList" readonly>
  List of text tracks (captions/subtitles). See text tracks API.
</ParamField>

### Ready state

<ParamField path="readyState" type="number" readonly>
  Current ready state. Values: `HAVE_NOTHING` (0), `HAVE_METADATA` (1), `HAVE_CURRENT_DATA` (2), `HAVE_FUTURE_DATA` (3), `HAVE_ENOUGH_DATA` (4).
</ParamField>

<ParamField path="networkState" type="number" readonly>
  Current network state. Values: `NETWORK_EMPTY` (0), `NETWORK_IDLE` (1), `NETWORK_LOADING` (2), `NETWORK_NO_SOURCE` (3).
</ParamField>

<ParamField path="error" type="MediaError | null" readonly>
  Most recent error, or null if no error occurred.
</ParamField>

### Other properties

<ParamField path="buffered" type="TimeRanges" readonly>
  Time ranges that have been buffered. For Helios, this is typically the full duration.
</ParamField>

<ParamField path="seekable" type="TimeRanges" readonly>
  Time ranges that can be seeked to. For Helios, this is typically the full duration.
</ParamField>

<ParamField path="played" type="TimeRanges" readonly>
  Time ranges that have been played.
</ParamField>

<ParamField path="currentSrc" type="string" readonly>
  Current source URL (same as `src`).
</ParamField>

<ParamField path="preservesPitch" type="boolean">
  Whether audio pitch is preserved during rate changes. Default is `true`.
</ParamField>

<ParamField path="defaultPlaybackRate" type="number">
  Default playback rate to use when resetting. Default is `1.0`.
</ParamField>

<ParamField path="defaultMuted" type="boolean">
  Default muted state (reflects the `muted` attribute).
</ParamField>

## Methods

### play()

Starts or resumes playback.

```javascript theme={null}
await player.play();
```

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

### pause()

Pauses playback.

```javascript theme={null}
player.pause();
```

### load()

Loads or reloads the composition from the `src` attribute.

```javascript theme={null}
player.load();
```

### fastSeek(time)

Seeks to the specified time. Identical to setting `currentTime`.

```javascript theme={null}
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.

```javascript theme={null}
player.canPlayType('video/mp4'); // Returns ""
```

**Parameters:**

* `type` (string) - MIME type to check

**Returns:** `"" | "maybe" | "probably"`

### requestPictureInPicture()

Requests picture-in-picture mode.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
const diagnostics = await player.getDiagnostics();
console.log(diagnostics);
```

**Returns:** `Promise<DiagnosticReport>`

## Events

### Playback events

<ParamField path="play" type="Event">
  Fired when playback starts.
</ParamField>

<ParamField path="pause" type="Event">
  Fired when playback pauses.
</ParamField>

<ParamField path="ended" type="Event">
  Fired when playback reaches the end.
</ParamField>

<ParamField path="timeupdate" type="Event">
  Fired periodically as `currentTime` updates during playback.
</ParamField>

<ParamField path="seeking" type="Event">
  Fired when a seek operation begins.
</ParamField>

<ParamField path="seeked" type="Event">
  Fired when a seek operation completes.
</ParamField>

<ParamField path="ratechange" type="Event">
  Fired when `playbackRate` changes.
</ParamField>

### Loading events

<ParamField path="loadstart" type="Event">
  Fired when loading begins.
</ParamField>

<ParamField path="loadedmetadata" type="Event">
  Fired when metadata (duration, dimensions) is loaded.
</ParamField>

<ParamField path="loadeddata" type="Event">
  Fired when the first frame is loaded.
</ParamField>

<ParamField path="canplay" type="Event">
  Fired when enough data is available to start playing.
</ParamField>

<ParamField path="canplaythrough" type="Event">
  Fired when playback can likely play through without buffering.
</ParamField>

<ParamField path="durationchange" type="Event">
  Fired when duration changes.
</ParamField>

### Audio events

<ParamField path="volumechange" type="Event">
  Fired when volume or muted state changes.
</ParamField>

### Display events

<ParamField path="resize" type="Event">
  Fired when the player dimensions change.
</ParamField>

<ParamField path="enterpictureinpicture" type="Event">
  Fired when entering picture-in-picture mode.
</ParamField>

<ParamField path="leavepictureinpicture" type="Event">
  Fired when leaving picture-in-picture mode.
</ParamField>

### Error events

<ParamField path="error" type="ErrorEvent">
  Fired when an error occurs.
</ParamField>

## Event handler properties

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

```javascript theme={null}
// 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:

```css theme={null}
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;
}
```

<ParamField path="--helios-controls-bg" type="color" default="rgba(0, 0, 0, 0.6)">
  Background color for the controls bar.
</ParamField>

<ParamField path="--helios-text-color" type="color" default="white">
  Text and icon color in controls.
</ParamField>

<ParamField path="--helios-accent-color" type="color" default="#007bff">
  Accent color for interactive elements and highlights.
</ParamField>

<ParamField path="--helios-range-track-color" type="color" default="#555">
  Background color for range sliders.
</ParamField>

<ParamField path="--helios-font-family" type="string" default="sans-serif">
  Font family for UI text.
</ParamField>

<ParamField path="--helios-caption-scale" type="number" default="0.05">
  Caption font size as a fraction of video height.
</ParamField>

<ParamField path="--helios-caption-bg" type="color" default="rgba(0, 0, 0, 0.7)">
  Caption background color.
</ParamField>

<ParamField path="--helios-caption-color" type="color" default="white">
  Caption text color.
</ParamField>

<ParamField path="--helios-caption-font-family" type="string" default="sans-serif">
  Font family for captions.
</ParamField>

## CSS parts

The player exposes Shadow DOM parts for advanced styling:

```css theme={null}
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

```html theme={null}
<!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>
```