Migrate from Mux Player

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:

<video-player>
  <video-skin>
    <mux-video></mux-video>
  </video-skin>
</video-player>

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

<script src="https://cdn.jsdelivr.net/npm/@mux/mux-player" defer></script>

<mux-player
  playback-id="EcHgOK9coz5K…"
  metadata-video-title="Test VOD"
  metadata-viewer-user-id="user-id-007"
  thumbnail-time="2"
></mux-player>

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/video.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/media/mux-video.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/extensions/mux-data.js"></script>

<video-player content-title="Test VOD">
  <video-skin style="aspect-ratio: 16 / 9">
    <mux-video
      src="https://stream.mux.com/EcHgOK9coz5K….m3u8"
      poster-time="2"
      playsinline
      crossorigin="anonymous"
    ></mux-video>
    <mux-data player-software-name="my-app"></mux-data>
  </video-skin>
</video-player>

<script type="module">
  document.querySelector('mux-data').metadata = {
    video_title: 'Test VOD',
    viewer_user_id: 'user-id-007',
  };
</script>

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

import '@videojs/html/video/player';
import '@videojs/html/video/skin';
import '@videojs/html/media/mux-video';
import '@videojs/html/extensions/mux-data';

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

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

'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>
  );
}

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.

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

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

<video-player>
  <media-container class="player-surface">
    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
    <my-overlay></my-overlay>
  </media-container>
</video-player>

.player-surface {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}

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.

document.querySelector('mux-video')!.source = { playbackId: 'EcHgOK9coz5K…' };

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

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

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

Here’s where each Mux Player attribute lands:

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.

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.

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 '@videojs/html/ui/title';

<video-player content-title="Test VOD">
  <video-skin>
    <media-title></media-title>
  </video-skin>
</video-player>

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:

<video-player poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2">
  <video-skin>
    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
    <img
      slot="poster"
      alt=""
      style="background: url('data:image/webp;base64,…') center / contain no-repeat"
    />
  </video-skin>
</video-player>

<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>

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:

/* Mux Player */
mux-player {
  --accent-color: rebeccapurple;
}

/* Video.js v10 */
video-skin {
  --media-accent-color: rebeccapurple;
}

<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:

<media-hotkey keys="ArrowRight" action="seekStep" value="30"></media-hotkey>
<media-hotkey keys="ArrowLeft" action="seekStep" value="-30"></media-hotkey>
<media-gesture type="doubletap" action="seekStep" value="30" region="right"></media-gesture>

<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

import { PlayerController, playerContext, ReactiveElement, selectTime } from '@videojs/html';

class MyElapsed extends ReactiveElement {
  #time = new PlayerController(this, playerContext, selectTime);
}

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

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

Drive playback

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:

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.

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/live-video.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/media/mux-video.js"></script>

<live-video-player>
  <live-video-skin>
    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
  </live-video-skin>
</live-video-player>

import '@videojs/html/live-video/player';
import '@videojs/html/live-video/skin';
import '@videojs/html/media/mux-video';

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.

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.

<script type="module">
  import '@videojs/html/ui/live-button';
</script>

<media-live-button class="station-live-button">On air</media-live-button>

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:

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:

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:

<mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8">
  <track kind="chapters" src="/chapters.vtt" default />
</mux-video>

<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

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.

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;
}

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

• Mux Video and Mux Audio
• Mux Data
• Skins and Customize skins