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

package/docs/{how-to → guides}/migrate-from-media-chrome.md

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