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

package/docs/reference/{gesture.md → components/gesture.md}

@@ -4,17 +4,13 @@ Map tap and double-tap gestures to player actions
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/gesture';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-gesture
   type="doubletap"
   region="right"
@@ -26,14 +22,16 @@ html
 
 ## Behavior
 
-`Gesture` is a behavior component: it renders no visible interface. Place it inside a [Container](./player-container.md) to map a `tap` or `doubletap` gesture to a player action. A tap must use the primary pointer and complete within 250 milliseconds. When a matching double-tap gesture exists, the first tap waits briefly to see whether a second tap follows.
+`<media-gesture>` is a behavior component: it renders no visible interface. Place it inside a [`<media-container>`](./player-container.md) to map a `tap` or `doubletap` gesture to a player action.
+
+A tap must use the primary pointer and complete within 250 milliseconds. When a matching double-tap gesture exists, the first tap waits briefly to see whether a second tap follows.
 
 Use `pointer` to accept only `mouse`, `touch`, or `pen` input. Use `region` to divide the container horizontally:
 
-*   Left and right regions split the container into halves.
-*   Left, center, and right regions split it into thirds.
-*   A center-only region covers the full container.
-*   A single left or right region covers that half of the container.
+- Left and right regions split the container into halves.
+- Left, center, and right regions split it into thirds.
+- A center-only region covers the full container.
+- A single left or right region covers that half of the container.
 
 An unregional gesture acts as a fallback outside the active regions. When several registrations match the same gesture, the first registration wins.
 
@@ -49,17 +47,9 @@ Gestures supplement visible, keyboard-operable controls; they should never be th
 
 This example follows the common video-player pattern: click to play or pause, double-click the left or right side to seek ten seconds, and double-click the center to toggle fullscreen.
 
-Click: play/pause · Double-click: −10s · fullscreen · +10s
-
-Play Pause Replay
-
-index.html
-
-index.css
-
-index.ts
+**index.html**
 
-```
+```html
 <video-player>
   <media-container class="html-gesture-basic">
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
@@ -76,7 +66,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .html-gesture-basic {
   position: relative;
 }
@@ -121,8 +114,12 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
 import '@videojs/html/ui/gesture';
 import '@videojs/html/ui/play-button';
 ```
@@ -131,110 +128,11 @@ import '@videojs/html/ui/play-button';
 
 ### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`action*`
-
-`'togglePaused' | 'toggleMuted' | 'tog...`
-
-`—`
-
-▸
-
-Attribute
-
-`action`
-
-Description
-
-Built-in player action or same-named custom store action to run when the gesture is recognized.
-
-Type
-
-`'togglePaused' | 'toggleMuted' | 'toggleFullscreen' | 'toggleSubtitles' | 'togglePictureInPicture' | 'toggleControls' | 'seekStep' | 'volumeStep' | 'speedUp' | 'speedDown' | string & object`
-
-`type*`
-
-`'tap' | 'doubletap'`
-
-`—`
-
-▸
-
-Attribute
-
-`type`
-
-Description
-
-Gesture to recognize.
-
-`disabled`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the gesture is disabled.
-
-`pointer`
-
-`'mouse' | 'touch' | 'pen'`
-
-`—`
-
-▸
-
-Attribute
-
-`pointer`
-
-Description
-
-Pointer type that may activate the gesture. All pointer types are accepted when omitted.
-
-`region`
-
-`'left' | 'center' | 'right'`
-
-`—`
-
-▸
-
-Attribute
-
-`region`
-
-Description
-
-Optional horizontal part of the container that may activate the gesture.
-
-`value`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`value`
-
-Description
-
-Numeric value passed to actions such as `seekStep` and `volumeStep`. Uses their shared step when omitted.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `action` (required) | `'togglePaused' \| 'toggleMuted' \| 'toggleFullscreen' \| 'toggleSubtitles' \| 'togglePictureInPicture' \| 'toggleControls' \| 'seekStep' \| 'volumeStep' \| 'speedUp' \| 'speedDown' \| string & {}` | — | Built-in player action or same-named custom store action to run when the gesture is recognized. |
+| `type` (required) | `'tap' \| 'doubletap'` | — | Gesture to recognize. |
+| `disabled` | `boolean` | — | Whether the gesture is disabled. |
+| `pointer` | `'mouse' \| 'touch' \| 'pen'` | — | Pointer type that may activate the gesture. All pointer types are accepted when omitted. |
+| `region` | `'left' \| 'center' \| 'right'` | — | Optional horizontal part of the container that may activate the gesture. |
+| `value` | `number` | — | Numeric value passed to actions such as `seekStep` and `volumeStep`. Uses their shared step when omitted. |

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

@@ -0,0 +1,47 @@
+# google-cast
+
+Options for the Google Cast extension that configures the receiver and load request
+
+Adds the [Google Cast extension](../../guides/architecture.md) to the player’s media. It renders nothing — place it inside the player as a sibling of the media element, and pair it with a [CastButton](./cast-button.md). See [Cast to AirPlay and Chromecast](../../guides/casting.md) for the complete setup.
+
+## Import
+
+```bash
+pnpm add @videojs/html @videojs/google-cast
+```
+
+```ts
+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.0.0-rc.4/extensions/google-cast.js"></script>
+```
+
+## Anatomy
+
+```html
+<google-cast></google-cast>
+```
+
+## Options
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `receiver` | `receiver` | Cast receiver application ID. Defaults to Google’s Default Media Receiver (`CC1AD845`) |
+| `src` | `src` | Source URL loaded on the receiver. Defaults to the source the browser is playing |
+| `content-type` | `contentType` | MIME type of the Cast source. When unset, the receiver infers it from the URL |
+| `stream-type` | `streamType` | Stream type reported to the receiver. Falls back to the player’s stream type |
+| — | `customData` | Custom data sent to the receiver with each load request |
+
+`customData` takes an object, so it’s a property only, with no matching attribute.
+
+When the Cast `src` is an HLS playlist, Video.js detects the segment format and sets the receiver’s `hlsSegmentFormat` and `hlsVideoSegmentFormat` load-request fields. The Default Media Receiver plays HLS natively, so no extra receiver setup is needed.
+
+## See also
+
+- [Cast to AirPlay and Chromecast](../../guides/casting.md): Add remote playback to a player
+- [CastButton component reference](./cast-button.md)
+- [Remote Playback feature reference](../api/feature-remote-playback.md)

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

@@ -0,0 +1,87 @@
+# hls-audio
+
+Audio-only HLS element that plays the audio rendition of an HLS stream
+
+Audio-only HLS element that plays just the audio rendition of an HLS stream — even when the source is a mixed audio/video manifest. Useful for audio podcast players, background audio, and bandwidth-constrained contexts where downloading video data would be wasted. For full audio/video HLS playback, see the [HLS video component](./hls-video.md).
+
+## Import
+
+```ts
+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.0.0-rc.4/media/hls-audio.js"></script>
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<hls-audio class="hls-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls></hls-audio>
+```
+
+**index.css**
+
+```css
+.hls-audio {
+  width: 100%;
+  height: 54px;
+}
+```
+
+**index.ts**
+
+```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 |
+| --- | --- | --- | --- |
+| `alternativeMediaSuggestion` | `string \| undefined` | — | Read-only. A complete sentence naming the Media to reach for when this one can't play a source. Appended to the copy this adapter logs. Empty here, and overridden the same way as on the video adapter — see its note. `hls-audio` has no better-equipped sibling of its own; the Mux audio Media built on this engine does, and points at the hls.js-backed one. |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `disableRemotePlayback` | `boolean` | `false` | |
+| `engine` | `{ state: { [K in keyof S]-?: Signal<S[K]> }; context: { [K in keyof C]-?: Signal<C[K]> }; destroy(): Promise<void> }` | — | Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `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`, `crossOrigin`, `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`.
+
+### 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

@@ -0,0 +1,51 @@
+# hls-background-video
+
+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.
+
+See [Add a background video](../../guides/background-video.md) for layout, poster, accessibility, and source-choice guidance.
+
+## Import
+
+```ts
+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.0.0-rc.4/media/hls-background-video.js"></script>
+```
+
+## Source behavior
+
+`src` takes a complete HLS manifest URL. The engine starts loading when it receives the URL and pins the largest rendition that fits the screen. The ladder may be video-only, but its video renditions must use fMP4/CMAF. This engine does not include MPEG-TS transmuxing or DRM playback.
+
+```html
+<hls-background-video
+  src="https://media.example.com/hero.m3u8"
+  crossorigin
+></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.
+
+## API
+
+| Member | Description |
+| --- | --- |
+| `src` | HLS manifest URL |
+| `error` | Fatal SPF media error for the current source, or `null` |
+| `video` | Inner native `<video>` element |
+
+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.
+
+## Styling
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--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/hls-video.md

@@ -0,0 +1,110 @@
+# hls-video
+
+Lightweight HLS video element with minimal bundle size
+
+The lightweight HLS video element, optimized for minimal bundle size. The [hls.js video component](./hlsjs-video.md) is the larger, more compatible alternative.
+
+## Import
+
+```ts
+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.0.0-rc.4/media/hls-video.js"></script>
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<media-container class="media-container">
+  <hls-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hls-video>
+</media-container>
+```
+
+**index.css**
+
+```css
+.media-container {
+  position: relative;
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/container';
+import '@videojs/html/media/hls-video';
+```
+
+## API Reference
+
+### Attributes
+
+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`.
+
+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 |
+| --- | --- | --- | --- |
+| `alternativeMediaSuggestion` | `string \| undefined` | — | Read-only. A complete sentence naming the Media to reach for when this one can't play a source — `Try the hls.js-backed Mux media instead: import the hls-js flavor in place of the spf one.` Appended to the copy this adapter surfaces, and to the notices it logs. Name the flavor, not an import path: a Media is reached through several packages, each with its own counterpart. Empty here: `hls-video` has no better-equipped sibling to point at. A Media that does (a Mux Video built on this engine, whose hls.js-backed counterpart plays MPEG-TS and DRM) overrides this static, and its copy gains the second sentence with no other change. |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `disableRemotePlayback` | `boolean` | `false` | |
+| `engine` | `{ state: { [K in keyof S]-?: Signal<S[K]> }; context: { [K in keyof C]-?: Signal<C[K]> }; destroy(): Promise<void> }` | — | Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `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" (the same target the engine's `seekToLiveEdge` seeks to: window end − HOLD-BACK). `NaN` when the stream isn't live or nothing is resolved yet. Derived at read time from the engine's live window — no change event; re-read on `timeupdate`/`progress` (as the store's live feature does). |
+| `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`, `crossOrigin`, `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`, `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. |

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

@@ -0,0 +1,126 @@
+# hlsjs-video
+
+HLS video element powered by hls.js for adaptive bitrate streaming
+
+HLS video element powered by [hls.js](https://github.com/video-dev/hls.js/) for adaptive bitrate streaming, with full feature support across every browser. It’s more compatible than the lightweight [HLS video component](./hls-video.md), which is smaller and covers most HLS playback. For browser-native playback, see the [native HLS video component](./native-hls-video.md).
+
+## Import
+
+```bash
+pnpm add @videojs/hlsjs-video
+```
+
+```ts
+import '@videojs/html/media/hlsjs-video';
+```
+
+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.4/media/hlsjs-video.js"></script>
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<media-container class="media-container">
+  <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
+</media-container>
+```
+
+**index.css**
+
+```css
+.media-container {
+  position: relative;
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/container';
+import '@videojs/html/media/hlsjs-video';
+```
+
+## API Reference
+
+### Attributes
+
+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`.
+
+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` | `MediaContentData \| undefined` | — | Read-only. |
+| `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. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `isPictureInPicture` | `boolean` | — | 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` | `{ src?: string; type?: 'application/vnd.apple.mpegurl' \| 'video/mp4'; preferPlayback?: 'mse' \| 'native'; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`preferPlayback`, `engine`). Assigning it derives `src`. Sources are compared structurally, so reassigning an equivalent object is a no-op. Only a change to the engine options (or to the resolved content type) recreates the playback engine. |
+| `src` | `string` | `''` | Media source URL. Assigning it replaces the identity half of `source` and leaves `type` and the engine options intact, so changing the URL never disturbs engine configuration. |
+| `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`. |
+| `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`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.
+
+### Engine options
+
+#### `source.engine.nativeHls`
+
+When playback falls back to the browser’s own HLS, hls.js isn’t involved and its options don’t apply. This configures that path instead.
+
+| 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 [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.
+
+### Events
+
+Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `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 |
+| --- | --- |
+| `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. |
+
+### 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. |