@videojs/html 10.2.0 → 10.4.0

package/docs/reference/components/audio.md

@@ -70,4 +70,22 @@ This native audio element uses a child source and browser controls while providi
 ```ts
 import '@videojs/html/audio/player';
 import '@videojs/html/ui/container';
-```
+```
+
+## API Reference
+
+### Attributes
+
+Accepts the standard `<audio>` attributes. See the [MDN `<audio>` reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/audio): `autoplay`, `controls`, `controlslist`, `crossorigin`, `disableremoteplayback`, `loop`, `muted`, `preload`, `src`.
+
+### Properties
+
+Exposes the native media properties. See [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disableRemotePlayback`, `duration`, `ended`, `error`, `loop`, `mediaKeys`, `muted`, `networkState`, `paused`, `playbackRate`, `played`, `preload`, `preservesPitch`, `readyState`, `remote`, `seekable`, `seeking`, `sinkId`, `src`, `srcObject`, `textTracks`, `volume`.
+
+### Methods
+
+Supports the native media methods. See [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `addTextTrack`, `canPlayType`, `fastSeek`, `load`, `pause`, `play`, `setMediaKeys`, `setSinkId`.
+
+### Events
+
+Fires the standard media events: `abort`, `canplay`, `canplaythrough`, `durationchange`, `emptied`, `encrypted`, `ended`, `error`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`, `waitingforkey`.

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

@@ -13,7 +13,7 @@ import '@videojs/html/background/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/background.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/background.js"></script>
 ```
 
 ## Anatomy

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

@@ -4,7 +4,7 @@ Decorative background video element with automatic muting and looping
 
 Decorative background video for a source the browser can play natively. By default it’s muted, looped, and autoplaying.
 
-`<background-video>` renders a `<video>` inside shadow DOM and fills the box you give the component. Use the opt-out attributes in the [API reference](#api-reference) to change its playback defaults.
+`<background-video>` renders a `<video>` inside shadow DOM and fills the box you give the component. Use the opt-out attributes in the [API](#api) to change its playback defaults.
 
 An HLS URL only works where the browser has native HLS playback. See [Add a background video](../../guides/background-video.md) to choose a cross-browser HLS or Mux path and set up layout, poster, and decorative semantics.
 
@@ -17,7 +17,7 @@ import '@videojs/html/media/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/background-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/background-video.js"></script>
 ```
 
 ## Examples
@@ -48,20 +48,35 @@ Or load it from the [CDN](../../guides/cdn.md):
 import '@videojs/html/media/background-video';
 ```
 
-## API Reference
+## API
 
 ### Attributes
 
 | Attribute | Description |
 | --- | --- |
-| `src` | URL of a video the browser can play directly, such as an MP4 or WebM file. |
-| `nomuted` | Opt out of muted playback. By default the video is muted. |
-| `noloop` | Opt out of looped playback. By default the video loops. |
-| `noautoplay` | Opt out of autoplay. By default the video autoplays. |
+| `src` | URL of a video the browser can play directly, such as an MP4 or WebM file |
+| `nomuted` | Turns off muting |
+| `noloop` | Turns off looping |
+| `noautoplay` | Turns off autoplay |
+| `crossorigin`, `preload`, `controls`, `controlslist` | Passed through to the inner video |
 
-### CSS Custom Properties
+An explicit `muted`, `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.
 
-| Variable | Default | Description |
+### Properties
+
+| Property | Description |
+| --- | --- |
+| `src` | URL of the video. Assigning a new one restarts playback |
+| `error` | The inner video’s `MediaError`, or `null` |
+| `target` | Inner native `<video>` element. Call `play()` and `pause()` on it |
+
+The element also fires an `error` event when the inner video does.
+
+## Styling
+
+| Custom property | Default | Description |
 | --- | --- | --- |
-| `--media-object-fit` | `inherit` | Controls how the video fits its container. |
-| `--media-object-position` | `50% 50%` | Controls the position of the video within its container. |
+| `--media-object-fit` | `inherit` | How the video fits its box |
+| `--media-object-position` | `50% 50%` | Position of the video within its box |
+
+Set an explicit size on the custom element or an author-owned wrapper.

package/docs/reference/components/buffering-indicator.md

@@ -16,7 +16,7 @@ import '@videojs/html/ui/buffering-indicator';
 
 ## Behavior
 
-Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.
+Shows a loading indicator when the media is waiting to buffer and not paused, or while media with `autoplay` is trying to start, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends, or when the browser refuses the autoplay.
 
 ## Styling
 
@@ -102,7 +102,7 @@ State is reflected as data attributes for CSS styling.
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `visible` | `boolean` | Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused. |
+| `visible` | `boolean` | Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused, or while it's trying to autoplay. |
 
 ### Data attributes
 

package/docs/reference/components/captions-radio-group.md

@@ -175,7 +175,7 @@ import '@videojs/html/ui/captions-radio-group';
 
 ### media-captions-radio-group
 
-Menu radio group that generates an Off `<media-menu-radio-item>` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.
+Menu radio group that generates an Off `<media-menu-radio-item>` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item; its `data-part` `label` and `badge` descendants receive the track's text.
 
 #### Props
 
@@ -197,7 +197,7 @@ State is reflected as data attributes for CSS styling.
 | `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
 | `disabled` | `boolean` | Whether the entire option group is disabled. |
 | `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
-| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media exposes a meaningful selection. `unsupported` when the media has no such capability at all. |
 
 #### Data attributes
 
@@ -206,7 +206,7 @@ State is reflected as data attributes for CSS styling.
 | `data-active` | — | Present when captions are enabled. |
 | `data-disabled` | — | Present when track selection is disabled. |
 | `data-hidden` | — | Present when track selection is unavailable. |
-| `data-availability` | `'available' \| 'unavailable'` | Indicates captions availability (`available` or `unavailable`). |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates captions availability (`available` or `unavailable`). |
 
 #### Events
 

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/cloudflare-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/cloudflare-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/cloudflare-video.js"></script>
 ```
 
 ## Load a source

package/docs/reference/components/controls.md

@@ -30,6 +30,8 @@ If the user is active, or if the video is paused, this component will show contr
 
 User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.
 
+The controls also report whether playback has started, with `data-started`. A pending autoplay counts as started, matching the play button. Pausing does not clear it.
+
 `visibility` selects between the two modes. The default, `auto`, follows the player’s controls visibility state as described above. `always` keeps the controls visible and reports the user as active regardless of playback or idle state, and works without the controls feature. The idle delay itself is not configurable.
 
 ```html
@@ -44,7 +46,7 @@ User activity is tracked via pointer movement, keyboard input, and focus events
 
 `<media-controls-backdrop>` is an optional presentational sibling of `<media-controls-content>`. It receives the same controls state data attributes, allowing its styling and transitions to be authored independently from the controls surface.
 
-The controls parts ship no styles. These example rules provide click-through and fade behavior:
+The controls parts ship no styles. These example rules provide click-through and fade behavior, and keep the controls hidden until playback starts. Use `visibility` rather than `opacity` for that last rule, so the hidden controls can’t receive focus:
 
 ```css
 /* Click-through: clicks pass through controls to video beneath */
@@ -74,6 +76,12 @@ media-controls-content:not([data-visible]) {
 media-controls-backdrop:not([data-visible]) {
   opacity: 0;
 }
+
+/* Hide the controls until playback starts */
+media-controls-content:not([data-started]),
+media-controls-backdrop:not([data-started]) {
+  visibility: hidden;
+}
 ```
 
 ## Accessibility
@@ -208,7 +216,7 @@ import '@videojs/html/ui/time';
 
 ### media-controls
 
-Tracks controls visibility, reflects it as data attributes, and shares it with its descendant controls parts. Hiding the controls closes any popup open inside it.
+Tracks controls visibility and whether playback has started, reflects them as data attributes, and shares them with its descendant controls parts. Hiding the controls closes any popup open inside it.
 
 #### Props
 
@@ -224,6 +232,7 @@ State is reflected as data attributes for CSS styling.
 | --- | --- | --- |
 | `visible` | `boolean` | Whether the controls are visible. |
 | `userActive` | `boolean` | Whether the user has recently interacted with the player. |
+| `started` | `boolean` | Whether playback has started or the media is trying to autoplay. |
 
 #### Data attributes
 
@@ -231,6 +240,7 @@ State is reflected as data attributes for CSS styling.
 | --- | --- |
 | `data-visible` | Present when controls are visible. |
 | `data-user-active` | Present when the user has recently interacted. |
+| `data-started` | Present when playback has started or the media is trying to autoplay. |
 
 ### media-controls-backdrop
 
@@ -242,6 +252,7 @@ Presentational backdrop that reflects its owning controls surface's state.
 | --- | --- |
 | `data-visible` | Present when controls are visible. |
 | `data-user-active` | Present when the user has recently interacted. |
+| `data-started` | Present when playback has started or the media is trying to autoplay. |
 
 ### media-controls-content
 
@@ -253,6 +264,7 @@ Interactive surface that reflects its owning controls state.
 | --- | --- |
 | `data-visible` | Present when controls are visible. |
 | `data-user-active` | Present when the user has recently interacted. |
+| `data-started` | Present when playback has started or the media is trying to autoplay. |
 
 ### media-controls-group
 
@@ -263,4 +275,5 @@ Layout group for related controls; sets `role="group"` when labeled.
 | Attribute | Description |
 | --- | --- |
 | `data-visible` | Present when controls are visible. |
-| `data-user-active` | Present when the user has recently interacted. |
+| `data-user-active` | Present when the user has recently interacted. |
+| `data-started` | Present when playback has started or the media is trying to autoplay. |

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

@@ -0,0 +1,192 @@
+# dailymotion-video
+
+Video component that plays Dailymotion videos through a Dailymotion player configuration
+
+The Dailymotion player plays videos inside a player configuration you create in [Dailymotion Studio](https://www.dailymotion.com/partner/embed/players), and this component drives it through the [Dailymotion Web SDK](https://developers.dailymotion.com/reference/web-sdk-player-methods). Dailymotion refuses any embed that doesn’t name a player configuration, so every source carries a Player ID. See [Create a Player](https://developers.dailymotion.com/docs/create-a-player) in the official Dailymotion documentation.
+
+> **Caution: Works without a skin**
+>
+> Dailymotion’s terms don’t allow covering its player, so this component uses Dailymotion’s own controls instead of a Video.js skin (see [Use Dailymotion’s controls](#use-dailymotions-controls)). If you need it to work with a skin, [open an issue](https://github.com/videojs/video.js/issues) describing your use case.
+
+## Import
+
+```bash
+pnpm add @videojs/dailymotion-video
+```
+
+```ts
+import '@videojs/html/media/dailymotion-video';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/dailymotion-video.js"></script>
+```
+
+## Load a source
+
+The simplest `src` is the player embed URL Dailymotion Studio gives you, which names both the player configuration and the video:
+
+```html
+<dailymotion-video src="https://geo.dailymotion.com/player/x8lr5.html?video=x84sh87"></dailymotion-video>
+```
+
+### Specify the Player ID
+
+These URLs name a video but no player configuration, so pair them with `engine.dailymotion.player`:
+
+- Video page URLs: `dailymotion.com/video/<id>`
+- Legacy embed URLs: `dailymotion.com/embed/video/<id>`, or `geo.dailymotion.com/player.html?video=<id>`, where they now redirect
+- Short links: `dai.ly/<id>`
+
+`engine.dailymotion.player` also wins over the configuration a player embed URL names. [Configure the player in Dailymotion Studio](#configure-the-player-in-dailymotion-studio) covers where a Player ID comes from. Dailymotion’s [runtime parameters](https://developers.dailymotion.com/reference/web-sdk-player-runtime-parameters) go next to it:
+
+```ts
+const video = document.querySelector('dailymotion-video');
+video.source = {
+  src: 'https://www.dailymotion.com/video/x84sh87',
+  engine: { dailymotion: { player: 'x8lr5', startTime: 10 } },
+};
+```
+
+The URL’s query can also carry Dailymotion’s `startTime` (or the older `start`), `scaleMode`, and `customConfig[key]=value`, as Dailymotion’s iframe embed reads them; `engine.dailymotion` wins over them. `loop`, `autoplay`, and mute come from the component’s own props.
+
+Without a Player ID, the component reports a `MEDIA_ERR_SRC_NOT_SUPPORTED` error instead of creating a player Dailymotion would reject, and in development it logs a warning that points to `engine.dailymotion.player`. The SDK script is loaded from `geo.dailymotion.com` with the first player created on the page; under a [Content Security Policy](../../guides/content-security-policy.md), allow that origin.
+
+## Use Dailymotion’s controls
+
+Dailymotion’s [Terms of Use](https://legal.dailymotion.com/en/terms-of-use/) don’t allow blocking any part of its embedded player, including its links back to Dailymotion. So the component always lets the player take pointer input, and Dailymotion’s own controls, logo, and links stay usable.
+
+A [skin](../../guides/skins.md) doesn’t work over the player, which takes the pointer input over the video before the skin can see it, so use the component without one, as in [Basic Usage](#basic-usage).
+
+## Configure the player in Dailymotion Studio
+
+Create a player configuration on the Players page in [Dailymotion Studio](https://www.dailymotion.com/partner/embed/players). Its Player ID is the part of the player embed URL Studio gives you after `/player/`: `x8lr5` in `geo.dailymotion.com/player/x8lr5.html`.
+
+The player configuration decides what the embed can’t change at runtime:
+
+| Setting | Effect |
+| --- | --- |
+| Controls | Which of Dailymotion’s controls show. `controls` has no effect. |
+| Autostart | `autoplay` decides whether the video starts: with it off, the component pauses the configuration’s autostart as it starts. An ad that plays first is never paused, and the video after it is. Turning Autostart off avoids the pause. |
+| Autonext | When the player moves on to the next video by itself, `src` still names the one you loaded. It also overrides `loop`: the video stops at the end, and the component reports `ended`. |
+| Picture-in-picture | Dailymotion’s picture-in-picture moves the player out of the element. |
+| Poster, preload, and inline playback | `poster`, `preload`, and `playsinline` are accepted for parity with `<video>` but have no effect. |
+
+## Behavior
+
+- Volume and mute both work, like a native `<video>`. Dailymotion has no separate mute, so muting sets its volume to `0` and unmuting restores the previous level.
+- `playbackRate` takes Dailymotion’s rates, `0.25` to `2` in steps of `0.25`. Dailymotion rounds any other value up to the next one and caps it at `2`, and `playbackRate` then reports the rate it plays at.
+- `loop` is passed to Dailymotion, which restarts the video itself.
+- A new source loads into the same player while the Player ID and the runtime parameters other than `startTime` stay the same, whether they come from `engine.dailymotion` or the URL’s query. Any other change creates a new player, since Dailymotion only reads them when a player is created. So does `autoplay`, but only at the next load: call `load()` to apply a change right away. `muted` and `loop` change in place.
+- Depending on the player configuration, Dailymotion may ignore a seek made before the video first plays, and playback then starts from the beginning. To start at a known position, set `startTime` on the source (under `engine.dailymotion`, or in the URL) instead: Dailymotion applies it on load.
+- Seeking while paused stays paused, as on a native `<video>`. Dailymotion starts playback on a seek from its start or end screen, and the component pauses it again as it starts, unless an ad plays first.
+- The SDK reports no buffered range, so `buffered` ends at the furthest point played.
+- Ads play inside the embed, and the component never pauses one. `paused` follows the ad while it plays, but `currentTime` and `duration` always describe the video.
+- When the browser refuses to start playback, as it does for unmuted autoplay, the component reports `pause` instead of playing.
+- Fullscreen targets the element the player is built in.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<dailymotion-video muted src="https://geo.dailymotion.com/player/x8lr5.html?video=x84sh87" class="dailymotion-video"></dailymotion-video>
+```
+
+**index.css**
+
+```css
+.dailymotion-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/dailymotion-video';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Starts playback on each load, through Dailymotion's `autoplay` parameter and a play sent once the player is ready. When off, a player configuration whose Autostart is on is paused as it starts, unless an ad plays first. |
+| `controls` | `boolean` | `false` | Has no effect: the player configuration decides whether Dailymotion's controls show, which the SDK can't change. |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `playsinline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `src` | `string` | `''` | |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Starts playback on each load, through Dailymotion's `autoplay` parameter and a play sent once the player is ready. When off, a player configuration whose Autostart is on is paused as it starts, unless an ad plays first. |
+| `buffered` | `TimeRangeLike` | — | Read-only. |
+| `controls` | `boolean` | `false` | Has no effect: the player configuration decides whether Dailymotion's controls show, which the SDK can't change. |
+| `currentSrc` | `string` | — | Read-only. |
+| `currentTime` | `number` | — | |
+| `defaultMuted` | `boolean` | `false` | |
+| `duration` | `number` | — | Read-only. |
+| `ended` | `boolean` | — | Read-only. |
+| `engine` | `{ play(): void; pause(): void; seek(time: number): void; setVolume(volume: number): void; setPlaybackSpeed(speed: number): void; setLoop(loop: boolean): void; updateParams(params: Record<string, unknown>): void; loadContent(options: { video: string; startTime?: number }): void; getState(): Promise<DailymotionPlayerState>; getSettings(): { autostart?: string }; on(event: string, listener: ((state: DailymotionPlayerState) => void)): void; off(event: string, listener?: ((state: DailymotionPlayerState) => void)): void; destroy(): void } \| null` | — | Read-only. The SDK's player object, or null until the player is ready. |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `paused` | `boolean` | — | Read-only. |
+| `playbackRate` | `number` | — | Dailymotion plays at a fixed set of rates (`0.25` to `2` in quarter steps): it rounds any other rate up to the next one, and caps it at `2`. |
+| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `readyState` | `number` | — | Read-only. |
+| `seekable` | `TimeRangeLike` | — | Read-only. |
+| `seeking` | `boolean` | — | Read-only. |
+| `source` | `{ src?: string; engine?: DailymotionSourceEngineConfig } \| null` | `null` | Dailymotion video URL in `src`, player configuration and parameters under `engine.dailymotion`. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Unsupported: the player draws its own subtitles and reports no cues to render elsewhere. |
+| `volume` | `number` | — | |
+
+### Engine options
+
+#### `source.engine.dailymotion`
+
+Pass the Player ID as `player`, plus [Dailymotion runtime parameters](https://developers.dailymotion.com/reference/web-sdk-player-runtime-parameters) under `source.engine.dailymotion`, spelled exactly as Dailymotion spells them. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+The video comes from `src`, and `loop` and `autoplay` from the props of the same name, so none of them has an `engine.dailymotion` spelling. Mute isn’t a runtime parameter either: the component applies it through the SDK. [Configure the player in Dailymotion Studio](#configure-the-player-in-dailymotion-studio) lists what only the player configuration decides, such as controls.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `customConfig` | `Record<string, string> \| undefined` | Advertising key-values ([https://developers.dailymotion.com/docs/custom-config](https://developers.dailymotion.com/docs/custom-config)). |
+| `player` | `string \| undefined` | Player ID of a player configuration from Dailymotion Studio. Required unless `src` is a player embed URL, which names its own; this one wins over it. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the iframe the SDK builds. |
+| `scaleMode` | `'fit' \| 'fill' \| 'fillLeft' \| 'fillRight' \| 'fillTop' \| 'fillBottom' \| undefined` | How the video fills the player. Defaults to `'fit'`. |
+| `startTime` | `number \| undefined` | Start position in seconds. |
+
+### Methods
+
+Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.
+
+### Events
+
+Implements these standard media events through the embedded player: `canplay`, `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `ratechange`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `loadcomplete` | |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

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

@@ -21,7 +21,25 @@ import '@videojs/html/media/dash-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/dash-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/dash-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a DASH manifest (MPD) URL.
+
+```html
+<dash-video src="https://example.com/manifest.mpd"></dash-video>
+```
+
+The structured `source` object pairs the URL with dash.js settings under `engine.dashJs`. Setting `source` derives `src`, and changing `engine.dashJs` applies the settings to the running player instead of recreating it.
+
+```ts
+const video = document.querySelector('dash-video')!;
+video.source = {
+  src: 'https://example.com/manifest.mpd',
+  engine: { dashJs: { streaming: { buffer: { bufferTimeAtTopQuality: 30 } } } },
+};
 ```
 
 ## Examples
@@ -87,7 +105,7 @@ Also exposes these properties from the native media API. See [HTMLVideoElement](
 
 ### 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/dialog.md

@@ -35,6 +35,12 @@ Place a button immediately before `media-dialog`, or connect them explicitly wit
 
 The close part and Escape close the dialog. Other buttons inside the dialog, including player controls, do not close it.
 
+### Inside and outside a player
+
+A dialog inside a player is confined to that player. The rest of the player becomes inert, but the page around it stays interactive and `aria-modal` is omitted. A dialog outside a player is modal for the whole page, with `aria-modal="true"` and everything outside the popup inert.
+
+The backdrop and popup get `data-scope`: `player` inside a player and `document` outside one. The built-in skin styles use it to switch from `position: absolute` to `position: fixed`. In your own styles, give a dialog outside a player `position: fixed` so it covers the viewport, as with any headless dialog. Inside a skin, give the backdrop and popup a `z-index` above the controls; the built-in skins use `40` and `50`.
+
 Your application decides what opening and closing mean for the media. The example starts playback after opening and pauses it as soon as the dialog closes. Handle the promise returned by `play()`, since browsers can reject autoplay when it is not allowed.
 
 Use [`<media-alert-dialog>`](./alert-dialog.md) for urgent messages that require acknowledgement. [`<media-error-dialog>`](./error-dialog.md) is the player-error specialization. Both use the same dialog behavior.
@@ -48,8 +54,24 @@ Use the open and transition data attributes to style the modal and its animation
 | `data-open` | Present while the dialog is open, including its closing transition |
 | `data-starting-style` | Present at the start of the opening transition |
 | `data-ending-style` | Present during the closing transition |
+| `data-scope` | `player` inside a player, `document` outside one |
 
 ```css
+media-dialog-backdrop {
+  position: absolute;
+  z-index: 40;
+}
+
+media-dialog-popup {
+  position: absolute;
+  z-index: 50;
+}
+
+media-dialog-backdrop[data-scope="document"],
+media-dialog-popup[data-scope="document"] {
+  position: fixed;
+}
+
 media-dialog-backdrop:not([data-open]),
 media-dialog-popup:not([data-open]) {
   display: none;
@@ -65,9 +87,9 @@ media-dialog-popup[data-ending-style] {
 
 ## Accessibility
 
-The popup uses `role="dialog"` and `aria-modal="true"`. Include `<media-dialog-title>` so the dialog always has an accessible name. `<media-dialog-description>` is optional. These parts receive generated IDs connected through `aria-labelledby` and `aria-describedby`. The trigger receives `aria-haspopup`, `aria-controls`, and `aria-expanded`.
+The popup uses `role="dialog"`, plus `aria-modal="true"` outside a player. Include `<media-dialog-title>` so the dialog always has an accessible name. `<media-dialog-description>` is optional. These parts receive generated IDs connected through `aria-labelledby` and `aria-describedby`. The trigger receives `aria-haspopup`, `aria-controls`, and `aria-expanded`.
 
-When the dialog opens, focus moves to an element with `autofocus`, the first focusable element, or the popup itself. Tab and Shift + Tab keep focus within the dialog, and content outside the dialog becomes inert. Closing restores focus to the trigger, or to the element that was focused before the dialog opened.
+When the dialog opens, focus moves to an element with `autofocus`, the first focusable element, or the popup itself. Tab and Shift + Tab keep focus within the dialog, and content outside the dialog, within its player or the page, becomes inert. Closing restores focus to the trigger, or to the element that was focused before the dialog opened.
 
 Dialogs inside the same player container share modal coordination. Opening one closes the current dialog and dismisses any open menu, tooltip, or popover before focus moves into the new popup.
 
@@ -276,14 +298,16 @@ State is reflected as data attributes for CSS styling.
 | `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
 | `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
 | `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |
+| `scope` | `'player' \| 'document'` | `player` when the dialog is rendered inside a player and confined to it, otherwise `document`. |
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 #### Events
 
@@ -298,11 +322,12 @@ Presentational backdrop that reflects its owning dialog's state.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-close
 
@@ -310,11 +335,12 @@ Button that closes its owning dialog; the element itself takes `role="button"` a
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-description
 
@@ -326,11 +352,12 @@ Semantic popup that owns focus management and dialog transition completion.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-title
 

package/docs/reference/components/error-dialog.md

@@ -229,6 +229,7 @@ State is reflected as data attributes for CSS styling.
 | `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
 | `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
 | `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |
+| `scope` | `'player' \| 'document'` | `player` when the dialog is rendered inside a player and confined to it, otherwise `document`. |
 
 ### media-dialog-backdrop
 
@@ -236,11 +237,12 @@ Presentational backdrop that reflects its owning dialog's state.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-popup
 
@@ -248,8 +250,9 @@ Semantic popup that owns focus management and dialog transition completion.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |

package/docs/reference/components/gesture.md

@@ -35,7 +35,7 @@ Use `pointer` to accept only `mouse`, `touch`, or `pen` input. Use `region` to d
 
 An unregional gesture acts as a fallback outside the active regions. When several registrations match the same gesture, the first registration wins.
 
-Choose a built-in `action` from the API reference below, or use an application-defined name to call a same-named action on the player store. Pass `value` as seconds for `seekStep` or as a volume delta such as `0.05` or `-0.05` for `volumeStep`. When omitted, these actions use the 10-second or five-percentage-point default. A left-region seek gesture uses the negative step. Unknown action names do nothing and warn in development.
+Choose a built-in `action` from the API reference below, or use an application-defined name to call a same-named action on the player store. Pass `value` as seconds for `seekStep`, as a volume delta such as `0.05` or `-0.05` for `volumeStep`, or as a rate change such as `0.1` for `speedUp` and `speedDown`. When omitted, the seek and volume actions use the 10-second or five-percentage-point default, and the speed actions move to the next faster or slower of the player’s playback rates. A left-region seek gesture uses the negative step. Unknown action names do nothing and warn in development.
 
 ## Accessibility
 
@@ -135,4 +135,4 @@ import '@videojs/html/ui/play-button';
 | `disabled` | `boolean` | — | Whether the gesture is disabled. |
 | `pointer` | `'mouse' \| 'touch' \| 'pen'` | — | Pointer type that may activate the gesture. All pointer types are accepted when omitted. |
 | `region` | `'left' \| 'center' \| 'right'` | — | Optional horizontal part of the container that may activate the gesture. |
-| `value` | `number` | — | Numeric value passed to actions such as `seekStep` and `volumeStep`. Uses their shared step when omitted. |
+| `value` | `number` | — | Numeric value passed to actions such as `seekStep`, `volumeStep`, `speedUp`, and `speedDown`. The seek and volume actions use their shared step when omitted, and the speed actions move through the player's playback rates. |