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

package/docs/reference/api/translation-phrases.md

@@ -0,0 +1,107 @@
+# Translation phrases
+
+Semantic i18n keys, their English defaults, and the player UI that uses them
+
+Video.js uses opaque semantic keys so English copy can change without breaking translation packs. English defaults are defined in `packages/core/src/core/i18n/locales/en.ts`. Both HTML and React controls use the same keys.
+
+Locale packs and provider overrides use nested objects, so `buttons.play` is authored as `{ buttons: { play: '…' } }`. Translators and the `<media-text token>` attribute use the dotted form.
+
+## Playback controls
+
+| Key | English default | Used by |
+| --- | --- | --- |
+| `buttons.play` | Play | Play button and its tooltip |
+| `buttons.pause` | Pause | Play button and its tooltip |
+| `buttons.replay` | Replay | Play button and its tooltip |
+| `buttons.mute` | Mute | Mute button and its tooltip |
+| `buttons.unmute` | Unmute | Mute button and its tooltip |
+| `seek.forward` | Seek forward `{seconds}` seconds | Seek-forward button and its tooltip |
+| `seek.backward` | Seek backward `{seconds}` seconds | Seek-backward button and its tooltip |
+| `fullscreen.enter` | Enter fullscreen | Fullscreen button |
+| `fullscreen.exit` | Exit fullscreen | Fullscreen button |
+| `captions.enable` | Enable captions | Captions button and captions selection control |
+| `captions.disable` | Disable captions | Captions button and captions selection control |
+| `pip.enter` | Enter picture-in-picture | Picture-in-picture button |
+| `pip.exit` | Exit picture-in-picture | Picture-in-picture button |
+| `live.playing` | Playing live | Live button |
+| `live.seekToEdge` | Seek to live edge | Live button |
+| `live.badge` | Live | Live button badge |
+| `cast.start` | Start casting | Cast button |
+| `cast.stop` | Stop casting | Cast button |
+| `cast.connecting` | Connecting | Cast button |
+| `airplay.start` | Start AirPlay | AirPlay button |
+| `airplay.stop` | Stop AirPlay | AirPlay button |
+| `container.label` | Media player | Player container aria label |
+
+## Time and volume
+
+| Key | English default | Used by |
+| --- | --- | --- |
+| `slider.seek` | Seek | Time slider aria label |
+| `time.current` | Current time | Current-time display aria label |
+| `time.duration` | Duration | Duration display aria label |
+| `time.remaining` | Remaining | Remaining-time display aria label |
+| `time.elapsedSuffix` | `{duration} elapsed` | Elapsed time in a toggleable display aria label |
+| `time.durationSuffix` | `{duration} duration` | Duration in a toggleable display aria label |
+| `time.remainingSuffix` | `{duration} remaining` | Remaining time display |
+| `time.showElapsed` | `Show elapsed time, {duration}.` | Toggleable time display aria label |
+| `time.showDuration` | `Show duration, {duration}.` | Toggleable time display aria label |
+| `time.showRemaining` | `Show remaining time, {duration}.` | Toggleable time display aria label |
+| `time.toggleElapsed` | `Toggle between elapsed and remaining time.` | Elapsed-time toggle aria description |
+| `time.toggleDuration` | `Toggle between duration and remaining time.` | Duration toggle aria description |
+| `time.position` | `{current} of {duration}` | Time slider value text |
+| `time.unknown` | Media not loaded, unknown time. | Time display aria label and time slider value text before a duration is known |
+| `playback.rate` | Playback rate `{rate}` | Playback-rate button and radio group |
+| `volume.mutedValue` | `{percent}, muted` | Muted volume slider value text |
+| `volume.muted` | Muted | Volume input feedback |
+| `volume.label` | Volume | Volume slider aria label |
+| `volume.value` | Volume `{value}` | Volume input feedback |
+
+## Playback feedback
+
+| Key | English default | Used by |
+| --- | --- | --- |
+| `status.captionsOn` | Captions on | Input feedback after enabling captions |
+| `status.captionsOff` | Captions off | Input feedback after disabling captions |
+| `status.paused` | Paused | Input feedback after pausing |
+| `status.playing` | Playing | Input feedback after starting playback |
+| `status.fullscreen` | Fullscreen | Input feedback after entering fullscreen |
+| `status.pip` | Picture in picture | Input feedback after entering picture-in-picture |
+| `status.exitPip` | Exit picture in picture | Input feedback after exiting picture-in-picture |
+| `status.seekedTo` | Seeked to `{time}` | Status announcer after a seek |
+
+## Errors
+
+| Key | English default | Used by |
+| --- | --- | --- |
+| `errors.aborted` | You stopped media playback before it finished. | Media error dialog for `MEDIA_ERR_ABORTED` |
+| `errors.network` | This media could not be loaded due to a network or server issue. | Media error dialog for `MEDIA_ERR_NETWORK` |
+| `errors.decode` | This media could not be played. It may be corrupted, or your browser may not support its format. | Media error dialog for `MEDIA_ERR_DECODE` |
+| `errors.source` | This media could not be loaded. It may be unavailable, or your browser may not support its format. | Media error dialog for `MEDIA_ERR_SRC_NOT_SUPPORTED` |
+| `errors.encrypted` | This media could not be played because it could not be decrypted. | Media error dialog for `MEDIA_ERR_ENCRYPTED` |
+| `errors.unplayable` | This media is unsupported by the player. | Media error dialog when the player cannot play a source the browser supports |
+| `errors.title` | Something went wrong. | Generic media error dialog title |
+| `errors.unexpected` | An unexpected error occurred. | Generic media error dialog fallback description |
+| `common.empty` | `''` | Empty description for a custom media error |
+| `common.ok` | OK | Error dialog confirmation button |
+
+## Settings and track menus
+
+| Key | English default | Used by |
+| --- | --- | --- |
+| `menu.settings` | Settings | Video settings menu trigger |
+| `menu.quality` | Quality | Quality menu |
+| `menu.audio` | Audio | Audio-track menu and fallback track label |
+| `menu.default` | Default | Reserved default-option label; no stock control currently emits it |
+| `menu.speed` | Speed | Playback-rate menu |
+| `menu.captions` | Captions | Captions menu |
+| `menu.playbackRate` | Playback rate | Playback-rate radio group |
+| `menu.back` | Back | Nested settings-menu back button |
+| `menu.off` | Off | Captions menu option |
+| `menu.auto` | Auto | Automatic-quality option |
+| `menu.autoWithLabel` | Auto (`{label}`) | Automatic-quality option with the active rendition |
+| `menu.subtitles` | Subtitles | Subtitles track option |
+
+## Related pages
+
+- [Internationalize the player](../../guides/internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.

package/docs/reference/api/vjs8-legacy-component.md

@@ -0,0 +1,21 @@
+# VJS8_LEGACY_COMPONENT
+
+Legacy Video.js 8 component registration error
+
+`videojs.registerComponent()` was the Video.js 8 component tree. Video.js 10 components are custom elements and React components.
+
+## Trigger
+
+```javascript
+videojs.registerComponent('MyButton', MyButton);
+```
+
+## Video.js 10 equivalent
+
+Define a custom element and place it inside `<video-skin>` or your own skin markup.
+
+See [Migrate from Video.js 8](../../guides/migrate-from-video-js-8.md) for the full setup.
+
+## Video.js 8
+
+Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

package/docs/reference/api/vjs8-legacy-get-player.md

@@ -0,0 +1,21 @@
+# VJS8_LEGACY_GET_PLAYER
+
+Legacy Video.js 8 player lookup error
+
+`videojs.getPlayer()` looked players up by id. Video.js 10 has no registry; hold a reference to the element.
+
+## Trigger
+
+```javascript
+const player = videojs.getPlayer('my-video');
+```
+
+## Video.js 10 equivalent
+
+`document.querySelector('video-player')` and call actions on its `store.state`.
+
+See [Migrate from Video.js 8](../../guides/migrate-from-video-js-8.md) for the full setup.
+
+## Video.js 8
+
+Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

package/docs/reference/api/vjs8-legacy-init.md

@@ -0,0 +1,21 @@
+# VJS8_LEGACY_INIT
+
+Legacy Video.js 8 player initialization error
+
+`videojs()` was the Video.js 8 API. Video.js 10 has no factory; players are components you compose.
+
+## Trigger
+
+```javascript
+const player = videojs('my-video', { controls: true });
+```
+
+## Video.js 10 equivalent
+
+Keep `import 'video.js'`, remove the factory call, and render `<video-player><video-skin><video src></video></video-skin></video-player>`.
+
+See [Migrate from Video.js 8](../../guides/migrate-from-video-js-8.md) for the full setup.
+
+## Video.js 8
+
+Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

package/docs/reference/api/vjs8-legacy-options.md

@@ -0,0 +1,21 @@
+# VJS8_LEGACY_OPTIONS
+
+Legacy Video.js 8 global options error
+
+`videojs.options` held Video.js 8 global defaults. Video.js 10 has no global; configuration lives on the components you render.
+
+## Trigger
+
+```javascript
+videojs.options.autoplay = true;
+```
+
+## Video.js 10 equivalent
+
+Set attributes on `<video-player>`, `<video-skin>`, and the media element.
+
+See [Migrate from Video.js 8](../../guides/migrate-from-video-js-8.md) for the full setup.
+
+## Video.js 8
+
+Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

package/docs/reference/api/vjs8-legacy-plugin.md

@@ -0,0 +1,21 @@
+# VJS8_LEGACY_PLUGIN
+
+Legacy Video.js 8 plugin registration error
+
+`videojs.registerPlugin()` was the Video.js 8 plugin system. Video.js 10 has no plugin registry.
+
+## Trigger
+
+```javascript
+videojs.registerPlugin('myPlugin', function () { /* ... */ });
+```
+
+## Video.js 10 equivalent
+
+Compose behavior as components inside `<video-player>`, or add an extension such as `@videojs/google-cast`.
+
+See [Migrate from Video.js 8](../../guides/migrate-from-video-js-8.md) for the full setup.
+
+## Video.js 8
+
+Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

package/docs/reference/{airplay-button.md → components/airplay-button.md}

@@ -4,17 +4,13 @@ Accessible AirPlay toggle button that opens the WebKit playback target picker an
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/airplay-button';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-airplay-button></media-airplay-button>
 ```
 
@@ -22,49 +18,26 @@ html
 
 Opens the WebKit AirPlay playback target picker and reflects session state. AirPlay is a WebKit-only feature, so the button reports `availability: "unsupported"` outside Safari (macOS and iOS). On supported platforms availability flips to `"available"` once Safari discovers at least one AirPlay receiver on the local network, and `"unavailable"` otherwise.
 
-The button is hidden until `availability` is `"available"`: the HTML custom element receives the native `hidden` attribute, and the React component returns `null`. An explicitly disabled, otherwise available button stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker.
+The button is hidden until `availability` is `"available"`: the element receives the native `hidden` attribute.
 
-The component consumes the unified [`remotePlayback`](./feature-remote-playback.md) store feature alongside `CastButton`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).
+An explicitly disabled, otherwise available button stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker.
+
+The component consumes the unified [`remotePlayback`](../api/feature-remote-playback.md) store feature alongside `<media-cast-button>`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).
 
 WebKit does not expose a `"connecting"` intermediate state — the `state` slice flips directly between `"disconnected"` and `"connected"` when the AirPlay session changes. When connected, the picker itself acts as the disconnect UI.
 
 ## Styling
 
-Attribute
-
-Values
-
-Description
-
-`data-airplay-state`
-
-`"disconnected"` | `"connecting"` | `"connected"`
-
-Current AirPlay session state
-
-`data-availability`
-
-`"available"` | `"unavailable"` | `"unsupported"`
-
-Whether AirPlay is reachable on the current platform
-
-`data-disabled`
-
-Present / absent
-
-Present when the button is non-interactive
-
-`data-hidden`
-
-Present / absent
-
-Present on the HTML element while AirPlay is unavailable or unsupported
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-airplay-state` | `"disconnected"` \| `"connecting"` \| `"connected"` | Current AirPlay session state |
+| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether AirPlay is reachable on the current platform |
+| `data-disabled` | Present / absent | Present when the button is non-interactive |
+| `data-hidden` | Present / absent | Present on the HTML element while AirPlay is unavailable or unsupported |
 
 Use `data-airplay-state` to swap icons or labels based on the session state:
 
-css
-
-```
+```css
 /* AirPlay active */
 media-airplay-button[data-airplay-state="connected"] {
   color: var(--accent);
@@ -73,9 +46,7 @@ media-airplay-button[data-airplay-state="connected"] {
 
 Use `data-disabled` to style an explicitly disabled, available button:
 
-css
-
-```
+```css
 media-airplay-button[data-disabled] {
   cursor: not-allowed;
   opacity: 0.5;
@@ -92,15 +63,9 @@ Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when di
 
 ### Basic Usage
 
-Stop AirPlay Start AirPlay
-
-index.html
-
-index.css
-
-index.ts
+**index.html**
 
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -111,7 +76,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -157,7 +125,10 @@ index.ts
   filter: grayscale(1);
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/airplay-button';
@@ -167,152 +138,28 @@ import '@videojs/html/ui/airplay-button';
 
 ### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`disabled`
-
-`boolean`
-
-`false`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the button is disabled.
-
-`label`
-
-`object`
-
-`''`
-
-▸
-
-Attribute
-
-`label`
-
-Description
-
-Custom label for the button.
-
-Type
-
-`{ key: string; text: string } | string | ((state: AirPlayButtonState) => Text | string)`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether the button is disabled. |
+| `label` | `{ key: string; text: string } \| string \| ((state: AirPlayButtonState) => Text \| string)` | `''` | Custom label for the button. |
 
 ### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`label`
-
-`{ key: string; text: string } | string`
-
-`state`
-
-`'disconnected' | 'connecting' | 'conn...`
-
-▸
-
-Description
-
-Current AirPlay connection state.
-
-Type
-
-`'disconnected' | 'connecting' | 'connected'`
-
-`availability`
-
-`MediaFeatureAvailability`
-
-▸
-
-Description
-
-Whether AirPlay is available on the active platform and media.
-
-`disabled`
-
-`boolean`
-
-▸
-
-Description
-
-Non-interactive but still focusable (mirrors `aria-disabled`).
-
-`hidden`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the button is hidden until AirPlay is available.
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `{ key: string; text: string } \| string` | |
+| `state` | `'disconnected' \| 'connecting' \| 'connected'` | Current AirPlay connection state. |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether AirPlay is available on the active platform and media. |
+| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
+| `hidden` | `boolean` | Whether the button is hidden until AirPlay is available. |
 
 ### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-airplay-state`
-
-`'disconnected' | 'connecting' | 'conn...`
-
-▸
-
-Description
-
-Current AirPlay connection state.
-
-Type
-
-`'disconnected' | 'connecting' | 'connected'`
-
-`data-availability`
-
-`MediaFeatureAvailability`
-
-▸
-
-Description
-
-Whether AirPlay is available on the active platform and media.
-
-`data-disabled`
-
-▸
-
-Description
-
-Present when the button is non-interactive (mirrors `aria-disabled`).
-
-`data-hidden`
-
-▸
-
-Description
-
-Present when the button is hidden because AirPlay is unavailable.
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-airplay-state` | `'disconnected' \| 'connecting' \| 'connected'` | Current AirPlay connection state. |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether AirPlay is available on the active platform and media. |
+| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
+| `data-hidden` | — | Present when the button is hidden because AirPlay is unavailable. |