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.

Import

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

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

MuxVideo derives a poster image and a storyboard from the playback ID. source.poster and source.storyboard configure the generated URLs.

When MuxVideo 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.

MuxVideo 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 MuxVideo has to be CORS-enabled for that cross-origin <track> to load at all. Thumbnail 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, MuxVideo does not generate the corresponding URL.

<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    playback: { token: playbackToken },
    poster: { token: posterToken },
    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 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:

Add @videojs/mux-data to the installation before using the telemetry component below:

pnpm add @videojs/mux-data
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'
source{ drm?: MuxDrmParams } | nullnull
srcstring''
streamTypeMediaStreamType"unknown"

Engine options

source.engine.hlsJs

Options passed under source.engine.hlsJs.

OptionTypeDetails
abrBandWidthFactornumber | undefined
abrBandWidthUpFactornumber | undefined
abrControllertypeof AbrController | undefined
abrEwmaDefaultEstimatenumber | undefined
abrEwmaDefaultEstimateMaxnumber | undefined
abrEwmaFastLivenumber | undefined
abrEwmaFastVoDnumber | undefined
abrEwmaSlowLivenumber | undefined
abrEwmaSlowVoDnumber | undefined
abrMaxWithRealBitrateboolean | undefined
appendErrorMaxRetrynumber | undefined
assetPlayerIdstring | undefined
audioPreferenceAudioSelectionOption | undefined
audioStreamControllertypeof AudioStreamController | undefined
audioTrackControllertypeof AudioTrackController | undefined
autoStartLoadboolean | undefined
backBufferLengthnumber | undefined
bufferControllertypeof BufferController | undefined
capLevelControllertypeof CapLevelController | undefined
capLevelOnFPSDropboolean | undefined
capLevelToPlayerSizeboolean | undefined
captionsTextTrack1Labelstring | undefined
captionsTextTrack1LanguageCodestring | undefined
captionsTextTrack2Labelstring | undefined
captionsTextTrack2LanguageCodestring | undefined
captionsTextTrack3Labelstring | undefined
captionsTextTrack3LanguageCodestring | undefined
captionsTextTrack4Labelstring | undefined
captionsTextTrack4LanguageCodestring | undefined
certLoadPolicyLoadPolicy | undefined
cmcdCMCDControllerConfig | undefined
cmcdControllertypeof CMCDController | undefined
contentSteeringControllertypeof ContentSteeringController | un...
cueHandlerCuesInterface | undefined
debugboolean | ILogger | undefined
defaultAudioCodecstring | undefined
detectStallWithCurrentTimeMsnumber | undefined
drmSystemOptionsDRMSystemOptions | undefined
drmSystemsDRMSystemsConfiguration | undefined
emeControllertypeof EMEController | undefined
emeEnabledboolean | undefined
enableCEA708Captionsboolean | undefined
enableDateRangeMetadataCuesboolean | undefined
enableEmsgKLVMetadataboolean | undefined
enableEmsgMetadataCuesboolean | undefined
enableID3MetadataCuesboolean | undefined
enableIMSC1boolean | undefined
enableInterstitialPlaybackboolean | undefined
enableSoftwareAESboolean | undefined
enableWebVTTboolean | undefined
enableWorkerboolean | undefined
errorControllertypeof ErrorController | undefined
fetchSetupRequest) | undefined | function
fLoaderFragmentLoaderConstructor | undefined
forceKeyFrameOnDiscontinuityboolean | undefined
fpsControllertypeof FPSController | undefined
fpsDroppedMonitoringPeriodnumber | undefined
fpsDroppedMonitoringThresholdnumber | undefined
fragLoadingMaxRetrynumber | undefined
fragLoadingMaxRetryTimeoutnumber | undefined
fragLoadingRetryDelaynumber | undefined
fragLoadingTimeOutnumber | undefined
fragLoadPolicyLoadPolicy | undefined
frontBufferFlushThresholdnumber | undefined
highBufferWatchdogPeriodnumber | undefined
ignoreDevicePixelRatioboolean | undefined
ignorePlaylistParsingErrorsboolean | undefined
initialLiveManifestSizenumber | undefined
interstitialAppendInPlaceboolean | undefined
interstitialAssetListLoadPolicyLoadPolicy | undefined
interstitialLiveLookAheadnumber | undefined
interstitialsControllertypeof InterstitialsController | unde...
keyLoadPolicyLoadPolicy | undefined
levelLoadingMaxRetrynumber | undefined
levelLoadingMaxRetryTimeoutnumber | undefined
levelLoadingRetryDelaynumber | undefined
levelLoadingTimeOutnumber | undefined
licenseResponseCallbackundefined | function
licenseXhrSetupUint8Array | Promise<Uint8Array | void>) | undefined | function
liveBackBufferLengthnumber | null | undefined
liveDurationInfinityboolean | undefined
liveMaxLatencyDurationnumber | undefined
liveMaxLatencyDurationCountnumber | undefined
liveSyncDurationnumber | undefined
liveSyncDurationCountnumber | undefined
liveSyncMode'edge' | 'buffered' | undefined
liveSyncOnStallIncreasenumber | undefined
loaderobject
lowLatencyModeboolean | undefined
manifestLoadingMaxRetrynumber | undefined
manifestLoadingMaxRetryTimeoutnumber | undefined
manifestLoadingRetryDelaynumber | undefined
manifestLoadingTimeOutnumber | undefined
manifestLoadPolicyLoadPolicy | undefined
maxAudioFramesDriftnumber | undefined
maxBufferHolenumber | undefined
maxBufferLengthnumber | undefined
maxBufferSizenumber | undefined
maxDevicePixelRationumber | undefined
maxFragLookUpTolerancenumber | undefined
maxLiveSyncPlaybackRatenumber | undefined
maxLoadingDelaynumber | undefined
maxMaxBufferLengthnumber | undefined
maxStarvationDelaynumber | undefined
minAutoBitratenumber | undefined
nudgeMaxRetrynumber | undefined
nudgeOffsetnumber | undefined
nudgeOnVideoHoleboolean | undefined
playlistLoadPolicyLoadPolicy | undefined
pLoaderPlaylistLoaderConstructor | undefined
preferManagedMediaSourceboolean | undefined
preserveManualLevelOnErrorboolean | undefined
primarySessionIdstring | undefined
progressiveboolean | undefined
renderTextTracksNativelyboolean | undefined
requestMediaKeySystemAccessFuncMediaKeyFunc | null | undefined
requireKeySystemAccessOnStartboolean | undefined
startFragPrefetchboolean | undefined
startLevelnumber | undefined
startOnSegmentBoundaryboolean | undefined
startPositionnumber | undefined
steeringManifestLoadPolicyLoadPolicy | undefined
stretchShortVideoTrackboolean | undefined
subtitlePreferenceSubtitleSelectionOption | undefined
subtitleStreamControllertypeof SubtitleStreamController | und...
subtitleTrackControllertypeof SubtitleTrackController | unde...
testBandwidthboolean | undefined
timelineControllertypeof TimelineController | undefined
timelineOffsetnumber | undefined
useMediaCapabilitiesboolean | undefined
videoPreferenceVideoSelectionOption | undefined
widevineLicenseUrlstring | undefined
workerPathstring | null | undefined
xhrSetupvoid) | undefined | function

source.engine.nativeHls

Options passed under source.engine.nativeHls.

OptionTypeDetails
drmSystemsDrmSystemsConfig | undefined

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.