Skip to content

GuidePlayback

Monitor playback with Mux Data

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

Mux Data measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data extension to a player and it monitors whichever media that player is playing:

Install the extension alongside the framework façade. The MuxVideo example also installs the Mux playback adapter:

pnpm add @videojs/react @videojs/mux-video @videojs/mux-data
import { Container, createPlayer } from '@videojs/react';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function App() {
  return (
    <Player>
      <Container>
        <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
        <MuxData />
      </Container>
    </Player>
  );
}

That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it anywhere inside the player.

Set the environment key

Mux Data needs to know which environment a view belongs to. For Mux-hosted playback, you do not need to set an environment key. The extension 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:

For the hls.js example, also install @videojs/hlsjs-video. Replace the media and extension in the primary example with <MonitoredHlsVideo />:

pnpm add @videojs/hlsjs-video
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { MuxData } from '@videojs/react/extensions/mux-data';

function MonitoredHlsVideo() {
  return (
    <>
      <HlsJsVideo src="https://example.com/stream.m3u8" />
      <MuxData envKey="YOUR_ENV_KEY" />
    </>
  );
}

An explicit envKey overrides the environment Mux infers from the playback ID. 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 MuxVideo, HlsJsVideo, DashVideo, and the rest alike.

How much the extension reports depends on the engine playing the stream. All media report the playback metrics available from the media element. The extension also recognizes hls.js and 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 without a JavaScript engine, like native HLS or a plain <video>, report only the element-level metrics.

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 to label views with your own titles, viewer IDs, and custom dimensions. metadata takes an object. In HTML, set it as a JavaScript property:

<MuxData metadata={{ video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' }} />

Configuration

The MuxData reference 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

Guides