# hlsMetadataTrack

A track definition for the ID3 and EXT-X-DATERANGE metadata hls.js publishes

## Import

```tsx
import { hlsMetadataTrack } from '@videojs/react';
```

`hlsMetadataTrack` is a [track definition](https://videojs.org/docs/framework/react/reference/api/define-text-track) for `{ kind: 'metadata', label: 'id3' }`, the track hls.js publishes timed metadata on. Its cues are typed as `HlsMetadataCue`. The [text cues feature](https://videojs.org/docs/framework/react/reference/api/feature-text-cues) reads the track like any other metadata track.

hls.js plays streams in [`HlsJsVideo`](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) and the media built on it, such as [`MuxVideo`](https://videojs.org/docs/framework/react/reference/components/mux-video), when they play through Media Source Extensions. Where the browser plays HLS natively, as Safari does, in-band metadata arrives as `DataCue`s on the browser’s own metadata tracks instead; read those with a `{ kind: 'metadata' }` filter.

## Cues

Each cue carries one ID3 frame or one `EXT-X-DATERANGE` attribute. Its `type` tells which, and narrows `value`:

| `type` | Source | `value` |
| --- | --- | --- |
| `'org.id3'` | An ID3 frame in the stream’s segments, or carried in an `emsg` box. hls.js types the second `https://aomedia.org/emsg/ID3`; the player reads both as `org.id3`. | `Id3Frame`: the frame id as `key`, such as `TXXX` or `PRIV`, its description or owner as `info`, and its `data`. |
| `'com.apple.quicktime.HLS'` | An `EXT-X-DATERANGE` tag in the playlist. | `HlsDateRangeAttribute`: the attribute name as `key`, such as `CLASS` or `X-AD-ID`, and its `data`. |

A date range’s cues span the range, from its start to its end.

## Usage

**AdBadge.tsx**

```tsx
import { hlsMetadataTrack, useActiveTextCues } from '@videojs/react';

function AdBadge() {
  const cues = useActiveTextCues(hlsMetadataTrack);
  const inAd = cues.some((cue) => cue.type === 'com.apple.quicktime.HLS' && cue.value?.key === 'X-AD-ID');

  return inAd ? <span className="ad-badge">Ad</span> : null;
}
```

## Exports

| Export | Description |
| --- | --- |
| `HlsMetadataCue` | A metadata cue from hls.js, typed by its `type`. |
| `Id3Frame` | An ID3 frame: `key`, `info`, and `data`. |
| `HlsDateRangeAttribute` | One `EXT-X-DATERANGE` attribute: `key` and `data`. |

---

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