HlsJsVideo

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

Props

Accepts the standard React props for a native <video>, plus these Video.js-specific props:

Prop	Type	Default
`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'`).

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.

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

Ref

Forwards its ref to the rendered <video>. The ref is an HTMLVideoElement and exposes its complete native property and method API.

Events

Handle standard media events with React event props such as onPlay and onTimeUpdate. For native events without a React prop, attach a listener through the ref with addEventListener.