ReferenceMedia

native-hls-video

HLS video element using the browser's built-in HLS support

HLS video element that relies on the browser’s native HLS support. Works on Safari and other browsers with built-in HLS playback. For cross-browser HLS support, use the hls.js video component instead.

Import

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

Or load it from the CDN:

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

Load a source

src takes an HLS manifest URL, which the browser plays with its own HLS support.

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

The structured source object adds drm and engine options to the URL. Setting source derives src.

Protected content

source.drm names your license servers, keyed by EME key system id.

const video = document.querySelector('native-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' },
  },
};

The browser’s own HLS licenses FairPlay only, so the com.apple.fps entry is the one this component uses. Media sources covers DRM in more depth.

Examples

Basic Usage

<media-container class="media-container">
  <native-hls-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></native-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/native-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 Current stream type (`'on-demand'` / `'live'` / `'unknown'`).

Properties

Property	Type	Default
`contentData`	`MediaContentData \| undefined`	—
Description Read-only.
`engine`	`null`	—
Description Read-only. Underlying playback engine — always `null`. Native HLS has no JS engine; the browser handles playback directly.
`error`	`MediaError \| null`	—
Description Read-only.
`isFullscreen`	`boolean`	—
Description Read-only.
`isPictureInPicture`	`boolean`	—
Description Read-only.
`liveEdgeStart`	`number`	—
Description Read-only. Playback time where the live edge begins. Calculated from the newest available time and the playlist's live-edge offset. `NaN` when the stream is not live or the offset is unavailable.
`preload`	`MediaPreloadType`	`'metadata'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`object`	`null`
Description Structured source: what to play (`src`) plus how to play it (`engine.nativeHls`). Assigning it derives `src`. Only a new URL reaches the element, so reassigning an equivalent source neither reloads nor disturbs key exchange. Use `src` or `load()` to reload what is already playing. Changing this source does not emit `sourcechange`. When the hls.js media component uses native HLS playback, it emits its own `sourcechange` and forwards the native playback events. Type `{ src?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: NativeHlsEngineConfig } \| null`
`src`	`string`	`''`
Description Media source URL. Assigning it replaces the identity half of `source` and leaves `engine` intact, so changing the URL never disturbs key exchange. Like the element's own `src`, assigning it always loads — including the URL already playing.
`streamType`	`'on-demand' \| 'live' \| 'unknown'`	`'unknown'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
`targetLiveWindow`	`number`	—
Description Read-only. Describes the kind of live window available. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown. This value is not a duration.
`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: autoplaybufferedcontrolscrossOrigincurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedisablePictureInPicturedisableRemotePlaybackdurationendedloopmutedpausedplaybackRateplayedplaysInlineposterreadyStateremoteseekableseekingtextTrackstitlevideoHeightvideoWidthvolume

Engine options

`source.engine.nativeHls`

This element hands playback to the browser, so there’s no JavaScript engine to configure. This carries the one thing native playback still needs from you. Media Sources covers how engine options fit into a structured source.

const video = document.querySelector('native-hls-video');
video.source = {
  src: 'https://example.com/playlist.m3u8',
  engine: {
    nativeHls: {
      drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
    },
  },
};

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: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayremoveTextTrackrequestFullscreenrequestPictureInPicture

Events

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

Also emits these Video.js-specific events:

Event	Description
`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.