NativeHlsVideo

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 { NativeHlsVideo } from '@videojs/react/media/native-hls-video';

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

Props

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

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

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.

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.