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

package/docs/guides/migrate-from-video-js-8.md

@@ -0,0 +1,467 @@
+# Migrate from Video.js 8
+
+Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
+
+Video.js 8 gives you one function, `videojs()`, and one large options object. It enhances a `<video>` element and returns a player with a control bar, plugin system, and component tree.
+
+Video.js v10 is a rebuild, not a drop-in version bump. There is no `videojs()` call, options object, or plugin registry. You compose a player from a few named pieces instead.
+
+> **Caution**
+>
+> This isn’t a version bump you can do with a find-and-replace. Plan it as a rewrite of your player setup, and read this guide before you estimate it.
+
+Video.js 8 lives on at its [repo](https://github.com/videojs/video.js) and [docs](https://legacy.videojs.org). The `video.js` package on npm is still Video.js 8, so `npm install video.js` won’t get you v10. Video.js 10 ships as scoped `@videojs/*` packages.
+
+## Three pieces instead of one
+
+In v8 the player was everything: playback, UI, and the skin on top of it. Options configured all three, which is why the options object grew so large.
+
+v10 splits those jobs up. Learning the three names first makes the rest of this guide much shorter.
+
+**The player** is the outer element. It holds state and hands that state to everything inside it, and it draws nothing. This is the closest thing to a v8 `player` instance, but it owns state rather than DOM. Which state it holds depends on the [features](./features.md) it’s built from.
+
+**The media** is the thing that plays the video. This is where v8’s *tech* went. A plain `<video>` plays progressive files, and there’s a [media component](./media-sources.md) for HLS, DASH, YouTube, Vimeo, and Mux. Swapping one for another is a tag change, and the rest of your player keeps working.
+
+**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. It’s the v8 control bar and skin combined, except [skins](./skins.md) are plain trees of components you can read and edit rather than a class hierarchy you subclass.
+
+So a v8 embed becomes a player wrapped around a skin wrapped around a media:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="/video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+Most of this guide is about which of those three a given v8 option now belongs to.
+
+## Your first player
+
+Here’s a standard v8 setup: one file, captions, a poster, and the default skin.
+
+```html
+<link href="https://vjs.zencdn.net/8.x/video-js.css" rel="stylesheet" />
+
+<video
+  id="my-video"
+  class="video-js"
+  controls
+  preload="auto"
+  poster="/poster.jpg"
+  data-setup="{}"
+>
+  <source src="/video.mp4" type="video/mp4" />
+  <track kind="captions" src="/captions/en.vtt" srclang="en" label="English" default />
+</video>
+
+<script src="https://vjs.zencdn.net/8.x/video.min.js"></script>
+```
+
+v10 ships web components, so the migration keeps its declarative feel. One script from the CDN gives you the video [preset](./presets.md): a player, a skin, and a media element that already fit together.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+
+<video-player poster="/poster.jpg">
+  <video-skin class="aspect-video">
+    <video src="/video.mp4" preload="auto" playsinline>
+      <track kind="captions" src="/captions/en.vtt" srclang="en" label="English" default />
+      <track kind="metadata" src="/storyboard.vtt" label="thumbnails" default />
+    </video>
+  </video-skin>
+</video-player>
+```
+
+With a bundler, the same thing is two imports:
+
+```js
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+```
+
+Four differences worth understanding, because each one is a pattern you’ll see again:
+
+- **No `class="video-js"`, no `data-setup`, no `videojs()` call.** The custom elements register themselves and wire up when the browser upgrades them. Nothing scans the page looking for players.
+- **No `controls` attribute.** The skin *is* the controls. Including a skin is how you ask for them, which is also how you opt out: leave it out and you get a player with no UI.
+- **The poster is player metadata, not a media attribute.** Set `poster` on `<video-player>`, and the skin, not the browser, controls how it appears. For more advanced control (like supplying your own image element), see [Add a poster and loading placeholder](./poster.md).
+- **Your `<track>` elements don’t change.** Captions, subtitles, chapters, and thumbnails are all still tracks, and the skin shows the matching controls when it finds them.
+
+There’s also a minimal skin, closer to v8’s control bar if the default’s frosted look is too much of a change. Swap `video.js` for `video-minimal.js` and `<video-skin>` for `<video-minimal-skin>`.
+
+## Where your options went
+
+The v8 options object is gone, and its contents scattered in four directions. This is the biggest conceptual step, so it’s worth understanding the four buckets before you go looking for a specific option.
+
+1. **Media attributes.** Anything the browser itself understands stays exactly where it was, on your media element.
+2. **Player metadata.** The title and poster belong to player state, which lets the skin or your custom UI render them.
+3. **Your CSS.** Sizing, aspect ratio, and responsive behavior are layout, and layout is yours.
+4. **Composition.** Which controls exist, which shortcuts fire, which language you’re in. You express these by choosing components rather than by setting flags.
+
+### Media attributes
+
+Port these across untouched. They’re native attributes and always were.
+
+| Video.js 8 | Video.js v10 |
+| --- | --- |
+| `autoplay`, `muted`, `loop`, `preload`, `playsinline`, `crossorigin` | the same attributes on your media |
+| `sources: [{ src, type }]` | `src`, or `<source>` children for progressive fallback |
+| `disablePictureInPicture` | `disablepictureinpicture` |
+
+### Player metadata
+
+| Video.js 8 | Video.js v10 |
+| --- | --- |
+| `poster` | `poster` on `<video-player>` |
+| `posterImage: false` | leave the player’s poster unset |
+| the title in `TitleBar` | `content-title` on `<video-player>`, rendered with the `<media-title>` element |
+
+The poster belongs to player state rather than the media, which lets the skin control how it appears:
+
+```html
+<video-player poster="/poster.jpg">
+  <video-skin>
+    <video src="/video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+The packaged video and live-video skins already include the [`<media-title>`](../reference/components/title.md) element, so setting `content-title` on the player displays it. Audio skins do not include a title. Add `<media-title>` where you want it in a custom layout or skin source you added to your project. For poster rendering options — including placeholders and custom image elements — see [Add a poster and loading placeholder](./poster.md) and the [`<media-poster>`](../reference/components/poster.md) reference.
+
+### Your CSS
+
+v8 had a small sizing language of its own. v10 doesn’t, because CSS already has one.
+
+| Video.js 8 | Video.js v10 |
+| --- | --- |
+| `fluid: true` | `width: 100%` on the skin |
+| `responsive: true` | the skins already adapt their layout to their own width |
+| `aspectRatio: '16:9'` | `aspect-ratio: 16 / 9` |
+| `width`, `height` | `width`, `height` |
+| `fill: true` | `width: 100%; height: 100%` |
+| `breakpoints` | the skins use container queries internally; use your own for your layout |
+
+### Composition
+
+These are the ones that need a decision rather than a rename, so each has a section below.
+
+| Video.js 8 | Where it lives now |
+| --- | --- |
+| `techOrder`, `html5.vhs.*` | [Techs become media components](#techs-become-media-components) |
+| `children`, `controlBar: { … }` | [Customize your player](#customize-your-player) |
+| `userActions.hotkeys`, `userActions.click`, `userActions.doubleClick` | [Customize your player](#customize-your-player) |
+| `plugins`, `videojs.registerPlugin` | [Plugins](#plugins) |
+| `languages`, `language`, `videojs.addLanguage` | [Languages](#languages) |
+| `liveui`, `liveTracker` | [Live and audio-only](#live-and-audio-only) |
+| `audioOnlyMode`, `audioPosterMode` | [Live and audio-only](#live-and-audio-only) |
+| `playbackRates` | not configurable yet ([#1404](https://github.com/videojs/v10/issues/1404)) |
+| `textTrackSettings` | no equivalent; see [Known gaps](#known-gaps) |
+| `spatialNavigation` | no equivalent; see [Known gaps](#known-gaps) |
+| `inactivityTimeout` | delay not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728)); `inactivityTimeout: 0` maps to `visibility="always"` on the controls component |
+| `errorDisplay`, `notSupportedMessage` | the skins include an error dialog |
+| `ModalDialog` | compose a [dialog](../reference/components/dialog.md); your application controls media playback when it opens and closes |
+
+## Techs become media components
+
+v8’s tech system was one of its harder ideas: an abstraction layer with a registry, a resolution order, and source handlers on top. Getting HLS meant getting VHS, which meant reasoning about `overrideNative` and hoping the right thing won.
+
+v10 replaces the whole mechanism with a choice you make in markup. You pick the [media component](./media-sources.md) that plays your format, and that’s the tech decision.
+
+| What you’re playing | Video.js 8 | Video.js v10 |
+| --- | --- | --- |
+| MP4, WebM | `techOrder: ['html5']` | a plain `<video>` |
+| HLS | VHS | [HLS video](../reference/components/hls-video.md) |
+| HLS, needing hls.js directly | `videojs.Vhs` | [hls.js video](../reference/components/hlsjs-video.md) |
+| HLS, native only | `html5.vhs.overrideNative: false` | [native HLS video](../reference/components/native-hls-video.md) |
+| DASH | VHS | [DASH video](../reference/components/dash-video.md) |
+| YouTube, Vimeo | a tech plugin | the YouTube and Vimeo components |
+| Mux | a tech plugin | [Mux Video](../reference/components/mux-video.md) |
+
+Each needs its own import.
+
+Package-manager installations also need the matching media package. The lightweight HLS component shown below uses `@videojs/spf`; the hls.js component uses `@videojs/hlsjs-video`; Mux video and audio use `@videojs/mux-video` and `@videojs/mux-audio`; DASH uses `@videojs/dash-video`; Vimeo uses `@videojs/vimeo-video`; and Shaka and Wistia use `@videojs/shaka-video` and `@videojs/wistia-video`.
+
+For HLS from the CDN:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/hls-video.js"></script>
+```
+
+With a package manager, install SPF and import the HTML registration instead:
+
+```bash
+npm install @videojs/html @videojs/spf
+```
+
+```ts
+import '@videojs/html/media/hls-video';
+```
+
+Then swap the tag:
+
+```html
+<video-player>
+  <video-skin>
+    <hls-video src="/stream.m3u8" playsinline></hls-video>
+  </video-skin>
+</video-player>
+```
+
+The lightweight HLS component runs on SPF, Video.js’s own playback engine, and helps keep v10 small. The hls.js component is a much larger download but more compatible, supporting TS-packaged media and DRM. Choose the one whose supported feature set fits your stream.
+
+Your VHS tuning options don’t have direct equivalents. Rendition capping, bandwidth hints, and the rest are engine-specific, so they belong to whichever engine you chose rather than to a shared options object.
+
+## Customize your player
+
+In v8, customizing meant three different techniques depending on what you wanted: options for some things, `addChild` and component subclassing for others, and CSS overrides on `.vjs-*` selectors for the look. v10 has one path with three levels of commitment. Try them in order.
+
+### Level 1: pick a skin
+
+The default skin is a modern, frosted look. The minimal skin is closer to v8’s 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).
+
+Both also include AirPlay and Cast buttons, which v8 had no answer for. Follow [Cast to AirPlay and Chromecast](./casting.md) to add the Google Cast extension. Remote playback is a feature you compose in rather than a plugin you install.
+
+### Level 2: restyle it
+
+v8 customization meant writing selectors against internal class names and hoping they survived the next release. v10 skins expose custom properties instead, which are part of the public surface:
+
+```css
+/* Video.js 8 */
+.video-js .vjs-play-progress {
+  background-color: rebeccapurple;
+}
+
+/* Video.js v10 */
+video-player {
+  --media-accent-color: rebeccapurple;
+}
+```
+
+`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces at once. 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, which is the closest thing to v8’s `font-size` trick for sizing controls. [Customize skins](./customize-skins.md#style-a-packaged-skin) has the full list.
+
+### 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.
+
+This is where v8’s `controlBar` config and `addChild` calls end up, and honestly it’s the better trade. Instead of `controlBar: { pictureInPictureToggle: false }`, you delete a line. Instead of subclassing a component to change its behavior, you edit the markup.
+
+Keep the player and skin registration imports. The skin import registers the container and UI elements that the copied layout uses; you do not render the skin element itself:
+
+```js
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+```
+
+Then write the layout yourself:
+
+```html
+<video-player>
+  <media-container>
+    <video src="/video.mp4" playsinline></video>
+
+    <media-poster><img src="/poster.jpg" alt="" decoding="async" /></media-poster>
+
+    <media-controls>
+      <media-controls-content>
+        <media-play-button></media-play-button>
+        <media-mute-button></media-mute-button>
+        <media-volume-slider></media-volume-slider>
+        <media-time type="current"></media-time>
+        <media-time-slider>
+          <media-slider-track>
+            <media-slider-fill></media-slider-fill>
+            <media-slider-buffer></media-slider-buffer>
+          </media-slider-track>
+          <media-slider-thumb></media-slider-thumb>
+        </media-time-slider>
+        <media-time type="duration"></media-time>
+        <media-fullscreen-button></media-fullscreen-button>
+        <!-- No media-pip-button, so no picture-in-picture control renders. -->
+      </media-controls-content>
+    </media-controls>
+
+    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
+    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
+    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
+    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
+
+    <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
+  </media-container>
+</video-player>
+```
+
+Those hotkey and gesture declarations are where `userActions` went. v8’s `userActions.hotkeys` was a function you wrote; here each shortcut is a component with a key and an action, and `userActions.click` and `doubleClick` become gestures with a region. The packaged skins already include a sensible set of both, which is why you don’t see them in the earlier examples.
+
+When you add the skin source, you also take on its CSS. The packaged skins ship styles for everything above; a bare layout renders unstyled until you bring those along, so the added source includes the skin’s stylesheet next to its markup.
+
+## Plugins
+
+v10 has no plugin system. There’s no `videojs.registerPlugin`, no `player.myPlugin()`, and no plugin lifecycle.
+
+That’s a deliberate choice rather than a missing feature. v8 plugins existed largely because there was no other way in: to add a control, change a behavior, or support a format, you had to reach into player internals through the one door the plugin API provided. v10 gives you the front door instead: components you can add, skin source you can change, and media elements you can swap. Most of what plugins did is now ordinary composition.
+
+Audit your plugins and sort them into four piles:
+
+- **Formats and techs** (`videojs-contrib-*`, YouTube, Vimeo, Mux). Replace with the matching media component. See [Techs become media components](#techs-become-media-components).
+- **UI additions** (extra buttons, overlays, custom control bars). Rebuild them by editing the skin source in your project, or with [your own component](./build-your-own-component.md). This is usually less code than the plugin was.
+- **Workarounds** for v8 limitations. Check whether the limitation still exists before you port anything.
+- **Genuinely missing features** (ads, playlists). These need real work, and some have no home yet. Get them on the list early, because they’ll drive your timeline.
+
+That last pile is the honest risk in a v8 migration. If your player depends on an ads plugin, there’s no v10 answer today.
+
+## Read player state
+
+### Events
+
+Your media element is a real media element, so every event you already listen for still fires on it. The listeners port directly; only where you attach them changes.
+
+```js
+// Video.js 8
+const player = videojs('my-video');
+player.on('timeupdate', () => console.log(player.currentTime()));
+
+// Video.js v10
+const video = document.querySelector('video');
+video.addEventListener('timeupdate', () => console.log(video.currentTime));
+```
+
+One category doesn’t survive that translation, because those were never media events. v8’s UI events (`useractive`, `userinactive`, `playerresize`, `texttrackchange`) were the player’s own. Read the equivalent from player state instead.
+
+### Player 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 as that state changes:
+
+```js
+import { PlayerController, playerContext, ReactiveElement, selectTime } from '@videojs/html';
+
+class MyElapsed extends ReactiveElement {
+  #time = new PlayerController(this, playerContext, selectTime);
+}
+```
+
+### Drive playback
+
+v8 used accessor methods for everything: `player.currentTime()` to read, `player.currentTime(10)` to write. v10 keeps that single-object habit: control everything through the player. Its store holds the state each feature tracks and an action for each of these calls — playback, seeking, volume, rate, fullscreen, captions, and quality alike.
+
+You can also write to the media element directly. That is safe because player state derives from the native media events: set `media.currentTime` and the time slider follows. There is no wrapper to fall out of sync.
+
+| Video.js 8 | Video.js v10 |
+| --- | --- |
+| `player.play()`, `player.pause()` | the player’s `play`, `pause`, `togglePaused`, or `media.play()`, `media.pause()` |
+| `player.currentTime()` / `player.currentTime(10)` | `currentTime` in player state, the player’s `seek(10)`, or `media.currentTime` |
+| `player.duration()` | `duration` in player state, or `media.duration` |
+| `player.volume()`, `player.muted()` | the player’s `setVolume`, `toggleMuted`, or `media.volume`, `media.muted` |
+| `player.playbackRate()` | the player’s `setPlaybackRate`, or `media.playbackRate` |
+| `player.src({ src, type })` | set `src` on the media or replace the media element (`<video>` tag, `<hlsjs-video>`, `<dash-video>`, etc) |
+| `player.requestFullscreen()`, `exitFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen`, `toggleFullscreen` |
+| `player.textTracks()`, `addRemoteTextTrack()` | `<track>` elements, and `textTrackList` in player state, `textTracks` in media |
+| `player.audioTracks()` | `audioTrackList` in player state, `audioTracks` in media |
+| `player.error()` | `error` in player state |
+| `player.dispose()` | remove the element |
+| `player.tech()` | the media component’s public `engine` escape hatch, where one exists |
+| `videojs.getPlayer(id)` | hold a reference to the element |
+
+Everything the table describes as “the player’s” lives on the player element’s store. Hold a reference to `<video-player>` the way you held a v8 player instance, and call actions on its `store.state`:
+
+```js
+const player = document.querySelector('video-player');
+
+player.store.state.toggleFullscreen();
+```
+
+Swapping sources is the change most likely to surprise you. There’s no `player.src()`; you set `src` on the media element, or replace the media element entirely, and the UI follows. Changing formats is changing tags.
+
+## Languages
+
+v8 shipped one language and asked you to register more with `videojs.addLanguage`. v10 ships locale packs for around 50 languages, so most apps need no setup at all. See [Internationalize the player](./internationalization.md).
+
+To override individual strings:
+
+```js
+import { registerI18n } from '@videojs/html/i18n';
+
+registerI18n('en', {
+  buttons: { play: 'Start video', pause: 'Pause video' },
+  menu: { settings: 'Options' },
+});
+```
+
+See [Internationalize the player](./internationalization.md) for scoped overrides, custom locales, and runtime switching.
+
+## Live and audio-only
+
+v8 turned live UI on with a `liveui` flag, and audio-only on with `audioOnlyMode`. In v10 these are different players with different skins, because live and audio-only have different state and a genuinely different UI. See [Presets](./presets.md).
+
+```html
+<live-video-player>
+  <live-video-skin>
+    <hls-video src="/live.m3u8"></hls-video>
+  </live-video-skin>
+</live-video-player>
+```
+
+For audio, use the audio player with the audio skin, or the live audio pair. There’s also a background video player for muted, chrome-free background video, which v8 had no answer for.
+
+You get `targetLiveWindow` and `liveEdgeStart` in state, plus a live button that jumps to the live edge. The live preset does not include `streamType`; add the stream type feature to a custom player when you need it. v8’s `liveTracker` tuning has no equivalent ([#1730](https://github.com/videojs/v10/issues/1730)).
+
+The live composition is deliberately narrower than the video one. It leaves out playback rate, quality, and audio-track state, so those controls don’t appear in a live skin’s settings menu. If you need an omitted feature on a live player, build your own player from a feature list rather than taking the preset’s.
+
+That’s what [`createPlayer`](../reference/api/html-create-player.md) is for. Hand it a feature list and you get back the mixins to define your own player element.
+
+## Moved utilities
+
+v8 put a handful of utilities on the `videojs` global for anyone building a custom component or plugin: `videojs.time.formatTime`, `videojs.dom`, `videojs.fn.throttle`, and a few others. There’s no global in v10, but the same job is covered by `@videojs/utils`.
+
+| Video.js 8 | Video.js v10 |
+| --- | --- |
+| `videojs.time.formatTime(seconds, guide)` | `formatTime(seconds, guide)` from `@videojs/utils/time` |
+| a hand-rolled remaining-time or percent string | `formatTimeAsPhrase(seconds)` and `formatPercent(fraction)`, from `@videojs/utils/time` and `@videojs/utils/percent` |
+| `videojs.fn.throttle(fn, wait)` | `throttle(fn, ms)` from `@videojs/utils/function` |
+| `videojs.dom.isEl(value)` and its type-specific cousins | `isHTMLVideoElement`, `isHTMLMediaElement`, `isDocument`, and other narrowing checks from `@videojs/utils/dom` |
+| `videojs.obj.merge(a, b)` | `defaults(object, defaultValues)` from `@videojs/utils/object`, alongside `pick`, `omit`, `deepEqual`, and `shallowEqual` |
+
+These are worth reaching for before writing your own when extending the player. For example, `formatTime` is the exact digital-clock formatting the packaged skins use for their own time displays, so a custom one will match. The package is split into subpaths, so you can import only the module you need. Other than `time`, it includes `array`, `events`, `i18n`, `jwt`, `predicate`, `string`, and `types` subpaths for anything else a custom component or plugin replacement needs.
+
+Import the util function directly with a `<script>` tag:
+
+```html
+<script src="
+    https://cdn.jsdelivr.net/npm/@videojs/utils@10.0.0-rc.3/dist/time/formatTime.min.js
+"></script>
+```
+
+Or with a bundler:
+
+```bash
+npm install @videojs/utils
+```
+
+```js
+import { formatTime } from '@videojs/utils/time';
+```
+
+## Known gaps
+
+Ordered roughly by how likely each is to block a v8 migration.
+
+- **No ads support.** v8’s IMA and ad-plugin ecosystem has no v10 equivalent. This is the most common hard blocker.
+- **No playlist support.** No `videojs-playlist` equivalent.
+- **No plugin system**, by design. Budget for rebuilding UI plugins as components. See [Plugins](#plugins).
+- Playback rates are a fixed set — `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` — so v8’s `playbackRates` has no equivalent yet ([#1404](https://github.com/videojs/v10/issues/1404)).
+- No text-track settings dialog. v8’s `textTrackSettings` let viewers restyle captions; v10 exposes only the positioning custom properties its skins define.
+- No spatial navigation. v8’s `spatialNavigation` for TV and D-pad remotes has no equivalent.
+- 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).
+- No VHS-equivalent tuning surface. Engine settings belong to the engine you chose, and the lightweight HLS component deliberately exposes few of them.
+- Chapters render in the time slider from a `<track kind="chapters">`, and its segments reflect `data-active`. There is no player-level active chapter value or chapter menu, so v8’s chapters menu has no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). Cue points aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
+- The controls auto-hide delay isn’t configurable, so arbitrary `inactivityTimeout` values have no equivalent ([#1728](https://github.com/videojs/v10/issues/1728)). The common `inactivityTimeout: 0` case is covered by `visibility="always"` on the controls component in a custom layout or a skin layout in your project.
+- No full-window fullscreen fallback. v8 had one for browsers without the Fullscreen API; [support is around 96%](https://caniuse.com/fullscreen) now.
+- Multiple `<source>` elements with `size` metadata don’t become a quality menu. Use HLS or DASH for adaptive quality; picking renditions by resolution won’t be added ([#1415](https://github.com/videojs/v10/issues/1415)).
+- Two skins, and no runtime theme switch.
+- Native controls are not automatically removed when custom controls load ([#1160](https://github.com/videojs/v10/issues/1160)).
+- 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)).
+
+## See also
+
+- [Features](./features.md) and [Presets](./presets.md)
+- [Media sources](./media-sources.md)
+- [Skins](./skins.md) and [Customize skins](./customize-skins.md)

package/docs/guides/mux-data.md

@@ -0,0 +1,76 @@
+# Monitor playback with Mux Data
+
+Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
+
+[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](./architecture.md) to a player and it monitors whichever media that player is playing:
+
+Install the extension alongside the framework façade. The `<mux-video>` example also installs the Mux playback adapter:
+
+```bash
+pnpm add @videojs/html @videojs/mux-video @videojs/mux-data
+```
+
+**index.html**
+
+```html
+<video-player>
+  <media-container>
+    <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" playsinline></mux-video>
+    <mux-data></mux-data>
+  </media-container>
+</video-player>
+```
+
+Register the `<mux-data>` element by importing `@videojs/html/extensions/mux-data`.
+
+That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it inside the player, as a sibling of the media element.
+
+> **Note**
+>
+> Mux Data is opt-in. No media element monitors playback on its own, Mux ones included, so nothing is measured and no beacons are sent until you add the extension.
+
+## Set the environment key
+
+Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.
+
+Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
+
+```html
+<hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
+<mux-data env-key="YOUR_ENV_KEY"></mux-data>
+```
+
+An explicit key always wins, so set one to send Mux-hosted views to a specific environment.
+
+## How it works
+
+The extension attaches to the media the player is using, not to a specific element type, so it monitors [`<mux-video>`](../reference/components/mux-video.md), [`<hlsjs-video>`](../reference/components/hlsjs-video.md), [`<dash-video>`](../reference/components/dash-video.md), and the rest alike.
+
+How much it reports depends on the engine playing the stream. Every media gets the playback metrics the media element itself can tell us. On top of that, the component recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media with no JavaScript engine, like native HLS or a plain `<video>`, report the element-level metrics alone.
+
+The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.
+
+## Describe the view
+
+Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:
+
+```ts
+const muxData = document.querySelector('mux-data');
+muxData.metadata = { video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' };
+```
+
+## Configuration
+
+The [`<mux-data>` reference](../reference/components/mux-data.md) lists every option: the metadata and software fields above, plus the beacon domain, cookie, debug, and SDK settings. Most options update the current view in place; changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, ending the current view and starting a new one.
+
+## Related pages
+
+### Components
+
+- [mux-data](../reference/components/mux-data.md): Options for the Mux Data extension that monitors playback quality
+- [mux-video](../reference/components/mux-video.md): Video element for Mux-hosted HLS streams
+- [mux-audio](../reference/components/mux-audio.md): Audio element for Mux-hosted HLS streams
+
+### Guides
+
+- [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.