@videojs/html 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/guides/media-sources.md

@@ -0,0 +1,317 @@
+# Media sources
+
+Set what a media element plays and how its engine plays it with the structured source property
+
+Every media element takes a `src`. Elements that drive a playback engine also take `source`, a structured object that carries the URL alongside everything else about that source:
+
+```ts
+const video = document.querySelector('hlsjs-video');
+
+video.source = {
+  src: 'https://example.com/stream.m3u8',
+  preferPlayback: 'mse',
+  engine: { hlsJs: { maxBufferLength: 60 } },
+};
+```
+
+## Three tiers, three homes
+
+The shape answers one question: does this option describe the source, or how to play it?
+
+| Tier | Home | Example |
+| --- | --- | --- |
+| Which source to play | `source.src`, or an element’s own identity fields | `src`, `<mux-video>`’s `playbackId` |
+| How to interpret it | `source.type` | `'video/mp4'` |
+| How Video.js plays it | `source`, at the top level | `preferPlayback`, `maxAutoResolution`, `capRenditionToPlayerSize` |
+| How a specific engine behaves | `source.engine`, under that engine’s name | hls.js’s `maxBufferLength`, in `source.engine.hlsJs` |
+| An extension’s own settings | that extension’s attributes and properties | [Mux Data](./mux-data.md), [`<google-cast>`](../reference/components/google-cast.md) |
+
+`type` is worth reaching for when the URL lies about its contents. Video.js infers the content type from the file extension, so a manifest served from an extensionless or signed URL may need to say so explicitly:
+
+```ts
+video.source = { src: 'https://example.com/asset?id=42', type: 'application/vnd.apple.mpegurl' };
+```
+
+The legacy HLS spelling `application/x-mpegURL` is accepted as an alias, and matching is case-insensitive. An HLS source whose `type` isn’t recognized is handed to the browser as-is rather than to hls.js, which leaves quality and audio-track selection unavailable.
+
+## `src` and `source` stay in sync
+
+They are two views of the same thing, and writing either updates the other. Setting `source` derives `src`. Setting `src` replaces only the identity half and **keeps the rest, such as `type` and the engine options, intact**:
+
+```ts
+video.source = { src: 'https://example.com/a.m3u8', preferPlayback: 'native' };
+
+video.src = 'https://example.com/b.m3u8';
+
+// playback options survive the URL change
+video.source; // { src: 'https://example.com/b.m3u8', preferPlayback: 'native' }
+```
+
+A `sourcechange` event fires whenever `source` changes, from either direction.
+
+## Assigning `source` replaces it
+
+`source` is not merged. A new object is a fresh start, and keys you leave out are dropped:
+
+```ts
+video.source = { src, type: 'video/mp4', preferPlayback: 'native' };
+
+// type and preferPlayback are gone, because the new object omits them
+video.source = { src };
+```
+
+## Equivalent sources cost nothing
+
+Sources are compared **structurally**, not by reference. Reassigning an object with the same values is a no-op — no reload, and no engine teardown:
+
+```ts
+video.source = { src, engine: { hlsJs: { maxBufferLength: 60 } } };
+video.source = { src, engine: { hlsJs: { maxBufferLength: 60 } } }; // no-op
+```
+
+Only a change to the engine options, `preferPlayback`, or the resolved content type recreates the playback engine.
+
+> **Note**
+>
+> `source` holds an object, so it’s a property, not an attribute — there is no `source=""` in HTML. `src` remains the attribute, and it’s the one to reach for when your markup only names a URL.
+
+## Engine options
+
+Engine options live under `source.engine`, **namespaced by engine**. Each key there holds that engine’s own configuration object, handed over untouched — there’s no Video.js wrapper around it, so whatever the engine documents works:
+
+| Key | Elements that read it | It holds |
+| --- | --- | --- |
+| `engine.hlsJs` | [`<hlsjs-video>`](../reference/components/hlsjs-video.md), [`<mux-video>`](../reference/components/mux-video.md), [`<mux-audio>`](../reference/components/mux-audio.md) | an [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) |
+| `engine.nativeHls` | [`<native-hls-video>`](../reference/components/native-hls-video.md), and the three above whenever the browser plays the manifest | options for the browser’s own HLS support (today, [DRM](#licensing-one-engine-differently)) |
+| `engine.dashJs` | [`<dash-video>`](../reference/components/dash-video.md) | [dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) |
+| `engine.vimeo` | [`<vimeo-video>`](../reference/components/vimeo-video.md) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
+| `engine.youtube` | [`<youtube-video>`](../reference/components/youtube-video.md) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
+| `engine.cloudflare` | [`<cloudflare-video>`](../reference/components/cloudflare-video.md) | [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) |
+| `engine.spotify` | [`<spotify-audio>`](../reference/components/spotify-audio.md) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
+| `engine.tiktok` | [`<tiktok-video>`](../reference/components/tiktok-video.md) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
+| `engine.twitch` | [`<twitch-video>`](../reference/components/twitch-video.md) | [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) |
+
+Naming the engine rather than using one generic key matters where an element has more than one to choose from. `<hlsjs-video>` plays through hls.js or through the browser depending on the platform and `preferPlayback`, and only one of them runs — so a single source can describe both paths without either engine reading the other’s options.
+
+hls.js reads its options when the engine is constructed, so changing them tears down the engine and builds a new one:
+
+```ts
+video.source = {
+  src: 'https://example.com/stream.m3u8',
+  engine: { hlsJs: { maxBufferLength: 60, enableWorker: false } },
+};
+```
+
+dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
+
+```ts
+const video = document.querySelector('dash-video');
+
+video.source = {
+  src: 'https://example.com/manifest.mpd',
+  engine: { dashJs: { streaming: { abr: { maxBitrate: { video: 2000 } } } } },
+};
+```
+
+Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.
+
+### Options Video.js normalizes
+
+Where an option means the same thing across engines, it sits on `source` itself rather than inside an engine’s namespace.
+
+`preferPlayback` picks between [hls.js](https://github.com/video-dev/hls.js/) and the browser’s own HLS support:
+
+```ts
+video.source = { src: 'https://example.com/stream.m3u8', preferPlayback: 'native' };
+```
+
+It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `<hlsjs-video>`, `<mux-video>`, and `<mux-audio>` accept it; DASH and Vimeo have no second playback path.
+
+`maxAutoResolution` caps the highest rendition adaptive bitrate selection reaches for on its own:
+
+```ts
+video.source = { src: 'https://example.com/stream.m3u8', maxAutoResolution: '720p' };
+```
+
+The cap limits automatic selection without hiding anything. Renditions above it stay in `videoRenditions`, so a viewer can still choose 1080p by hand. Reach for it to hold down bandwidth on a stream that would otherwise climb to 4K, or to keep a background or thumbnail player cheap.
+
+Renditions are matched on pixel area rather than height, which keeps unusual aspect ratios honest: an ultrawide 2560×1080 rendition carries more pixels than 16:9 1080p, so a `'1080p'` cap leaves it out. When every rendition sits above the cap, the smallest one plays.
+
+Changing the cap applies to the running engine, so playback continues uninterrupted. It needs the hls.js engine — native HLS playback ignores it, and audio-only streams have no video renditions to cap.
+
+### Capping to the player’s size
+
+A 400px-wide player has no use for a 4K rendition, so `capRenditionToPlayerSize` holds automatic selection to the smallest rendition that still covers the element. It defaults to `true`, and the cap follows the element as it’s resized:
+
+```ts
+video.source = { src: 'https://example.com/stream.m3u8', capRenditionToPlayerSize: false };
+```
+
+The element is measured in device pixels, so a `2` device pixel ratio asks for twice the rendition a CSS measurement would — a 640px-wide player on a retina screen still gets 720p. Switch the cap off for a player whose layout size understates what it needs, such as one that goes fullscreen without a resize.
+
+`minAutoResolution` bounds how far down that cap can reach, and defaults to `'720p'`:
+
+```ts
+video.source = { src: 'https://example.com/stream.m3u8', minAutoResolution: '480p' };
+```
+
+**It is not a quality floor.** It bounds the size-derived cap and nothing else. When bandwidth is poor, adaptive selection still drops below it — the cap is a ceiling, and selection stays free underneath. It also never raises an explicit `maxAutoResolution`: ask for at most `'360p'` alongside a `'720p'` floor and you get `'360p'`.
+
+The default is there because the low rungs of a ladder exist for poor network conditions, and capping a small player down to them looks worse than its size suggests. Name a lower rung to weaken the floor, or `'270p'` to lift it for any real ladder.
+
+### Four things that sound alike
+
+Four separate mechanisms bound which rendition plays, and they’re easy to mistake for each other:
+
+| Option | Side | What it does |
+| --- | --- | --- |
+| `source.playback.maxResolution` | Server | A Mux query param. Trims the manifest, so higher renditions never arrive — not even by hand. |
+| `source.maxAutoResolution` | Client | A ceiling on automatic selection. Everything still arrives and stays selectable by hand. |
+| `source.capRenditionToPlayerSize` | Client | The same kind of ceiling, derived from the element’s rendered size and moving with it. |
+| `source.minAutoResolution` | Client | A bound on the one above. Not a quality minimum, and not related to `playback.minResolution`. |
+
+`playback.maxResolution` and `playback.minResolution` are the server-side pair: they decide what the manifest carries. The other three only bound what adaptive selection picks from whatever does arrive.
+
+## DRM protected sources
+
+Protected content is licensed through `source.drm`, keyed by EME key system id — alongside the URL rather than inside an engine’s namespace, because which engine plays the manifest is decided later and both paths read it:
+
+```ts
+video.source = {
+  src: 'https://example.com/protected.m3u8',
+  drm: {
+    'com.apple.fps': {
+      licenseUrl: 'https://license.example.com/fairplay',
+      serverCertificateUrl: 'https://license.example.com/fairplay-cert',
+    },
+    'com.widevine.alpha': { licenseUrl: 'https://license.example.com/widevine' },
+    'com.microsoft.playready': { licenseUrl: 'https://license.example.com/playready' },
+  },
+};
+```
+
+Name every system you hold a license server for — which one gets used is the browser’s choice. `serverCertificateUrl` is the DRM server (application) certificate FairPlay requires; Widevine and PlayReady ignore it.
+
+### What each path can license
+
+The same `drm` reaches both playback paths, and how far it gets is the one thing worth knowing about each:
+
+| Path | Key systems it negotiates | What Video.js does with `drm` |
+| --- | --- | --- |
+| hls.js (MSE) | FairPlay, Widevine, PlayReady | Hands it to hls.js as `drmSystems`, with `emeEnabled` switched on |
+| The browser’s own HLS | FairPlay | Answers the element’s key requests itself: POSTs the CDM’s license request to `licenseUrl` and hands the response back |
+
+So a source naming only Widevine plays through hls.js and cannot play on the native path — [`<native-hls-video>`](../reference/components/native-hls-video.md), or any HLS element the browser ends up playing the manifest for. Video.js says so in development, and encrypted media that gets there with no `com.apple.fps` license server fails with a `MEDIA_ERR_ENCRYPTED` error rather than hanging.
+
+For Widevine on hls.js, Video.js asks for a hardware-backed CDM first, falling back to whatever robustness the browser offers, so content restricted to L1 devices plays where it can. Supplying your own `requestMediaKeySystemAccessFunc` replaces that entirely.
+
+### Licensing one engine differently
+
+An engine’s own `drmSystems` **replaces** `source.drm`, for that engine alone. Reach for it when one path licenses differently, or when you need more of [hls.js’s DRM configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#drmsystems) than `drm` covers:
+
+```ts
+video.source = {
+  src: 'https://example.com/protected.m3u8',
+  drm: { 'com.apple.fps': { licenseUrl, serverCertificateUrl } },
+  engine: {
+    // hls.js licenses from here instead, and the native path still from `drm`.
+    hlsJs: { drmSystems: { 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } } },
+  },
+};
+```
+
+It replaces rather than merges, so the FairPlay server above is gone as far as hls.js is concerned. `engine.nativeHls.drmSystems` does the same for the native path.
+
+## Mux sources name a playback ID
+
+[`<mux-video>`](../reference/components/mux-video.md) and [`<mux-audio>`](../reference/components/mux-audio.md) identify a source by `playbackId` rather than a URL, and derive `src` from it. Everything else works the same, engine options included:
+
+```ts
+const video = document.querySelector('mux-video');
+
+video.source = {
+  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+  playback: { maxResolution: '1080p' },
+  engine: { hlsJs: { maxBufferLength: 60 } },
+};
+```
+
+`playback` params ride along in the URL, so `playback.maxResolution` decides which renditions the manifest carries in the first place. `maxAutoResolution` is the other half of that pair: it caps what adaptive selection picks from the renditions that do arrive. Use `playback.maxResolution` when a viewer should never get 4K, and `maxAutoResolution` when they should be able to ask for it.
+
+The same split applies at the bottom of the ladder, and the names are close enough to be worth restating: `playback.minResolution` asks Mux to leave the lowest renditions out of the manifest, while `minAutoResolution` is a client-side bound on the player-size cap. They are unrelated.
+
+Setting a Mux stream URL as `src` works too — the element parses the playback ID and query params back out into `source`. To play something Mux doesn’t host, name it with `src` inside `source`; engine options still apply.
+
+Two more source params describe images rather than playback. `source.storyboard` and `source.poster` carry the modifiers for the storyboard VTT and the poster still — both belong to the source, since a signed token scopes them to one playback ID:
+
+```ts
+video.source = { playbackId, storyboard: { format: 'jpg' }, poster: { time: 12 } };
+```
+
+`<mux-video>` uses the storyboard itself, adding the thumbnail `<track>` for you so hover previews work without extra markup. Live streams have no storyboard, so the track is dropped once the stream type is known, and signed playback without a matching storyboard token adds none.
+
+### Mux signs DRM with a token
+
+Mux serves FairPlay, Widevine, and PlayReady from URLs derived from a single license token, so `source.drm` takes that token in place of the license servers it would otherwise name. Mux fills the rest in for you, so protected media plays whichever path the browser takes:
+
+```ts
+video.source = {
+  playbackId,
+  playback: { token: playbackToken },
+  drm: { token: drmToken },
+};
+```
+
+DRM playback is always signed, so a `playback.token` belongs alongside it — and `poster.token` / `storyboard.token` for the images. Each is scoped to a different audience, so they are four separate tokens rather than one reused four times. Sign them on your server; see [Mux’s DRM guide](https://www.mux.com/docs/guides/protect-videos-with-drm) for how.
+
+A `drm.token` that isn’t scoped to DRM is ignored rather than sent, since the license request would be rejected. License servers named alongside the token win, key by key, for the systems Mux doesn’t license:
+
+```ts
+video.source = {
+  playbackId,
+  playback: { token: playbackToken },
+  // FairPlay and PlayReady from Mux, Widevine from your own server.
+  drm: { token: drmToken, 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } },
+};
+```
+
+`source.poster` gets no such treatment — it’s only data, and nothing applies it to the media. Both URLs are readable from `contentData`, keyed by what each one describes:
+
+```ts
+video.contentData;
+// {
+//   poster: 'https://image.mux.com/PLAYBACK_ID/thumbnail.webp?time=12',
+//   storyboard: 'https://image.mux.com/PLAYBACK_ID/storyboard.vtt?format=jpg',
+// }
+
+// Use the still as the poster, if that's what you want it for.
+video.poster = video.contentData.poster ?? '';
+```
+
+It’s read-only and derived from `source`, so read it again after `sourcechange`. A key is missing when its URL can’t be built: no playback ID, or signed playback with no matching image token. Changing the URLs means changing the params they’re built from.
+
+One more key arrives later. Mux publishes a small metadata document for each asset, and the media loads it alongside the stream, so `contentData.title` fills in with the asset’s title once it does — `contentdatachange` announces it. The player reads it as the fallback for its own title, so a Mux asset titled in the dashboard names itself without a `content-title` on the player. Any other entries the document carries ride along under their own keys. An untitled asset adds nothing.
+
+`source.poster` takes the [full set of Mux image modifiers](https://www.mux.com/docs/guides/get-images-from-a-video), so a narrower still for a small viewport is a `width`:
+
+```ts
+video.source = { ...video.source, poster: { width: 320 } };
+```
+
+Because `source` has no attribute, the poster frame has one of its own. `poster-time` reflects to `source.poster.time`, letting you set it from markup:
+
+```html
+<mux-video src="https://stream.mux.com/PLAYBACK_ID.m3u8" poster-time="12"></mux-video>
+```
+
+It survives a `src` change, so swapping the source keeps the frame you asked for.
+
+## Elements without engine options
+
+[`<hls-video>`](../reference/components/hls-video.md) and [`<hls-audio>`](../reference/components/hls-audio.md) take `src` and the usual media attributes but expose no `source`. They run on our own playback engine, which does not accept configuration from the element yet.
+
+## See also
+
+- [hlsjs-video element reference](../reference/components/hlsjs-video.md)
+- [mux-video element reference](../reference/components/mux-video.md)
+- [dash-video element reference](../reference/components/dash-video.md)

package/docs/guides/migrate-from-media-chrome.md

@@ -0,0 +1,266 @@
+# Migrate from Media Chrome
+
+Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
+
+Video.js v10’s HTML player uses the same `media-*` custom-element convention as Media Chrome, so most of the work is **renaming and reshaping**, not rewriting.
+
+> **Note**
+>
+> Scoped to apps that compose their own player from Media Chrome elements. If you use `<mux-player>`, follow the Mux Player migration guide instead.
+
+## Before you begin
+
+Install Video.js and choose a [preset](./presets.md) (see [Installation](./installation.md)). Start with its ready-made skin if those controls fit your player. If you need to keep a custom control bar, build it from the individual Video.js UI components instead.
+
+```bash
+npm install @videojs/html
+```
+
+## Map the controller
+
+Media Chrome wraps a slotted `<video slot="media">` in a single `<media-controller>`. Video.js splits that into two elements. The player owns state and draws nothing. The `<media-container>` is the box everything lives in, with the media as a plain child.
+
+```html
+<!-- Media Chrome -->
+<media-controller>
+  <video slot="media" src="video.m3u8"></video>
+  <media-control-bar>
+    <media-play-button></media-play-button>
+  </media-control-bar>
+</media-controller>
+```
+
+**JavaScript**
+
+```js
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/controls';
+import '@videojs/html/ui/controls-content';
+import '@videojs/html/ui/play-button';
+import '@videojs/html/icons/element';
+```
+
+**HTML**
+
+```html
+<!-- Video.js -->
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls>
+      <media-controls-content>
+        <media-play-button class="player-play-button">
+          <media-icon class="player-play-icon" name="play"></media-icon>
+          <media-icon class="player-pause-icon" name="pause"></media-icon>
+        </media-play-button>
+      </media-controls-content>
+    </media-controls>
+  </media-container>
+</video-player>
+```
+
+**CSS**
+
+```css
+.player-pause-icon {
+  display: none;
+}
+
+.player-play-button:defined:not([data-paused]) .player-play-icon {
+  display: none;
+}
+
+.player-play-button:defined:not([data-paused]) .player-pause-icon {
+  display: inline-flex;
+}
+```
+
+## Map controller attributes
+
+Media Chrome configures behavior through `<media-controller>` attributes. Video.js v10 has no single controller element, so these settle into three places:
+
+- **Player features** — playback behavior that comes from the player’s feature set. A preset picks one for you; `createPlayer` lets you name your own.
+- **`<media-container>` and `<media-controls>`** — layout, focus, and autohide.
+- **Dedicated elements** — `<media-hotkey>`, `<media-gesture>`, and friends, declared in markup.
+
+| Media Chrome attribute | Video.js v10 | How |
+| --- | --- | --- |
+| `audio` | the audio preset | Choose an audio player and audio skin rather than toggling at runtime. |
+| `autohide` | `media-controls` (built in) | Controls auto-hide after inactivity automatically. `autohide="-1"` becomes `visibility="always"` on `media-controls`; the delay is currently fixed, see [Known gaps](#known-gaps). |
+| `fullscreenelement` | `media-container` | Fullscreen targets the container element. |
+| `gesturesdisabled` | `media-gesture disabled`, or omit | Disable per gesture element, or leave the gestures out. |
+| `nohotkeys` | `media-hotkey disabled`, or omit | Disable per hotkey element, or leave them out. |
+| `hotkeys="noarrowleft …"` | individual `media-hotkey` | Each shortcut is its own element, so remove the ones you don’t want. |
+| `keyboardforwardseekoffset`, `keyboardbackwardseekoffset` | `value` on `media-hotkey` | Set the signed seek amount per element. |
+| `defaultsubtitles` | `<track default>` for authored tracks | Add `default` to an authored captions or subtitles track. Tracks discovered from a provider or manifest don’t have one generic player-level default flag. |
+| `defaultstreamtype` | `streamType` feature | Partial: derived from the media, with no pre-load default. |
+| `liveedgeoffset`, `seektoliveoffset` | live media engine | Live-edge behavior lives in the playback engine, not a UI attribute. |
+| `lang` | i18n translator | Localization is configured through the [translator and locale registry](./internationalization.md). |
+
+### Hotkeys
+
+Media Chrome toggles keyboard shortcuts with `nohotkeys` and `hotkeys`. Video.js declares each shortcut as its own element, so you opt in to exactly the keys you want and set seek offsets inline:
+
+```html
+<media-hotkey keys="Space" action="togglePaused"></media-hotkey>
+<media-hotkey keys="m" action="toggleMuted"></media-hotkey>
+<media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
+<media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
+```
+
+To drop a shortcut, remove its element or add `disabled`. There’s no global “all hotkeys off” switch; omit the elements you don’t need.
+
+### Gestures
+
+`gesturesdisabled` becomes per-element `<media-gesture>` controls. Tap and double-tap behavior — click to toggle play, double-tap to seek or go fullscreen — is declared explicitly:
+
+```html
+<media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
+<media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
+<media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>
+```
+
+Remove an element or set `disabled` to turn a gesture off.
+
+## Map the elements
+
+Most names match. These are the renames that bite:
+
+| Media Chrome | Video.js v10 | Note |
+| --- | --- | --- |
+| `media-controller` | a player plus `media-container` | one element becomes two: state and layout |
+| `media-control-bar` | `media-controls`, `media-controls-group` | grouping |
+| `media-time-range` | `media-time-slider` | “range” becomes “slider” |
+| `media-volume-range` | `media-volume-slider` | “range” becomes “slider” |
+| `media-time-display`, `media-duration-display` | `media-time` | one element, set via attribute |
+| `media-loading-indicator` | `media-buffering-indicator` | rename |
+| `media-poster-image` | `media-poster` | rename, and the image source moves — see below |
+| `media-seek-backward-button`, `media-seek-forward-button` | `media-seek-button` | one element, direction via signed `seconds` |
+| `media-rendition-menu` | `media-quality-radio-group` | inside `media-menu` |
+| `media-captions-menu` | `media-captions-radio-group` | inside `media-menu` |
+| `media-playback-rate-menu` | `media-playback-rate-radio-group` | inside `media-menu` |
+| `media-audio-track-menu` | `media-audio-track-radio-group` | inside `media-menu` |
+
+Unchanged names: `media-play-button`, `media-mute-button`, `media-fullscreen-button`, `media-pip-button`, `media-airplay-button`, `media-cast-button`, `media-captions-button`, `media-playback-rate-button`, `media-tooltip`, and `media-thumbnail`.
+
+> **Caution**
+>
+> Matching tag names do not mean matching appearance. Media Chrome buttons include default icons and styles. Individual Video.js buttons provide behavior, state, and an accessible name, but no visible content or finished styling. Add text, an SVG, or a `<media-icon>`, plus your own CSS. Without visible content, a button can work while showing nothing. Sliders also need their child elements and CSS. Use a ready-made skin when you want finished controls.
+
+Video.js sliders use `media-slider-track`, `media-slider-fill`, and `media-slider-thumb`. See [`media-time-slider`](../reference/components/time-slider.md) and [`media-volume-slider`](../reference/components/volume-slider.md) for copy-paste markup and CSS.
+
+Media Chrome’s named icon slots do not carry over. Remove attributes such as `slot="play"` and put the icon directly inside the Video.js button. Import `@videojs/html/icons/element` to use `<media-icon>`, as shown in [Map the controller](#map-the-controller). Set `family="minimal"` to use the Minimal skin’s icon designs. You can also use your own text or SVG.
+
+`media-poster` is the one rename that changes shape. Where `media-poster-image` took its own `src`, `media-poster` wraps the image you bring:
+
+```html
+<media-poster>
+  <img src="/poster.jpg" alt="" decoding="async" />
+</media-poster>
+```
+
+## Rewrite your styles
+
+Media Chrome reflects state as `media*` attributes such as `mediapaused`; Video.js uses `data-*`.
+
+```css
+/* Media Chrome */
+media-play-button[mediapaused] .play-icon { display: inline; }
+```
+
+```css
+/* Video.js HTML */
+media-play-button[data-paused] .play-icon { display: inline; }
+```
+
+Continuous values 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 that shared prefix is a naming convention, not a compatibility layer. Keep a variable only when its documented meaning matches.
+
+| Media Chrome theme variable | Packaged Video.js skin | Migration |
+| --- | --- | --- |
+| `--media-accent-color` or `--media-range-bar-color` | `--media-accent-color` | Closest match for slider fills and accented controls. |
+| `--media-primary-color` | no direct equivalent | Often colors every control icon in Media Chrome; Video.js’s accent variable has narrower semantics. |
+| `--media-secondary-color` | no direct equivalent | Add the skin source and author this palette role in your CSS. |
+| `--media-control-background` | no direct equivalent | Add the skin source and author the CSS. |
+| `--media-control-hover-background` | no direct equivalent | Add the skin source and author the CSS. |
+| `--media-range-track-height` | no direct equivalent | Add the skin source and author the slider CSS. |
+
+The packaged Video.js skins expose `--media-accent-color`, `--media-accent-text-color`, `--media-border-radius`, and `--media-scale-unit` for broad customization. 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](./skins.md) and [presets](./presets.md). Start from a preset, then [add its skin source to your project](./customize-skins.md#style-skin-source), rather than authoring a template.
+
+Ready-made HTML skins keep their controls inside Shadow DOM. Code outside the skin sees a click as coming from the skin, not the button inside it. Some control events also stay inside the skin. Do not use an outside listener to identify which built-in button was clicked.
+
+Keep playback event handlers on your `<video>` or `<audio>`. When you build a custom control bar, attach click and input handlers directly to those controls. With a ready-made skin, read media or player state instead of listening for clicks inside the skin.
+
+Keep the skin when its CSS variables and content slots cover your changes. Build a custom control bar when you want to start from scratch. Add the skin source to your project when you want its existing layout and styles but need to change the controls inside it.
+
+## Control the player imperatively
+
+Control everything through the player’s store. Media Chrome had no player object; Video.js gives you one, with an action for every operation — `play`, `togglePaused`, `seek`, `setVolume`, `toggleFullscreen` — so one mental model covers playback and the state the browser doesn’t own, such as fullscreen, captions, and quality.
+
+Hold a reference to the player element and call actions on its store:
+
+```js
+const player = document.querySelector('video-player');
+
+player.store.state.toggleFullscreen();
+```
+
+The Media Chrome habit of scripting the media element directly still works, unchanged. The media is a plain child of the player, and Video.js derives player state from the native media events, so `video.play()` or `video.currentTime = 30` never leaves the controls out of sync. The media element also stays the way to swap `src`, replace the media component, and listen for native events.
+
+## Known gaps
+
+These Media Chrome features have no direct equivalent yet. Several can be approximated; see [Workarounds](#workarounds).
+
+- No configurable `autohide` delay and no `autohideovercontrols` ([#1728](https://github.com/videojs/v10/issues/1728)). Disabling autohide (`autohide="-1"`) is covered by `visibility="always"` on the controls component; see [Workarounds](#workarounds).
+- No `defaultduration` placeholder before the media loads ([#1729](https://github.com/videojs/v10/issues/1729))
+- Volume and muted preferences are not persisted across sessions, so Media Chrome’s `novolumepref` and `nomutedpref` opt-outs have nothing to opt out of ([#944](https://github.com/videojs/v10/issues/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](https://github.com/videojs/v10/issues/1786)).
+- No `breakpoints` or container-breakpoint attributes; use CSS container queries instead
+- No `seektoliveoffset` or `noautoseektolive` controls, and live-edge offset and tolerance aren’t configurable ([#1730](https://github.com/videojs/v10/issues/1730))
+- Chapters render and each time-slider segment reflects `data-active`, but there’s no player-level active chapter value, `chapterchange` event, or menu to jump between them ([#1873](https://github.com/videojs/v10/issues/1873))
+- Cue points are not supported ([#1442](https://github.com/videojs/v10/issues/1442))
+
+Chapters themselves do work. Add a default `<track kind="chapters">` and the packaged skins segment the time slider and show the chapter title on hover, via `media-time-slider-chapters` and `media-time-slider-chapter-title`.
+
+## Workarounds
+
+### Disable autohide (`autohide="-1"`)
+
+Set `visibility="always"` on `media-controls` and the controls stay visible regardless of activity. Packaged skins don’t expose that attribute; to keep a preset skin’s look, [add the skin source to your project](./customize-skins.md#style-skin-source) and set it on the skin’s controls element rather than overriding private selectors.
+
+### Breakpoints
+
+The skin root is an inline-size container named `media-root`, so write responsive styles with container queries instead of `breakpoints` attributes. This is exactly how the built-in skins adapt:
+
+```css
+@container media-root (width > 40rem) {
+  .media-controls { /* wide layout */ }
+}
+```
+
+### Default duration
+
+There’s no player input for a pre-load duration. Use `preload="metadata"`, the default, so the real duration is known almost immediately; only `preload="none"` defers it. If you must defer loading, render your own static placeholder in markup.
+
+### Preference persistence
+
+Media Chrome remembers volume, muted state, and language across sessions. Video.js v10 persists nothing, so restore and save the values yourself.
+
+Work against the store directly: `selectVolume(store.state).setVolume(…)` on init, and `store.subscribe(…)` to save on change.
+
+### 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. The escape hatch is a custom live control built against the `selectLive` and `selectTime` player state.
+
+## See also
+
+- [Installation](./installation.md)
+- [UI components](./ui-components.md)
+- [Skins](./skins.md) and [Customize skins](./customize-skins.md)