# Monitor playback with Mux Data

Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player

[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](https://videojs.org/docs/framework/html/guides/architecture) to a player and it monitors whichever media that player is playing:

Install the extension alongside the framework façade. The `<mux-video>` example also installs the Mux playback adapter:

```bash
pnpm add @videojs/html @videojs/mux-video @videojs/mux-data
```

**index.html**

```html
<video-player>
  <media-container>
    <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" playsinline></mux-video>
    <mux-data></mux-data>
  </media-container>
</video-player>
```

Register the `<mux-data>` element by importing `@videojs/html/extensions/mux-data`.

That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it inside the player, as a sibling of the media element.

> **Note**
>
> Mux Data is opt-in. No media element monitors playback on its own, Mux ones included, so nothing is measured and no beacons are sent until you add the extension.

## Set the environment key

Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.

Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):

```html
<hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
<mux-data env-key="YOUR_ENV_KEY"></mux-data>
```

An explicit key always wins, so set one to send Mux-hosted views to a specific environment.

## How it works

The extension attaches to the media the player is using, not to a specific element type, so it monitors [`<mux-video>`](https://videojs.org/docs/framework/html/reference/components/mux-video), [`<hlsjs-video>`](https://videojs.org/docs/framework/html/reference/components/hlsjs-video), [`<dash-video>`](https://videojs.org/docs/framework/html/reference/components/dash-video), and the rest alike.

How much it reports depends on the engine playing the stream. Every media gets the playback metrics the media element itself can tell us. On top of that, the component recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media with no JavaScript engine, like native HLS or a plain `<video>`, report the element-level metrics alone.

The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.

## Describe the view

Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:

```ts
const muxData = document.querySelector('mux-data');
muxData.metadata = { video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' };
```

## Configuration

The [`<mux-data>` reference](https://videojs.org/docs/framework/html/reference/components/mux-data) lists every option: the metadata and software fields above, plus the beacon domain, cookie, debug, and SDK settings. Most options update the current view in place; changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, ending the current view and starting a new one.

## Related pages

### Components

- [mux-data](https://videojs.org/docs/framework/html/reference/components/mux-data): Options for the Mux Data extension that monitors playback quality
- [mux-video](https://videojs.org/docs/framework/html/reference/components/mux-video): Video element for Mux-hosted HLS streams
- [mux-audio](https://videojs.org/docs/framework/html/reference/components/mux-audio): Audio element for Mux-hosted HLS streams

### Guides

- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/html/guides/casting): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

---

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