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

package/docs/guides/migrate-from-plyr.md

@@ -2,20 +2,47 @@
 
 Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
 
-Video.js v10 is not a drop-in replacement for Plyr. Plyr wraps one media element with a constructor and options object. Video.js composes a player, media component, and skin in markup, then exposes behavior through [player state](./features.md).
+Replace Plyr’s constructor and options object with a Video.js player, media component, and skin. Read playback and UI state through [player state](./features.md).
 
-Start with the Minimal skin, move media settings into markup, and replace calls to the Plyr instance with native media APIs or Video.js state actions.
+Start with the Neutral skin, move media settings into markup, and replace calls to the Plyr instance with native media APIs or Video.js store actions.
+
+## AI Quickstart
+
+Paste this prompt into your coding agent:
+
+```
+Migrate this project's Plyr player to Video.js v10 for HTML. Use @videojs/html or its CDN bundles for a page without a build step.
+
+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.
+
+Read the migration guide at https://videojs.org/docs/framework/html/guides/migrate-from-plyr, 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.
+
+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.
+
+From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.
+
+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.
+
+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.
+
+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.
+```
 
 ## What changes
 
-- **The player becomes three pieces.** Player state, the media component, and the skin are separate, so you can replace one without wrapping or forking the others.
-- **Streaming behavior becomes player state.** HLS, DASH, and Mux integrations expose renditions, tracks, and live state to the UI instead of leaving that wiring to application code.
-- **The UI is composable.** Buttons, sliders, menus, gestures, and hotkeys are individual accessible components. Start with the Minimal or Default skin, then [add its source to your project](#edit-skin-source) when you need to change the structure.
-- **Remote playback is built in.** The video skins include AirPlay and Cast controls. Follow [Cast to AirPlay and Chromecast](./casting.md) to add the Google Cast extension.
+- **Player, media, and skin are separate.** Put source settings on the media, poster metadata on the player, and controls in the skin.
+- **HLS and DASH need a streaming media component.** Keep the playback engine your app requires; see [Streaming](#streaming).
+- **Controls are composed in a skin.** To migrate Plyr’s `controls`, hotkeys, or gestures, [edit skin source](#edit-skin-source).
+- **Casting needs setup.** The video skins include AirPlay and Cast buttons. The Cast button needs the Google Cast extension. Follow [Cast to AirPlay and Chromecast](./casting.md).
 
 > **Note**
 >
-> Video.js v10 is still moving toward GA. Features like ads, playlists, preference persistence, and cue-point APIs are active areas, so check [Known gaps](#known-gaps) when those features matter to your migration.
+> Check [Known gaps](#known-gaps) before replacing your player, especially if your app uses ads, persisted preferences, source-based quality selection, or fullscreen fallback. Keep your existing media URLs and track files when adapting the examples.
 
 ## Basic migration
 
@@ -40,73 +67,84 @@ const player = new Plyr('#player', {
 </script>
 ```
 
-The Minimal skin is the closest built-in starting point for this migration.
+The Neutral skin is the closest built-in starting point for this migration.
 
-The easiest path is the CDN:
+For an HTML page without a bundler, load the CDN preset:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video-minimal.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/video-neutral.js"></script>
 
 <video-player poster="/path/to/poster.jpg">
-  <video-minimal-skin>
+  <video-neutral-skin style="aspect-ratio: 16 / 9">
     <video src="/path/to/video.mp4" playsinline>
       <track kind="captions" label="English" src="/path/to/captions/en.vtt" srclang="en" default />
       <track kind="metadata" label="thumbnails" src="/path/to/storyboard.vtt" default />
     </video>
-  </video-minimal-skin>
+  </video-neutral-skin>
 </video-player>
 ```
 
-If you prefer not to use the CDN, you can use the individual modules:
+For a bundler installation, install the HTML package and import the player and skin:
+
+```bash
+npm install @videojs/html
+```
 
 ```js
 import '@videojs/html/video/player';
-import '@videojs/html/video/minimal-skin';
+import '@videojs/html/video/neutral-skin';
 ```
 
 ### Notes
 
-- The skin attaches its styles automatically to its shadow root.
-- The poster moves from `data-poster` on the media to `poster` on `<video-player>`. The skin reads that value and controls how the poster appears. For more advanced control (like supplying your own image element), see [Add a poster and loading placeholder](./poster.md).
-- There’s also a default skin with a modern, frosted appearance that some may prefer. Try it by removing the `-minimal` suffix from the script `src` if you’re using the CDN, or the `minimal-` prefix from the imports.
+- The skin adds its styles to its own shadow root. You do not link a stylesheet.
+- Remove `controls` from the media so the browser’s native controls do not appear beside the skin’s controls.
+- The poster moves from `data-poster` on the media to `poster` on `<video-player>`. The skin reads that value and controls how the poster appears. To supply your own image element, see [Add a poster and loading placeholder](./poster.md).
+- To use the Default skin, change `<video-neutral-skin>` to `<video-skin>`. From the CDN, load `video.js` instead of `video-neutral.js`. With a bundler, replace the Neutral skin import with `@videojs/html/video/skin`.
+
+If caption or thumbnail tracks come from a different origin than the page, set `crossorigin="anonymous"` on the media (`crossOrigin="anonymous"` in React). Also serve the media and track files with CORS headers that allow your page’s origin. See [Thumbnail](../reference/components/thumbnail.md).
 
 ## Map common features
 
 ### Streaming
 
-If you’re using HLS or DASH to stream your media, you’re in luck; we have prebuilt [media components](./media-sources.md) you can slot in with much improved integration over Plyr implementations.
+For HLS or DASH, replace the native video component with a [media component](./media-sources.md) for that format. Check that the component’s engine supports your stream before you choose it.
 
 #### HLS
 
-Replace `<video>` with `<hls-video>`. If you’re using the CDN, add an additional script:
+If your Plyr integration uses hls.js, keep it by using the hls.js video component. The installation CLI’s `--media hls` option selects this component.
+
+The SPF [HLS video](../reference/components/hls-video.md) component is an alternative for fMP4/CMAF streams. It does not support MPEG-TS segments, raw ADTS AAC, or whole-segment AES-128 encryption. It supports DRM through `source.drm`. Verify your license configuration and browser support with the engine you choose before switching.
+
+Replace `<video>` with `<hlsjs-video>`. If you’re using the CDN, add an additional script:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/hls-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/hlsjs-video.js"></script>
 ```
 
-For a package-manager installation, install SPF and add its façade import:
+For a bundler installation, install the adapter package and add the media import:
 
 ```bash
-npm install @videojs/html @videojs/spf
+npm install @videojs/html @videojs/hlsjs-video
 ```
 
 ```js
-import '@videojs/html/media/hls-video';
+import '@videojs/html/media/hlsjs-video';
 ```
 
-Set the `src` to the URL for the m3u8 manifest.
+Set `src` to your `.m3u8` manifest URL.
 
 #### DASH
 
-Very similar to HLS in that we have a drop-in component.
+Use the DASH media component for an unprotected DASH source. For DRM-protected DASH, use [Shaka video](../reference/components/shaka-video.md) and configure `source.drm`; the dash.js component has no DRM configuration input. See [the DRM migration example](./migrate-from-video-js-8.md#drm).
 
 Replace `<video>` with `<dash-video>`. If you’re using the CDN, add an additional script:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/dash-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/dash-video.js"></script>
 ```
 
-For a package-manager installation, install dash.js and add its façade import:
+For a package-manager installation, install the DASH adapter package and add the media import:
 
 ```bash
 npm install @videojs/html @videojs/dash-video
@@ -116,13 +154,19 @@ npm install @videojs/html @videojs/dash-video
 import '@videojs/html/media/dash-video';
 ```
 
-Set the `src` to the URL for the mpd manifest.
+Set `src` to your `.mpd` manifest URL.
 
 ### Vimeo
 
-Vimeo is supported through a prebuilt component.
+Use the Vimeo media component for your existing Vimeo source.
 
-Replace `<video>` with `<vimeo-video>` and add the module import:
+Replace `<video>` with `<vimeo-video>`. For a CDN installation, add the media script:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/vimeo-video.js"></script>
+```
+
+For a bundler installation, install the adapter package and add the module import:
 
 ```bash
 npm install @videojs/html @videojs/vimeo-video
@@ -136,9 +180,19 @@ Set the `src` to the URL for the Vimeo video, for example `https://vimeo.com/769
 
 ### YouTube
 
-YouTube is supported through a first-class media component.
+Use the YouTube media component for your existing YouTube source.
+
+Replace `<video>` with `<youtube-video>`. For a CDN installation, add the media script:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/media/youtube-video.js"></script>
+```
+
+For a bundler installation, install the adapter package and add the module import:
 
-Replace `<video>` with `<youtube-video>` and add the module import:
+```bash
+npm install @videojs/html @videojs/youtube-video
+```
 
 ```js
 import '@videojs/html/media/youtube-video';
@@ -146,27 +200,23 @@ import '@videojs/html/media/youtube-video';
 
 ```html
 <video-player>
-  <video-minimal-skin>
+  <video-neutral-skin>
     <youtube-video src="https://youtu.be/aqz-KE-bpKQ" playsinline></youtube-video>
-  </video-minimal-skin>
+  </video-neutral-skin>
 </video-player>
 ```
 
-The component accepts YouTube watch, short, embed, Shorts, live, playlist, and privacy-enhanced URLs, as well as raw 11-character video IDs.
+The component accepts YouTube watch, `youtu.be` short-link, embed, Shorts, live, playlist, and privacy-enhanced (`youtube-nocookie.com`) URLs, as well as raw 11-character video IDs.
 
 ### Internationalization
 
-Video.js v10 ships with English labels by default and includes locale packs for:
+Video.js defaults to English. To migrate Plyr’s `i18n` strings, register translation overrides or pass them to a provider. For shipped locales and language selection, follow [Internationalize the player](./internationalization.md).
 
-`ar`, `az`, `bg`, `bn`, `bs`, `ca`, `cs`, `cy`, `da`, `de`, `el`, `es`, `et`, `eu`, `fa`, `fi`, `fr`, `gd`, `gl`, `he`, `hi`, `hr`, `hu`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `mr`, `nb`, `ne`, `nl`, `nn`, `oc`, `pl`, `pt-BR`, `pt-PT`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `te`, `th`, `tr`, `uk`, `vi`, `zh-CN`, and `zh-TW`.
-
-The shorthand tags `pt` and `zh` are also available as aliases. See [Internationalize the player](./internationalization.md) for the full picture.
-
-For CDN users:
+To select a locale, wrap the player in `<media-i18n>` and set `lang` to your locale tag, such as `lang="ja"`. The CDN preset registers this element. With a bundler, import `@videojs/html/i18n` to register it. For English overrides from the CDN:
 
 ```html
 <script type="module">
-  import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/i18n.js';
+  import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/i18n.js';
 
   registerI18n('en', {
     buttons: {
@@ -179,49 +229,49 @@ For CDN users:
   });
 </script>
 
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video-minimal.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/video-neutral.js"></script>
 
 <video-player>
-  <video-minimal-skin>
+  <video-neutral-skin>
     <video src="/video.mp4" playsinline></video>
-  </video-minimal-skin>
+  </video-neutral-skin>
 </video-player>
 ```
 
-For package users, same idea but import from `@videojs/html/i18n`.
+With a bundler, import `registerI18n` from `@videojs/html/i18n`.
 
 ## Configuration
 
-Plyr uses an object to set configuration options whereas Video.js v10 uses a component structure and attributes instead. We’re using a composition model rather than a configuration model. This reduces bundle size and only includes functionality you actually require.
-
-Here’s a matrix for configuration options in Plyr and how each maps to Video.js v10:
+Move media options to attributes or props. For controls and interactions, use a skin or [edit its installed source](#edit-skin-source). Where the table says to edit local skin source, it means those installed files:
 
 | Plyr option | Video.js v10 |
 | --- | --- |
-| `controls` | The [skins](./skins.md) include the common controls, laid out in a familiar way that users would expect. Not every Plyr control ships in every skin—the video skins do not include `rewind` and `fast-forward` buttons, for example. To change which controls appear, or to customize the skin beyond basic colors, [add the skin source to your project](#edit-skin-source) and change controls, layout, styles, or icons. |
-| `rewind`, `fast-forward`, `seekTime` | The audio skins include 10-second skip buttons; the video skins do not. [Add the skin source to your project](#edit-skin-source), then add a [seek button](../reference/components/seek-button.md), which skips by its `seconds` value (default `30`; negative values seek backward). |
-| `settings` | Included automatically in the skins when quality, speed, audio tracks, or captions are available. |
-| `autoplay`, `muted`, `loop`, `playsinline`, `preload` | These are attributes on your media (e.g. `<video>`) component. |
+| `controls` | Choose a [skin](./skins.md) with the controls you need, or edit local skin source. Video skins do not include `rewind` or `fast-forward` buttons. |
+| `rewind`, `fast-forward`, `seekTime` | The audio skins include 10-second skip buttons; the video skins do not. In local skin source, add a [seek button](../reference/components/seek-button.md), which skips by its `seconds` value (default `30`; negative values seek backward). |
+| `settings` | The skins show a settings menu automatically when quality, speed, audio tracks, or captions are available. |
+| `autoplay`, `muted`, `loop`, `playsinline`, `preload` | Set these on the media. For video-backed React media, use `autoPlay` and `playsInline`; the other names stay the same. YouTube and Vimeo use `autoplay`. |
 | `poster` / `data-poster` | Set `poster` on the player. See [Basic migration](#basic-migration). |
 | `ratio` | Set `aspect-ratio` in CSS on the skin component. |
-| `hideControls` | Preset skins auto-hide controls based on activity. `hideControls: false` maps to `visibility="always"` on the controls component in a custom or installed skin layout; the delay is currently not configurable. |
-| `clickToPlay` | Preset video skins include click and tap gestures. [Add the skin source to your project](#edit-skin-source) to remove or change them. |
-| `keyboard` | Preset video skins include common hotkeys. [Add the skin source to your project](#edit-skin-source) to remove or change them. |
-| `tooltips` | Preset skins include tooltips for common controls. [Add the skin source to your project](#edit-skin-source) to customize them. |
+| `hideControls` | Preset skins hide controls after inactivity. For `hideControls: false`, set `visibility="always"` on the controls component in a custom layout or installed skin source. The hide delay is not configurable yet. |
+| `clickToPlay` | Preset video skins include click and tap gestures. Edit local skin source to remove or change them. |
+| `keyboard` | Preset video skins include common hotkeys. Edit local skin source to remove or change them. For `keyboard.global: true`, set `target="document"` on the hotkey components. |
+| `tooltips` | Preset skins include tooltips for common controls. Edit local skin source to customize them. |
 | `captions` | Add `<track kind="captions">` or `<track kind="subtitles">`; preset skins show captions controls when tracks are available. |
 | `previewThumbnails` | Add `<track kind="metadata" label="thumbnails">`; preset video skins show slider thumbnails when thumbnail cues are available. |
-| `quality` | Works when the media provider exposes renditions. Plain MP4 source arrays do not currently become a quality menu automatically. |
-| `speed` | Included in the preset settings menu when playback rates are available. |
-| `fullscreen` | Native fullscreen is supported; Plyr’s full-window fallback is not a matching feature. |
+| `quality` | The quality menu appears when the media exposes renditions, such as HLS or DASH. Plain MP4 source arrays do not currently become a quality menu automatically. |
+| `speed` | The preset settings menu uses a fixed rate list; `speed.options` does not carry over. See [Known gaps](#known-gaps). |
+| `fullscreen` | Native fullscreen is supported. Video.js has no equivalent of Plyr’s full-window fallback. |
 | `provider: 'vimeo'` | Use the Vimeo media component inside the player skin as shown in [Vimeo](#vimeo) above. |
 | `provider: 'youtube'` | Use the YouTube media component inside the player skin as shown in [YouTube](#youtube) above. |
-| `storage` | Unsupported at this time. |
-| `i18n` | The most common languages are available by default but you can also provide custom translations, if required. See [Internationalization](#internationalization) above for more info. |
+| `storage` | Persist preferences in your app; see [Remember user preferences](./user-preferences.md). |
+| `i18n` | English is the default. Select a locale with an i18n provider or provide custom translations. See [Internationalization](#internationalization). |
 | `ads` | Unsupported at this time. |
 
+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).
+
 ## Customize the controls
 
-Plyr’s `controls` option chooses which controls appear. Video.js skins come with their own control set and layout. Keep the skin when that UI fits your player. To remove, reorder, or restyle its controls, [add the skin source to your project](#edit-skin-source) and edit it. Adding a child to a skin does not place it inside the control bar.
+Plyr’s `controls` option chooses which controls appear. Video.js skins come with their own control set and layout. Keep the skin when that UI fits your player. To remove, reorder, or restyle its controls, [add the skin source to your project](#edit-skin-source) and edit it. A component you add as a child of a packaged skin does not appear in its control bar.
 
 If your app already has a custom control bar, build it from individual [UI components](./ui-components.md). Video.js handles the media action, accessible name, and state. You add the visible contents, layout, and CSS.
 
@@ -229,33 +279,72 @@ Individual HTML buttons include no text, icon, or finished styling. Add your own
 
 ## Use the imperative API
 
-Control everything through the player’s store. Every Plyr call has a matching store action, so one mental model covers playback, volume, fullscreen, and captions alike:
+Use [store actions](../reference/api/player-store.md) for playback, seeking, volume, fullscreen, and captions:
 
-| Plyr | Video.js v10 store action |
+| Plyr | Video.js v10 |
 | --- | --- |
-| `player.play()`, `player.pause()` | `play()`, `pause()`, or `togglePaused()` |
+| `player.play()`, `player.pause()` | `play()`, `pause()` |
 | `player.currentTime = 10` | `seek(10)` |
-| `player.volume = 0.5` | `setVolume(0.5)` |
-| `player.muted = true` | `toggleMuted()` |
+| `player.volume = 0.5` | `setVolume(0.5)`, which also unmutes |
+| `player.muted = true` | `setMuted(true)` |
 | `player.speed = 1.5` | `setPlaybackRate(1.5)` |
-| `player.fullscreen.enter()` | `requestFullscreen()` |
+| `player.fullscreen.enter()`, `player.fullscreen.exit()` | `requestFullscreen()`, `exitFullscreen()` |
+| `player.fullscreen.toggle()` | `isFullscreen ? exitFullscreen() : requestFullscreen()` |
 | `player.toggleCaptions()` | `toggleSubtitles()` |
 
-You can still script the media element directly when you want to. Plyr routed calls through its wrapper because the wrapper had to know about every change; Video.js derives player state from the native media events, so `video.play()` or `video.currentTime = 10` keeps every control in sync. The media element is also the way to change content: set `src` on the media component to swap sources, and replace the component when the media type changes, such as moving from `<video>` to `<hls-video>`. The player UI follows the attached media.
+Plyr’s [volume setter](https://github.com/sampotts/plyr/blob/v3.8.4/src/js/plyr.js#L507-L542) unmutes for values above zero, as `setVolume` does. Set `media.volume` directly only when you intend to preserve mute state.
+
+If the volume is `0`, `setMuted(false)` also sets it to `0.25`. To unmute and keep a zero volume, set `media.muted` directly.
+
+Native media methods and properties also update player state through media events. To change content, set `src` on the media component. If the new source needs a different playback engine, replace the element, such as moving from `<video>` to `<hlsjs-video>`. The player UI follows the attached media.
+
+Call store actions after the player is defined and media is attached:
+
+```html
+<button id="toggle-playback" type="button">Toggle playback</button>
+
+<script type="module">
+  await customElements.whenDefined('video-player');
+  const player = document.querySelector('video-player');
+
+  document.querySelector('#toggle-playback').addEventListener('click', () => {
+    if (!player.store.target) return;
+
+    if (player.store.paused) {
+      player.store.play();
+    } else {
+      player.store.pause();
+    }
+  });
+</script>
+```
 
-The store’s actions live on the player element’s `store.state`: query `<video-player>` and call `player.store.state.togglePaused()`. Your media element is also a plain child in your markup, so you can query and drive it directly. To keep a custom element in sync with player state, use [`PlayerController`](../reference/api/player-controller.md):
+To keep a custom element in sync with player state, use [`PlayerController`](../reference/api/player-controller.md):
 
 ```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>
 ```
 
 ## Rewrite styles
 
-Video.js v10 skins offer similar color customization via CSS custom properties. [Add the skin source to your project](#edit-skin-source) when you need deeper control over layout, control structure, icons, or interaction styling.
+Like Plyr, Video.js skins let you customize colors with CSS custom properties. [Add the skin source to your project](#edit-skin-source) when you need deeper control over layout, control structure, icons, or interaction styling.
 
 ```css
 /* Plyr */
@@ -271,20 +360,21 @@ video-player {
 }
 ```
 
-`--media-accent-color` reaches the sliders, active buttons, and accent surfaces, so it’s the closest match for Plyr’s `--plyr-color-main`. Video.js picks a readable text color to sit on top of it; set `--media-accent-text-color` to choose that yourself. `--media-border-radius` and `--media-scale-unit` cover rounding and control sizing. See [Customize skins](./customize-skins.md#style-a-packaged-skin) for the full list.
+`--media-accent-color` reaches the sliders, active buttons, and accent surfaces, so it’s the closest match for Plyr’s `--plyr-color-main`. 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` and `--media-scale-unit` cover rounding and control sizing. See [Customize skins](./customize-skins.md#style-a-packaged-skin) for the full list.
 
 ## Edit skin source
 
-For changes to controls, layout, or icons, 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 icons, 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.
 
 ## Known gaps
 
 - Plyr’s `ads` option has no built-in equivalent.
-- Plyr’s `storage` option has no built-in equivalent for persisted volume, captions language, muted state, speed, or quality. Player setting persistence is tracked in [#944](https://github.com/videojs/v10/issues/944); subtitle language preference is tracked in [#1423](https://github.com/videojs/v10/issues/1423).
-- Plyr’s full-window fullscreen fallback has no matching Video.js feature. This was designed as a fallback when the Fullscreen API wasn’t supported, but given [browser support for fullscreen is around 96%](https://caniuse.com/fullscreen), it’s unlikely to be required.
-- Plain MP4 source arrays with `size` metadata do not automatically create a quality menu. Use Mux, HLS, or DASH for adaptive quality when possible. A simpler source-driven quality menu may be considered later.
-- Preset skins segment the time slider and show chapter titles when the media includes a default `<track kind="chapters">`. Dedicated cue-point APIs are not complete yet; see [#1442](https://github.com/videojs/v10/issues/1442).
-- The controls auto-hide delay is not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728)). Disabling auto-hide is possible with `visibility="always"` on the controls component, but not from a preset skin’s attributes.
+- Plyr’s `storage` option has no built-in equivalent for persisted volume, captions language, muted state, speed, or quality. Player setting persistence is tracked in [#944](https://github.com/videojs/v10/issues/944). For application-managed persistence, follow [Remember user preferences](./user-preferences.md).
+- Playback rates are fixed at `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, and `2`. Plyr’s `speed.options` has no equivalent yet ([#1404](https://github.com/videojs/v10/issues/1404)).
+- Plyr’s full-window fullscreen fallback has no matching Video.js feature. Test fullscreen on your supported browsers; see [Browser support](./browser-support.md).
+- Plain MP4 source arrays with `size` metadata do not automatically create a quality menu. Use Mux, HLS, or DASH for adaptive quality when possible.
+- Preset skins segment the time slider and show chapter titles when the media includes a default `<track kind="chapters">`. Cue points are not implemented yet; see [#1442](https://github.com/videojs/v10/issues/1442).
+- The controls auto-hide delay is not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728)). To disable auto-hide, set `visibility="always"` on the controls component in a custom layout or installed skin source. Packaged skins do not expose this setting.
 - Native controls are not automatically removed when custom controls load; see [#1160](https://github.com/videojs/v10/issues/1160).
 
 ## Related pages