MuxVideo

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

Import

pnpm add @videojs/mux-video

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

Load a source

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

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

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.

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 },
  }}
/>

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"
    />
  );
}

.mux-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

{ type?: 'application/vnd.apple.mpegurl' | 'video/mp4'; preferPlayback?: 'mse' | 'native'; maxAutoResolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } | null

Partial<Record<KeySystem, DrmSystemConfig>> | undefined