@videojs/html 10.2.0 → 10.4.0

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.2.0/media/playerjs-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/playerjs-video.js"></script>
 ```
 
 ## Load a source
@@ -155,7 +155,7 @@ These attributes configure the embedded media adapter:
 | `seeking` | `boolean` | — | Read-only. |
 | `source` | `{ src?: string; engine?: PlayerJsSourceEngineConfig } \| null` | `null` | Embed URL in `src`, extra URL parameters under `engine.playerJs`. Re-derives `src`; equal sources skip reload. |
 | `src` | `string` | `''` | |
-| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: player.js has no text track surface. |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Unsupported: player.js has no text track surface. |
 | `volume` | `number` | — | |
 
 ### Engine options

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.2.0/media/shaka-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/shaka-video.js"></script>
 ```
 
 ## Load a source
@@ -134,7 +134,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/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.4.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. Unsupported: 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.2.0/media/spotify-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/spotify-audio.js"></script>
 ```
 
 ## Load a source
@@ -105,7 +105,7 @@ These attributes configure the embedded media adapter:
 | `seeking` | `boolean` | — | Read-only. |
 | `source` | `{ src?: string; engine?: SpotifySourceEngineConfig } \| null` | `null` | Spotify URL or URI in `src`, plus embed options under `engine.spotify`. Replacing it re-derives `src`. |
 | `src` | `string` | `''` | |
-| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: the embed exposes no captions or other text tracks. |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Unsupported: the embed exposes no captions or other text tracks. |
 
 ### Engine options
 
@@ -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.2.0/media/tiktok-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/tiktok-video.js"></script>
 ```
 
 ## Load a source
@@ -117,7 +117,7 @@ These attributes configure the embedded media adapter:
 | `seeking` | `boolean` | — | Read-only. |
 | `source` | `{ src?: string; engine?: TikTokSourceEngineConfig } \| null` | `null` | TikTok URL or id in `src`, player params under `engine.tiktok`. Re-derives `src`; equal sources skip reload. |
 | `src` | `string` | `''` | |
-| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: `closed_caption` is the embed's only say over captions. |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Unsupported: `closed_caption` is the embed's only say over captions. |
 
 ### Engine options
 
@@ -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-markers.md

@@ -0,0 +1,194 @@
+# media-time-slider-markers
+
+Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks
+
+A part of the [time slider](./time-slider.md) that draws a marker for each cue on the text tracks a filter matches, such as ad breaks, quiz questions, or highlights. Its props, data attributes, and custom properties are listed with the time slider’s other parts.
+
+## Import
+
+```ts
+import '@videojs/html/ui/time-slider-markers';
+```
+
+## Anatomy
+
+```html
+<media-time-slider>
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-time-slider-markers label="ads"></media-time-slider-markers>
+  <media-slider-thumb></media-slider-thumb>
+</media-time-slider>
+```
+
+Each marker is a `<div>`, or a clone of a `<template>` child. The template must contain exactly one HTML root element, and stays in the light DOM.
+
+```html
+<media-time-slider-markers label="ads">
+  <template>
+    <div class="ad-marker"></div>
+  </template>
+</media-time-slider-markers>
+```
+
+## Behavior
+
+The `kind`, `label`, and `language` attributes pick the tracks whose cues are drawn. The `filter` property takes a filter object, a function, or a [track definition](../api/define-text-track.md) instead, and takes priority over the attributes. With neither, nothing is drawn.
+
+Tracks from the media and from the app are drawn alike. While the markers are rendered, the [text cues feature](../api/feature-text-cues.md) reads the tracks they match, so tracks it skips by default work too.
+
+A cue whose end is its start is a point, drawn as a marker with no width and `data-point`. Any other cue is a range, spanning from its start to its end and clamped to the slider. Markers sit on the same span as the slider: from `0` to the media’s duration, or to the end of its seekable range while the duration is unknown. Cues outside that span, and every cue while it’s unknown, aren’t drawn. Markers are ordered by start, then end.
+
+## Styling
+
+| Attribute | Description |
+| --- | --- |
+| `data-active` | Present while the marker’s cue is active. |
+| `data-point` | Present when the cue marks one moment rather than a span. |
+
+Each marker also carries the slider’s data attributes, such as `data-orientation`, and its geometry through:
+
+- `--media-slider-marker-start`
+- `--media-slider-marker-end`
+- `--media-slider-marker-width`, the marker’s size along the slider, `0%` for a point
+
+Markers are unstyled. Position each one from its custom properties, and give points a visible width:
+
+```css
+media-time-slider-markers > div {
+  position: absolute;
+  inset-block: 0;
+  left: var(--media-slider-marker-start);
+  width: var(--media-slider-marker-width);
+  min-width: 4px;
+}
+
+media-time-slider-markers > [data-active] {
+  background: orange;
+}
+```
+
+## Accessibility
+
+The markers render with `aria-hidden="true"`; the slider’s value is what assistive technology reads. When a marker carries meaning a viewer needs, such as an upcoming ad break, convey it another way too.
+
+## Examples
+
+### Basic usage
+
+An app track labeled `ads` holds a point at 8 seconds and a range from 18 to 24 seconds. A marker turns orange while its cue is active.
+
+**index.html**
+
+```html
+<video-player class="html-time-slider-markers-basic">
+  <media-container class="html-time-slider-markers-basic__container">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <media-time-slider class="html-time-slider-markers-basic__slider">
+      <media-slider-track class="html-time-slider-markers-basic__track">
+        <media-slider-fill class="html-time-slider-markers-basic__fill"></media-slider-fill>
+      </media-slider-track>
+      <media-time-slider-markers label="ads" class="html-time-slider-markers-basic__markers">
+        <template>
+          <div class="html-time-slider-markers-basic__marker"></div>
+        </template>
+      </media-time-slider-markers>
+      <media-slider-thumb class="html-time-slider-markers-basic__thumb"></media-slider-thumb>
+    </media-time-slider>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-time-slider-markers-basic__container {
+  position: relative;
+}
+
+.html-time-slider-markers-basic__container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.html-time-slider-markers-basic__slider {
+  position: absolute;
+  right: 12px;
+  bottom: 12px;
+  left: 12px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.html-time-slider-markers-basic__track,
+.html-time-slider-markers-basic__markers {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+}
+
+.html-time-slider-markers-basic__track {
+  overflow: hidden;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+}
+
+.html-time-slider-markers-basic__fill {
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  background: white;
+}
+
+.html-time-slider-markers-basic__marker {
+  position: absolute;
+  inset-block: 0;
+  left: var(--media-slider-marker-start);
+  width: var(--media-slider-marker-width);
+  min-width: 4px;
+  background: #facc15;
+}
+
+.html-time-slider-markers-basic__marker[data-point] {
+  transform: translateX(-50%);
+}
+
+.html-time-slider-markers-basic__marker[data-active] {
+  background: #f97316;
+}
+
+.html-time-slider-markers-basic__thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 12px;
+  height: 12px;
+  background: white;
+  border-radius: 50%;
+  transform: translateX(-50%);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/time-slider-markers';
+
+const player = document.querySelector('video-player');
+
+player?.store.addTextTrack({
+  kind: 'metadata',
+  label: 'ads',
+  cues: [{ startTime: 8 }, { startTime: 18, endTime: 24 }],
+});
+```

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

@@ -50,6 +50,8 @@ Add `<media-time-slider-chapters>` to divide the slider track into sections. Eac
 
 The required template must contain exactly one HTML root element. It remains in the light DOM and is cloned for each normalized chapter range. When no chapter cues are available, it is cloned once as a full-width, cue-less range.
 
+To draw a marker for each cue on a text track, such as an ad break, add the markers element, documented on its own page as [media-time-slider-markers](./time-slider-markers.md).
+
 ## Behavior
 
 Displays and controls the current playback position. Dragging the slider seeks the media. The fill level reflects `currentTime / duration` as a percentage, and the buffer level shows how much media has been buffered.
@@ -483,6 +485,18 @@ Clones a light-DOM template once per normalized chapter range.
 
 The required template must contain exactly one HTML root element. When no chapter cues are available, the template is cloned once for a full-duration range.
 
+### media-time-slider-markers
+
+Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks. Pick tracks with the `kind`, `label`, and `language` attributes, or with the `filter` property; with neither, nothing is drawn. The store reads the matching tracks while the element is connected, so tracks it doesn't read by default work too.
+
+Each marker clones the light-DOM template, which must contain exactly one HTML root element, or is a `<div>` without one. Markers are decorative: the slider's own value is what assistive technology reads.
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-seeking` | Present when a seek operation is in progress. |
+
 ### media-slider-buffer
 
 Displays the buffered range on the slider track.

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.2.0/media/twitch-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.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` | `''` | |