@videojs/react 10.0.0-beta.31 → 10.0.0-beta.32

package/docs/how-to/migrate-from-mux-player.md

@@ -2,11 +2,13 @@
 
 Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
 
-Mux Player is one element that does everything. You drop in `<mux-player>` with a playback ID and you get HLS playback, a themed UI, analytics, captions, Chromecast, AirPlay, and keyboard shortcuts, all wired together.
+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 integrations.
 
-Video.js v10 asks you to name the pieces you want. That sounds like more work, and for the first five minutes it is. In exchange, the player you ship only contains what you asked for, and when you need to change how something behaves you can open it up instead of hoping there’s an attribute for it.
+This guide moves a working Mux Player embed to those pieces, then maps the settings and APIs you are most likely to need next.
 
-This guide walks you from a working Mux Player embed to a working Video.js player, then covers the things you’ll reach for next.
+Tip
+
+Did you use Mux Player without controls as a hero, ambient loop, or decorative video? Go to [Add a background video](./add-a-background-video.md). It starts with a browser-playable video file, then covers the HLS and Mux background components.
 
 ## Three pieces instead of one
 
@@ -60,7 +62,7 @@ bash
 npm install @videojs/react
 ```
 
-One new idea here. Instead of one component that does everything, you pick a [preset](../concepts/presets.md) that matches what you’re building. A preset is a player, a skin, and a media element that already fit together. `@videojs/react/video` is the general-purpose one, and it’s what you want unless you’re doing something unusual.
+Start with the general-purpose `@videojs/react/video` [preset](../concepts/presets.md), then add the Mux media and analytics components:
 
 tsx
 
@@ -74,10 +76,17 @@ import { MuxVideo } from '@videojs/react/media/mux-video';
 
 export function MyPlayer() {
   return (
-    <VideoPlayer>
-      <VideoSkin className="aspect-video" poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2">
-        <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} playsInline crossOrigin="anonymous" />
-        <MuxData playerSoftwareName="my-app" metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }} />
+    <VideoPlayer title="Test VOD">
+      <VideoSkin className="aspect-video">
+        <MuxVideo
+          source={{ playbackId: 'EcHgOK9coz5K…', poster: { time: 2 } }}
+          playsInline
+          crossOrigin="anonymous"
+        />
+        <MuxData
+          playerSoftwareName="my-app"
+          metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }}
+        />
       </VideoSkin>
     </VideoPlayer>
   );
@@ -88,18 +97,41 @@ export function MyPlayer() {
 
 The `'use client'` directive is there because the player owns browser state.
 
+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 `MuxData` component shown above. Keep it when you want a behaviorally equivalent migration; omit it only when you intend to stop monitoring.
+
 A few things worth calling out:
 
-*   **The poster is yours to build.** Mux Player derived one from the playback ID; here you point the skin at an `image.mux.com` URL, and `thumbnail-time="2"` becomes `?time=2`. [`MuxVideo`](../reference/mux-video.md) derives the same URL and reports it, but the poster is a skin concern today, so nothing reads it for you.
+*   **MuxVideo 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 MuxVideo. Set `poster` on the player only when you want to use your own URL.
 *   **You didn’t add a storyboard track, and you get hover previews.** The Mux media adds and maintains the thumbnail track itself, and removes it for live streams, where storyboards don’t exist.
 *   **Analytics needs no environment key.** Mux resolves the environment from the playback ID. See [Mux Data](../concepts/mux-data.md).
-*   **Set the aspect ratio yourself,** in your own CSS on the skin. There’s no `ratio` attribute, because sizing belongs to your layout.
+*   **Chromecast is opt-in.** Follow [Cast to AirPlay and Chromecast](./cast-to-airplay-and-chromecast.md) when you want it; leave the integration out when you don’t.
+
+### Move your layout styles
+
+Mux Player was one visible, measurable element. Video.js separates player state from the visible surface.
+
+If you use `VideoSkin`, put width, height, aspect ratio, positioning, and DOM measurements on `VideoSkin`. The `skin.css` import shown above makes the media, controls, poster, and overlays fill and layer within it. `VideoPlayer` renders no DOM element of its own.
 
-Two things are opt-in that used to be automatic. Analytics is the [Mux Data](../reference/mux-data.md) component, and Chromecast is a [Cast](../concepts/cast.md) component. Leave either out and you don’t ship its code. That, incidentally, is the answer to Mux Player’s `disable-tracking`: don’t include Mux Data.
+If you leave out `VideoSkin` to build your own UI, add a [`Container`](../reference/player-container.md). Style and measure that element, and put overlays inside it:
+
+tsx
+
+```
+import { Container } from '@videojs/react';
+
+<VideoPlayer>
+  <Container style={{ position: 'relative', width: '100%', aspectRatio: '16/9' }}>
+    <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />
+    <MyOverlay />
+  </Container>
+</VideoPlayer>
+```
 
 Note
 
-There are no `on*` props, which is the one part of a React migration that takes real work. See [Read player state](#read-player-state).
+Put standard media handlers such as `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` on `MuxVideo`. Use [`usePlayer`](../reference/use-player.md) for player-store state. See [Read player state](#read-player-state).
 
 ## Mux settings live in a source object
 
@@ -183,11 +215,11 @@ Video.js v10
 
 `thumbnail-time`
 
-`?time=` on the poster URL you build
+`source.poster.time`
 
 poster size, crop, rotation, format
 
-query parameters on that URL
+`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.
 
@@ -231,14 +263,30 @@ Your metadata keys don’t change. They’re the same `snake_case` names Mux Dat
 
 ## Titles and posters
 
-`metadata-video-title` quietly did two jobs in Mux Player. It labelled the video for analytics, and it was the title the viewer read. Those are separate now, which is worth knowing before you go looking for the one attribute that used to do both:
+Mux Player used the same title for analytics and on-screen display. Video.js separates them.
+
+For analytics, use `metadata.video_title` on the Mux Data component.
 
-*   For analytics, it’s `metadata.video_title` on the Mux Data component.
-*   For display, it’s `content-title` on the player.
+For display, use `title` on the player.
 
-`content-title` reaches player state, so your own UI can read it. No packaged skin draws it, so setting it alone won’t put a title on screen ([#1123](https://github.com/videojs/v10/issues/1123)).
+The title reaches player state, but the packaged skins don’t place it in their layouts. Add the [Title](../reference/title.md) component as a child of a packaged skin, or place it in an ejected or custom layout, when you want viewers to see it:
 
-The poster is a skin concern. Build an `image.mux.com` URL and hand it over:
+tsx
+
+```
+import { Title } from '@videojs/react';
+import { VideoPlayer, VideoSkin } from '@videojs/react/video';
+
+<VideoPlayer title="Test VOD">
+  <VideoSkin>
+    <Title />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+`MuxVideo` 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:
+
+A generated poster becomes available after `MuxVideo` mounts. Pass `poster` to `VideoPlayer` when the image must appear in server-rendered HTML.
 
 jsx
 
@@ -259,7 +307,7 @@ jsx
 
 `renderPoster` customizes the poster image, so its background can show Mux Player’s `placeholder` while the real poster loads.
 
-Mux serves the poster from its `thumbnail` endpoint, so every Mux Player poster attribute becomes a query parameter you append: `thumbnail-time` is `?time=`, and the size, crop, rotation, and format options work the same way. See [Add a poster placeholder](./add-a-poster-placeholder.md) for more examples or the [Poster](../reference/poster.md) reference for the component itself.
+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](./add-a-poster-and-loading-placeholder.md) for more examples or the [Poster](../reference/poster.md) reference for the component itself.
 
 ## Customize your player
 
@@ -271,24 +319,28 @@ Two are packaged. The default skin is a modern, frosted look. The minimal skin i
 
 ### Level 2: restyle it
 
-Set custom properties. The common case, a brand color:
+Set custom properties on the skin. The common case is a brand color:
 
-css
+Give the skin a class you own:
+
+tsx
 
 ```
-/* Mux Player */
-mux-player {
-  --accent-color: rebeccapurple;
-}
+<VideoSkin className="my-player-skin">...</VideoSkin>
+```
+
+css
 
-/* Video.js v10 */
-video-skin {
+```
+.my-player-skin {
   --media-accent-color: rebeccapurple;
 }
 ```
 
 `--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces. Video.js derives a readable text color to sit on top of it; override that with `--media-accent-text-color` if you’d rather choose. `--media-border-radius` rounds the player, and `--media-scale-unit` scales the whole control bar at once. [Customize skins](./customize-skins.md) 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 eject the skin, only when you need a closer palette match.
+
 ### Level 3: eject
 
 **Ejecting** means copying the skin’s source into your project and editing it, the way you would a shadcn component. The packaged skin isn’t compiled magic; it’s a tree of components, so ejecting starts as copy and paste. [Customize skins](./customize-skins.md) has copy-paste-ready implementations for every packaged skin.
@@ -309,7 +361,7 @@ Removing a control is removing a line. That’s the trade you get for the extra
 
 ## Read player state
 
-There are **no `on*` props**. Read state through the preset’s [`usePlayer`](../reference/use-player.md) hook, typed to that preset’s features:
+Standard media event props port directly to `MuxVideo`: `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` work on the rendered video element. Read player-store state through the preset’s [`usePlayer`](../reference/use-player.md) hook, typed to that preset’s features:
 
 tsx
 
@@ -324,9 +376,7 @@ function Elapsed() {
 
 Every feature has a selector (`selectPlayback`, `selectTime`, `selectVolume`, `selectQuality`, `selectLive`, `selectTextTrack`, and so on) for when you want a whole slice rather than one value.
 
-Be honest with yourself about this one when you plan the work. If your app leans on `onPlay`, `onTimeUpdate`, `onEnded`, and `onError`, there’s no line-by-line port; those become hooks, or listeners you attach to a `ref` on the media component.
-
-For raw media events, attach listeners to a `ref`. The Mux media is a real media element underneath, so `play`, `timeupdate`, `ended`, and `error` all fire on it.
+Use a ref for imperative browser media APIs or for custom events that do not have React event props, such as `sourcechange`. The ref value is the rendered `HTMLVideoElement`.
 
 ### Drive playback
 
@@ -401,13 +451,14 @@ The default doesn’t promise which engine it uses, which is what leaves it free
 
 The Mux audio component follows the same three paths, and pairs with the audio player and audio skins.
 
-## Live streams and the settings menu
+## Live streams
 
-Live streams use a different player and skin, because live has different state and a different UI.
+Unlike Mux Player, you’ll have to pick a live preset yourself; it won’t switch automatically for you.
 
 tsx
 
 ```
+import '@videojs/react/live-video/skin.css';
 import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
 import { MuxVideo } from '@videojs/react/media/mux-video';
 
@@ -418,13 +469,69 @@ import { MuxVideo } from '@videojs/react/media/mux-video';
 </LiveVideoPlayer>
 ```
 
-You get `streamType`, `targetLiveWindow`, and `liveEdgeStart` in state, plus a live button that jumps to the live edge. See [the live feature](../reference/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 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/feature-live.md).
+
+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.
+
+Use [`createPlayer`](../reference/create-player.md) to create a `Player` component and matching `usePlayer` hook.
+
+### Add your own jump-to-live button
+
+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.
+
+tsx
+
+```
+import { LiveButton } from '@videojs/react';
+
+<LiveButton className="station-live-button">On air</LiveButton>
+```
+
+Do not rebuild this behavior from `duration` or set `currentTime` to `Infinity`.
+
+### Troubleshoot live playback
+
+#### An on-demand video shows live controls
+
+Video.js does not replace the preset after reading the HLS playlist. Render the video preset for on-demand content and the live preset for live content. If the same part of your app handles both, choose the preset from application or content metadata before rendering. If only the manifest can tell you, use a custom player with the stream type feature and choose the controls from that state.
+
+#### `selectStreamType` returns `undefined`
+
+The live preset does not include the [stream type feature](../reference/feature-stream-type.md). Add `streamTypeFeature` to a custom player when you need `streamType` in player state.
+
+The HLS media object also reads `'live'` or `'on-demand'` from the playlist. In React, get that object with [`useMedia`](../reference/use-media.md). In HTML, read `streamType` from `<mux-video>`.
+
+#### A live stream has a finite duration
+
+The browser may report `Infinity` for live playback, but the player’s [time feature](../reference/feature-time.md) reports the end of the available video. That number stays finite and moves forward with the stream.
+
+Do not use `duration` to decide whether a source is live. Read `streamType`, or check that `targetLiveWindow` is not `NaN`.
+
+#### `targetLiveWindow` does not match the rewind time
+
+Despite its name, `targetLiveWindow` does not report a number of seconds. It describes the kind of live stream:
+
+Value
+
+Meaning
+
+`0`
 
-The live composition is narrower than the video one on purpose: it leaves out quality, audio-track, and playback-rate state, none of which apply cleanly to a stream with no fixed duration. So a live skin’s settings menu holds captions and nothing else. If you need one of the others on a live player, build your own player from a feature list rather than taking the preset’s.
+A sliding live window
 
-That’s what [`createPlayer`](../reference/create-player.md) is for. Hand it a feature list and you get back a `Player` component and a `usePlayer` hook, the same pair every preset is built from.
+`Infinity`
 
-### The settings menu
+A live event with playback history
+
+`NaN`
+
+On-demand or not known yet
+
+To find the times a viewer can seek to, read `buffer.seekable`. It contains `[start, end]` pairs. The first start is the oldest available time, and the last end is the newest. Both move forward on a sliding live stream.
+
+`liveEdgeStart` is the playback time where the player starts treating the viewer as live. The live button seeks to the last end in `buffer.seekable`, which may be later than `liveEdgeStart`.
+
+## The settings menu
 
 On a video player, the settings menu appears on its own when there’s something to put in it:
 
@@ -438,7 +545,7 @@ Quality
 
 [Quality radio group](../reference/quality-radio-group.md)
 
-Lets a viewer pick a rendition. To cap the manifest instead, use `source.playback.maxResolution`.
+Lets a viewer pick the video quality. To set the highest available quality instead, use `source.playback.maxResolution`.
 
 Audio tracks
 
@@ -474,11 +581,11 @@ jsx
 
 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)).
 
-Two gaps to plan around. The player exposes `chaptersCues` as a read-only array, but there’s no active-chapter state and no `chapterchange` event, and no menu to jump between chapters ([#1873](https://github.com/videojs/v10/issues/1873)). If your app highlights the current chapter in its own UI, derive it from `currentTime` and `chaptersCues`. Cue points aren’t implemented at all ([#1442](https://github.com/videojs/v10/issues/1442)).
+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.** 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:
+**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:
 
 js
 
@@ -491,6 +598,8 @@ js
 }
 ```
 
+Signed playback needs its own poster token even when MuxVideo 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, MuxVideo 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)).
 
 **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:
@@ -509,7 +618,7 @@ DRM playback is always signed, so `drm.token` needs a `playback.token` beside it
 
 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.
 
-## Escape hatches
+## Access the media and playback engine
 
 Mux Player
 
@@ -517,11 +626,15 @@ Video.js v10
 
 `media.nativeEl`
 
-a `ref` on the media component, then `.target`
+`ref.current` from a `ref` on the media component
+
+the Video.js media object
+
+[`useMedia()`](../reference/use-media.md) inside the player
 
 the hls.js instance
 
-`.host.engine` through that same `ref`, on the hls.js-backed flavor
+the media object’s `.engine`, reached through [`useMedia`](../reference/use-media.md), on the hls.js-backed flavor
 
 `prefer-playback`
 
@@ -529,25 +642,38 @@ the hls.js instance
 
 `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.
 
+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.
+
+The media component’s React ref is the native `HTMLVideoElement`; it has no `.target` or `.host`. Use the player context for the Video.js media object:
+
+tsx
+
+```
+import { useMedia } from '@videojs/react';
+
+function EngineAccess() {
+  const media = useMedia();
+  const engine = media && 'engine' in media ? media.engine : null;
+
+  // `engine` is the active hls.js instance for the `/hls-js` flavor.
+  return null;
+}
+```
+
+Import the `/hls-js` flavor when your app depends on that engine. The default flavor deliberately doesn’t promise which engine it uses.
+
 Program Date Time has no convenience surface: no `getStartDate()`, no `currentPdt`. The player exposes `liveEdgeStart` and `targetLiveWindow`; for PDT itself, reach into the engine.
 
 ## Known gaps
 
 Ordered roughly by how many migrations they’ll touch.
 
-*   No skin draws `content-title`, so setting it alone won’t put a title on screen ([#1123](https://github.com/videojs/v10/issues/1123)).
-*   Playback 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)).
 *   Two skins, against Mux Player’s five themes, and no runtime theme switch. That’s a deliberate trade, fewer looks each of which you can eject, but it’s a real difference if you shipped `theme="classic"`.
-*   Chapters render on the time slider, but there’s no active-chapter state, no `chapterchange` event, and no chapter menu ([#1873](https://github.com/videojs/v10/issues/1873)). No `addChapters()` either ([#1268](https://github.com/videojs/v10/issues/1268)).
-*   Cue points aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
-*   No `playback-id` attribute; use a `src` URL or the `source` object.
 *   Lazy loading (`loading="viewport|page"`) has no equivalent.
-*   The SPF Mux media doesn’t license DRM and doesn’t play TS-packaged media ([#1776](https://github.com/videojs/v10/issues/1776)). The default flavor does both.
-*   Signed playback works, but there’s no expired-token message and no auto-refresh ([#1432](https://github.com/videojs/v10/issues/1432)).
-*   Neither packaged video skin includes skip buttons; add a seek button.
 *   The controls auto-hide delay isn’t configurable, and there’s no disabled state for the controls ([#1728](https://github.com/videojs/v10/issues/1728)).
-*   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 manifest decide.
-*   Caption styling is limited to the skins’ positioning custom properties.
+*   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.
 
 ## See also

package/docs/how-to/migrate-from-plyr.md

@@ -2,22 +2,17 @@
 
 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 an options object; Video.js v10 is built a bit differently. The player is composed, not configured. That means the player you ship is smaller and faster, and when you’re ready to customize it, it’s easy to go under the hood and build what you need. It also means there’s a bit more set-up to get started.
+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](../concepts/features.md).
 
-The migration is mostly **moving configuration into markup** and replacing Plyr’s instance API with native media APIs or Video.js [player state](../concepts/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.
 
-## Why switch?
+## What changes
 
-Plyr is simple and familiar, so the reason to migrate should be practical. These are the strongest wins when your app can use HTML5, HLS, DASH, Vimeo, YouTube, or Mux-backed media. We’ve taken our vast experience building some of the best players and thrown it all into Video.js v10.
-
-*   **♿ Accessibility starts in the component model.** Plyr has long-running reports around WCAG compliance, slider semantics, keyboard behavior, focus visibility, and menu roles ([#905](https://github.com/sampotts/plyr/issues/905), [#103](https://github.com/sampotts/plyr/issues/103)). Video.js v10 exposes buttons, sliders, menus, radio groups, and tooltips as focused components with state attributes and [accessibility behavior](../concepts/accessibility.md) built into each part.
-*   **📺 Streaming controls are first-class media state.** Streaming was an afterthought in Plyr. HLS quality switching is one of Plyr’s most-requested gaps ([#1741](https://github.com/sampotts/plyr/issues/1741), [#218](https://github.com/sampotts/plyr/issues/218)). Video.js v10 models HLS, DASH, and Mux-backed media directly, so quality UI can read rendition state instead of parsing manifests and wiring hls.js in application code.
-*   **🧩 Composition keeps player code cleaner.** Players, media elements, skins, controls, gestures, and hotkeys are separate pieces. You can replace one part without wrapping or forking the whole player.
-*   **✨ Two polished skins are ready to use.** Minimal is the closest starting point for Plyr migrations, while Default gives you a modern, frosted design. Both can be [ejected](#ejecting) when you want to customize the layout, styling, or icons.
-*   **📡 Remote playback is part of the built-in video UI.** Plyr has an open Google Cast request dating back years ([#112](https://github.com/sampotts/plyr/issues/112)). Video.js v10 includes [Cast](../concepts/cast.md) and AirPlay controls through a shared remote playback feature.
-*   **⚛️ React gets a native API.** Plyr integrations in React tend to wrap an imperative constructor around framework-owned DOM ([#254](https://github.com/sampotts/plyr/issues/254)), and lifecycle cleanup can get awkward when routes or components unmount ([#1001](https://github.com/sampotts/plyr/issues/1001)). `@videojs/react` gives you players, components, hooks, and TypeScript types instead.
-*   **🎛️ Layout and skins are easier to own.** Plyr’s iframe and aspect-ratio behavior has produced workarounds for cropping and fullscreen sizing ([#339](https://github.com/sampotts/plyr/issues/339)). Video.js v10 separates the player, container, media, and skin, so sizing belongs to the container or skin and the UI can be [ejected](#ejecting) when you need full control.
-*   **⌨️ Input behavior is explicit.** Plyr has recurring mobile tap and fullscreen threads ([#718](https://github.com/sampotts/plyr/issues/718), [#1190](https://github.com/sampotts/plyr/issues/1190)). Video.js v10 has common gestures and hotkey support built into the skins, and you can [eject](#ejecting) to customize them.
+*   **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.
+*   **React uses native components and hooks.** `@videojs/react` owns its lifecycle instead of wrapping an imperative constructor around framework-owned DOM.
+*   **The UI is composable.** Buttons, sliders, menus, gestures, and hotkeys are individual accessible components. Start with the Minimal or Default skin, then [eject it](#ejecting) 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](./cast-to-airplay-and-chromecast.md) to add the Google Cast integration.
 
 Note
 
@@ -25,9 +20,7 @@ Video.js v10 is still moving toward GA. Features like ads, playlists, preference
 
 ## Basic migration
 
-Let’s start with the most basic example of getting Plyr up and running and replace it with a Video.js v10 player.
-
-This snippet will render a basic video player with thumbnail previews, captions and a poster image.
+Start with a Plyr player that has captions, thumbnail previews, and a poster:
 
 html
 
@@ -50,7 +43,7 @@ const player = new Plyr('#player', {
 </script>
 ```
 
-The closest Video.js skin to the Plyr skin is the Minimal skin, so we’ll use that for this example.
+The Minimal skin is the closest built-in starting point for this migration.
 
 First, install the dependency:
 
@@ -76,8 +69,8 @@ interface AppVideoPlayerProps {
 
 export function AppVideoPlayer({ origin }: AppVideoPlayerProps) {
   return (
-    <VideoPlayer>
-      <MinimalVideoSkin poster={`${origin}/poster.jpg`}>
+    <VideoPlayer poster={`${origin}/poster.jpg`}>
+      <MinimalVideoSkin className="app-video-player">
         <Video src={`${origin}/video.mp4`} playsInline>
           <track kind="captions" label="English" src={`${origin}/captions/en.vtt`} srclang="en" default />
           <track kind="metadata" label="thumbnails" src={`${origin}/storyboard.vtt`} default />
@@ -91,11 +84,12 @@ export function AppVideoPlayer({ origin }: AppVideoPlayerProps) {
 ### Notes
 
 *   `@videojs/react/video` is a [preset](../concepts/presets.md): a player, a skin, and a media element that already fit together. `VideoPlayer` is the piece that owns the state, built from the standard set of [features](../concepts/features.md) for video.
-*   The poster is a prop on the skin rather than a `poster` attribute on the media, which gives the skin control over how it appears. That’s much like Plyr’s `data-poster`.
+*   The poster URL is metadata on `VideoPlayer`. The skin reads that metadata and controls how the poster appears. To replace the rendered image, pass `renderPoster` to the skin.
 *   This example assumes all your files for a given asset live in the same path, using consistent filenames. This will almost certainly need adjusting for your implementation.
+*   If `origin` points somewhere other than your page’s origin, add `crossOrigin="anonymous"` to `<Video>` and serve those files with CORS headers. A cross-origin thumbnail track only loads when the media element is CORS-enabled. See [Thumbnail](../reference/thumbnail.md).
 *   There’s also a default skin with a modern, frosted appearance that some may prefer. Try it by switching the CSS import filename to `skin.css` and the `MinimalVideoSkin` import and usage to `VideoSkin`.
 
-## Advanced migration
+## Map common features
 
 ### Streaming
 
@@ -171,7 +165,7 @@ Video.js v10 ships with English labels by default and includes locale packs for:
 
 `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 [Internationalization](../concepts/i18n.md) for the full picture.
+The shorthand tags `pt` and `zh` are also available as aliases. See [Internationalize the player](./internationalize-the-player.md) for the full picture.
 
 Use the React provider when you want scoped overrides:
 
@@ -232,7 +226,7 @@ These are attributes on your media (e.g. `<video>`) component.
 
 `poster` / `data-poster`
 
-The skin owns the poster, as shown in [Basic migration](#basic-migration) above.
+In HTML, slot an image into the skin. In React, set `poster` on `VideoPlayer`. See [Basic migration](#basic-migration).
 
 `ratio`
 
@@ -294,11 +288,15 @@ The most common languages are available by default but you can also provide cust
 
 Unsupported at this time.
 
-## Dynamic sources
+## 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, [eject the skin](#ejecting) and edit the copied implementation. Adding a child to a skin does not place it inside the control bar.
+
+If your app already has a custom control bar, build it from individual [UI components](../concepts/ui-components.md). Video.js handles the media action, accessible name, and state. You add the visible contents, layout, and CSS.
 
-In Video.js v10 you can swap out the `src` or the media component itself and the UI will update.
+Individual React buttons do not include visible content. Use their `render` props to add an icon or text and style the element you return. Eject a ready-made skin when you need to change its control set or layout.
 
-## Imperative API
+## Use the imperative API
 
 Use the media element for standard playback operations:
 
@@ -338,16 +336,33 @@ Fullscreen feature or fullscreen control
 
 Text-track feature or captions control
 
+To change content without changing media type, set `src` on the media component. Replace the component when the media type changes, such as moving from `Video` to `HlsVideo`. The player UI follows the attached media.
+
 For custom UI, read and write through the Video.js player store.
 
-Import the preset’s [`usePlayer`](../reference/use-player.md) hook and call it directly or with a selector:
+Import the preset’s [`usePlayer`](../reference/use-player.md) hook and call it from a descendant of `VideoPlayer`. The component that creates `VideoPlayer` cannot also consume its context, so put store access in a child component:
 
 tsx
 
 ```
-import { usePlayer } from '@videojs/react/video';
+import '@videojs/react/video/minimal-skin.css';
+import { MinimalVideoSkin, usePlayer, Video, VideoPlayer } from '@videojs/react/video';
 
-const currentTime = usePlayer((state) => state.currentTime);
+function CurrentTime() {
+  const currentTime = usePlayer((state) => state.currentTime);
+  return <output>{Math.round(currentTime)} seconds</output>;
+}
+
+export function AppVideoPlayer() {
+  return (
+    <VideoPlayer>
+      <MinimalVideoSkin>
+        <Video src="/video.mp4" playsInline />
+        <CurrentTime />
+      </MinimalVideoSkin>
+    </VideoPlayer>
+  );
+}
 ```
 
 ## Rewrite styles
@@ -361,16 +376,20 @@ css
 .plyr {
   --plyr-color-main: rebeccapurple;
 }
+```
+
+css
 
-/* Video.js */
-video-player {
+```
+/* Video.js React: the className from the basic example */
+.app-video-player {
   --media-accent-color: rebeccapurple;
 }
 ```
 
 `--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) for the full list.
 
-## Ejecting
+## Eject a skin
 
 If you need extra customization of layout, styles, or icons, you can “eject” the skin into your application, much like a shadcn installation. Copy the skin and its CSS into your project, then modify the components and styles directly. [Customize skins](./customize-skins.md) has copy-paste-ready implementations for every packaged skin.