Skip to content

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.5.0/media/hlsjs-video.js"></script>

Load a source

src takes an HLS manifest URL.

<hlsjs-video src="https://example.com/playlist.m3u8"></hlsjs-video>

The structured source object says what to play and how to play it: type for a manifest URL without an .m3u8 extension, preferPlayback to choose between hls.js ('mse') and the browser’s own HLS ('native'), the adaptive resolution caps, drm, and engine options. Setting source derives src. Media sources explains each option.

const video = document.querySelector('hlsjs-video')!;
video.source = {
  src: 'https://example.com/manifest',
  type: 'application/vnd.apple.mpegurl',
  preferPlayback: 'mse',
  maxAutoResolution: '1080p',
};

Protected content

source.drm names your license servers, keyed by EME key system id. Name every system you hold a license server for: which one gets negotiated is the browser’s choice.

const video = document.querySelector('hlsjs-video')!;
video.source = {
  src: 'https://example.com/protected.m3u8',
  drm: {
    'com.apple.fps': {
      licenseUrl: 'https://example.com/fairplay',
      serverCertificateUrl: 'https://example.com/fairplay.cer',
    },
    'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
  },
};

hls.js receives every system named here. When the browser’s own HLS plays the stream, only the com.apple.fps entry applies. Media sources covers what each path can license and how to configure hls.js’s DRM directly.

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>

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>

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:

AttributeTypeDefaultDetails
stream-type'on-demand' | 'live' | 'unknown''unknown'

Properties

PropertyTypeDefaultDetails
audioRenditionsAudioRenditionListLike | undefined—
audioTracksAudioTrackListLike | undefined—
contentDataMediaContentData | undefined—
disableRemotePlaybackunknownfalse
engineHls | null—
engineNamestring | undefined—
errorMediaError | null—
isFullscreenboolean—
isPictureInPictureboolean—
liveEdgeStartnumber—
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'
targetLiveWindownumber—
videoRenditionsVideoRenditionListLike | undefined—
videoTracksVideoTrackListLike | undefined—
webkitCurrentPlaybackTargetIsWirelessboolean | undefined—
webkitPresentationModeWebKitPresentationMode | undefined—
webkitSetPresentationModeundefined | function—

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.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayremoveTextTrackrequestFullscreenrequestPictureInPicture

Events

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

Also emits these Video.js-specific events:

EventDescription
sourcechangeFired when source changes, either directly or by resolving a new src. Read source for the new value.
streamtypechangeFired when the detected stream type changes. Read streamType for the new value.
targetlivewindowchangeFired when the target live window changes. Read targetLiveWindow for the new value.

CSS custom properties

VariableDescription
--media-video-border-radiusBorder radius of the video element.
--media-object-fitObject fit for the video.
--media-object-positionObject position for the video.
--media-caption-track-durationDuration of the caption track transition.
--media-caption-track-delayDelay before the caption track transition.
--media-caption-track-yVertical offset of the caption track.