@videojs/html 10.1.0 → 10.3.0

package/docs/reference/components/play-button.md

@@ -18,22 +18,24 @@ import '@videojs/html/ui/play-button';
 
 The play button is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.
 
+While media with `autoplay` is trying to start, the button shows **pause**, and clicking it cancels the autoplay. If the browser refuses the autoplay, the button returns to **play**.
+
 ## Styling
 
-Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:
+Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. While autoplay is pending, the button omits `data-paused` and adds `data-started`, so the pause icon shows. For example:
 
 ```css
 /* Paused (but not ended) */
 media-play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }
 
-/* Playing */
+/* Playing, or autoplay pending */
 media-play-button:not([data-paused]) .pause-icon { display: inline; }
 
 /* Ended */
 media-play-button[data-ended] .replay-icon { display: inline; }
 ```
 
-After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn’t started yet:
+The `data-started` attribute is present while the media tries to autoplay, and from first play until a new source is loaded. Use this to hide the play button when media hasn’t started yet:
 
 ```css
 /* Hide play button before first play */
@@ -146,6 +148,6 @@ State is reflected as data attributes for CSS styling.
 
 | Attribute | Description |
 | --- | --- |
-| `data-paused` | Present when the media is paused. |
+| `data-paused` | Present when the media is paused and not trying to autoplay. |
 | `data-ended` | Present when the media has ended. |
-| `data-started` | Present when playback has started. |
+| `data-started` | Present when playback has started or the media is trying to autoplay. |

package/docs/reference/components/playback-rate-button.md

@@ -16,12 +16,20 @@ import '@videojs/html/ui/playback-rate-button';
 
 ## Behavior
 
-Cycles through playback rates on click. The default rate list is `[0.2, 0.5, 0.7, 1, 1.2, 1.5, 1.7, 2]`. After the last rate, it wraps back to the first. If the current rate isn’t in the list (e.g., set programmatically), the button jumps to the next rate greater than the current one.
+Cycles through the player’s playback rates on click, in the order they are listed. The default list is `[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]`; see the [playback rate feature](../api/feature-playback-rate.md) to set your own for the whole player, or set `rates` on the button to give it its own list. After the last rate, it wraps back to the first. If the current rate isn’t in the list (e.g., set programmatically), the button jumps to the next rate greater than the current one.
 
 When `commandfor` is set, activation opens the linked playback-rate menu instead of cycling through rates. Use this mode when the button is the trigger for a `<media-menu>` that contains playback-rate options.
 
+When the media’s playback rate is unavailable or unsupported, such as on an embed that takes no speed command, the element receives the native `hidden` attribute and ignores activation.
+
 ## Styling
 
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-rate` | Number | Current playback rate |
+| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether the media can change its playback rate |
+| `data-hidden` | Present / absent | Present on the HTML element while playback rate is unavailable or unsupported |
+
 Display the current rate using the `data-rate` attribute:
 
 ```css
@@ -32,7 +40,7 @@ media-playback-rate-button::after {
 
 ## Accessibility
 
-Renders a `<button>` with an automatic `aria-label` of `"Playback rate {rate}"` (e.g., `"Playback rate 1.5"`). Override with the `label` prop. Keyboard activation: Enter / Space.
+Renders a `<button>` with an automatic `aria-label` of `"Playback rate, {rate}"` (e.g., `"Playback rate, 1.5"`). Its tooltip shows `"Playback rate"` without the value. Override both with the `label` prop. Keyboard activation: Enter / Space.
 
 In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.
 
@@ -97,18 +105,29 @@ import '@videojs/html/ui/playback-rate-button';
 | --- | --- | --- | --- |
 | `disabled` | `boolean` | `false` | Whether the button is disabled. |
 | `label` | `{ key: string; text: string } \| string \| ((state: PlaybackRateButtonState) => Text \| string)` | `''` | Custom label for the button. |
+| `rates` | `readonly number[] \| string` | `[]` | Rates to cycle through, in order, in place of the player's `defaultPlaybackRates`. HTML takes a space-separated list, such as `rates="1 1.5 2"`. |
 
 ### State
 
 State is reflected as data attributes for CSS styling.
 
-| Property | Type |
-| --- | --- |
-| `label` | `{ key: string; text: string } \| string` |
-| `rate` | `number` |
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `{ key: string; text: string } \| string` | |
+| `rate` | `number` | |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can change its playback rate. |
+| `hidden` | `boolean` | Whether the button is hidden because the media has no playback rate to change. |
 
 ### Data attributes
 
 | Attribute | Type | Description |
 | --- | --- | --- |
-| `data-rate` | `number` | Current playback rate. |
+| `data-rate` | `number` | Current playback rate. |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates playback rate availability (`available`, `unavailable`, `unsupported`). |
+| `data-hidden` | — | Present when the button is hidden because the media has no playback rate to change. |
+
+### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-playback-rate-length` | Characters in the current rate as text, such as `4` for `1.75`. Lets a skin size the label to fit the button. |

package/docs/reference/components/playback-rate-radio-group.md

@@ -27,7 +27,9 @@ import '@videojs/html/ui/menu-item-indicator';
 
 ## Behavior
 
-The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
+The group is available when the configured media exposes playback rates. It offers the player’s playback rates, or its own when you set `rates`. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
+
+When the current rate isn’t one the group offers, such as `1.1` set through the media API, the group adds it as an extra item before the next faster rate. That item carries `data-custom`, and its accessible name is “Custom, 1.1×” while its visible label stays `1.1×`. It goes away once the rate is back on the list.
 
 `<media-playback-rate-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.
 
@@ -40,7 +42,7 @@ The group is available when the configured media exposes playback rates. Option
 | `data-hidden` | Present / absent | Present when playback-rate selection is unavailable. |
 | `data-availability` | `"available"` / `"unavailable"` | Whether playback rates are available. |
 
-Unavailable groups receive the native `hidden` attribute.
+Unavailable groups receive the native `hidden` attribute. Each item carries `data-rate`, and an item for a current rate the group doesn’t offer also carries `data-custom`.
 
 ## Accessibility
 
@@ -180,6 +182,7 @@ Menu radio group that generates a `<media-menu-radio-item>` per available playba
 | --- | --- | --- | --- |
 | `disabled` | `boolean` | `false` | Whether playback rate selection is disabled. |
 | `formatRate` (attribute `format-rate`) | `((rate: number) => string)` | `formatPlaybackRate` | Custom formatter for visible playback rate labels. |
+| `rates` | `readonly number[] \| string` | `[]` | Rates to offer, in order, in place of the player's `defaultPlaybackRates`. HTML takes a space-separated list, such as `rates="1 1.5 2"`. |
 
 #### State
 
@@ -192,7 +195,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. |
 | `rate` | `number` | |
 
 #### Data attributes
@@ -202,7 +205,7 @@ State is reflected as data attributes for CSS styling.
 | `data-rate` | `number` | Current playback rate. |
 | `data-disabled` | — | Present when playback rate selection is disabled. |
 | `data-hidden` | — | Present when playback rate selection is unavailable. |
-| `data-availability` | `'available' \| 'unavailable'` | Indicates playback rate availability (`available` or `unavailable`). |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates playback rate availability (`available`, `unavailable`, `unsupported`). |
 
 #### Events
 

package/docs/reference/components/player.md

@@ -124,14 +124,14 @@ Video.js elements clean up after themselves when you remove them from the page:
 - `<video-player>` and the UI elements destroy themselves two animation frames after they’re removed. Destroying the player also destroys its store.
 - Media components such as `<hlsjs-video>` tear down their playback engine in a microtask after they’re removed.
 
-Moving an element synchronously, removing it and inserting it elsewhere with no `await` in between, triggers neither. To keep an element through a longer move, add the `keep-alive` attribute:
+Moving an element synchronously, removing it and inserting it elsewhere with no `await` in between, triggers neither. To keep the player through a longer move, add the `keep-alive` attribute to it and to its media component:
 
 ```html
 <video-player keep-alive>
-  <media-container keep-alive>
+  <media-container>
     <hlsjs-video src="/stream.m3u8" keep-alive></hlsjs-video>
   </media-container>
 </video-player>
 ```
 
-`keep-alive` applies only to the element that carries it; descendants don’t inherit it. Set it on every Video.js element in the tree you move. Packaged skins don’t pass it to the controls inside them, so move a player that uses a packaged skin synchronously. An element with `keep-alive` is never destroyed automatically. When you’re finished with it, call `destroy()` on the player and UI elements, and `adapter.destroy()` on media components, which release their engine that way. A destroyed element can’t be reconnected; create a new one instead.
+On the player, `keep-alive` covers the player and every UI element inside it, including the controls inside a packaged skin. Media components don’t inherit it, because destroying the player doesn’t release their engine: give each one its own `keep-alive`, or it tears down its engine as usual. An element you remove on its own from a kept-alive tree still destroys itself. `keep-alive` only stops an element from destroying itself: destroying an element, automatically or with `destroy()`, also destroys the UI elements inside it, including ones that carry `keep-alive`. When you’re finished, call `destroy()` on the player and `adapter.destroy()` on each media component to release its engine. A destroyed element can’t be reconnected; create a new one instead.

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/playerjs-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.1.0/media/playerjs-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/playerjs-video.js"></script>
 ```
 
 ## Load a source

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

@@ -220,7 +220,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
 
@@ -229,7 +229,7 @@ State is reflected as data attributes for CSS styling.
 | `data-quality` | `string` | Current quality value. |
 | `data-disabled` | — | Present when quality selection is disabled. |
 | `data-hidden` | — | Present when quality selection is unavailable. |
-| `data-availability` | `'available' \| 'unavailable'` | Indicates quality availability (`available` or `unavailable`). |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates quality availability (`available` or `unavailable`). |
 
 #### Events
 

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

@@ -21,7 +21,7 @@ import '@videojs/html/media/shaka-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.1.0/media/shaka-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/shaka-video.js"></script>
 ```
 
 ## Load a source
@@ -121,6 +121,7 @@ These Video.js-specific attributes configure media behavior:
 | `isFullscreen` | `boolean` | — | Read-only. |
 | `isPictureInPicture` | `boolean` | — | Read-only. |
 | `liveEdgeStart` | `number` | — | Read-only. |
+| `playbackRateRange` | `{ min: number; max: number } \| undefined` | — | Read-only. The target's narrower rate range, when it reports one; native media accept the browser's range. |
 | `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `'metadata'` | How much to fetch before playback is asked for, mirroring the media element's own `preload`. Shaka has no split between "know the source" and "buffer it", so this maps onto when and how `engine.load()` runs:<br>- `'auto'` — load immediately with the configured buffering goals.<br>- `'metadata'` — load immediately, holding buffering to about a segment; the configured goals come back on the first play intent.<br>- `'none'` / `''` — hold the load entirely until the first play intent. A play intent is a `play` event, a target that is already playing, or `autoplay` — which the spec lets override `preload` for good reason: with nothing fetched there is nothing whose readiness could ever fire it. Widening (`none` → `auto`) takes effect immediately; narrowing after a load began cannot un-fetch and leaves it alone. |
 | `source` | `{ src?: string; type?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: ShakaEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`drm`, `engine.shaka`). Replacing it re-derives `src`. Shaka takes configuration on a live player, so changing `engine.shaka` re-applies it in place instead of recreating the engine. |
 | `src` | `string` | `''` | |

package/docs/reference/components/slider.md

@@ -73,6 +73,8 @@ Renders with `role="slider"` and automatic ARIA attributes (`aria-valuemin`, `ar
 - Home: jump to minimum
 - End: jump to maximum
 
+Before each keyboard step, the value snaps to the nearest multiple of `step`.
+
 ## Examples
 
 ### Basic

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

@@ -0,0 +1,227 @@
+# soundcloud-audio
+
+Audio component that plays SoundCloud tracks and sets through the SoundCloud Widget
+
+The [SoundCloud Widget](https://developers.soundcloud.com/docs/api/html5-widget) plays public and private SoundCloud tracks and sets. This component drives the widget and reports its state like a native `<audio>` element, so a [player skin](../../guides/skins.md) can control it.
+
+## Import
+
+```bash
+pnpm add @videojs/soundcloud-audio
+```
+
+```ts
+import '@videojs/html/media/soundcloud-audio';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/soundcloud-audio.js"></script>
+```
+
+## Load a source
+
+`src` takes any of these SoundCloud URLs:
+
+- A track: `soundcloud.com/<user>/<track>`
+- A set: `soundcloud.com/<user>/sets/<set>`
+- A private track or set, with its secret token: `soundcloud.com/<user>/<track>/s-<token>`
+- An API resource: `api.soundcloud.com/tracks/<id>` or `api.soundcloud.com/playlists/<id>`, with an optional `secret_token`. The id can also be a URN such as `soundcloud:tracks:<id>`
+- A widget embed URL: `w.soundcloud.com/player/?url=...`, as SoundCloud’s own embed code gives it
+
+`m.soundcloud.com` links work too. Add `#t=` to start at a given time, in seconds (`#t=90`), clock time (`#t=1:30`), or units (`#t=1m30s`). Profiles, likes, and other pages that list sounds are not supported.
+
+```html
+<soundcloud-audio src="https://soundcloud.com/forss/flickermood#t=1:30"></soundcloud-audio>
+```
+
+## Controls
+
+The widget is the only UI SoundCloud offers, so `controls` decides whether the component is visible at all. Without `controls`, the component hides itself and plays as an invisible transport: a hidden iframe still loads and plays, so a [player skin](../../guides/skins.md) drives playback while the widget takes no room on the page.
+
+```html
+<audio-player>
+  <audio-skin>
+    <soundcloud-audio src="https://soundcloud.com/forss/flickermood"></soundcloud-audio>
+  </audio-skin>
+</audio-player>
+```
+
+With `controls`, the component shows the widget, and the audio skin draws its controls below it, so the two do not overlap. Anything the listener does in the widget shows in the skin: play, pause, seeking on the waveform, and picking another track of a set. The widget is also the part of the page that credits the uploader and links back to the sound on SoundCloud (see [SoundCloud’s terms of use](#soundclouds-terms-of-use)).
+
+```html
+<soundcloud-audio src="https://soundcloud.com/forss/flickermood" controls></soundcloud-audio>
+```
+
+With `controls`, the component is 166 pixels tall by default, SoundCloud’s classic layout. Set a height to change it. From about 300 pixels, a set also shows its track list, and 450 pixels shows most of it. The large artwork layout of `visual: true` (see [widget parameters](#widget-parameters)) needs 300 pixels or more. At the default height, the artwork shows only behind the waveform.
+
+```css
+soundcloud-audio {
+  height: 300px;
+}
+```
+
+## Widget parameters
+
+By default, the component hides the parts of the widget a skin has no use for: the buy, share, and download buttons, comments, reposts, the teaser, the related tracks shown after a track ends, and the large artwork layout. The uploader, the title, the artwork, and the SoundCloud logo stay whenever the widget shows.
+
+Change any of these, or set `color`, under `source.engine.soundcloud`, spelled as SoundCloud spells them:
+
+```ts
+const audio = document.querySelector('soundcloud-audio');
+audio.source = {
+  src: 'https://soundcloud.com/forss/sets/soulhack',
+  engine: { soundcloud: { color: '#ff5500', start_track: 2, sharing: true } },
+};
+```
+
+Without JavaScript, put the parameters on a widget embed URL instead:
+
+```html
+<soundcloud-audio
+  src="https://w.soundcloud.com/player/?url=https%3A%2F%2Fsoundcloud.com%2Fforss%2Fsets%2Fsoulhack&color=%23ff5500&start_track=2"
+></soundcloud-audio>
+```
+
+Engine options win over the parameters of a widget embed URL, which win over the defaults. Set an option to `null` to drop a default.
+
+## Behavior
+
+- A set plays as one source. When the widget moves on to the next track, `duration` changes, `currentTime` starts again from `0`, and `durationchange` fires. `ended` fires only after the last track. `play()` after the end starts the set again from its first track.
+- `loop` replays the track, or the set from its first track. If the widget does not start again, `ended` still fires.
+- Volume and mute both work. The widget has no separate mute, so muting sets its volume to `0` and unmuting restores the previous level. Mute applies before autoplay starts, so a muted autoplay starts muted.
+- `autoplay` starts playback once the widget is ready. Browsers can still refuse it, as they do for any embed. The widget’s own `auto_play` parameter does the same and is never written to the widget URL, so the volume always applies first.
+- `buffered` is the stretch the widget reports as loaded, from where playback last started or landed.
+- The widget does not support playback rate, picture-in-picture, fullscreen, or text tracks, so the component offers none of them, and a player skin hides those controls.
+- `preload`, `playsinline`, and `poster` are accepted for parity with `<audio>` but have no effect.
+- A track that is private without its secret token, removed, or not available in the listener’s region reports a `MEDIA_ERR_SRC_NOT_SUPPORTED` error, and so does a URL the component does not recognize. A widget that has not finished loading after 5 seconds reports a `MEDIA_ERR_NETWORK` error. An error the widget reports during playback fires a non-fatal `error` event but leaves `error` empty, because a set moves on to its next track by itself.
+
+## SoundCloud’s terms of use
+
+The widget is covered by the [SoundCloud Terms of Use](https://soundcloud.com/terms-of-use#use-of-soundcloud-players-and-widget), in the section about players and widgets. Without written consent from SoundCloud, you may not use the widget to:
+
+- Aggregate SoundCloud content into a separate destination that substantially replicates what SoundCloud offers, or into a content service where SoundCloud content is a material part.
+- Embed content on a site dedicated to one artist, unless the content is yours and you are that artist or represent them, or on a site dedicated to one genre.
+
+These limits apply to commercial and non-commercial use. You also may not use the widget in a way that suggests that SoundCloud, an artist, or anyone else endorses or supports your site. SoundCloud can block your use of the widget at any time, for any reason.
+
+The [SoundCloud API terms](https://developers.soundcloud.com/docs/api/terms-of-use), which ask you to credit the uploader and SoundCloud with links back to the sound, apply when you use the SoundCloud API, for example to play stream URLs in a player of your own. This component uses the widget, which [SoundCloud says handles that credit itself](https://developers.soundcloud.com/docs/api/buttons-logos). The widget gives that credit only while it shows, which is with `controls`. Without `controls`, we recommend that your page give the credit itself: name the uploader, name SoundCloud as the source, and link to the sound on SoundCloud. The Terms of Use also say you must not remove trademark, copyright, or other proprietary or legal notices that appear on content from SoundCloud.
+
+## Privacy
+
+The widget loads from SoundCloud as soon as the component renders. The [SoundCloud Privacy Policy](https://soundcloud.com/pages/privacy) says that SoundCloud may receive personal data when a visitor opens a page with an embedded widget, including which site they are on, and may recognize the visitor. The widget also stores data in the visitor’s browser. SoundCloud does not document an embed mode that avoids this, so if your site needs consent before it loads third-party content, render the component only after the visitor agrees.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<soundcloud-audio class="soundcloud-audio" src="https://soundcloud.com/forss/flickermood" controls></soundcloud-audio>
+```
+
+**index.css**
+
+```css
+.soundcloud-audio {
+  width: 100%;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/soundcloud-audio';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Starts playback once the widget is ready, after the volume and start position apply. Browsers may refuse it. |
+| `controls` | `boolean` | `false` | |
+| `loop` | `boolean` | `false` | Replays the track, or a set from its first track, when the last one ends. |
+| `muted` | `boolean` | `false` | |
+| `playsinline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `src` | `string` | `''` | |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Starts playback once the widget is ready, after the volume and start position apply. Browsers may refuse it. |
+| `buffered` | `TimeRangeLike` | — | Read-only. The stretch the widget reports loaded, from where playback last started or landed. |
+| `contentData` | `{ title?: string \| null; poster?: string \| null; storyboard?: string \| null; readonly [key: string]: MediaContentValue }` | — | Read-only. The `title` and `poster` of the track playing, which change with each track of a set. Empty until the widget reports them, and again across a source change. `contentdatachange` announces both. |
+| `controls` | `boolean` | `false` | |
+| `currentSrc` | `string` | — | Read-only. |
+| `currentTime` | `number` | — | |
+| `defaultMuted` | `boolean` | `false` | |
+| `duration` | `number` | — | Read-only. |
+| `ended` | `boolean` | — | Read-only. |
+| `engine` | `Window \| null` | — | Read-only. The widget's window, which commands are posted to. Null until rendered. |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `loop` | `boolean` | `false` | Replays the track, or a set from its first track, when the last one ends. |
+| `muted` | `boolean` | `false` | |
+| `paused` | `boolean` | — | Read-only. |
+| `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?: SoundCloudSourceEngineConfig } \| null` | `null` | SoundCloud URL in `src`, widget parameters under `engine.soundcloud`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: SoundCloud has no captions or other text tracks. |
+| `volume` | `number` | — | |
+
+### Engine options
+
+#### `source.engine.soundcloud`
+
+Pass [SoundCloud Widget parameters](https://developers.soundcloud.com/docs/api/html5-widget#parameters) under `source.engine.soundcloud`, spelled exactly as SoundCloud spells them, plus anything SoundCloud adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+The sound comes from `src`, so `url` has no `engine.soundcloud` spelling. `referrerPolicy` sets the `referrerpolicy` of the widget iframe rather than a widget parameter.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `auto_play` | `boolean \| null \| undefined` | Start playback once the widget is ready, as `autoplay` does. Never written to the URL. |
+| `buying` | `boolean \| null \| undefined` | Show the buy button. Defaults to `false`. |
+| `color` | `string \| null \| undefined` | Hex color of the play button and other accents, such as `'#ff5500'`. |
+| `download` | `boolean \| null \| undefined` | Show the download button. Defaults to `false`. |
+| `hide_related` | `boolean \| null \| undefined` | Hide the related tracks the widget offers once a track ends. Defaults to `true`. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the widget iframe. Not a widget parameter. |
+| `sharing` | `boolean \| null \| undefined` | Show the share button. Defaults to `false`. |
+| `show_artwork` | `boolean \| null \| undefined` | Show the artwork. |
+| `show_comments` | `boolean \| null \| undefined` | Show listener comments on the waveform. Defaults to `false`. |
+| `show_playcount` | `boolean \| null \| undefined` | Show the play count. |
+| `show_reposts` | `boolean \| null \| undefined` | Show reposts. Defaults to `false`. |
+| `show_teaser` | `boolean \| null \| undefined` | Show SoundCloud's promotional teaser. Defaults to `false`. |
+| `show_user` | `boolean \| null \| undefined` | Show the uploader's name. The widget is what credits the uploader, so keep it unless the page does that elsewhere. |
+| `single_active` | `boolean \| null \| undefined` | When `false`, playing this widget does not pause the other SoundCloud widgets on the page. |
+| `start_track` | `number \| null \| undefined` | Index of the track in a set to start from. |
+| `visual` | `boolean \| null \| undefined` | The large artwork layout. Defaults to `false`. |
+
+### Methods
+
+Supports these media methods: `load`, `pause`, `play`.
+
+### Events
+
+Implements these standard media events through the embedded player: `canplay`, `canplaythrough`, `durationchange`, `emptied`, `ended`, `error`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `contentdatachange` | Fired when the widget reports the title and artwork of a track, and when they are cleared. Read `contentData` for them. |
+| `loadcomplete` | |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/spotify-audio';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.1.0/media/spotify-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/spotify-audio.js"></script>
 ```
 
 ## Load a source
@@ -134,7 +134,7 @@ Supports these media methods: `load`, `pause`, `play`.
 
 ### Events
 
-Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `seeked`, `seeking`, `timeupdate`, `waiting`.
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `seeked`, `seeking`, `timeupdate`, `waiting`.
 
 Also emits these Video.js-specific events:
 

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/tiktok-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.1.0/media/tiktok-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/tiktok-video.js"></script>
 ```
 
 ## Load a source
@@ -155,7 +155,7 @@ Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `reques
 
 ### Events
 
-Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
 
 Also emits these Video.js-specific events:
 

package/docs/reference/components/time-slider.md

@@ -95,6 +95,8 @@ Renders with `role="slider"` and an automatic `aria-label` that resolves to “S
 - Home: seek to start
 - End: seek to end
 
+Before each keyboard seek, the current time snaps to the nearest multiple of `step`. With the default `step` of `1`, pressing Arrow Right at 12.4 seconds seeks to 13 seconds.
+
 `<media-time-slider-chapter-title>` follows the pointer during pointer interaction. While the slider has keyboard focus, it follows the current playback position and announces chapter changes.
 
 ## Examples
@@ -422,13 +424,13 @@ import '@videojs/html/ui/slider-value';
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `changeThrottle` (attribute `change-throttle`) | `number` | `100` | Leading+trailing throttle (ms) for `onValueChange` during drag. |
-| `disabled` | `boolean` | — | Whether the slider is non-interactive. |
+| `disabled` | `boolean` | `false` | Whether the slider is non-interactive. |
 | `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
-| `largeStep` (attribute `large-step`) | `number` | — | Large step increment (Page Up/Down keys). |
-| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
+| `largeStep` (attribute `large-step`) | `number` | `10` | Large step increment in seconds (Page Up/Down keys). |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of slider movement. |
 | `pauseOnDrag` (attribute `pause-on-drag`) | `boolean` | `false` | When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before. |
-| `step` | `number` | — | Step increment for value changes (arrow keys). |
-| `thumbAlignment` (attribute `thumb-alignment`) | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
+| `step` | `number` | `1` | Step increment in seconds for value changes (arrow keys). |
+| `thumbAlignment` (attribute `thumb-alignment`) | `'center' \| 'edge'` | `'center'` | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
 
 #### State
 

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/twitch-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.1.0/media/twitch-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/twitch-video.js"></script>
 ```
 
 ## Load a source
@@ -52,7 +52,7 @@ video.source = {
 ## Behavior
 
 - Volume and mute both work, like a native `<video>`.
-- `playbackRate` is reported but never applied: the embed has no rate command.
+- No playback rate: the embed has no rate command, so the player hides its rate controls.
 - `loop` restarts a finished video from the top; the embed has no loop parameter.
 - `controls` is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
 - Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.
@@ -117,7 +117,6 @@ These attributes configure the embedded media adapter:
 | `loop` | `boolean` | `false` | |
 | `muted` | `boolean` | `false` | |
 | `paused` | `boolean` | — | Read-only. |
-| `playbackRate` | `number` | — | |
 | `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
 | `playsInline` | `boolean` | `true` | |
 | `poster` | `string` | `''` | |

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

@@ -1,8 +1,8 @@
 # video-compat-skin
 
-A video skin designed for broader browser compatibility
+The video preset's plain, unbranded skin, a polished step above native controls
 
-The Compat skin of the video preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. Its time slider supports chapter segments and thumbnail previews. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Compat skin of the video preset: the same core controls with plain, unbranded surfaces that avoid newer visual effects such as backdrop blur. It puts large play and seek buttons in the center, fullscreen, picture-in-picture, Cast, and AirPlay in a top corner, and chapter segments and thumbnail previews on its time slider. The preset also provides [VideoSkin](./video-skin.md), [NeutralVideoSkin](./video-neutral-skin.md), and [ScaffoldVideoSkin](./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 video preset provides basic controls and plain surfaces,
 import '@videojs/html/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.3.0/video-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/video-neutral-skin.md

@@ -2,7 +2,7 @@
 
 The video preset's visually lighter skin, closer to a classic control bar
 
-The neutral skin of the video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. The [default video skin](./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 video preset ships.
+The neutral skin of the video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. The preset also provides [VideoSkin](./video-skin.md), [CompatVideoSkin](./video-compat-skin.md), and [ScaffoldVideoSkin](./video-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Presets](../../guides/presets.md) for what the video preset ships.
 
 ## Import
 
@@ -13,7 +13,7 @@ import '@videojs/html/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.1.0/video-neutral.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-neutral.js"></script>
 ```
 
 ## Anatomy

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

@@ -2,7 +2,7 @@
 
 A video skin with minimal styling for custom skins
 
-The Scaffold skin of the 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. Its time slider supports chapter segments and thumbnail previews. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Scaffold skin of the 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. Its time slider supports chapter segments and thumbnail previews. The preset also provides [VideoSkin](./video-skin.md), [NeutralVideoSkin](./video-neutral-skin.md), and [CompatVideoSkin](./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/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.1.0/video-scaffold.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-scaffold.js"></script>
 ```
 
 ## Usage