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

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

@@ -4,17 +4,13 @@ Accessible mute/unmute button with keyboard support and volume state reflection
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/mute-button';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-mute-button></media-mute-button>
 ```
 
@@ -22,54 +18,29 @@ html
 
 Toggles mute on and off, and exposes a derived `volumeLevel` based on the current volume and mute state.
 
-Mute availability is separate from volume-level availability because some media can accept a mute command without supporting volume changes. When mute is unavailable or unsupported, the HTML custom element receives the native `hidden` attribute and the React component returns `null`. Toggling is also ignored while mute is unavailable.
-
-## Styling
-
-Attribute
-
-Values
-
-Description
-
-`data-muted`
-
-Present / absent
-
-Present when the media is muted
-
-`data-volume-level`
-
-`"off"` | `"low"` | `"medium"` | `"high"`
+Mute availability is separate from volume-level availability because some media can accept a mute command without supporting volume changes.
 
-Current volume level
+When mute is unavailable or unsupported, the element receives the native `hidden` attribute. Toggling is also ignored while mute is unavailable.
 
-`data-availability`
-
-`"available"` | `"unavailable"` | `"unsupported"`
-
-Whether the media can be muted
-
-`data-hidden`
-
-Present / absent
+## Styling
 
-Present on the HTML element while mute is unavailable or unsupported
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-muted` | Present / absent | Present when the media is muted |
+| `data-volume-level` | `"off"` \| `"low"` \| `"medium"` \| `"high"` | Current volume level |
+| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether the media can be muted |
+| `data-hidden` | Present / absent | Present on the HTML element while mute is unavailable or unsupported |
 
 Style the button based on muted state:
 
-css
-
-```
+```css
 media-mute-button[data-muted] .icon-muted { display: inline; }
 media-mute-button:not([data-muted]) .icon-unmuted { display: inline; }
 ```
 
 Use `data-volume-level` for multi-level icon switching:
 
-css
-
-```
+```css
 media-mute-button[data-volume-level="off"] .icon-off { display: inline; }
 media-mute-button[data-volume-level="low"] .icon-low { display: inline; }
 media-mute-button[data-volume-level="medium"] .icon-medium { display: inline; }
@@ -86,15 +57,9 @@ Renders a `<button>` with an automatic `aria-label`: “Unmute” when muted,
 
 ### Basic Usage
 
-Unmute Mute
-
-index.html
-
-index.css
+**index.html**
 
-index.ts
-
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -105,7 +70,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
 }
@@ -141,7 +109,10 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/mute-button';
@@ -149,15 +120,9 @@ import '@videojs/html/ui/mute-button';
 
 ### Volume Levels
 
-Off Low Medium High
-
-index.html
-
-index.css
+**index.html**
 
-index.ts
-
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -170,7 +135,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
 }
@@ -213,7 +181,10 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/mute-button';
@@ -223,149 +194,28 @@ import '@videojs/html/ui/mute-button';
 
 ### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`disabled`
-
-`boolean`
-
-`false`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the button is disabled.
-
-`label`
-
-`object`
-
-`''`
-
-▸
-
-Attribute
-
-`label`
-
-Description
-
-Custom label for the button.
-
-Type
-
-`{ key: string; text: string } | string | ((state: MuteButtonState) => Text | string)`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether the button is disabled. |
+| `label` | `{ key: string; text: string } \| string \| ((state: MuteButtonState) => Text \| string)` | `''` | Custom label for the button. |
 
 ### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`muted`
-
-`boolean`
-
-▸
-
-Description
-
-Whether audio is muted.
-
-`label`
-
-`{ key: string; text: string } | string`
-
-`volumeLevel`
-
-`'off' | 'low' | 'medium' | 'high'`
-
-▸
-
-Description
-
-Derived volume level:
-
-*   `off`: muted or volume is 0
-*   `low`: volume < 0.5
-*   `medium`: volume < 0.75
-*   `high`: volume >= 0.75
-
-`availability`
-
-`MediaFeatureAvailability`
-
-▸
-
-Description
-
-Whether the media can be muted at all.
-
-`hidden`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the button is hidden because the media has no mute to toggle.
+| Property | Type | Description |
+| --- | --- | --- |
+| `muted` | `boolean` | Whether audio is muted. |
+| `label` | `{ key: string; text: string } \| string` | |
+| `volumeLevel` | `'off' \| 'low' \| 'medium' \| 'high'` | Derived volume level:<br>- `off`: muted or volume is 0<br>- `low`: volume < 0.5<br>- `medium`: volume < 0.75<br>- `high`: volume >= 0.75 |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can be muted at all. |
+| `hidden` | `boolean` | Whether the button is hidden because the media has no mute to toggle. |
 
 ### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-muted`
-
-▸
-
-Description
-
-Present when the media is muted.
-
-`data-volume-level`
-
-`'off' | 'low' | 'medium' | 'high'`
-
-▸
-
-Description
-
-Indicates the volume level.
-
-`data-availability`
-
-`MediaFeatureAvailability`
-
-▸
-
-Description
-
-Indicates mute availability (`available`, `unavailable`, `unsupported`).
-
-`data-hidden`
-
-▸
-
-Description
-
-Present when the button is hidden because the media has no mute to toggle.
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-muted` | — | Present when the media is muted. |
+| `data-volume-level` | `'off' \| 'low' \| 'medium' \| 'high'` | Indicates the volume level. |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates mute availability (`available`, `unavailable`, `unsupported`). |
+| `data-hidden` | — | Present when the button is hidden because the media has no mute to toggle. |

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

@@ -0,0 +1,127 @@
+# mux-audio
+
+Audio element for Mux-hosted HLS streams
+
+Audio element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
+
+## Import
+
+```bash
+pnpm add @videojs/mux-audio
+```
+
+```ts
+import '@videojs/html/media/mux-audio';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/mux-audio.js"></script>
+```
+
+## Analytics and casting
+
+The Mux audio component plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](../../guides/mux-data.md) and [Google Cast](../../guides/casting.md) are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
+
+Install both extensions before using the example below:
+
+```bash
+pnpm add @videojs/mux-data @videojs/google-cast
+```
+
+```html
+<mux-audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-audio>
+<mux-data player-software-name="mux-audio"></mux-data>
+<google-cast></google-cast>
+```
+
+Register the elements by importing `@videojs/html/extensions/mux-data` and `@videojs/html/extensions/google-cast`.
+
+- [Mux Data — metadata, options, and configuration](../../guides/mux-data.md)
+- [Cast to AirPlay and Chromecast](../../guides/casting.md)
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<mux-audio class="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossorigin="anonymous" controls></mux-audio>
+```
+
+**index.css**
+
+```css
+.mux-audio {
+  width: 100%;
+  height: 54px;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/mux-audio';
+```
+
+## API Reference
+
+### Attributes
+
+Forwards these standard media attributes to the internal `<audio>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.
+
+These Video.js-specific attributes configure media behavior:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `audioRenditions` | `AudioRenditionListLike \| undefined` | — | Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
+| `audioTracks` | `AudioTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
+| `contentData` | `{ readonly [key: string]: MediaContentValue; title?: string; poster?: string; storyboard?: string }` | — | Read-only. What `source` says about its content. `poster` and `storyboard` are image URLs it describes rather than plays, from its `poster` and `storyboard` params; a key is absent when the URL can't be built — no playback ID, or signed playback without a matching image token. `title` and the rest come from the metadata Mux publishes for the asset, which loads with the source, so they arrive later than the URLs and are absent until then. The same object is handed back until something in it changes, and `contentdatachange` announces it when it does. Nothing here is applied for you, apart from the thumbnail track `<mux-video>` adds from `storyboard` (and drops for live streams). |
+| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
+| `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live. |
+| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ type?: 'application/vnd.apple.mpegurl' \| 'video/mp4'; preferPlayback?: 'mse' \| 'native'; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null` | `null` | Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that *do* arrive adaptive selection reaches for. The two halves are independent. |
+| `src` | `string` | `''` | Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs. |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |
+| `targetLiveWindow` | `number` | — | Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate). |
+| `videoRenditions` | `VideoRenditionListLike \| undefined` | — | Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
+| `videoTracks` | `VideoTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
+
+Also exposes these properties from the native media API. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `volume`.
+
+### Engine options
+
+#### `source.engine.nativeHls`
+
+Options passed under `source.engine.nativeHls`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |
+
+### Methods
+
+Supports these media methods. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `addTextTrack`, `canPlayType`, `load`, `pause`, `play`.
+
+### Events
+
+Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `durationchange`, `emptied`, `ended`, `error`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `contentdatachange` | Fired when `contentData` changes: the derived URLs with `source`, and the metadata once it loads. Read `contentData` for the new value. |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
+| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
+| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

package/docs/reference/{mux-background-video.md → components/mux-background-video.md}

@@ -2,41 +2,35 @@
 
 Mux-specific name for the HLS background video component
 
-MuxBackgroundVideo is the Mux-specific name for [HlsBackgroundVideo](./hls-background-video.md). The two names use the same implementation and API.
+`<mux-background-video>` is the Mux-specific name for [`<hls-background-video>`](./hls-background-video.md). The two names use the same implementation and API.
 
-Use this name when your source is a Mux HLS URL and the Mux identity makes the composition easier to read. See [Add a background video](../how-to/add-a-background-video.md) to compare the background-video options.
+Use this name when your source is a Mux HLS URL and the Mux identity makes the composition easier to read. See [Add a background video](../../guides/background-video.md) to compare the background-video options.
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/media/mux-background-video';
 ```
 
-Or load it from the [CDN](../concepts/cdn.md):
-
-html
+Or load it from the [CDN](../../guides/cdn.md):
 
-```
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/media/mux-background-video.js"></script>
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/mux-background-video.js"></script>
 ```
 
 ## Load a Mux source
 
 Pass a complete Mux HLS URL through `src`. This component does not take a playback ID or structured `source` object. Use Mux delivery query parameters to limit which renditions Mux includes in the manifest:
 
-html
-
-```
+```html
 <mux-background-video
   src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
   crossorigin
 ></mux-background-video>
 ```
 
-MuxBackgroundVideo does not create a poster or preview thumbnails, and it does not send analytics data. Keep the poster in your page and add analytics separately when you need them.
+`<mux-background-video>` does not create a poster or preview thumbnails, and it does not send analytics data. Keep the poster in your page and add analytics separately when you need them.
 
 ## API
 
-The source, error, fixed playback behavior, and CSS custom properties are identical to [HlsBackgroundVideo](./hls-background-video.md).
+The source, error, fixed playback behavior, and CSS custom properties are identical to [`<hls-background-video>`](./hls-background-video.md).

package/docs/reference/components/mux-data.md

@@ -0,0 +1,51 @@
+# mux-data
+
+Options for the Mux Data extension that monitors playback quality
+
+Adds the [Mux Data](https://data.mux.com) [extension](../../guides/architecture.md) to the player’s media. It renders nothing — place it inside the player as a sibling of the media element. See [Mux Data](../../guides/mux-data.md) for how monitoring works.
+
+## Import
+
+```bash
+pnpm add @videojs/html @videojs/mux-data
+```
+
+```ts
+import '@videojs/html/extensions/mux-data';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/extensions/mux-data.js"></script>
+```
+
+## Anatomy
+
+```html
+<mux-data></mux-data>
+```
+
+## Options
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `env-key` | `envKey` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
+| — | `metadata` | Mux Data metadata for the view |
+| `player-software-name` | `playerSoftwareName` | Player name reported to Mux Data |
+| `player-software-version` | `playerSoftwareVersion` | Player version reported to Mux Data. Defaults to the Video.js version |
+| `player-init-time` | `playerInitTime` | Epoch milliseconds the player was initialized. Defaults to when the element was created |
+| `beacon-collection-domain` | `beaconCollectionDomain` | Custom domain the beacons are sent to |
+| `disable-cookies` | `disableCookies` | Stops the SDK from setting cookies |
+| `debug` | `debug` | Turns on SDK debug logging |
+| — | `MuxDataSdk` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |
+
+`metadata` and `MuxDataSdk` take objects, so they’re properties only, with no matching attribute.
+
+Changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, which ends the current view and starts a new one. The rest update the view in place.
+
+## See also
+
+- [Mux Data](../../guides/mux-data.md): How monitoring works
+- [Mux video reference](./mux-video.md)
+- [Mux audio reference](./mux-audio.md)