@videojs/html 10.3.0 → 10.4.0

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

@@ -13,7 +13,7 @@ import '@videojs/html/audio/compat-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio-compat.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/audio-compat.js"></script>
 ```
 
 ## Anatomy

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

@@ -13,7 +13,7 @@ import '@videojs/html/audio/neutral-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio-neutral.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/audio-neutral.js"></script>
 ```
 
 ## Anatomy

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

@@ -13,7 +13,7 @@ import '@videojs/html/audio/scaffold-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio-scaffold.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/audio-scaffold.js"></script>
 ```
 
 ## Usage

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

@@ -13,7 +13,7 @@ import '@videojs/html/audio/skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/audio.js"></script>
 ```
 
 ## Anatomy

package/docs/reference/components/audio.md

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

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

@@ -13,7 +13,7 @@ import '@videojs/html/background/skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/background.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/background.js"></script>
 ```
 
 ## Anatomy

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

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

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

@@ -175,7 +175,7 @@ import '@videojs/html/ui/captions-radio-group';
 
 ### media-captions-radio-group
 
-Menu radio group that generates an Off `<media-menu-radio-item>` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.
+Menu radio group that generates an Off `<media-menu-radio-item>` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item; its `data-part` `label` and `badge` descendants receive the track's text.
 
 #### Props
 

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

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

package/docs/reference/components/controls.md

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

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

@@ -21,7 +21,7 @@ import '@videojs/html/media/dailymotion-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/dailymotion-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/dailymotion-video.js"></script>
 ```
 
 ## Load a source
@@ -157,7 +157,7 @@ These attributes configure the embedded media adapter:
 | `seeking` | `boolean` | — | Read-only. |
 | `source` | `{ src?: string; engine?: DailymotionSourceEngineConfig } \| null` | `null` | Dailymotion video URL in `src`, player configuration and parameters under `engine.dailymotion`. |
 | `src` | `string` | `''` | |
-| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: the player draws its own subtitles and reports no cues to render elsewhere. |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Unsupported: the player draws its own subtitles and reports no cues to render elsewhere. |
 | `volume` | `number` | — | |
 
 ### Engine options

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

@@ -21,7 +21,25 @@ import '@videojs/html/media/dash-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/dash-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/dash-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a DASH manifest (MPD) URL.
+
+```html
+<dash-video src="https://example.com/manifest.mpd"></dash-video>
+```
+
+The structured `source` object pairs the URL with dash.js settings under `engine.dashJs`. Setting `source` derives `src`, and changing `engine.dashJs` applies the settings to the running player instead of recreating it.
+
+```ts
+const video = document.querySelector('dash-video')!;
+video.source = {
+  src: 'https://example.com/manifest.mpd',
+  engine: { dashJs: { streaming: { buffer: { bufferTimeAtTopQuality: 30 } } } },
+};
 ```
 
 ## Examples
@@ -75,7 +93,6 @@ 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. |
 | `source` | `{ src?: string; engine?: DashEngineConfig } \| null` | `null` | Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`. Dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine. |
 | `src` | `string` | `''` | |
 | `streamType` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
@@ -88,7 +105,7 @@ Also exposes these properties from the native media API. See [HTMLVideoElement](
 
 ### Methods
 
-Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.
+Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `removeTextTrack`, `requestFullscreen`, `requestPictureInPicture`.
 
 ### Events
 

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

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

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

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

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

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

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

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

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

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