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 HlsJsVideo 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.0.0-beta.32/media/native-hls-video.js"></script>

Examples

Basic Usage

import { NativeHlsVideo } from '@videojs/react/media/native-hls-video';

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

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

<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`	`MediaStreamType`	`"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`	`{ src?: string; drm?: DrmSystemsConfig; engine?: NativeHlsEngineConfig } \| null`	`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 — an inline React prop, for instance — neither reloads nor disturbs key exchange. Use `src` or `load()` to reload what is already playing. Unlike `HlsJsAdapter`, this does not announce a `sourcechange`. It is also the delegate `HlsJsAdapter` plays native sources through, and every event it dispatches is re-dispatched there — which already announces its own.
`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. This is the imperative half of the API, and what `HlsJsAdapter` loads its native delegate through.
`streamType`	`MediaStreamType`	`"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`	`((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.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.

<NativeHlsVideo
  source={{
    src: 'https://example.com/playlist.m3u8',
    engine: {
      nativeHls: {
        drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
      },
    },
  }}
/>

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`	`DrmSystemsConfig \| undefined`
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.

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