# hlsMetadataTrack

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

## Import

```ts
import { hlsMetadataTrack } from '@videojs/html';
```

`hlsMetadataTrack` is a [track definition](https://videojs.org/docs/framework/html/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/html/reference/api/feature-text-cues) reads the track like any other metadata track.

hls.js plays streams in [`HlsJsVideo`](https://videojs.org/docs/framework/html/reference/components/hlsjs-video) and the media built on it, such as [`MuxVideo`](https://videojs.org/docs/framework/html/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

**id3.ts**

```ts
import { getActiveTextCues, hlsMetadataTrack } from '@videojs/html';

const player = document.querySelector('video-player')!;

player.store.subscribe(() => {
  for (const cue of getActiveTextCues(player.store, hlsMetadataTrack)) {
    if (cue.type === 'org.id3' && cue.value?.key === 'TXXX') console.log(cue.value.info, cue.value.data);
  }
});
```

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

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt