Skip to content
FrameworkStyle

Migrate from Mux Player

Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin

Mux Player combines HLS playback, UI, analytics, captions, remote playback, and keyboard shortcuts in one element. Video.js v10 composes those responsibilities from a player, media component, skin, and optional extensions.

This guide moves a working Mux Player embed to those pieces, then maps the settings and APIs you are most likely to need next.

Before you migrate

A few minutes of auditing tells you which sections of this guide apply to you:

  • List the Mux Player attributes and props you set. Each one appears in a mapping table below; the list is your migration checklist.
  • Grep your codebase for mux-player selectors. CSS rules and querySelector calls that reach into the element — mux-player::part(…), mux-player [role="slider"], player.shadowRoot — will silently stop matching after the swap. Plan to restyle with the skin’s custom properties or rebuild against Video.js components.
  • Find your event listeners and imperative calls (play(), currentTime, addChapters). Media APIs move to the media element; the rest is mapped under Drive playback.
  • Note your theme and CSS variables. Two skins replace Mux Player’s five themes, and --accent-color and friends have new names.
  • Check your catalog for DRM or TS-packaged assets. They decide which of the two Mux media flavors you can use; see Which Mux media should you use?.

Three pieces instead of one

Mux Player packs three jobs into a single element. Video.js splits them up, so it helps to learn the names before you write any code.

The player is the outer element. It holds state, hands that state to everything inside it, and draws nothing itself. Which state it holds depends on the features it’s built from.

The media is the thing that plays the video. The Mux media is the one you want: it knows what a playback ID is and how to talk to Mux. Swap it for another media component and the rest of your player keeps working.

The skin is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. Skins are pre-built arrangements of smaller components, and you can use one as-is, restyle it, or take it apart.

So a Mux Player embed becomes a player wrapped around a skin wrapped around a media:

<VideoPlayer>
  <VideoSkin>
    <MuxVideo />
  </VideoSkin>
</VideoPlayer>

Everything else in this guide is about which of those three a given Mux Player attribute now belongs to.

Your first player

Here’s a typical Mux Player embed. A playback ID, a title and viewer ID for analytics, and a poster pulled from two seconds in.

import MuxPlayer from '@mux/mux-player-react';

export function MyPlayer() {
  return (
    <MuxPlayer
      playbackId="EcHgOK9coz5K…"
      metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }}
      thumbnailTime={2}
    />
  );
}

@videojs/react gives you real React components rather than one component wrapping a custom element.

npm install @videojs/react @videojs/mux-video @videojs/mux-data

Start with the general-purpose @videojs/react/video preset, then add the Mux media and analytics components:

'use client';

import '@videojs/react/video/skin.css';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';

export function MyPlayer() {
  return (
    <VideoPlayer title="Test VOD">
      <VideoSkin style={{ aspectRatio: '16 / 9' }}>
        <MuxVideo
          source={{ playbackId: 'EcHgOK9coz5K…', poster: { time: 2 } }}
          playsInline
          crossOrigin="anonymous"
        />
        <MuxData
          playerSoftwareName="my-app"
          metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }}
        />
      </VideoSkin>
    </VideoPlayer>
  );
}

VideoPlayer is the piece that owns the state. To read that state, the preset ships a matching usePlayer hook.

The 'use client' directive is there because the player owns browser state.

A few things worth calling out:

  • The skin has no size of its own, so the examples give it one with an inline aspect-ratio. Any styling that sizes the skin works the same way, whether that’s a class of yours or a Tailwind utility like aspect-video. See Move your layout styles.
  • MuxVideo supplies the poster. It builds the image URL from the playback ID, and the skin displays it automatically. The example keeps the frame from two seconds in by configuring MuxVideo. Set poster on the player only when you want to use your own URL.
  • You didn’t add a storyboard track, and you get hover previews. The Mux media adds and maintains the thumbnail track itself, and removes it for live streams, where storyboards don’t exist.
  • Analytics needs no environment key. Mux resolves the environment from the playback ID. See Mux Data.
  • Chromecast is opt-in. Follow Cast to AirPlay and Chromecast when you want it; leave the extension out when you don’t.

Move your layout styles

Mux Player was one visible, measurable element. Video.js separates player state from the visible surface.

If you use VideoSkin, put width, height, aspect ratio, positioning, and DOM measurements on VideoSkin. The skin.css import shown above makes the media, controls, poster, and overlays fill and layer within it. VideoPlayer renders no DOM element of its own.

If you leave out VideoSkin to build your own UI, add a Container. Style and measure that element, and put overlays inside it:

import { Container } from '@videojs/react';

<VideoPlayer>
  <Container style={{ position: 'relative', width: '100%', aspectRatio: '16/9' }}>
    <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />
    <MyOverlay />
  </Container>
</VideoPlayer>

Mux settings live in a source object

Mux Player has an attribute for every Mux stream parameter: max-resolution, asset-start-time, custom-domain, and a dozen more. Video.js collects them into a single source object that describes what to play and how.

{
  playbackId: 'EcHgOK9coz5K…',
  playback: { maxResolution: '1080p', assetStartTime: 10, assetEndTime: 30 },
  poster: { time: 2, width: 1280 },
}

The groups map to the three URLs Mux serves. playback modifies the video stream, poster modifies the still image, and storyboard modifies the hover-preview track. Video.js builds all three URLs and converts your camel-case keys to the snake_case query parameters Mux expects, so assetStartTime goes out as asset_start_time.

Pass it as the source prop:

<MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />

You can also skip the object and pass src a full Mux URL. The component parses it back into a source, query parameters included:

<MuxVideo src="https://stream.mux.com/EcHgOK9coz5K….m3u8?max_resolution=1080p" />

There’s no playbackId prop of its own; it lives on source.

Here’s where each Mux Player attribute lands:

Mux Player Video.js v10
playback-id source.playbackId
custom-domain source.customDomain
max-resolution, min-resolution source.playback.maxResolution, .minResolution
rendition-order source.playback.renditionOrder
asset-start-time, asset-end-time source.playback.assetStartTime, .assetEndTime
program-start-time, program-end-time source.playback.programStartTime, .programEndTime
default-subtitles-lang source.playback.defaultSubtitlesLang
playback-token source.playback.token
thumbnail-token, storyboard-token source.poster.token, source.storyboard.token
drm-token source.drm.token
thumbnail-time source.poster.time
poster size, crop, rotation, format source.poster.width, .height, .fitMode, .rotate, .ext

Signed playback behaves the way it does in Mux Player: a token replaces every other parameter in its group, so caps and clipping have to be baked into the token itself.

Analytics moves to its own element

Mux Player’s analytics settings become attributes, properties, or props on the Mux Data extension, placed inside the player.

Mux Player Video.js v10
metadata={…} the metadata prop
envKey envKey, rarely needed for Mux-hosted content
disableCookies disableCookies
beaconCollectionDomain beaconCollectionDomain
playerSoftwareName, playerSoftwareVersion playerSoftwareName, playerSoftwareVersion
debug debug
disableTracking omit the component

Your metadata keys don’t change. They’re the same snake_case names Mux Data has always taken, so the values port across untouched.

Titles and posters

Mux Player used the same title for analytics and on-screen display. Video.js separates them.

For analytics, use metadata.video_title on the Mux Data extension.

For display, use title on the player.

The title reaches player state, but the packaged skins don’t place it in their layouts. Add the Title component as a child of a packaged skin, or place it in an ejected or custom layout, when you want viewers to see it:

import { Title } from '@videojs/react';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';

<VideoPlayer title="Test VOD">
  <VideoSkin>
    <Title />
  </VideoSkin>
</VideoPlayer>

MuxVideo supplies a poster from the playback ID, and source.poster controls the generated image. The skin displays it automatically. Pass poster to the player when you want to use your own URL:

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

<VideoPlayer poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2">
  <VideoSkin
    renderPoster={
      <img
        alt=""
        style={{ background: "url('data:image/webp;base64,…') center / contain no-repeat" }}
      />
    }
  >
    <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />
  </VideoSkin>
</VideoPlayer>

renderPoster customizes the poster image, so its background can show Mux Player’s placeholder while the real poster loads.

Mux serves the poster from its thumbnail endpoint, and source.poster configures that URL: thumbnail-time is source.poster.time, and the size, crop, rotation, and format options are width, height, fitMode, rotate, and ext beside it. Video.js converts those camel-case keys to the snake_case query parameters Mux expects. See Add a poster and loading placeholder for more examples or the Poster reference for the component itself.

Customize your player

Mux Player gives you attributes and documented CSS variables. Past that, you’re stuck. Video.js gives you three levels, and you should try them in order.

Level 1: pick a skin

Two are packaged. The default skin is a modern, frosted look. The minimal skin is closer to a classic control bar. Both bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See Skins.

Level 2: restyle it

Set custom properties on the skin. The common case is a brand color:

Give the skin a class you own:

<VideoSkin className="my-player-skin">...</VideoSkin>
.my-player-skin {
  --media-accent-color: rebeccapurple;
}

--media-accent-color reaches the sliders, the active buttons, and the accent surfaces. Video.js derives a readable text color to sit on top of it; override that with --media-accent-text-color if you’d rather choose. --media-border-radius rounds the player, and --media-scale-unit scales the whole control bar at once. Customize skins has the full list.

The skins use a different visual design, so you may not need to replace Mux Player’s primaryColor and secondaryColor directly. Start with --media-accent-color. Restyle individual surfaces, or eject the skin, only when you need a closer palette match.

Level 3: eject

For changes to controls, layout, or interactions, eject the skin into your project. Its components and styles become files you own. Customize skins covers the setup and available skins.

This is the level that per-control tweaks need, and it’s a genuine step up in effort from a Mux Player attribute. forward-seek-offset="30" was one character. In Video.js, the skins bake their seek step into their keyboard shortcuts and gestures, so changing it means editing those lines:

<Hotkey keys="ArrowRight" action="seekStep" value={30} />
<Hotkey keys="ArrowLeft" action="seekStep" value={-30} />
<Gesture type="doubletap" action="seekStep" value={30} region="right" />

While you’re in there: neither packaged video skin includes skip buttons. Mux Player’s themes show them, so if your users expect them, add a seek button, which takes seconds and defaults to 30.

Removing a control is removing a line. That’s the trade you get for the extra setup.

Read player state

Standard media event props port directly to MuxVideo: onPlay, onTimeUpdate, onEnded, and onError work on the rendered video element. Read player-store state through the preset’s usePlayer hook, typed to that preset’s features:

import { usePlayer } from '@videojs/react/video';

function Elapsed() {
  const currentTime = usePlayer((state) => state.currentTime);
  return <span>{currentTime}</span>;
}

Every feature has a selector (selectPlayback, selectTime, selectVolume, selectQuality, selectLive, selectTextTrack, and so on) for when you want a whole slice rather than one value.

The pair works exactly like React Context: Player is the Provider, and usePlayer is its useContext-style consumer, so it only works inside Player. If a component that needs player state renders outside Player, lift Player above it the way you’d lift any Provider. It renders no DOM, so wrapping a page or layout in it changes nothing visually and puts the store in reach of everything inside.

Use a ref for imperative browser media APIs or for custom events that do not have React event props, such as sourcechange. The ref value is the rendered HTMLVideoElement.

Drive playback

Mux Player Video.js v10
player.play(), player.pause() the player’s play, pause, togglePaused, or media.play(), media.pause()
player.currentTime = 10 the player’s seek(10), or media.currentTime = 10
player.volume, player.muted the player’s setVolume, toggleMuted, or media.volume, media.muted
player.playbackRate the player’s setPlaybackRate, or media.playbackRate
player.requestFullscreen() the player’s requestFullscreen, exitFullscreen, toggleFullscreen
player.addChapters([…]) a <track kind="chapters">, covered below

Control everything through the player: “the player’s” entries are store actions, reached the same way you read state above. Setting a standard media property directly works too — player state derives from the native media events, so the UI stays in sync either way.

Which Mux media should you use?

You can skip this section until you hit one of the two problems in it.

MuxVideo comes in two flavors, backed by two different playback engines, and the import path chooses between them. Start with the default. The tradeoff: the /spf flavor is smaller and the /hls-js flavor is more compatible:

Import Engine When
.../media/mux-video hls.js The default. Start here.
.../media/mux-video/spf SPF You want a much smaller bundle and neither problem below applies.
.../media/mux-video/hls-js hls.js You want to pin hls.js, and reach its instance and settings.

SPF is Video.js’s own playback engine, and it’s the reason v10 can be as small as it is. It doesn’t do two things hls.js does:

  • TS-packaged media. Some Mux assets are packaged as TS rather than CMAF. If any of your catalog is, stay on the default.
  • DRM. SPF doesn’t license protected content.

Both flavors register the same element and take the same source, so moving between them is an import change and nothing else. Don’t import both into one build; only one registration wins.

The default doesn’t promise which engine it uses, which is what leaves it free to change. Import /hls-js if your app depends on hls.js being the one. Otherwise take the default: it plays everything.

The Mux audio component follows the same three paths, and pairs with the audio player and audio skins.

Live streams

Unlike Mux Player, you’ll have to pick a live preset yourself; it won’t switch automatically for you.

import '@videojs/react/live-video/skin.css';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
import { MuxVideo } from '@videojs/react/media/mux-video';

<LiveVideoPlayer>
  <LiveVideoSkin>
    <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} playsInline />
  </LiveVideoSkin>
</LiveVideoPlayer>

You get targetLiveWindow and liveEdgeStart in player state, plus a live button that jumps to the live edge. The live preset doesn’t include streamType state and doesn’t force a source to be live. The Mux media detects the manifest: targetLiveWindow is NaN for an on-demand or unknown source, 0 for a sliding live window, and Infinity for a live event with playback history. See the live feature.

The live composition is narrower than the video one on purpose: it leaves out quality, audio-track, and playback-rate state. A live skin’s settings menu therefore holds captions and nothing else. If you need one of the omitted features on a live player, build your own player from a feature list rather than taking the preset’s.

Use createPlayer to create a Player component and matching usePlayer hook.

Add your own jump-to-live button

The live skin already includes a live button. If you build your own controls, use that same component and style it to match your app. It keeps track of whether playback is live and returns viewers to the newest available point in the stream.

import { LiveButton } from '@videojs/react';

<LiveButton className="station-live-button">On air</LiveButton>

Do not rebuild this behavior from duration or set currentTime to Infinity.

Troubleshoot live playback

An on-demand video shows live controls

Video.js does not replace the preset after reading the HLS playlist. Render the video preset for on-demand content and the live preset for live content. If the same part of your app handles both, choose the preset from application or content metadata before rendering. If only the manifest can tell you, use a custom player with the stream type feature and choose the controls from that state.

selectStreamType returns undefined

The live preset does not include the stream type feature. Add streamTypeFeature to a custom player when you need streamType in player state.

The HLS media object also reads 'live' or 'on-demand' from the playlist. In React, get that object with useMedia. In HTML, read streamType from <mux-video>.

A live stream has a finite duration

The browser may report Infinity for live playback, but the player’s time feature reports the end of the available video. That number stays finite and moves forward with the stream.

Do not use duration to decide whether a source is live. Read streamType, or check that targetLiveWindow is not NaN.

targetLiveWindow does not match the rewind time

Despite its name, targetLiveWindow does not report a number of seconds. It describes the kind of live stream:

Value Meaning
0 A sliding live window
Infinity A live event with playback history
NaN On-demand or not known yet

To find the times a viewer can seek to, read buffer.seekable. It contains [start, end] pairs. The first start is the oldest available time, and the last end is the newest. Both move forward on a sliding live stream.

liveEdgeStart is the playback time where the player starts treating the viewer as live. The live button seeks to the last end in buffer.seekable, which may be later than liveEdgeStart.

The settings menu

On a video player, the settings menu appears on its own when there’s something to put in it:

What Component Notes
Quality Quality radio group Lets a viewer pick the video quality. To set the highest available quality instead, use source.playback.maxResolution.
Audio tracks Audio track radio group For multi-language audio.
Captions Captions radio group Rendered by the browser.
Speed Playback rate radio group The rates are a fixed set — 0.2, 0.5, 0.7, 1, 1.2, 1.5, 1.7, 2 — and you can’t choose your own yet (#1404).

Caption styling is limited to the positioning custom properties the skins expose. There’s no equivalent of a text-track settings dialog.

Chapters and cue points

Chapters are content, not an API call. Add a chapters track inside your media and the skins segment the time slider and show the chapter title on hover:

<MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }}>
  <track kind="chapters" src="/chapters.vtt" default />
</MuxVideo>

There’s no addChapters(). If you were building that VTT on the fly, you’ll still need to, but you point the player at it instead of passing an array (#1268).

The time slider marks the segment containing the current playback time with data-active, so you can style the active segment. The player still has no active-chapter state, chapterchange event, or menu for jumping between chapters (#1873). If UI outside the time slider needs the current chapter, derive it from currentTime and the read-only chaptersCues array. Cue points aren’t implemented at all (#1442).

Signed playback and DRM

Signed playback works today. Follow Mux’s secure video playback guide to create a signing key and generate these tokens on your server. Each token is a parameter in its own group, and Video.js checks each one’s audience before building a URL, so a token in the wrong slot produces no URL rather than a request Mux would reject:

{
  playbackId: 'EcHgOK9coz5K…',
  playback: { token: '…' },   // audience: v
  poster: { token: '…' },     // audience: t
  storyboard: { token: '…' }, // audience: s
}

Signed playback needs its own poster token even when MuxVideo would otherwise derive the poster from the playback ID. Put Mux’s thumbnail token at source.poster.token. If it is missing or has the wrong audience, MuxVideo cannot build a poster URL.

Neither player refreshes tokens. Mux Player at least notices an expired one and shows a friendly message; Video.js doesn’t surface that yet (#1432).

DRM works on the default Mux media and on native HLS. Hand it a license token and Video.js derives the FairPlay, Widevine, and PlayReady license servers from it, along with the FairPlay application certificate:

{
  playbackId: 'EcHgOK9coz5K…',
  playback: { token: '…' },
  drm: { token: '…' }, // audience: d
}

DRM playback is always signed, so drm.token needs a playback.token beside it. For content Mux doesn’t license, name license servers yourself, keyed by key system; yours win over the derived ones key by key.

The SPF flavor doesn’t license DRM (#1776), which is one of the two reasons to stay on the default import.

Access the media and playback engine

Mux Player Video.js v10
media.nativeEl ref.current from a ref on the media component
the Video.js media object useMedia() inside the player
the hls.js instance the media object’s .engine, reached through useMedia, on the hls.js-backed flavor
prefer-playback source.preferPlayback, or pick native HLS outright

source.preferPlayback is the closest mapping: set it to 'native' and the Mux media hands playback to the browser’s own HLS support instead of building an MSE pipeline, which is what prefer-playback="native" did.

The media component’s React ref is the native HTMLVideoElement; it has no .target or .host. Use the player context for the Video.js media object:

import { useMedia } from '@videojs/react';

function EngineAccess() {
  const media = useMedia();
  const engine = media && 'engine' in media ? media.engine : null;

  // `engine` is the active hls.js instance for the `/hls-js` flavor.
  return null;
}

Import the /hls-js flavor when your app depends on that engine. The default flavor deliberately doesn’t promise which engine it uses.

Program Date Time has no convenience surface: no getStartDate(), no currentPdt. The player exposes liveEdgeStart and targetLiveWindow; for PDT itself, reach into the engine.

Known gaps

Ordered roughly by how many migrations they’ll touch.

  • Two skins, against Mux Player’s five themes, and no runtime theme switch. That’s a deliberate trade, fewer looks you can eject, but it’s a real difference if you shipped theme="classic".
  • Lazy loading (loading="viewport|page") has no equivalent.
  • The controls auto-hide delay isn’t configurable, and there’s no disabled state for the controls (#1728).
  • Nothing persists between sessions: volume, captions language, speed, quality. That’s out of scope for GA (#944). Default subtitle language is tracked at #1423, though Mux users can set source.playback.defaultSubtitlesLang and let the HLS playlist decide.
  • Smaller conveniences without homes yet: debug mode (#1406) and autoplay with a muted fallback (#1039). Unmuting from zero volume already restores a sensible level, so Mux Player’s smart-unmute behavior carries over.

See also