Skip to content

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.6.0/media/hls-video.js"></script>

Load a source

src takes an HLS manifest URL.

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

The structured source object carries what a URL can’t: drm for protected content. Setting source derives src.

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('hls-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' },
  },
};

FairPlay needs a serverCertificateUrl unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. Media sources covers DRM in more depth.

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>

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>

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
contentDataMediaContentData | undefined—
crossOrigin'anonymous' | 'use-credentials' | nullnull
disableRemotePlaybackbooleanfalse
errorobject—
isFullscreenboolean—
isPictureInPictureboolean—
liveEdgeStartnumber—
preload'' | 'none' | 'metadata' | 'auto'''
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'
targetLiveWindownumber—
webkitCurrentPlaybackTargetIsWirelessboolean | undefined—
webkitPresentationModeWebKitPresentationMode | undefined—
webkitSetPresentationModeundefined | function—

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

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayremoveTextTrackrequestFullscreenrequestPictureInPicture

Events

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

Also emits these Video.js-specific events:

EventDescription
errorFired when a fatal condition is reported. Read error for it.
sourcechangeFired when source changes. 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.