GuideMigrate
Migrate from Media Chrome
Move a Media Chrome player to Video.js v10, mapping its controller, controls, styles, and imperative calls
Replace Media Chrome’s controller with a Video.js player and container, then migrate your controls to React components. Keep the playback sources and interactions your app needs. Rebuild each control’s visible contents and styles.
AI Quickstart
Copy this prompt into your coding agent to plan and run the migration.
Your prompt
Install the Video.js skill:
`npx @videojs/cli agents skills`
.Run it and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project.
Migrate this project's Media Chrome player to Video.js 10:
`npx @videojs/cli agents init --from media-chrome --project existing`
.Run it to print version-matched instructions for these choices without changing files. The command detects the package manager, framework, app setup, and installation method from the project and explains how to choose the preset, skin, media, media URL, and extensions, so follow its output for those. If a choice conflicts with the project, ask me before changing it.
1. Install the Video.js skill: `npx @videojs/cli agents skills`. Run it and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project.
2. Migrate this project's Media Chrome player to Video.js 10: `npx @videojs/cli agents init --from media-chrome --project existing`. Run it to print version-matched instructions for these choices without changing files. The command detects the package manager, framework, app setup, and installation method from the project and explains how to choose the preset, skin, media, media URL, and extensions, so follow its output for those. If a choice conflicts with the project, ask me before changing it.Before you begin
Check Known gaps for controller options and preferences your app relies on. List your media sources, custom controls, event handlers, and theme rules.
Install Video.js and choose a preset (see Installation). If the preset’s ready-made skin has the controls you need, start with it. To keep a custom control bar, build it from the individual Video.js UI components instead.
Map the controller
The examples use the same MP4 source before and after migration. For HLS, DASH, or an embed, keep your existing source and choose its media component.
Media Chrome wraps a slotted <video slot="media"> in a single <media-controller>. Video.js splits that into two components. The player owns state and renders nothing. The container holds the media and controls. Put the media directly inside the container.
Media Chrome’s React package wraps its custom elements. @videojs/react ships native components instead. VideoPlayer comes from the video preset, and Container holds the media and controls:
Create player.css with the rules below for layout, button styling, and control visibility. If your framework does not allow global CSS imports in components, import player.css from the entry point your app uses for global styles. Alternatively, add these rules to your app’s global stylesheet and remove the ./player.css import:
A preset player has a fixed set of features. For a custom set, call createPlayer once outside your React component. Pass it the feature list, then use the Player component and typed usePlayer hook it returns.
Read player state with usePlayer, useMedia, and useStore. Player hooks must run in a descendant component rendered inside VideoPlayer or the Player returned by createPlayer. A hook called in the component that renders VideoPlayer or Player is outside that provider. Call the hook from a child component.
Map controller attributes
Media Chrome configures behavior through <media-controller> attributes. Video.js v10 has no single controller component, so these settings move to three places:
- Player features — playback behavior that comes from the player’s feature set. A preset includes a fixed feature set. With
createPlayer, you choose the feature set. ContainerandControls— layout, focus, and autohide.- Dedicated components —
Hotkey,Gesture, and similar components, rendered inside the player.
Hotkeys
Media Chrome toggles keyboard shortcuts with nohotkeys and hotkeys. Video.js declares each shortcut as its own component, so you opt in to exactly the keys you want and set seek offsets inline:
In a custom layout, render these components inside the player’s Container. With installed skin source, edit its existing hotkey declarations.
To drop a shortcut, remove its component or pass disabled. There’s no global “all hotkeys off” switch; omit the components you don’t need.
Gestures
Declare each tap or double-tap behavior with a Gesture component. For example, declare a tap that toggles playback, or a double-tap that seeks or enters fullscreen:
In a custom layout, render these components inside the player’s Container. With installed skin source, edit its existing gesture declarations. A packaged skin already declares its own gestures, so do not add duplicates.
Remove a component or pass disabled to turn a gesture off.
Map the elements
Most names carry over as PascalCase components without the media- prefix. Start with these name changes:
Unchanged names, in PascalCase: PlayButton, MuteButton, FullscreenButton, PiPButton, AirPlayButton, CastButton, CaptionsButton, PlaybackRateButton, Tooltip, and Thumbnail.
React buttons do not include visible content either. Use a button’s render prop to add it, as shown in Map the controller. Build sliders from parts such as TimeSlider.Track, TimeSlider.Fill, and TimeSlider.Thumb, then add your own CSS.
Compound parts are namespaced under their component, such as TimeSlider.Track. See the UI components concept for the full set.
Poster also works differently. Put the poster URL on VideoPlayer; Poster.Root owns its state and Poster.Image accepts image attributes such as alt. If you set srcSet on Poster.Image, it overrides the player poster URL. Pair srcSet with sizes for responsive images.
Inside your custom player’s container, render the poster beside its media and controls:
Rewrite your styles
Media Chrome reflects state in attributes such as mediapaused. Video.js uses data-* attributes such as data-paused.
Values that change continuously, such as slider position, use CSS custom properties: sliders expose --media-slider-fill and --media-slider-pointer.
Map theme variables by meaning
Media Chrome and Video.js both use names beginning with --media-, but the shared prefix does not make their variables compatible. Keep a variable only when its documented meaning matches.
The packaged Video.js skins expose eight custom properties:
- Colors:
--media-accent-color,--media-accent-text-color, and--media-border-color. - Corners:
--media-border-radius. - Interface font:
--media-font-family. - Media and poster fit and position:
--media-object-fitand--media-object-position. - Control sizing:
--media-scale-unit.
See Customize skins for their meanings and defaults. Do not assume another Media Chrome variable will work because its name starts with --media-.
Themes become skins
Media Chrome’s <template>-based themes (media-theme) become Video.js skins and presets. Start from a preset, then add its skin source to your project.
React skins do not use Shadow DOM. Use render props when you build individual controls. Add a ready-made skin’s source to your project when you need to change its controls or layout.
Control the player imperatively
Use store actions such as play, pause, seek, setVolume, requestFullscreen, and exitFullscreen to control playback and UI state.
Select an action with the same usePlayer hook you read state with:
Keep native media calls such as video.play() and assignments such as video.currentTime = 30. Video.js updates player state from media events. Set src on the media component to change content, and replace the component when the source needs a different playback engine.
For video-backed media, a ref points to the rendered HTMLVideoElement. YouTube and Vimeo refs point to an HTMLIFrameElement. To call media methods on those embeds, pass a mediaRef, which receives the playback adapter, or call useMedia() from a component inside the player.
useMedia() returns the Video.js media object. If that object exposes an engine property, use it to access the playback engine.
Known gaps
These Media Chrome features have no direct equivalent yet. Several can be approximated; see Workarounds.
- No configurable
autohidedelay and noautohideovercontrols(#1728). To disable autohide (autohide="-1"), setvisibility="always"on the controls component; see Workarounds. - No
defaultdurationplaceholder before the media loads (#1729) - Volume and muted preferences are not persisted across sessions, so Media Chrome’s
novolumeprefandnomutedprefopt-outs have nothing to opt out of (#944). Video.js can choose an initial subtitle track from the locale, but it does not yet remember the viewer’s later language choice (#1786). - No
breakpointsor container-breakpoint attributes; use CSS container queries instead - No
seektoliveoffsetornoautoseektolivecontrols, and live-edge offset and tolerance aren’t configurable (#1730) - Chapters render and each time-slider segment reflects
data-active, but there’s no player-level active chapter value,chapterchangeevent, or menu for jumping between chapters (#1873) - Cue points are not supported (#1442)
Chapters still work. Add a <track kind="chapters"> with the default attribute. The packaged skins then split the time slider into chapter segments and show the chapter title on hover, via TimeSlider.Chapters and TimeSlider.ChapterTitle.
Workarounds
Disable autohide (autohide="-1")
Set visibility="always" on Controls.Root to keep the controls visible regardless of activity. Packaged skins do not expose this prop. To keep a packaged skin’s look, add its source to your project and set visibility="always" on its controls component.
Breakpoints
For custom UI, add a class to your container and another to the controls you want to change. Define and query your own CSS container:
Packaged HTML skin controls are inside Shadow DOM; external selectors cannot reach them. React skin selectors are private. To change a packaged skin’s responsive layout, add its source to your project and edit the container queries in its local styles.
Default duration
There is no player input for a duration placeholder. Set preload="metadata" to request the duration before playback. The duration is available only after the network request and engine loading finish. If you defer loading, render a static placeholder in your own UI.
Preference persistence
Media Chrome remembers volume, muted state, and language across sessions. Video.js does not persist these preferences. Follow Remember user preferences to restore and save them in your app.
Actions throw before the media attaches. Wait until store.target is set, restore the saved values, and then start saving changes. For captions or quality, also wait for the relevant track or rendition list before restoring a selection.
Live edge offsets
seektoliveoffset and noautoseektolive are governed by the playback engine rather than the UI layer, so there’s no attribute to tune them today. As a workaround, build a custom live control that reads player state through selectLive and selectTime.