Skip to content
FrameworkStyle

MuxVideo

Video element for Mux-hosted HLS streams

Video element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.

Load a source

The source param builds the URL for you from a playback ID, an optional custom domain, and playback params. Playback params are just camelCased Mux playback query params; for example, max_resolution becomes maxResolution.

<MuxVideo
  source={{ 
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    customDomain: 'media.example.com',
    playback: { maxResolution: '1080p' }
  }} 
/>

If for some reason you need a bit more control, you can use the src param with a plain ’ol URL, too:

<MuxVideo
  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
/>

MuxVideo fires a sourcechange event when the source actually changes. Setting the same values again, like a fresh object on a React re-render, doesn’t fire it.

Thumbnails and storyboards

thumbnail and storyboard default to URLs derived from source: the poster image and the storyboard VTT that drives hover previews on the time slider. MuxVideo injects the storyboard <track> automatically, skipping it for live streams. Set either prop to a URL to override the derived one.

Signed playback

For signed playback, put the playback token on source.playback.token. The token replaces every other playback param, so bake modifiers like resolution and time bounds into the token when you sign it.

Thumbnail and storyboard URLs need their own audience-scoped tokens, source.thumbnail.token (aud: 't') and source.storyboard.token (aud: 's'). Without a matching image token, MuxVideo derives no thumbnail or storyboard URL, since an unsigned request would be rejected.

<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    playback: { token: playbackToken },
    thumbnail: { token: thumbnailToken },
    storyboard: { token: storyboardToken },
  }}
/>

Analytics and casting

MuxVideo plays Mux streams. It doesn’t monitor them or cast them — Mux Data and Google Cast are separate components you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:

import { GoogleCast } from '@videojs/react/media/google-cast';
import { MuxData } from '@videojs/react/media/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';

<MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
<MuxData playerSoftwareName="mux-video" />
<GoogleCast />
Mux Data
Metadata, options, and configuration
Google Cast
Receivers, load requests, and session state

Examples

Basic Usage

import { MuxVideo } from '@videojs/react/media/mux-video';

export default function BasicUsage() {
  return (
    <MuxVideo
      className="mux-video"
      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
      autoPlay
      muted
      playsInline
      loop
      crossOrigin="anonymous"
    />
  );
}

API Reference

Props

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

PropTypeDefaultDetails
configHlsMediaConfig{}
preloadPreloadType'metadata'
sourceMuxSource | nullnull
srcstring''
storyboardstring''
streamTypeStreamType'unknown'
thumbnailstring''

Ref

Forwards its ref to the rendered <video>. The ref is an HTMLVideoElement and exposes its complete native property and method API.

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.