# hlsjs-video

HLS video element powered by hls.js for adaptive bitrate streaming

HLS video element powered by [hls.js](https://github.com/video-dev/hls.js/) for adaptive bitrate streaming, with full feature support across every browser. It’s more compatible than the lightweight [HLS video component](https://videojs.org/docs/framework/html/reference/components/hls-video), which is smaller and covers most HLS playback. For browser-native playback, see the [native HLS video component](https://videojs.org/docs/framework/html/reference/components/native-hls-video).

## Import

```bash
pnpm add @videojs/hlsjs-video
```

```ts
import '@videojs/html/media/hlsjs-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/hlsjs-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `audioRenditions` | `AudioRenditionListLike \| undefined` | — | Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `audioTracks` | `AudioTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live. |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; type?: 'application/vnd.apple.mpegurl' \| 'video/mp4'; preferPlayback?: 'mse' \| 'native'; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`preferPlayback`, `engine`). Assigning it derives `src`. Sources are compared structurally, so reassigning an equivalent object is a no-op. Only a change to the engine options (or to the resolved content type) recreates the playback engine. |
| `src` | `string` | `''` | Media source URL. Assigning it replaces the identity half of `source` and leaves `type` and the engine options intact, so changing the URL never disturbs engine configuration. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |
| `targetLiveWindow` | `number` | — | Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate). |
| `videoRenditions` | `VideoRenditionListLike \| undefined` | — | Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `videoTracks` | `VideoTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

### Engine options

#### `source.engine.nativeHls`

When playback falls back to the browser’s own HLS, hls.js isn’t involved and its options don’t apply. This configures that path instead.

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt