hlsjs-video

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

HLS video element powered by hls.js for adaptive bitrate streaming. It’s the recommended choice for HLS playback: full feature support across every browser. For alternatives, see NativeHlsVideo (browser-native HLS) or HlsVideo (lightweight HLS).

Examples

Basic Usage

import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

export default function BasicUsage() {
  return <HlsJsVideo className="hlsjs-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
}

.hlsjs-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

<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/media/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: autopictureinpictureautoplaycontrolscontrolslistcrossorigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysinlineposterpreloadsrc

These Video.js-specific attributes configure media behavior:

Attribute	Type	Default	Details
`stream-type`	`StreamType`	`'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`	`Target["contentData"] \| undefined`	`—`
Description Read-only.
`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`	`(ErrorLike & 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`	`PreloadType`	`'metadata'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`HlsSource \| null`	`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 — an inline React prop, for instance — is a no-op. Only a change to the engine options (or to the resolved content type) recreates the playback engine.
`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`	`StreamType`	`'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`	`((mode: WebKitPresentationMode) => void) \| undefined`	`—`
Description Read-only.

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

Engine options

`source.engine.hlsJs`

Pass hls.js’s own configuration here. It’s handed to hls.js untouched, so every option in its config reference works, spelled the way hls.js spells it. Media Sources covers how engine options fit into a structured source.

The names and types below come from hls.js’s own type definitions, so they tell you what exists and what shape it takes. hls.js documents what each one does; the descriptions are theirs to write, and most are blank here because its types carry none.

const video = document.querySelector('hlsjs-video');
video.source = {
  src: 'https://example.com/playlist.m3u8',
  engine: { hlsJs: { maxBufferLength: 30, lowLatencyMode: true } },
};

Option	Type	Details
`abrBandWidthFactor`	`number`
`abrBandWidthUpFactor`	`number`
`abrController`	`typeof AbrController`
`abrEwmaDefaultEstimate`	`number`
Description Default bandwidth estimate in bits/s prior to collecting fragment bandwidth samples
`abrEwmaDefaultEstimateMax`	`number`
`abrEwmaFastLive`	`number`
`abrEwmaFastVoD`	`number`
`abrEwmaSlowLive`	`number`
`abrEwmaSlowVoD`	`number`
`abrMaxWithRealBitrate`	`boolean`
`appendErrorMaxRetry`	`number`
`assetPlayerId`	`string`
`audioPreference`	`AudioSelectionOption`
`audioStreamController`	`typeof AudioStreamController`
`audioTrackController`	`typeof AudioTrackController`
`autoStartLoad`	`boolean`
`backBufferLength`	`number`
`bufferController`	`typeof BufferController`
`capLevelController`	`typeof CapLevelController`
`capLevelOnFPSDrop`	`boolean`
`capLevelToPlayerSize`	`boolean`
`captionsTextTrack1Label`	`string`
`captionsTextTrack1LanguageCode`	`string`
`captionsTextTrack2Label`	`string`
`captionsTextTrack2LanguageCode`	`string`
`captionsTextTrack3Label`	`string`
`captionsTextTrack3LanguageCode`	`string`
`captionsTextTrack4Label`	`string`
`captionsTextTrack4LanguageCode`	`string`
`certLoadPolicy`	`LoadPolicy`
`cmcd`	`CMCDControllerConfig`
`cmcdController`	`typeof CMCDController`
`contentSteeringController`	`typeof ContentSteeringController`
`cueHandler`	`CuesInterface`
`debug`	`boolean \| ILogger`
`defaultAudioCodec`	`string`
`detectStallWithCurrentTimeMs`	`number`
`drmSystemOptions`	`DRMSystemOptions \| undefined`
`drmSystems`	`Partial<Record<KeySystems, DRMSystemC...`
Type `Partial<Record<KeySystems, DRMSystemConfiguration>> \| undefined`
`emeController`	`typeof EMEController`
`emeEnabled`	`boolean`
`enableCEA708Captions`	`boolean`
`enableDateRangeMetadataCues`	`boolean`
`enableEmsgKLVMetadata`	`boolean`
`enableEmsgMetadataCues`	`boolean`
`enableID3MetadataCues`	`boolean`
`enableIMSC1`	`boolean`
`enableInterstitialPlayback`	`boolean`
`enableSoftwareAES`	`boolean`
`enableWebVTT`	`boolean`
`enableWorker`	`boolean`
`errorController`	`typeof ErrorController`
`fetchSetup`	`function`
Type `(context: LoaderContext, initParams: any) => Request \| Promise<Request>`
`fLoader`	`FragmentLoaderConstructor`
`forceKeyFrameOnDiscontinuity`	`boolean`
`fpsController`	`typeof FPSController`
`fpsDroppedMonitoringPeriod`	`number`
`fpsDroppedMonitoringThreshold`	`number`
`fragLoadingMaxRetry`	`number`
`fragLoadingMaxRetryTimeout`	`number`
`fragLoadingRetryDelay`	`number`
`fragLoadingTimeOut`	`number`
`fragLoadPolicy`	`LoadPolicy`
`frontBufferFlushThreshold`	`number`
`highBufferWatchdogPeriod`	`number`
`ignoreDevicePixelRatio`	`boolean`
`ignorePlaylistParsingErrors`	`boolean`
`initialLiveManifestSize`	`number`
`interstitialAppendInPlace`	`boolean`
`interstitialAssetListLoadPolicy`	`LoadPolicy`
`interstitialLiveLookAhead`	`number`
`interstitialsController`	`typeof InterstitialsController`
`keyLoadPolicy`	`LoadPolicy`
`levelLoadingMaxRetry`	`number`
`levelLoadingMaxRetryTimeout`	`number`
`levelLoadingRetryDelay`	`number`
`levelLoadingTimeOut`	`number`
`licenseResponseCallback`	`function`
Type `(this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext) => ArrayBuffer`
`licenseXhrSetup`	`function`
Type `(this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext, licenseChallenge: Uint8Array<ArrayBufferLike>) => void \| ... 1 more ... \| Promise<...>`
`liveBackBufferLength`	`number \| null`
`liveDurationInfinity`	`boolean`
`liveMaxLatencyDuration`	`number`
`liveMaxLatencyDurationCount`	`number`
`liveSyncDuration`	`number`
`liveSyncDurationCount`	`number`
`liveSyncMode`	`"buffered" \| "edge"`
`liveSyncOnStallIncrease`	`number`
`loader`	`function`
Type `new (confg: HlsConfig) => Loader<LoaderContext>`
`lowLatencyMode`	`boolean`
`manifestLoadingMaxRetry`	`number`
`manifestLoadingMaxRetryTimeout`	`number`
`manifestLoadingRetryDelay`	`number`
`manifestLoadingTimeOut`	`number`
`manifestLoadPolicy`	`LoadPolicy`
`maxAudioFramesDrift`	`number`
`maxBufferHole`	`number`
`maxBufferLength`	`number`
`maxBufferSize`	`number`
`maxDevicePixelRatio`	`number`
`maxFragLookUpTolerance`	`number`
`maxLiveSyncPlaybackRate`	`number`
`maxLoadingDelay`	`number`
`maxMaxBufferLength`	`number`
`maxStarvationDelay`	`number`
`minAutoBitrate`	`number`
`nudgeMaxRetry`	`number`
`nudgeOffset`	`number`
`nudgeOnVideoHole`	`boolean`
`playlistLoadPolicy`	`LoadPolicy`
`pLoader`	`PlaylistLoaderConstructor`
`preferManagedMediaSource`	`boolean`
`preserveManualLevelOnError`	`boolean`
`primarySessionId`	`string`
`progressive`	`boolean`
`renderTextTracksNatively`	`boolean`
`requestMediaKeySystemAccessFunc`	`MediaKeyFunc \| null`
`requireKeySystemAccessOnStart`	`boolean`
`startFragPrefetch`	`boolean`
`startLevel`	`number`
`startOnSegmentBoundary`	`boolean`
`startPosition`	`number`
`steeringManifestLoadPolicy`	`LoadPolicy`
`stretchShortVideoTrack`	`boolean`
`subtitlePreference`	`SubtitleSelectionOption`
`subtitleStreamController`	`typeof SubtitleStreamController`
`subtitleTrackController`	`typeof SubtitleTrackController`
`testBandwidth`	`boolean`
`timelineController`	`typeof TimelineController`
`timelineOffset`	`number`
`useMediaCapabilities`	`boolean`
`videoPreference`	`VideoSelectionOption`
`widevineLicenseUrl`	`string`
`workerPath`	`string \| null`
`xhrSetup`	`function`
Type `(xhr: XMLHttpRequest, url: string) => void \| Promise<void>`

`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	Details
`--media-video-border-radius`
Description Border radius of the video element.
`--media-object-fit`
Description Object fit for the video.
`--media-object-position`
Description Object position for the video.
`--media-caption-track-duration`
Description Duration of the caption track transition.
`--media-caption-track-delay`
Description Delay before the caption track transition.
`--media-caption-track-y`
Description Vertical offset of the caption track.