# 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 the [hls.js video component](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) instead.

## Import

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

## Load a source

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

```tsx
<NativeHlsVideo src="https://example.com/playlist.m3u8" />
```

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](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess).

```tsx
<NativeHlsVideo
  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](https://videojs.org/docs/framework/react/guides/media-sources#drm-protected-sources) covers DRM in more depth.

## Examples

### Basic Usage

**App.tsx**

```tsx
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 />;
}
```

**App.css**

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

## API Reference

### Props

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: NativeHlsEngineConfig } \| null` | `null` | 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. |
| `src` | `string` | `''` | 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'` | 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](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

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

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | 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. |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<NativeHlsVideo ref={ref} />
```

#### `mediaRef`

Receives the `NativeHlsAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { NativeHlsAdapter } from '@videojs/native-hls-video';

const mediaRef = useRef<NativeHlsAdapter>(null);

<NativeHlsVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt
