> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/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

**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.

```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

**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:

```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;
}
```

**--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:

```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>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.