ReferenceMedia

hls-video

Lightweight HLS video element with minimal bundle size

The lightweight HLS video element, optimized for minimal bundle size. The hls.js video component is the larger, more compatible alternative.

Import

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

Or load it from the CDN:

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

Examples

Basic Usage

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

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

import '@videojs/html/ui/container';
import '@videojs/html/media/hls-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 the engine sends them, the same way the browser does under native playback. Any other value, or no attribute, leaves requests at the platform default and sends no cross-origin cookies.

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.

<hls-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hls-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 The source's stream type — `'live'`, `'on-demand'`, or `'unknown'` until a media playlist has been parsed. Setting a non-`'unknown'` value pins a user override (detection stops updating it); setting `'unknown'` reverts to the engine's detected value.

Properties

Property	Type	Default
`alternativeMediaSuggestion`	`string \| undefined`	—
Description Read-only. A complete sentence naming the Media to reach for when this one can't play a source — `Try the hls.js-backed Mux media instead: import the hls-js flavor in place of the spf one.` Appended to the copy this adapter surfaces, and to the notices it logs. Name the flavor, not an import path: a Media is reached through several packages, each with its own counterpart. Empty here: `hls-video` has no better-equipped sibling to point at. A Media that does (a Mux Video built on this engine, whose hls.js-backed counterpart plays MPEG-TS and DRM) overrides this static, and its copy gains the second sentence with no other change.
`contentData`	`MediaContentData \| undefined`	—
Description Read-only.
`crossOrigin`	`'anonymous' \| 'use-credentials' \| null`	`null`
`disableRemotePlayback`	`boolean`	`false`
`engine`	`object`	—
Description Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. Type `{ state: { [K in keyof S]-?: Signal<S[K]> }; context: { [K in keyof C]-?: Signal<C[K]> }; destroy(): Promise<void> }`
`error`	`object`	—
Description Read-only. The current fatal error, or `null`. Only fatal conditions appear here — the engine reports non-fatal ones too (they stay in `engine.state.errors`), and promoting them would tell a consumer playback had failed when it hadn't. Resets per source. Fires `'error'` when set. Type `{ code: number; message: string; data?: unknown } \| null`
`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 — playback at `currentTime >= liveEdgeStart` counts as "at the live edge" (the same target the engine's `seekToLiveEdge` seeks to: window end − HOLD-BACK). `NaN` when the stream isn't live or nothing is resolved yet. Derived at read time from the engine's live window — no change event; re-read on `timeupdate`/`progress` (as the store's live feature does).
`preload`	`'' \| 'none' \| 'metadata' \| 'auto'`	`''`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`object`	`null`
Description Structured source: the manifest URL plus what a URL cannot carry, which today is the license servers for protected content. Setting it derives `src`. Assigning the same object back costs nothing — changing anything takes a new one. Type `{ src?: string; type?: string; drm?: Partial<Record<string, DrmSystemConfig>> } \| null`
`src`	`string`	`''`
`streamType`	`'on-demand' \| 'live' \| 'unknown'`	`'unknown'`
Description The source's stream type — `'live'`, `'on-demand'`, or `'unknown'` until a media playlist has been parsed. Setting a non-`'unknown'` value pins a user override (detection stops updating it); setting `'unknown'` reverts to the engine's detected value.
`targetLiveWindow`	`number`	—
Description Read-only. The target live window: `NaN` for on-demand (or unknown), `0` for standard sliding-window live, `Infinity` for DVR (`#EXT-X-PLAYLIST-TYPE:EVENT`). Fires `targetlivewindowchange` on change.
`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: autoplaybufferedcontrolscurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedisablePictureInPicturedurationendedloopmutedpausedplaybackRateplayedplaysInlineposterreadyStateremoteseekableseekingtextTrackstitlevideoHeightvideoWidthvolume

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayrequestFullscreenrequestPictureInPicture

Events

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

Also emits these Video.js-specific events:

Event	Description
`error`	Fired when a fatal condition is reported. Read `error` for it.
`sourcechange`	Fired when `source` changes. 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.