@videojs/html 10.2.0 → 10.4.0

package/docs/reference/components/google-analytics.md

@@ -0,0 +1,51 @@
+# google-analytics
+
+Options for the Google Analytics 4 extension that tracks video engagement and playback events
+
+Adds the Google Analytics 4 (GA4) [extension](../../guides/architecture.md) to the player. It renders nothing — place it anywhere inside the player, and it follows whatever media the player attaches, dispatching standard GA4 Enhanced Measurement video events and playback interaction events to `window.dataLayer`. See [Google Analytics](../../guides/google-analytics.md) for how telemetry works.
+
+## Import
+
+```bash
+pnpm add @videojs/html @videojs/google-analytics
+```
+
+```ts
+import '@videojs/html/extensions/google-analytics';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/extensions/google-analytics.js"></script>
+```
+
+## Anatomy
+
+```html
+<google-analytics></google-analytics>
+```
+
+## Options
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| — | `metadata` | Video metadata and custom dimensions reported with GA4 events |
+| `data-layer-name` | `dataLayerName` | Name of the dataLayer array on `window`. Defaults to `'dataLayer'` |
+| `disable-progress` | `disableProgress` | Disables 10%, 25%, 50%, and 75% progress milestones tracking |
+| `debug` | `debug` | Logs telemetry events to the console. Defaults to `false` |
+| — | `onEvent` | Callback to intercept dispatched events |
+
+`metadata` and `onEvent` take non-primitive values, so they’re properties only, with no matching attribute. Set them on the element, typed as the `GoogleAnalyticsExtension` class that `@videojs/html/extensions/google-analytics` exports.
+
+## Collection limits
+
+Google Analytics 4 enforces collection limits on event parameters:
+
+- **25 parameters per event**: The extension sends 8 standard parameters (`video_current_time`, `video_duration`, `video_percent`, `video_provider`, `video_stream_type`, `video_title`, `video_url`, and `visible`), leaving room for up to 17 custom dimensions in `metadata`.
+- **Parameter names**: Up to 40 characters in length.
+- **String values**: Up to 100 characters in length.
+
+## See also
+
+- [Google Analytics](../../guides/google-analytics.md): Configure GA4 video telemetry

package/docs/reference/components/google-cast.md

@@ -17,7 +17,7 @@ import '@videojs/html/extensions/google-cast';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/extensions/google-cast.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/extensions/google-cast.js"></script>
 ```
 
 ## Anatomy

package/docs/reference/components/hls-audio.md

@@ -13,9 +13,19 @@ import '@videojs/html/media/hls-audio';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/hls-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/hls-audio.js"></script>
 ```
 
+## Load a source
+
+`src` takes an HLS manifest URL. A mixed audio/video manifest works too: the audio component loads only the audio rendition.
+
+```html
+<hls-audio src="https://example.com/playlist.m3u8"></hls-audio>
+```
+
+The structured `source` object takes the same shape as the [HLS video component](./hls-video.md)’s, so one object can serve either. `source.drm` is accepted but unused, because this component composes no EME.
+
 ## Examples
 
 ### Basic Usage
@@ -39,4 +49,48 @@ Or load it from the [CDN](../../guides/cdn.md):
 
 ```ts
 import '@videojs/html/media/hls-audio';
-```
+```
+
+## API Reference
+
+### Attributes
+
+Forwards these standard media attributes to the internal `<audio>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.
+
+These Video.js-specific attributes configure media behavior:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stream-type` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `crossOrigin` | `'anonymous' \| 'use-credentials' \| null` | `null` | |
+| `disableRemotePlayback` | `boolean` | `false` | |
+| `error` | `{ code: number; message: string; data?: unknown } \| null` | — | Read-only. The current fatal error, or `null`. Only *fatal* conditions appear here — the engine reports non-fatal ones too, which stay in `engine.state.errors`. Resets per source. Fires `'error'` when set. |
+| `liveEdgeStart` | `number` | — | Read-only. |
+| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `''` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ src?: string; type?: string; drm?: Partial<Record<string, DrmSystemConfig>> } \| null` | `null` | Structured source, the same shape the video flavor takes so one object serves either. `drm` is accepted and inert: this engine composes no EME. It is kept in the shape rather than removed so a source can be handed to both flavors — and because Mux encrypts video renditions and leaves audio clear, so a protected playback ID plays here regardless. |
+| `src` | `string` | `''` | |
+| `streamType` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
+| `targetLiveWindow` | `number` | — | Read-only. |
+
+Also exposes these properties from the native media API. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `autoplay`, `buffered`, `controls`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `volume`.
+
+### Methods
+
+Supports these media methods. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `addTextTrack`, `canPlayType`, `load`, `pause`, `play`, `removeTextTrack`.
+
+### Events
+
+Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `error` | Fired when a fatal condition is reported. Read `error` for it. |
+| `sourcechange` | Fired when `source` changes. Read `source` for the new value. |

package/docs/reference/components/hls-background-video.md

@@ -2,7 +2,7 @@
 
 HLS background video without controls, audio, captions, or adaptive quality
 
-`<hls-background-video>` plays an HLS source through the SPF background engine. It is fixed to muted, autoplaying, inline, looped playback and omits controls, audio, text, DRM, and adaptive rendition switching.
+`<hls-background-video>` plays an HLS source through the SPF background engine. It is fixed to muted, inline playback, loops and autoplays unless you set `noloop` or `noautoplay`, and omits controls, audio, text, DRM, and adaptive rendition switching.
 
 See [Add a background video](../../guides/background-video.md) for layout, poster, accessibility, and source-choice guidance.
 
@@ -15,7 +15,7 @@ import '@videojs/html/media/hls-background-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/hls-background-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/hls-background-video.js"></script>
 ```
 
 ## Source behavior
@@ -29,18 +29,38 @@ Or load it from the [CDN](../../guides/cdn.md):
 ></hls-background-video>
 ```
 
-There is no `source` object, `preload` mode, or opt-out for muted, autoplay, and loop. Assigning a new `src` restarts playback from scratch.
+There is no `source` object, `preload` mode, or opt-out for muted. Assigning a new `src` restarts playback from scratch.
+
+Set `noautoplay` to hold playback until your script calls `target.play()`, for example after checking `prefers-reduced-motion`, and `noloop` to play the video once. Without `noautoplay`, calling `pause()` before the stream attaches has no effect: autoplay starts the video once the stream loads.
 
 ## API
 
-| Member | Description |
+### Attributes
+
+| Attribute | Description |
 | --- | --- |
 | `src` | HLS manifest URL |
+| `noloop` | Turns off looping |
+| `noautoplay` | Turns off autoplay |
+| `crossorigin`, `controls`, `controlslist` | Passed through to the inner video |
+| `keep-alive` | Keeps the engine running after the element is removed |
+
+An explicit `loop` or `autoplay` attribute wins over its opt-out. Opt-outs and passed-through attributes also apply when set or changed after the element is created. Muted can’t be turned off, and `preload` isn’t passed through: the engine loads as soon as it has a source.
+
+### Properties
+
+| Property | Description |
+| --- | --- |
+| `src` | HLS manifest URL. Assigning a new one restarts playback from scratch |
 | `error` | Fatal SPF media error for the current source, or `null` |
-| `video` | Inner native `<video>` element |
+| `target` | Inner native `<video>` element. Call `play()` and `pause()` on it |
+| `video` | Same element as `target` |
+| `adapter` | The `HlsBackgroundVideoAdapter` driving the inner video, including its SPF `engine` |
 
 The element also fires an `error` event when `error` becomes fatal. The inner video’s own `error` can remain `null` because SPF, rather than the browser, rejected the source.
 
+Removing the element releases its engine a microtask later. If the element has its own `keep-alive`, the engine keeps running until you call `adapter.destroy()`. `keep-alive` on an ancestor, such as `<background-video-player keep-alive>`, doesn’t keep it.
+
 ## Styling
 
 | Custom property | Default | Description |

package/docs/reference/components/hls-video.md

@@ -13,7 +13,47 @@ import '@videojs/html/media/hls-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/hls-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/hls-video.js"></script>
+```
+
+## Load a source
+
+`src` takes an HLS manifest URL.
+
+```html
+<hls-video src="https://example.com/playlist.m3u8"></hls-video>
+```
+
+The structured `source` object carries what a URL can’t: `drm` for protected content. Setting `source` derives `src`.
+
+## Protected content
+
+`source.drm` names your license servers, keyed by [EME key system id](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.
+
+```ts
+const video = document.querySelector('hls-video')!;
+video.source = {
+  src: 'https://example.com/protected.m3u8',
+  drm: {
+    'com.apple.fps': {
+      licenseUrl: 'https://example.com/fairplay',
+      serverCertificateUrl: 'https://example.com/fairplay.cer',
+    },
+    'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
+  },
+};
+```
+
+FairPlay needs a `serverCertificateUrl` unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. [Media sources](../../guides/media-sources.md#drm-protected-sources) covers DRM in more depth.
+
+## Cookie-gated streams
+
+A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard `crossorigin="use-credentials"` on the element and the engine sends them, the same way the browser does under native playback. Any other value, or no attribute, leaves requests at the platform default and sends no cross-origin cookies.
+
+The CDN must answer with `Access-Control-Allow-Credentials: true` and a specific `Access-Control-Allow-Origin`, not `*`, or the browser refuses the credentialed response.
+
+```html
+<hls-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hls-video>
 ```
 
 ## Examples
@@ -46,12 +86,64 @@ import '@videojs/html/ui/container';
 import '@videojs/html/media/hls-video';
 ```
 
-## Cookie-gated streams
+## API Reference
 
-A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard `crossorigin="use-credentials"` on the element and the engine sends them, the same way the browser does under native playback. Any other value, or no attribute, leaves requests at the platform default and sends no cross-origin cookies.
+### Attributes
 
-The CDN must answer with `Access-Control-Allow-Credentials: true` and a specific `Access-Control-Allow-Origin`, not `*`, or the browser refuses the credentialed response.
+Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.
 
-```html
-<hls-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hls-video>
-```
+These Video.js-specific attributes configure media behavior:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | The source's stream type — `'live'`, `'on-demand'`, or `'unknown'` until a media playlist has been parsed. Setting a non-`'unknown'` value pins a user override (detection stops updating it); setting `'unknown'` reverts to the engine's detected value. |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `crossOrigin` | `'anonymous' \| 'use-credentials' \| null` | `null` | |
+| `disableRemotePlayback` | `boolean` | `false` | |
+| `error` | `{ code: number; message: string; data?: unknown } \| null` | — | Read-only. The current fatal error, or `null`. Only *fatal* conditions appear here — the engine reports non-fatal ones too (they stay in `engine.state.errors`), and promoting them would tell a consumer playback had failed when it hadn't. Resets per source. Fires `'error'` when set. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `isPictureInPicture` | `boolean` | — | Read-only. |
+| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the live-edge window. Playback at `currentTime >= liveEdgeStart` counts as "at the live edge", and seeking to live lands here. `NaN` when the stream isn't live or nothing has loaded yet. No change event fires; re-read it on `timeupdate` or `progress`. |
+| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `''` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ src?: string; type?: string; drm?: Partial<Record<string, DrmSystemConfig>> } \| null` | `null` | Structured source: the manifest URL plus what a URL cannot carry, which today is the license servers for protected content. Setting it derives `src`. Assigning the same object back costs nothing — changing anything takes a new one. |
+| `src` | `string` | `''` | |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | The source's stream type — `'live'`, `'on-demand'`, or `'unknown'` until a media playlist has been parsed. Setting a non-`'unknown'` value pins a user override (detection stops updating it); setting `'unknown'` reverts to the engine's detected value. |
+| `targetLiveWindow` | `number` | — | Read-only. The target live window: `NaN` for on-demand (or unknown), `0` for standard sliding-window live, `Infinity` for DVR (`#EXT-X-PLAYLIST-TYPE:EVENT`). Fires `targetlivewindowchange` on change. |
+| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
+| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
+| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |
+
+Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.
+
+### Methods
+
+Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `removeTextTrack`, `requestFullscreen`, `requestPictureInPicture`.
+
+### Events
+
+Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `error` | Fired when a fatal condition is reported. Read `error` for it. |
+| `sourcechange` | Fired when `source` changes. Read `source` for the new value. |
+| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
+| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |
+
+### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-video-border-radius` | Border radius of the video element. |
+| `--media-object-fit` | Object fit for the video. |
+| `--media-object-position` | Object position for the video. |
+| `--media-caption-track-duration` | Duration of the caption track transition. |
+| `--media-caption-track-delay` | Delay before the caption track transition. |
+| `--media-caption-track-y` | Vertical offset of the caption track. |

package/docs/reference/components/hlsjs-video.md

@@ -17,7 +17,57 @@ import '@videojs/html/media/hlsjs-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/hlsjs-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/hlsjs-video.js"></script>
+```
+
+## Load a source
+
+`src` takes an HLS manifest URL.
+
+```html
+<hlsjs-video src="https://example.com/playlist.m3u8"></hlsjs-video>
+```
+
+The structured `source` object says what to play and how to play it: `type` for a manifest URL without an `.m3u8` extension, `preferPlayback` to choose between hls.js (`'mse'`) and the browser’s own HLS (`'native'`), the adaptive resolution caps, `drm`, and engine options. Setting `source` derives `src`. [Media sources](../../guides/media-sources.md) explains each option.
+
+```ts
+const video = document.querySelector('hlsjs-video')!;
+video.source = {
+  src: 'https://example.com/manifest',
+  type: 'application/vnd.apple.mpegurl',
+  preferPlayback: 'mse',
+  maxAutoResolution: '1080p',
+};
+```
+
+## Protected content
+
+`source.drm` names your license servers, keyed by [EME key system id](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.
+
+```ts
+const video = document.querySelector('hlsjs-video')!;
+video.source = {
+  src: 'https://example.com/protected.m3u8',
+  drm: {
+    'com.apple.fps': {
+      licenseUrl: 'https://example.com/fairplay',
+      serverCertificateUrl: 'https://example.com/fairplay.cer',
+    },
+    'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
+  },
+};
+```
+
+hls.js receives every system named here. When the browser’s own HLS plays the stream, only the `com.apple.fps` entry applies. [Media sources](../../guides/media-sources.md#drm-protected-sources) covers what each path can license and how to configure hls.js’s DRM directly.
+
+## Cookie-gated streams
+
+A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard `crossorigin="use-credentials"` on the element and hls.js sends them (`withCredentials` on its XHR loader, `credentials: 'include'` on its fetch loader), the same way the browser does under native playback. Any other value, or no attribute, leaves hls.js’s default and sends no cross-origin cookies. An `xhrSetup` or `fetchSetup` you pass through `source.engine.hlsJs` still runs, after this, on the same request.
+
+The CDN must answer with `Access-Control-Allow-Credentials: true` and a specific `Access-Control-Allow-Origin`, not `*`, or the browser refuses the credentialed response.
+
+```html
+<hlsjs-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hlsjs-video>
 ```
 
 ## Examples
@@ -50,16 +100,6 @@ import '@videojs/html/ui/container';
 import '@videojs/html/media/hlsjs-video';
 ```
 
-## Cookie-gated streams
-
-A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard `crossorigin="use-credentials"` on the element and hls.js sends them (`withCredentials` on its XHR loader, `credentials: 'include'` on its fetch loader), the same way the browser does under native playback. Any other value, or no attribute, leaves hls.js’s default and sends no cross-origin cookies. An `xhrSetup` or `fetchSetup` you pass through `source.engine.hlsJs` still runs, after this, on the same request.
-
-The CDN must answer with `Access-Control-Allow-Credentials: true` and a specific `Access-Control-Allow-Origin`, not `*`, or the browser refuses the credentialed response.
-
-```html
-<hlsjs-video src="https://cdn.example.com/stream.m3u8" crossorigin="use-credentials"></hlsjs-video>
-```
-
 ## API Reference
 
 ### Attributes
@@ -81,6 +121,7 @@ These Video.js-specific attributes configure media behavior:
 | `contentData` | `MediaContentData \| undefined` | — | Read-only. |
 | `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
 | `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `engineName` | `string \| undefined` | — | Read-only. Engine this media is playing through, reported to analytics such as Mux Data: `hlsjs` via MSE, `browser` for native HLS, or `undefined` until a source loads. Read from the instance because the engine is picked per source. |
 | `error` | `MediaError \| null` | — | Read-only. |
 | `isFullscreen` | `boolean` | — | Read-only. |
 | `isPictureInPicture` | `boolean` | — | Read-only. |
@@ -110,7 +151,7 @@ When playback falls back to the browser’s own HLS, hls.js isn’t involved and
 
 ### Methods
 
-Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.
+Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `removeTextTrack`, `requestFullscreen`, `requestPictureInPicture`.
 
 ### Events
 

package/docs/reference/components/hotkey.md

@@ -27,7 +27,7 @@ Key patterns are case-insensitive and may use:
 - `Mod` for `Meta` on macOS and `Ctrl` elsewhere.
 - The special `0-9` range for digit-based seeking.
 
-Choose an `action` from the API reference below. Pass `value` as seconds for `seekStep`, a volume delta such as `0.05` or `-0.05` for `volumeStep`, or a percentage from 0 to 100 for `seekToPercent`. When omitted, `seekStep` defaults to 10 seconds and `volumeStep` defaults to five percentage points; `ArrowLeft`, `j`, and `ArrowDown` use the negative step. When `value` is omitted from `seekToPercent` with `keys="0-9"`, the pressed digit supplies the percentage.
+Choose an `action` from the API reference below. Pass `value` as seconds for `seekStep`, a volume delta such as `0.05` or `-0.05` for `volumeStep`, a percentage from 0 to 100 for `seekToPercent`, or a rate change such as `0.1` for `speedUp` and `speedDown`. When omitted, `seekStep` defaults to 10 seconds and `volumeStep` defaults to five percentage points; `ArrowLeft`, `j`, and `ArrowDown` use the negative step. When `value` is omitted from `seekToPercent` with `keys="0-9"`, the pressed digit supplies the percentage. When it is omitted from `speedUp` and `speedDown`, they move to the next faster or slower of the player’s playback rates.
 
 Toggle actions ignore held-key repeats. Step, rate, and percentage actions may repeat. A matched shortcut prevents the browser’s default behavior. Unmodified shortcuts are ignored in editable fields, and Space or Enter still activates focused buttons, links, and sliders normally.
 
@@ -127,4 +127,4 @@ import '@videojs/html/ui/play-button';
 | `keys` (required) | `string` | — | Key pattern to match, such as `Space`, `ArrowRight`, or `Mod+k`. |
 | `disabled` | `boolean` | — | Whether the hotkey is disabled. |
 | `target` | `'player' \| 'document'` | — | Whether to listen on the player container or the document. |
-| `value` | `number` | — | Numeric value passed to actions such as `seekStep`, `volumeStep`, and `seekToPercent`. Arrow-key seek and volume actions use their shared input-action step when omitted. |
+| `value` | `number` | — | Numeric value passed to actions such as `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. Arrow-key seek and volume actions use their shared input-action step when omitted, and the speed actions move through the player's playback rates. |

package/docs/reference/components/live-audio-compat-skin.md

@@ -1,8 +1,8 @@
 # live-audio-compat-skin
 
-A live audio skin designed for broader browser compatibility
+The live audio preset's plain, unbranded skin, a polished step above native controls
 
-The Compat skin of the live audio preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. It shows a Live button in place of time controls. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Compat skin of the live audio preset: the same core controls with plain, unbranded surfaces that avoid newer visual effects such as backdrop blur. It shows a Live button in place of time controls and adds captions and AirPlay buttons that the default live audio skin leaves out. The preset also provides [LiveAudioSkin](./live-audio-skin.md), [NeutralLiveAudioSkin](./live-audio-neutral-skin.md), and [ScaffoldLiveAudioSkin](./live-audio-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Customize skins](../../guides/customize-skins.md) to install and edit its source.
 
 ## Import
 
@@ -10,6 +10,12 @@ The Compat skin of the live audio preset provides basic controls and plain surfa
 import '@videojs/html/live-audio/compat-skin';
 ```
 
+The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-audio-compat.js"></script>
+```
+
 ## Anatomy
 
 The skin goes between the player and the media component. It renders its controls around the media.

package/docs/reference/components/live-audio-neutral-skin.md

@@ -2,7 +2,7 @@
 
 The live audio preset's visually lighter skin, closer to a classic control bar
 
-The neutral skin of the live audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveAudioSkin](./live-audio-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live audio preset ships.
+The neutral skin of the live audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. The preset also provides [LiveAudioSkin](./live-audio-skin.md), [CompatLiveAudioSkin](./live-audio-compat-skin.md), and [ScaffoldLiveAudioSkin](./live-audio-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Presets](../../guides/presets.md) for what the live audio preset ships.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/live-audio/neutral-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-audio-neutral.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-audio-neutral.js"></script>
 ```
 
 ## Anatomy

package/docs/reference/components/live-audio-scaffold-skin.md

@@ -2,7 +2,7 @@
 
 A live audio skin with minimal styling for custom skins
 
-The Scaffold skin of the live audio preset provides functional controls with minimal styling and no transitions. It is a starting point for a custom skin, intended to be restyled before use. It shows a Live button in place of time controls. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Scaffold skin of the live audio preset provides functional controls with minimal styling and no transitions. It is a starting point for a custom skin, intended to be restyled before use. It shows a Live button in place of time controls. The preset also provides [LiveAudioSkin](./live-audio-skin.md), [NeutralLiveAudioSkin](./live-audio-neutral-skin.md), and [CompatLiveAudioSkin](./live-audio-compat-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Customize skins](../../guides/customize-skins.md) to install and edit its source.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/live-audio/scaffold-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-audio-scaffold.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-audio-scaffold.js"></script>
 ```
 
 ## Usage

package/docs/reference/components/live-audio-skin.md

@@ -2,7 +2,7 @@
 
 The live audio preset's default skin, which swaps time controls for a Live button
 
-The default skin of the live audio preset: the audio layout with the time slider and time displays swapped for a Live button. [NeutralLiveAudioSkin](./live-audio-neutral-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live audio preset ships.
+The default skin of the live audio preset: the audio layout with the time slider and time displays swapped for a Live button. The preset also provides [NeutralLiveAudioSkin](./live-audio-neutral-skin.md), [CompatLiveAudioSkin](./live-audio-compat-skin.md), and [ScaffoldLiveAudioSkin](./live-audio-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Presets](../../guides/presets.md) for what the live audio preset ships.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/live-audio/skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-audio.js"></script>
 ```
 
 ## Anatomy

package/docs/reference/components/live-video-compat-skin.md

@@ -1,8 +1,8 @@
 # live-video-compat-skin
 
-A live video skin designed for broader browser compatibility
+The live video preset's plain, unbranded skin, a polished step above native controls
 
-The Compat skin of the live video preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. It shows a Live button in place of time controls. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Compat skin of the live video preset: the same core controls with plain, unbranded surfaces that avoid newer visual effects such as backdrop blur. It puts a large play button in the center, fullscreen, picture-in-picture, Cast, and AirPlay in a top corner, and a Live button in place of time controls. The preset also provides [LiveVideoSkin](./live-video-skin.md), [NeutralLiveVideoSkin](./live-video-neutral-skin.md), and [ScaffoldLiveVideoSkin](./live-video-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Customize skins](../../guides/customize-skins.md) to install and edit its source.
 
 ## Import
 
@@ -10,6 +10,12 @@ The Compat skin of the live video preset provides basic controls and plain surfa
 import '@videojs/html/live-video/compat-skin';
 ```
 
+The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-video-compat.js"></script>
+```
+
 ## Anatomy
 
 The skin goes between the player and the media component. It renders its controls around the media.
@@ -30,6 +36,10 @@ The skin renders a poster image before playback starts. An element with `slot="p
 
 See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## Styling
 
 Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

package/docs/reference/components/live-video-neutral-skin.md

@@ -2,7 +2,7 @@
 
 The live video preset's visually lighter skin, closer to a classic control bar
 
-The neutral skin of the live video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveVideoSkin](./live-video-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live video preset ships.
+The neutral skin of the live video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. The preset also provides [LiveVideoSkin](./live-video-skin.md), [CompatLiveVideoSkin](./live-video-compat-skin.md), and [ScaffoldLiveVideoSkin](./live-video-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Presets](../../guides/presets.md) for what the live video preset ships.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/live-video/neutral-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-video-neutral.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-video-neutral.js"></script>
 ```
 
 ## Anatomy
@@ -36,6 +36,10 @@ The skin renders a poster image before playback starts. An element with `slot="p
 
 See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## Styling
 
 Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

package/docs/reference/components/live-video-scaffold-skin.md

@@ -2,7 +2,7 @@
 
 A live video skin with minimal styling for custom skins
 
-The Scaffold skin of the live video preset provides functional controls with minimal styling and no transitions. It is a starting point for a custom skin, intended to be restyled before use. It shows a Live button in place of time controls. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Scaffold skin of the live video preset provides functional controls with minimal styling and no transitions. It is a starting point for a custom skin, intended to be restyled before use. It shows a Live button in place of time controls. The preset also provides [LiveVideoSkin](./live-video-skin.md), [NeutralLiveVideoSkin](./live-video-neutral-skin.md), and [CompatLiveVideoSkin](./live-video-compat-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Customize skins](../../guides/customize-skins.md) to install and edit its source.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/live-video/scaffold-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-video-scaffold.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-video-scaffold.js"></script>
 ```
 
 ## Usage
@@ -36,6 +36,10 @@ The skin renders a poster image before playback starts. An element with `slot="p
 
 See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## Styling
 
 Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.