# 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](https://videojs.org/docs/framework/html/guides/architecture).
This guide moves a working Mux Player embed to those pieces, then maps the settings and APIs you are most likely to need next.
> **Tip**
>
> Did you use Mux Player without controls as a hero, ambient loop, or decorative video? Go to [Add a background video](https://videojs.org/docs/framework/html/guides/background-video). It starts with a browser-playable video file, then covers the HLS and Mux background components.
## Before you migrate
A few minutes of auditing tells you which sections of this guide apply to you:
- **List the Mux Player attributes or React props you set.** Compare them with the mapping tables below to make 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](#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?](#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 custom element. It holds state, hands that state to everything inside it, and draws no UI itself. Which state it holds depends on the [features](https://videojs.org/docs/framework/html/guides/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](https://videojs.org/docs/framework/html/guides/media-sources) 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](https://videojs.org/docs/framework/html/guides/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:
```html
```
Everything else in this guide is about which of those three a Mux Player setting 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.
```html
```
From the CDN, load the video [preset](https://videojs.org/docs/framework/html/guides/presets), the Mux media, and analytics:
```html
```
If you use a bundler instead of the CDN, the imports are the same three pieces plus the Mux Data extension:
```bash
npm install @videojs/html @videojs/mux-video @videojs/mux-data
```
```js
import '@videojs/html/video/player';
import '@videojs/html/video/skin';
import '@videojs/html/media/mux-video';
import '@videojs/html/extensions/mux-data';
```
> **Caution: Analytics changes from opt-out to opt-in**
>
> Mux Player monitors playback by default. Video.js sends no Mux Data beacons unless you add the `` extension shown above. Keep it when you want a behaviorally equivalent migration; omit it only when you intend to stop monitoring.
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](#move-your-layout-styles).
- **The Mux media 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 the Mux media. 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](https://videojs.org/docs/framework/html/guides/mux-data).
- **Chromecast is opt-in.** Follow [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/html/guides/casting) 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 ``, put width, height, aspect ratio, positioning, and DOM measurements on ``. Importing the skin registers the styles that make the media, controls, poster, and overlays fill and layer within it. The skin also makes `` boxless.
If you leave out `` to build your own UI, add a [``](https://videojs.org/docs/framework/html/reference/components/player-container). Style and measure that element, and put overlays inside it:
```html
```
```css
.player-surface {
position: relative;
display: block;
width: 100%;
aspect-ratio: 16 / 9;
}
```
`` and the other custom video elements do not create their own layout box. They fill their parent, so size and measure ``, not the video element.
## Mux settings live in a source object
Mux Player exposes Mux stream parameters as attributes such as `max-resolution`, `asset-start-time`, and `custom-domain`.
Video.js collects them into a single **source** object that describes what to play and how.
```js
{
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`.
Assign it as a property, since an object has no attribute form:
```ts
document.querySelector('mux-video')!.source = { playbackId: 'EcHgOK9coz5K…' };
```
You can also skip the object entirely and set `src` to a full Mux URL. The element parses it back into a source, query parameters included, which is what you want in markup you can’t run JavaScript against:
```html
```
There’s no `playback-id` attribute, so declarative markup uses the URL form.
Here’s where the Mux Player attributes land:
| 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 extension
Mux Player’s analytics settings become attributes or properties on the [Mux Data extension](https://videojs.org/docs/framework/html/reference/components/mux-data), placed inside the player.
| Mux Player | Video.js v10 |
| --- | --- |
| `metadata-*`, the `metadata` property | the `metadata` property |
| `env-key` | `env-key`, rarely needed for Mux-hosted content |
| `disable-cookies` | `disable-cookies` |
| `beacon-collection-domain` | `beacon-collection-domain` |
| `player-software-name`, `player-software-version` | `player-software-name`, `player-software-version` |
| `debug` | the `debug` property |
| `disable-tracking` | omit the component |
`metadata` is a property rather than an attribute because an object has no sensible string form.
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 `content-title` on the player.
An asset titled in the Mux dashboard supplies its own: the Mux media loads the asset’s metadata and the player falls back to that title when none is set on it, so the display title is optional for Mux-hosted video.
The packaged video and live-video skins show the resolved title at the top of the player and fade it with the controls, so the embeds above already display it. The [``](https://videojs.org/docs/framework/html/reference/components/title#styling) element sets `data-visible` while the controls are visible, so your skin overrides can move it differently. The audio skins have no title display.
A skin layout you added to your project, or a custom layout, shows the title only where you place it. Keep it inside the sized container from [Move your layout styles](#move-your-layout-styles) so it overlays the media:
```js
import '@videojs/html/ui/container';
import '@videojs/html/ui/title';
```
```html
```
`` 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:
```html
![]()
```
The player supplies the real poster. The slotted image supplies Mux Player’s `placeholder` as its background while that 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](https://videojs.org/docs/framework/html/guides/poster) for more examples or the [``](https://videojs.org/docs/framework/html/reference/components/poster) reference for the element 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](https://videojs.org/docs/framework/html/guides/skins).
### Level 2: restyle it
Set custom properties on the skin. The common case is a brand color:
```css
/* Mux Player */
mux-player {
--accent-color: rebeccapurple;
}
/* Video.js v10 */
video-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](https://videojs.org/docs/framework/html/guides/customize-skins#style-a-packaged-skin) 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 add the skin source to your project, only when you need a closer palette match.
### Level 3: edit skin source
For changes to controls, layout, or interactions, add the skin source to your project. Its components and styles become local files. [Customize skins](https://videojs.org/docs/framework/html/guides/customize-skins#style-skin-source) 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:
```html
```
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](https://videojs.org/docs/framework/html/reference/components/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
`` is a real media element, so every media event you already listen for still fires on it: `play`, `timeupdate`, `ended`, `error`, and the rest. Mux Player listeners port directly. There are a few extras: `streamtypechange`, `targetlivewindowchange`, `sourcechange`, and `contentdatachange`.
For UI state rather than media state, use [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) inside a custom element. Give it a selector for the feature you care about and it keeps your element in sync:
```js
import { PlayerController, playerContext, ReactiveElement, selectTime } from '@videojs/html';
class MyElapsed extends ReactiveElement {
#time = new PlayerController(this, playerContext, selectTime);
}
```
### 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 `