ReferenceMedia

hlsjs-video

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

HLS video element powered by hls.js for adaptive bitrate streaming, with full feature support across every browser. It’s more compatible than the lightweight HLS video component, which is smaller and covers most HLS playback. For browser-native playback, see the native HLS video component.

Import

pnpm add @videojs/hlsjs-video

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

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/hlsjs-video.js"></script>

Examples

Basic Usage

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

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

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

A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard crossorigin="use-credentials" on the element and hls.js sends them (withCredentials on its XHR loader, credentials: 'include' on its fetch loader), the same way the browser does under native playback. Any other value, or no attribute, leaves hls.js’s default and sends no cross-origin cookies. An xhrSetup or fetchSetup you pass through source.engine.hlsJs still runs, after this, on the same request.

The CDN must answer with Access-Control-Allow-Credentials: true and a specific Access-Control-Allow-Origin, not *, or the browser refuses the credentialed response.

<hlsjs-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hlsjs-video>

API Reference

Attributes

Forwards these standard media attributes to the internal <video>. See the MDN media element reference: autopictureinpictureautoplaycontrolscontrolslistcrossorigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysinlineposterpreloadsrc

These Video.js-specific attributes configure media behavior:

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

Properties

Property	Type	Default
`audioRenditions`	`AudioRenditionListLike \| undefined`	—
Description Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`audioTracks`	`AudioTrackListLike \| undefined`	—
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`contentData`	`MediaContentData \| undefined`	—
Description Read-only.
`disableRemotePlayback`	`unknown`	`false`
Description Whether remote playback (AirPlay, Google Cast) is disabled for this media.
`engine`	`Hls \| null`	—
Description 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`	—
Description Read-only.
`isFullscreen`	`boolean`	—
Description Read-only.
`isPictureInPicture`	`boolean`	—
Description Read-only.
`liveEdgeStart`	`number`	—
Description 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'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`object`	`null`
Description 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. Type `{ src?: string; type?: 'application/vnd.apple.mpegurl' \| 'video/mp4' \| string & {}; preferPlayback?: 'mse' \| 'native' \| string & {}; 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`
`src`	`string`	`''`
Description 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'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
`targetLiveWindow`	`number`	—
Description 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`	—
Description Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`videoTracks`	`VideoTrackListLike \| undefined`	—
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`webkitCurrentPlaybackTargetIsWireless`	`boolean \| undefined`	—
Description Read-only.
`webkitPresentationMode`	`WebKitPresentationMode \| undefined`	—
Description Read-only.
`webkitSetPresentationMode`	`undefined \| function`	—
Description Read-only. Type `((mode: WebKitPresentationMode) => void) \| undefined`

Also exposes these properties from the native media API. See HTMLVideoElement for details: autoplaybufferedcontrolscrossOrigincurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedisablePictureInPicturedurationendedloopmutedpausedplaybackRateplayedplaysInlineposterreadyStateremoteseekableseekingtextTrackstitlevideoHeightvideoWidthvolume

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	Details
`drmSystems`	`Partial<Record<KeySystem, DrmSystemCo...`
Description 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. Type `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined`

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayrequestFullscreenrequestPictureInPicture

Events

Re-dispatches these standard media events from the internal media element: abortaddtrackcanplaycanplaythroughchangecontentdatachangedurationchangeemptiedendedenterpictureinpictureerrorleavepictureinpictureloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangeremovetrackresizeseekedseekingstalledsuspendtimeupdatevolumechangewaiting

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.