Skip to content

ReferenceMedia

MuxVideo

Video element for Mux-hosted HLS streams

Video element for playing Mux-hosted HLS streams.

Import

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

Choose a playback engine

The Mux video component can play your video through one of two engines: SPF or hls.js. An engine is the code that downloads the stream and feeds it to the browser. You choose one by its import path.

SPF is Video.js’s own engine, built for the streams Mux delivers. It’s a fraction of hls.js’s size, and it will become the default in an upcoming release. hls.js is mature, widely used, and plays almost any HLS stream. The default import uses hls.js today.

Import Engine Choose it when
.../media/mux-video/spf SPF None of the cases under “When to use hls.js” applies to you.
.../media/mux-video hls.js today, SPF soon You want the recommended engine, and you’re fine with it changing in a future release.
.../media/mux-video/hls-js hls.js One of the cases under “When to use hls.js” applies to you.
import { MuxVideo } from '@videojs/react/media/mux-video/spf';

All three imports give you a MuxVideo component with the same basic API.

When to use SPF

  • You want a smaller page. SPF is about a quarter of hls.js’s size, which matters most with several players on a page or on slower connections.
  • You use AirPlay. Starting and stopping AirPlay works smoothly on SPF. hls.js can get into a bad state when you do either.

When to use hls.js

SPF is still under development. Use hls.js if any of these applies to you:

  • You stream live without slates. A slate is the image Mux shows while a broadcaster reconnects. Without one, playback stops at the point where the broadcaster dropped and came back, in the live stream and in the recording Mux makes of it.
  • You rely on detailed Mux Data. With SPF, Mux Data doesn’t receive playback errors, or detail like quality switches and download speed.
  • You need low latency. SPF plays low-latency live streams with the delay of an ordinary live stream.
  • You set quality limits on the player. SPF doesn’t let you set the lowest or highest quality the player picks on its own, or stop it from matching quality to the player’s size.
  • You support older iPhones. SPF needs iOS 17.1 or later.

SPF limitations in detail

Live streams without slates. When an encoder disconnects, Mux keeps the live stream open for its reconnect_window. With a slate, Mux fills that time with the slate image, so the stream stays continuous. Without one, no media arrives until the encoder reconnects, and Mux marks the break with EXT-X-DISCONTINUITY. The asset Mux records from the stream keeps the same discontinuity. SPF doesn’t handle discontinuities yet, in CMAF or MPEG-TS, so playback breaks there. To avoid it, set reconnect_window above 0 and, for standard-latency streams, use_slate_for_standard_latency to true. Handle live stream disconnects covers the settings.

Mux Data. Mux Data plugs into hls.js to collect engine-level data. It has no such integration for SPF, so it monitors the media element alone. Views, startup time, and rebuffering still come through. Errors SPF raises itself, such as a manifest that fails to load or content it can’t play, don’t, and neither do rendition switches or request timing and throughput.

Low-Latency HLS. SPF skips the partial segments (EXT-X-PART) that make LL-HLS low latency and loads whole segments instead. The stream plays as standard-latency live, at the distance from the live edge that the playlist’s HOLD-BACK sets. SPF logs a console warning when this happens.

Rendition limits. maxAutoResolution, minAutoResolution, and capRenditionToPlayerSize are hls.js options, so the SPF flavor doesn’t take them. SPF always caps the rendition to the player’s size. To limit renditions on either engine, use source.playback.maxResolution or source.playback.minResolution, which Mux applies to the playlist itself.

Browsers without Media Source Extensions. SPF plays through MediaSource, or ManagedMediaSource on iPhone, and has no fallback to the browser’s own HLS playback. iPhone Safari before iOS 17.1 has neither, so SPF can’t play there. The hls.js flavor falls back to native HLS.

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 ignores the same source object when it is assigned again. A new object fires sourcechange even when its values are equal, although an equivalent playback source does not reload.

Posters and storyboards

The Mux video component derives a poster image and a storyboard from the playback ID. source.poster and source.storyboard configure the generated URLs.

When the Mux video component is inside a player, it supplies the poster for the skin to display. Set poster on the player when you want to use your own image instead.

A generated poster becomes available after MuxVideo mounts. Pass poster to the player when the image must appear in server-rendered HTML.

The Mux video component injects the derived storyboard <track> automatically and removes it when the media detects a live stream. Configure the derived URLs through the source object:

<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    poster: { time: 2, width: 1280 },
    storyboard: { format: 'webp' },
  }}
/>

The storyboard lives on a Mux domain, so the Mux video component has to be CORS-enabled for that cross-origin <track> to load at all. The thumbnail component then fetches the sprite sheets its cues point at the same way:

<MuxVideo
  source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }}
  crossOrigin="anonymous"
/>

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.

Signed playback needs a separate token for each image URL. Put the thumbnail token (aud: 't') at source.poster.token and the storyboard token (aud: 's') at source.storyboard.token. If either token is missing or has the wrong audience, the Mux video component does not generate the corresponding URL.

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

Protected content

For DRM-protected playback, put the DRM license token on source.drm.token. The Mux video component derives the FairPlay, Widevine, and PlayReady license servers from it. DRM playback is always signed, so a playback.token belongs alongside it.

<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    playback: { token: playbackToken },
    drm: { token: drmToken },
  }}
/>

Media sources covers mixing Mux’s license servers with your own.

Analytics and casting

The Mux video component plays Mux streams. It doesn’t monitor them or cast them — Mux Data and Google Cast are separate extensions 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:

Install both extensions before using the example below:

pnpm add @videojs/mux-data @videojs/google-cast
import { createPlayer } from '@videojs/react';
import { GoogleCast } from '@videojs/react/extensions/google-cast';
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 function MuxPlayer() {
  return (
    <Player>
      <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
      <MuxData playerSoftwareName="mux-video" />
      <GoogleCast />
    </Player>
  );
}

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
disableRemotePlaybackunknownfalse
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'

Engine options

source.engine.nativeHls

Options passed under source.engine.nativeHls.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Refs

ref

Forwards to the rendered <video>, an HTMLVideoElement with its complete native property and method API.

const ref = useRef<HTMLVideoElement>(null);

<MuxVideo ref={ref} />

mediaRef

Receives the MuxVideoAdapter that drives the <video>, the same object useMedia() returns inside a player. It forwards the native media methods, properties, and events, such as play() and currentTime, and exposes the playback engine through engine. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use ref.

import type { MuxVideoAdapter } from '@videojs/mux-video';

const mediaRef = useRef<MuxVideoAdapter>(null);

<MuxVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();

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.