@videojs/html 10.0.0-rc.4 → 10.0.0-rc.5

package/docs/guides/migrate-from-mux-player.md

@@ -1,6 +1,6 @@
 # Migrate from Mux Player
 
-Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
+Move a Mux Player embed to Video.js v10 using a player, media component, skin, and analytics extension
 
 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](./architecture.md).
 
@@ -10,47 +10,55 @@ This guide moves a working Mux Player embed to those pieces, then maps the setti
 >
 > Did you use Mux Player without controls as a hero, ambient loop, or decorative video? Go to [Add a background video](./background-video.md). It starts with a browser-playable video file, then covers the HLS and Mux background components.
 
-## Before you migrate
+## AI Quickstart
 
-A few minutes of auditing tells you which sections of this guide apply to you:
+Paste this prompt into your coding agent:
 
-- **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).
+```
+Migrate this project's Mux Player player to Video.js v10 for HTML. Use @videojs/html or its CDN bundles for a page without a build step.
 
-## Three pieces instead of one
+Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.
 
-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.
+Read the migration guide at https://videojs.org/docs/framework/html/guides/migrate-from-mux-player, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.
 
-**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](./features.md) it’s built from.
+For installation guidance, read https://videojs.org/docs/framework/html/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.
 
-**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](./media-sources.md) and the rest of your player keeps working.
+From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.
 
-**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. [Skins](./skins.md) are pre-built arrangements of smaller components, and you can use one as-is, restyle it, or take it apart.
+Choose values for these options:
+- --media and --source-url: the existing content and playback requirements.
+- --method: the installation method.
+- --preset, --skin, and --extensions: the player UI and integrations.
 
-So a Mux Player embed becomes a player wrapped around a skin wrapped around a media:
+Add those options to `npx @videojs/cli agents init --framework html --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.
 
-```html
-<video-player>
-  <video-skin>
-    <mux-video></mux-video>
-  </video-skin>
-</video-player>
+After installing a package, switch to node_modules/@videojs/html/docs/llms.txt for documentation matching its version.
+
+Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
 ```
 
-Everything else in this guide is about which of those three a Mux Player setting now belongs to.
+## Before you migrate
+
+Make a migration checklist before changing your embed:
+
+- **List the Mux Player attributes or React props you set.** Compare them with the mapping tables below.
+- **Grep your codebase for `mux-player` selectors.** After the swap, CSS rules and `querySelector` calls that reach into the element stop matching, with no error. Look for patterns such as `mux-player::part(…)`, `mux-player [role="slider"]`, and `player.shadowRoot`. Restyle the UI with the skin’s custom properties or rebuild it with 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.** Compare your Mux Player theme with the two Video.js skins, and map its CSS variables.
+- **Check [Known gaps](#known-gaps)** for features your app needs.
+- **Check your catalog for MPEG-TS, raw ADTS AAC, AES-128, low-latency HLS, or DVR streams.** Check whether the SPF engine supports these requirements. If you use DRM, verify playback with whichever engine you choose. See [Which Mux media should you use?](#which-mux-media-should-you-use).
+
+Before loading Video.js, remove Mux Player imports and CDN scripts, plus any other imports that register legacy Mux Video or Media Chrome elements. Then reload the page. These libraries share custom-element names such as `mux-video` and `media-play-button`. A name can only have one definition per document, and Video.js keeps an existing definition. If both players must remain during migration, use separate documents, such as an iframe.
 
 ## 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.
+The examples keep a playback ID, analytics metadata, and a poster from two seconds into the video. Replace `YOUR_PLAYBACK_ID` with your existing playback ID before running them.
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@mux/mux-player" defer></script>
 
 <mux-player
-  playback-id="EcHgOK9coz5K…"
+  playback-id="YOUR_PLAYBACK_ID"
   metadata-video-title="Test VOD"
   metadata-viewer-user-id="user-id-007"
   thumbnail-time="2"
@@ -60,19 +68,19 @@ Here’s a typical Mux Player embed. A playback ID, a title and viewer ID for an
 From the CDN, load the video [preset](./presets.md), the Mux media, and analytics:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/mux-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/extensions/mux-data.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/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"
+      src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"
       poster-time="2"
       playsinline
       crossorigin="anonymous"
     ></mux-video>
-    <mux-data player-software-name="my-app"></mux-data>
+    <mux-data></mux-data>
   </video-skin>
 </video-player>
 
@@ -84,7 +92,7 @@ From the CDN, load the video [preset](./presets.md), the Mux media, and analytic
 </script>
 ```
 
-If you use a bundler instead of the CDN, the imports are the same three pieces plus the Mux Data extension:
+With a bundler, install the HTML package, Mux media adapter, and Mux Data extension. Import the player, skin, media, and extension:
 
 ```bash
 npm install @videojs/html @videojs/mux-video @videojs/mux-data
@@ -99,28 +107,28 @@ 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 `<mux-data>` extension shown above. Keep it when you want a behaviorally equivalent migration; omit it only when you intend to stop monitoring.
+> Mux Player monitors playback by default. Video.js sends no Mux Data beacons unless you add the `<mux-data>` extension shown above. Keep the extension to preserve Mux Player’s monitoring. Leave it out only if you intend to stop monitoring.
 
-A few things worth calling out:
+Preserve these behaviors when adapting the example:
 
-- **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 skin has no size of its own**, so the examples give it one with an inline `aspect-ratio`. Any CSS that sizes the skin works, such as your own class 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.
+- **Thumbnail previews come from the Mux media.** 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](./mux-data.md).
-- **Chromecast is opt-in.** Follow [Cast to AirPlay and Chromecast](./casting.md) when you want it; leave the extension out when you don’t.
+- **Chromecast is opt-in.** To add Chromecast, follow [Cast to AirPlay and Chromecast](./casting.md). Otherwise, leave the Google Cast extension out.
 
 ### Move your layout styles
 
 Mux Player was one visible, measurable element. Video.js separates player state from the visible surface.
 
-If you use `<video-skin>`, put width, height, aspect ratio, positioning, and DOM measurements on `<video-skin>`. Importing the skin registers the styles that make the media, controls, poster, and overlays fill and layer within it. The skin also makes `<video-player>` boxless.
+If you use `<video-skin>`, put width, height, aspect ratio, positioning, and DOM measurements on `<video-skin>`. Importing the skin registers the styles that make the media, controls, poster, and overlays fill the skin and stack inside it. The skin also stops `<video-player>` from creating a layout box of its own.
 
 If you leave out `<video-skin>` to build your own UI, add a [`<media-container>`](../reference/components/player-container.md). Style and measure that element, and put overlays inside it:
 
 ```html
 <video-player>
   <media-container class="player-surface">
-    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
+    <mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"></mux-video>
     <my-overlay></my-overlay>
   </media-container>
 </video-player>
@@ -137,6 +145,27 @@ If you leave out `<video-skin>` to build your own UI, add a [`<media-container>`
 
 `<mux-video>` and the other custom video elements do not create their own layout box. They fill their parent, so size and measure `<media-container>`, not the video element.
 
+The examples leave out the player software name and version. If your app already sets them, copy them to the Mux Data extension. Use `player-software-name` and `player-software-version` in HTML, or `playerSoftwareName` and `playerSoftwareVersion` in React. Preserve your existing Mux Data metadata as well.
+
+## Three pieces instead of one
+
+Use these three pieces when deciding where each Mux Player setting belongs:
+
+**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](./features.md) it’s built from.
+
+**The media** is the thing that plays the video. Use Mux media for Mux playback IDs and source settings. Choose another [media component](./media-sources.md) when changing providers, and check which capabilities it exposes.
+
+**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. [Skins](./skins.md) are pre-built arrangements of smaller components, and you can use one as-is, restyle it, or add its source to your project and edit it.
+
+## Autoplay
+
+Video.js uses native autoplay. Move Mux Player’s boolean autoplay setting to the media. For its string-valued modes:
+
+- `muted`: set both `autoplay` and `muted` on the media (`autoPlay` and `muted` in React).
+- `any`: on `loadstart`, call `play()` on the media. If the returned promise rejects, mute the media and call `play()` again. Implement this fallback in your app.
+
+Keep a manual play control available if autoplay fails. See [Handle autoplay](./autoplay.md).
+
 ## 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`.
@@ -145,7 +174,7 @@ Video.js collects them into a single **source** object that describes what to pl
 
 ```js
 {
-  playbackId: 'EcHgOK9coz5K…',
+  playbackId: 'YOUR_PLAYBACK_ID',
   playback: { maxResolution: '1080p', assetStartTime: 10, assetEndTime: 30 },
   poster: { time: 2, width: 1280 },
 }
@@ -153,16 +182,16 @@ Video.js collects them into a single **source** object that describes what to pl
 
 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:
+Set it as the element’s `source` property because an attribute cannot hold an object:
 
 ```ts
-document.querySelector('mux-video')!.source = { playbackId: 'EcHgOK9coz5K…' };
+document.querySelector('mux-video')!.source = { playbackId: 'YOUR_PLAYBACK_ID' };
 ```
 
-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:
+You can also skip the object entirely and set `src` to a full Mux URL. The element parses the URL, including its query parameters, into a source. Use this form in markup where you cannot run JavaScript:
 
 ```html
-<mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8?max_resolution=1080p"></mux-video>
+<mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8?max_resolution=1080p"></mux-video>
 ```
 
 There’s no `playback-id` attribute, so declarative markup uses the URL form.
@@ -177,18 +206,18 @@ Here’s where the Mux Player attributes land:
 | `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` |
+| the `default_subtitles_lang` playback parameter | `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` |
+| `thumbnail-time` | `poster-time` on `<mux-video>`, or `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.
+Signed playback behaves the way it does in Mux Player: a token replaces every other parameter in its group, so put resolution caps and clipping in the token itself.
 
 ## Analytics moves to its own extension
 
-Mux Player’s analytics settings become attributes or properties on the [Mux Data extension](../reference/components/mux-data.md), placed inside the player.
+Render the [Mux Data extension](../reference/components/mux-data.md) inside the player, and move Mux Player’s analytics settings to its attributes or properties.
 
 | Mux Player | Video.js v10 |
 | --- | --- |
@@ -197,10 +226,10 @@ Mux Player’s analytics settings become attributes or properties on the [Mux Da
 | `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 |
+| `debug` | the `debug` attribute or property |
 | `disable-tracking` | omit the component |
 
-`metadata` is a property rather than an attribute because an object has no sensible string form.
+Set `metadata` as a property because it takes an object, while attributes take strings.
 
 Your metadata keys don’t change. They’re the same `snake_case` names Mux Data has always taken, so the values port across untouched.
 
@@ -212,11 +241,11 @@ 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.
+Mux media loads the asset’s title from its metadata. If you omit the display title on the player, the player uses the title set in the Mux dashboard.
 
-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 [`<media-title>`](../reference/components/title.md#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.
+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 [`<media-title>`](../reference/components/title.md#styling) element sets `data-visible` while the controls are visible, so your skin overrides can style the title differently when the controls show or hide. 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:
+In installed skin source or a custom layout, the title appears where you place the title component. Put the title component inside the sized container from [Move your layout styles](#move-your-layout-styles) so it overlays the media:
 
 ```js
 import '@videojs/html/ui/container';
@@ -226,38 +255,40 @@ import '@videojs/html/ui/title';
 ```html
 <video-player content-title="Test VOD">
   <media-container class="player-surface">
-    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
+    <mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"></mux-video>
     <media-title></media-title>
   </media-container>
 </video-player>
 ```
 
-`<mux-video>` 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:
+`<mux-video>` 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.
+
+To show a placeholder while the generated poster loads:
 
 ```html
-<video-player poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2">
+<video-player>
   <video-skin>
-    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
+    <mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"></mux-video>
     <img
       slot="poster"
       alt=""
-      style="background: url('data:image/webp;base64,…') center / contain no-repeat"
+      style="background: url('/placeholder.webp') center / contain no-repeat"
     />
   </video-skin>
 </video-player>
 ```
 
-The player supplies the real poster. The slotted image supplies Mux Player’s `placeholder` as its background while that poster loads.
+Replace `/placeholder.webp` with your existing placeholder image URL or data URL. The slotted image shows the placeholder while the full poster loads. The Mux media supplies that full poster using your source settings and any thumbnail token.
 
-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](./poster.md) for more examples or the [`<media-poster>`](../reference/components/poster.md) reference for the element itself.
+Mux serves poster images from its `thumbnail` endpoint. Configure the image URL with `source.poster`. Move Mux Player’s `thumbnail-time` value to `poster-time` on `<mux-video>` or to `source.poster.time`. Set `width`, `height`, `fitMode`, `rotate`, and `ext` on `source.poster` to control image size, cropping, rotation, and format. Video.js converts those camel-case keys to the `snake_case` query parameters Mux expects. See [Add a poster and loading placeholder](./poster.md) for more examples or the [`<media-poster>`](../reference/components/poster.md) 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.
+Choose the smallest customization that meets your existing UI requirements: a packaged skin, its CSS variables, or editable skin source.
 
 ### 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](./skins.md).
+Video.js has three packaged skins. The Default skin groups settings in a menu. The Neutral skin has a compact layout like a classic player control bar. The Compat skin uses plain surfaces and basic controls for broader browser support. All three bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Skins](./skins.md).
 
 ### Level 2: restyle it
 
@@ -275,89 +306,127 @@ video-skin {
 }
 ```
 
-`--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](./customize-skins.md#style-a-packaged-skin) has the full list.
+`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces. Video.js picks a readable text color for content on the accent color. To choose that text color yourself, set `--media-accent-text-color`. `--media-border-radius` rounds the player’s corners. `--media-scale-unit` scales the whole control bar. [Customize skins](./customize-skins.md#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.
+The skins use a different visual design, so you may not need direct replacements for Mux Player’s primary and secondary colors. 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](./customize-skins.md#style-skin-source) covers the setup and available skins.
+For changes to controls, layout, or interactions, add the skin source to your project. Its TypeScript components and styles become local files that need a build step. A CDN-only page must add a build step before it can use this source. [Customize skins](./customize-skins.md#style-skin-source) covers the setup and available skins.
+
+To migrate `forward-seek-offset` and `backward-seek-offset`, edit the installed skin’s hotkey and gesture declarations.
 
-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:
+Replace the existing seek declarations, including the `j` and `l` shortcuts, with ones that use your offsets. These examples use 30 seconds forward and backward:
 
 ```html
 <media-hotkey keys="ArrowRight" action="seekStep" value="30"></media-hotkey>
 <media-hotkey keys="ArrowLeft" action="seekStep" value="-30"></media-hotkey>
+<media-hotkey keys="l" action="seekStep" value="30"></media-hotkey>
+<media-hotkey keys="j" action="seekStep" value="-30"></media-hotkey>
 <media-gesture type="doubletap" action="seekStep" value="30" region="right"></media-gesture>
+<media-gesture type="doubletap" action="seekStep" value="-30" region="left"></media-gesture>
 ```
 
-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](../reference/components/seek-button.md), which takes `seconds` and defaults to 30.
+Neither packaged video skin includes skip buttons. To keep those controls from Mux Player, add a [seek button](../reference/components/seek-button.md), which takes `seconds` and defaults to 30.
 
-Removing a control is removing a line. That’s the trade you get for the extra setup.
+To remove a control, remove it and its tooltip wrapper from the local controls layout.
 
-## Read player state
+## Read and control the player
 
-`<mux-video>` 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`.
+`<mux-video>` is a real media element, so every media event you already listen for still fires on it: `play`, `timeupdate`, `ended`, `error`, and the rest. Keep your Mux Player listeners. `<mux-video>` also fires `streamtypechange`, `targetlivewindowchange`, `sourcechange`, and `contentdatachange`.
 
 For UI state rather than media state, use [`PlayerController`](../reference/api/player-controller.md) 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';
+import { PlayerController, playerContext, selectTime, UIElement } from '@videojs/html';
 
-class MyElapsed extends ReactiveElement {
+class MyElapsed extends UIElement {
   #time = new PlayerController(this, playerContext, selectTime);
+
+  update(changed) {
+    super.update(changed);
+    this.textContent = `Elapsed: ${(this.#time.value?.currentTime ?? 0).toFixed(1)} s`;
+  }
 }
+
+customElements.define('my-elapsed', MyElapsed);
+```
+
+Render it inside your existing `<video-player>` so it can read that player’s state:
+
+```html
+<my-elapsed></my-elapsed>
 ```
 
 ### Drive playback
 
+Use the [player store](../reference/api/player-store.md) for state and actions:
+
 | Mux Player | Video.js v10 |
 | --- | --- |
-| `player.play()`, `player.pause()` | the player’s `play`, `pause`, `togglePaused`, or `media.play()`, `media.pause()` |
+| `player.play()`, `player.pause()` | the player’s `play` and `pause` actions, or `media.play()` and `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.volume` | Read `volume` from player state. Write it with `setVolume(value)`, which also unmutes for values above zero, or with `media.volume = value` to keep the mute state. |
+| `player.muted` | `muted` in player state; write with `setMuted(value)` |
 | `player.playbackRate` | the player’s `setPlaybackRate`, or `media.playbackRate` |
-| `player.requestFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen`, `toggleFullscreen` |
+| `player.requestFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen` |
 | `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.
+Standard media properties update player state through media events. If the volume is `0`, `setMuted(false)` also sets it to `0.25`. Mux Player’s smart-unmute behavior carries over through `setMuted(false)`. To unmute and keep a zero volume, set `media.muted` directly.
+
+Call actions on the player element’s `store` only after `player.store.target` is set, which means the media has attached. For example, wire seeking to a button:
+
+```html
+<button id="seek-to-ten" type="button">Seek to 10 seconds</button>
+
+<script type="module">
+  await customElements.whenDefined('video-player');
+  const player = document.querySelector('video-player');
+
+  document.querySelector('#seek-to-ten').addEventListener('click', () => {
+    if (!player.store.target) return;
+    player.store.seek(10);
+  });
+</script>
+```
+
+Store actions throw until the media attaches. Call fullscreen actions from a user interaction, such as a click handler.
 
 ## Which Mux media should you use?
 
-You can skip this section until you hit one of the two problems in it.
+Choose and test the engine before migration, especially when your catalog uses DRM or TS-packaged media.
 
-`<mux-video>` 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:
+`<mux-video>` supports two playback engines: SPF and hls.js. Choose the engine by import path. The `/spf` import is smaller, and `/hls-js` is more compatible. The default import currently uses hls.js. Start with that default:
 
 | 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. |
+| `.../media/mux-video/spf` | SPF | Your streams use fMP4/CMAF segments and fit the limitations below. |
+| `.../media/mux-video/hls-js` | hls.js | Your app depends on hls.js and needs its instance or 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:
+The SPF engine does not support MPEG-TS segments, raw ADTS AAC, or whole-segment AES-128 encryption. Keep the default for assets that need those formats. The SPF engine also lacks low-latency HLS support, and its DVR playback is experimental.
 
-- **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 support DRM through `source.drm`. Verify license exchange and playback with your protected assets on supported browsers before changing engines.
 
 All three imports register the same `<mux-video>` tag and accept the same source, so changing the engine is an import change. Load only one registration for that tag on a page.
 
-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 default import currently uses hls.js, but its engine can change in a future release. Use `/hls-js` when your app depends on hls.js APIs. Test the chosen engine with your assets and supported browsers.
 
-The Mux audio component follows the same three paths, and pairs with the audio player and audio skins.
+The Mux audio component has the same three import paths. Use it 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.
+Mux Player switches to live controls automatically. In Video.js, choose the live preset yourself.
 
 Register the live preset and Mux media. From the CDN:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/live-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/live-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/mux-video.js"></script>
 
 <live-video-player>
   <live-video-skin>
-    <mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8"></mux-video>
+    <mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"></mux-video>
   </live-video-skin>
 </live-video-player>
 ```
@@ -370,7 +439,9 @@ import '@videojs/html/live-video/skin';
 import '@videojs/html/media/mux-video';
 ```
 
-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](../reference/api/feature-live.md).
+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 reads the stream type from 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](../reference/api/feature-live.md).
+
+The live skins have no time slider. To preserve DVR scrubbing, add one to custom UI or installed skin source; follow [the DVR setup](./live-streams.md#dvr-let-users-scrub-back).
 
 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.
 
@@ -381,14 +452,14 @@ Use [`createPlayer`](../reference/api/html-create-player.md) to build a player e
 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.
 
 ```html
-<script type="module">
-  import '@videojs/html/ui/live-button';
-</script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/ui/live-button.js"></script>
 
 <media-live-button class="station-live-button">On air</media-live-button>
 ```
 
-Do not rebuild this behavior from `duration` or set `currentTime` to `Infinity`.
+With a bundler, import `@videojs/html/ui/live-button`. Render the button inside your custom player layout.
+
+Do not rebuild this behavior by reading `duration` or by setting `currentTime` to `Infinity`.
 
 ### Troubleshoot live playback
 
@@ -424,61 +495,65 @@ To find the times a viewer can seek to, read `buffer.seekable`. It contains `[st
 
 ## The settings menu
 
-On a video player, the settings menu appears on its own when there’s something to put in it:
+The video skins include a settings menu with the available quality, audio-track, captions, and playback-rate controls:
 
 | What | Component | Notes |
 | --- | --- | --- |
-| Quality | [Quality radio group](../reference/components/quality-radio-group.md) | Lets a viewer pick the video quality. To set the highest available quality instead, use `source.playback.maxResolution`. |
+| Quality | [Quality radio group](../reference/components/quality-radio-group.md) | Lets a viewer pick the video quality. Use `source.playback.maxResolution` to cap the stream’s available resolution; it does not force playback at that resolution. |
 | Audio tracks | [Audio track radio group](../reference/components/audio-track-radio-group.md) | For multi-language audio. |
 | Captions | [Captions radio group](../reference/components/captions-radio-group.md) | Rendered by the browser. |
 | Speed | [Playback rate radio group](../reference/components/playback-rate-radio-group.md) | 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](https://github.com/videojs/v10/issues/1404)). |
 
-Caption *styling* is limited to the positioning custom properties the skins expose. There’s no equivalent of a text-track settings dialog.
+When enabling captions without a previous selection in this player instance, `toggleSubtitles()` prefers a track matching `navigator.language`, then falls back to the first available caption or subtitle track. For an authored track that should show on load, add `default`. See [Show captions and subtitles](./captions.md).
+
+Video.js has no viewer-facing text-track settings dialog. You can style browser-rendered captions with `::cue`.
 
 ## 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](../reference/components/time-slider.md) and show the chapter title on hover:
+Add a chapters track with the `default` attribute inside your media. The skins then split the [time slider](../reference/components/time-slider.md) into chapter segments and show the chapter title on hover:
 
 ```html
-<mux-video src="https://stream.mux.com/EcHgOK9coz5K….m3u8">
+<mux-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8">
   <track kind="chapters" src="/chapters.vtt" default />
 </mux-video>
 ```
 
-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](https://github.com/videojs/v10/issues/1268)).
+To replace `addChapters()`, convert your chapter array to a WebVTT file and set its URL as the track’s `src` ([#1268](https://github.com/videojs/v10/issues/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](https://github.com/videojs/v10/issues/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](https://github.com/videojs/v10/issues/1442)).
 
 ## Signed playback and DRM
 
-**Signed playback works today.** Follow Mux’s [secure video playback guide](https://www.mux.com/docs/guides/secure-video-playback) 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:
+For signed playback, follow Mux’s [secure video playback guide](https://www.mux.com/docs/guides/secure-video-playback?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) to create a signing key and generate tokens on your server. In the example below, replace `YOUR_PLAYBACK_ID` with the signed asset’s playback ID. Replace each token placeholder with the matching server-generated token. Each token goes in its own group.
+
+Video.js checks the audience of poster, storyboard, and DRM tokens before building their URLs. It passes playback tokens through for Mux to validate. A misplaced playback token still produces a stream request that Mux rejects:
 
 ```js
 {
-  playbackId: 'EcHgOK9coz5K…',
-  playback: { token: '…' },   // audience: v
-  poster: { token: '…' },     // audience: t
-  storyboard: { token: '…' }, // audience: s
+  playbackId: 'YOUR_PLAYBACK_ID',
+  playback: { token: 'PLAYBACK_TOKEN' },   // audience: v
+  poster: { token: 'THUMBNAIL_TOKEN' },     // audience: t
+  storyboard: { token: 'STORYBOARD_TOKEN' }, // audience: s
 }
 ```
 
 Signed playback needs its own poster token even when the Mux media 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, the media 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](https://github.com/videojs/v10/issues/1432)).
+Neither player refreshes tokens. Mux Player detects an expired token and shows a message. Video.js does not report expired tokens yet ([#1432](https://github.com/videojs/v10/issues/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:
+For DRM on either Mux media flavor, supply a license token. Video.js derives the FairPlay, Widevine, and PlayReady license servers and the FairPlay application certificate:
 
 ```js
 {
-  playbackId: 'EcHgOK9coz5K…',
-  playback: { token: '…' },
-  drm: { token: '…' }, // audience: d
+  playbackId: 'YOUR_PLAYBACK_ID',
+  playback: { token: 'PLAYBACK_TOKEN' },
+  drm: { 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.
+DRM playback is always signed, so set both `source.drm.token` and `source.playback.token`. For content Mux does not license, add your own license servers to `source.drm`, keyed by key system. For each key system you configure, your server replaces the derived server.
 
-The SPF flavor doesn’t license DRM ([#1776](https://github.com/videojs/v10/issues/1776)), which is one of the two reasons to stay on the default import.
+The SPF flavor supports FairPlay, Widevine, and PlayReady through its EME license pipeline. DRM availability still depends on the browser, key system, and asset configuration.
 
 ## Access the media and playback engine
 
@@ -488,23 +563,23 @@ The SPF flavor doesn’t license DRM ([#1776](https://github.com/videojs/v10/iss
 | the hls.js instance | `.engine` on the `<mux-video>` element |
 | `prefer-playback` | `source.preferPlayback`, or pick [native HLS](../reference/components/native-hls-video.md) 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.
+`source.preferPlayback` is the closest mapping. To match `prefer-playback="native"`, set it to `'native'`. The Mux media then uses the browser’s built-in HLS support instead of building an MSE pipeline.
 
 > **Caution: Treat engine access as an escape hatch**
 >
 > Reading `.engine` couples your app to hls.js and the `/hls-js` flavor. Prefer Video.js state, events, and media APIs when they cover your use case. Reach into the engine only for functionality Video.js doesn’t expose.
 
-Program Date Time has no convenience surface: no `getStartDate()`, no `currentPdt`. The player exposes `liveEdgeStart` and `targetLiveWindow`; for PDT itself, reach into the engine.
+Video.js has no Program Date Time (PDT) helpers such as `getStartDate()` or `currentPdt`. The player exposes `liveEdgeStart` and `targetLiveWindow`. To read PDT, use the playback engine.
 
 ## Known gaps
 
-Ordered roughly by how many migrations they’ll touch.
+Check these limitations against your required features:
 
-- Two skins, against Mux Player’s five themes, and no runtime theme switch. That’s a deliberate trade, fewer skins whose files you can add to your project, but it’s a real difference if you shipped `theme="classic"`.
+- The two packaged skins do not reproduce Mux Player’s themes, and there is no runtime theme switch. Plan skin customization when preserving a theme such as `classic`.
 - Lazy loading (`loading="viewport|page"`) has no equivalent.
-- The controls auto-hide delay isn’t configurable ([#1728](https://github.com/videojs/v10/issues/1728)). Always-visible controls are available through `visibility="always"` on the controls component in a custom layout or a skin layout in your project.
-- Nothing persists between sessions: volume, captions language, speed, quality. That’s out of scope for GA ([#944](https://github.com/videojs/v10/issues/944)). Default subtitle language is tracked at [#1423](https://github.com/videojs/v10/issues/1423), though Mux users can set `source.playback.defaultSubtitlesLang` and let the HLS playlist decide.
-- Smaller conveniences without homes yet: debug mode ([#1406](https://github.com/videojs/v10/issues/1406)) and autoplay with a muted fallback ([#1039](https://github.com/videojs/v10/issues/1039)). Unmuting from zero volume already restores a sensible level, so Mux Player’s smart-unmute behavior carries over.
+- The controls auto-hide delay isn’t configurable ([#1728](https://github.com/videojs/v10/issues/1728)). For always-visible controls, set `visibility="always"` on the controls component in a custom layout or installed skin source.
+- Player preferences such as volume, captions language, speed, and quality are not persisted automatically ([#944](https://github.com/videojs/v10/issues/944)). Mux users can set `source.playback.defaultSubtitlesLang` so the HLS playlist sets the default subtitle language. For application-managed persistence, follow [Remember user preferences](./user-preferences.md).
+- Debug mode has no equivalent yet ([#1406](https://github.com/videojs/v10/issues/1406)).
 
 ## See also