@videojs/html 10.0.0-rc.4 → 10.0.0

package/docs/reference/api/player-store.md

@@ -0,0 +1,112 @@
+# Player store
+
+Every state field and action on the player store, grouped by the feature that adds it
+
+The player store combines the state and actions of every feature the player includes. A field or action exists only when its feature is included. This page lists the whole store; each feature’s reference page adds its selector and examples.
+
+## Access
+
+The player element exposes the store as `store`. State fields and actions are properties of the store, and `store.subscribe()` reports changes. `store.state` is a frozen snapshot of the current state, which is the object selectors take. Inside a custom element, [`PlayerController`](./player-controller.md) subscribes to a selection and updates its host.
+
+```ts
+const player = document.querySelector('video-player');
+
+player.store.paused;
+player.store.play();
+
+const unsubscribe = player.store.subscribe(() => {
+  console.log(player.store.currentTime);
+});
+```
+
+Each feature also exports a selector, such as `selectPlayback`, that returns its state and actions, or `undefined` when the player doesn’t include the feature. See [`createSelector`](./create-selector.md) to write your own.
+
+## State and actions
+
+Each feature links to the same entry on its reference page.
+
+| Name | Type | Feature | Description |
+| --- | --- | --- | --- |
+| `paused` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-paused) | Whether playback is paused. |
+| `ended` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-ended) | Whether playback has reached the end. |
+| `started` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-started) | Whether playback has started (played or seeked). |
+| `waiting` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-waiting) | Whether playback is stalled waiting for data. |
+| `play` | `() => Promise<void>` | [`playbackFeature`](./feature-playback.md#playback-action-play) | Start playback. Updates `paused` immediately when the media starts. |
+| `pause` | `() => void` | [`playbackFeature`](./feature-playback.md#playback-action-pause) | Pause playback. Updates `paused` immediately. |
+| `currentTime` | `number` | [`timeFeature`](./feature-time.md#time-state-currentTime) | Current playback position in seconds. |
+| `duration` | `number` | [`timeFeature`](./feature-time.md#time-state-duration) | Total duration in seconds (0 if unknown). |
+| `seeking` | `boolean` | [`timeFeature`](./feature-time.md#time-state-seeking) | Whether a seek operation is in progress. |
+| `seek` | `(time: number) => Promise<number>` | [`timeFeature`](./feature-time.md#time-action-seek) | Seek to a time in seconds. Returns the actual position after seek. |
+| `volume` | `number` | [`volumeFeature`](./feature-volume.md#volume-state-volume) | Volume level from 0 (silent) to 1 (max). |
+| `muted` | `boolean` | [`volumeFeature`](./feature-volume.md#volume-state-muted) | Whether audio is muted. |
+| `volumeAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`volumeFeature`](./feature-volume.md#volume-state-volumeAvailability) | Whether volume can be programmatically set on this platform. |
+| `mutedAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`volumeFeature`](./feature-volume.md#volume-state-mutedAvailability) | Whether the media can be muted. Separate from `volumeAvailability` because the two come apart: an embed can take a mute command while offering no way to set a level, and iOS Safari refuses a volume write on media that mutes perfectly well. |
+| `setVolume` | `(volume: number) => number` | [`volumeFeature`](./feature-volume.md#volume-action-setVolume) | Set volume (clamped 0-1). Returns the clamped value. |
+| `setMuted` | `(muted: boolean) => boolean` | [`volumeFeature`](./feature-volume.md#volume-action-setMuted) | Set the muted state, updating the store immediately. Unmuting at volume 0 restores volume to 0.25. Returns the new muted value. |
+| `isFullscreen` | `boolean` | [`fullscreenFeature`](./feature-fullscreen.md#fullscreen-state-isFullscreen) | Whether fullscreen mode is currently active. |
+| `fullscreenAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`fullscreenFeature`](./feature-fullscreen.md#fullscreen-state-fullscreenAvailability) | Whether fullscreen can be requested on this platform. |
+| `requestFullscreen` | `() => Promise<void>` | [`fullscreenFeature`](./feature-fullscreen.md#fullscreen-action-requestFullscreen) | Enter fullscreen mode. Tries container first, falls back to media element. |
+| `exitFullscreen` | `() => Promise<void>` | [`fullscreenFeature`](./feature-fullscreen.md#fullscreen-action-exitFullscreen) | Exit fullscreen mode. |
+| `userActive` | `boolean` | [`controlsFeature`](./feature-controls.md#controls-state-userActive) | Whether the user has recently interacted with the player. |
+| `controlsVisible` | `boolean` | [`controlsFeature`](./feature-controls.md#controls-state-controlsVisible) | Whether controls should be visible. |
+| `requestControlsLock` | `() => (() => void)` | [`controlsFeature`](./feature-controls.md#controls-action-requestControlsLock) | Keep controls visible during a sustained interaction. The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent. |
+| `toggleControls` | `(forceShow?: boolean) => boolean` | [`controlsFeature`](./feature-controls.md#controls-action-toggleControls) | Toggle controls visibility, or force it with `forceShow`. Returns the new `controlsVisible` value. |
+| `buffered` | `[number, number][]` | [`bufferFeature`](./feature-buffer.md#buffer-state-buffered) | Buffered time ranges as \[start, end\] tuples. |
+| `seekable` | `[number, number][]` | [`bufferFeature`](./feature-buffer.md#buffer-state-seekable) | Seekable time ranges as \[start, end\] tuples. |
+| `textTrackList` | `MediaTextTrack[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-textTrackList) | All text tracks available on the media element. |
+| `subtitlesShowing` | `boolean` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-subtitlesShowing) | Whether a captions/subtitles track is showing. |
+| `chaptersCues` | `MediaTextCue[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-chaptersCues) | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
+| `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-thumbnailsTrack) | The first thumbnails track, or `null` when there is none. |
+| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-toggleSubtitles) | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
+| `selectSubtitlesTrack` | `(id: string \| null) => void` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-selectSubtitlesTrack) | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
+| `playbackRates` | `readonly number[]` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRates) | Available playback rates. |
+| `playbackRate` | `number` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRate) | Current playback rate. |
+| `setPlaybackRate` | `(rate: number) => void` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-action-setPlaybackRate) | Set the playback rate. |
+| `isPictureInPicture` | `boolean` | [`pipFeature`](./feature-pip.md#pip-state-isPictureInPicture) | Whether picture-in-picture mode is currently active. |
+| `pictureInPictureAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`pipFeature`](./feature-pip.md#pip-state-pictureInPictureAvailability) | Whether picture-in-picture can be requested on this platform. |
+| `requestPictureInPicture` | `() => Promise<void>` | [`pipFeature`](./feature-pip.md#pip-action-requestPictureInPicture) | Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. |
+| `exitPictureInPicture` | `() => Promise<void>` | [`pipFeature`](./feature-pip.md#pip-action-exitPictureInPicture) | Exit picture-in-picture mode. |
+| `error` | `{ code: number; message: string } \| null` | [`errorFeature`](./feature-error.md#error-state-error) | The current media error, or null if none. |
+| `dismissError` | `() => void` | [`errorFeature`](./feature-error.md#error-action-dismissError) | Dismiss the current error by clearing it. |
+| `title` | `string` | [`metadataFeature`](./feature-metadata.md#metadata-state-title) | The resolved content title. Set it through the player, not through the store. |
+| `poster` | `string` | [`metadataFeature`](./feature-metadata.md#metadata-state-poster) | The resolved poster URL, independent of the media element's own `poster`. Set it through the player, not through the store. |
+| `currentSrc` | `string` | [`sourceFeature`](./feature-source.md#source-state-currentSrc) | Current media source URL (empty string if none). |
+| `canPlay` | `boolean` | [`sourceFeature`](./feature-source.md#source-state-canPlay) | Whether enough data is loaded to begin playback. |
+| `videoRenditionList` | `MediaVideoRendition[]` | [`qualityFeature`](./feature-quality.md#quality-state-videoRenditionList) | Video renditions available for manual quality selection. |
+| `activeVideoRendition` | `{ id: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } \| null` | [`qualityFeature`](./feature-quality.md#quality-state-activeVideoRendition) | Video rendition currently playing, including when automatic ABR is selected. |
+| `selectVideoRendition` | `(id: string) => void` | [`qualityFeature`](./feature-quality.md#quality-action-selectVideoRendition) | Select a video rendition by `id`, or automatic ABR with `"auto"`. |
+| `audioTrackList` | `MediaAudioTrack[]` | [`audioTrackFeature`](./feature-audio-track.md#audioTrack-state-audioTrackList) | Audio tracks available for manual track selection. |
+| `selectAudioTrack` | `(id: string) => void` | [`audioTrackFeature`](./feature-audio-track.md#audioTrack-action-selectAudioTrack) | Select an audio track by `id`. |
+| `remotePlaybackState` | `'disconnected' \| 'connecting' \| 'connected'` | [`remotePlaybackFeature`](./feature-remote-playback.md#remotePlayback-state-remotePlaybackState) | Current remote playback connection state. |
+| `remotePlaybackAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`remotePlaybackFeature`](./feature-remote-playback.md#remotePlayback-state-remotePlaybackAvailability) | Whether remote playback can be requested on this platform. |
+| `promptRemotePlayback` | `() => Promise<void>` | [`remotePlaybackFeature`](./feature-remote-playback.md#remotePlayback-action-promptRemotePlayback) | Prompt the user to pick a remote playback device. Exits fullscreen first when connecting. |
+| `liveEdgeStart` | `number` | [`liveFeature`](./feature-live.md#live-state-liveEdgeStart) | Playback time where the live edge begins. Playback is live when `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown. |
+| `targetLiveWindow` | `number` | [`liveFeature`](./feature-live.md#live-state-targetLiveWindow) | Describes the kind of live window available. This value is not a duration. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown. |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | [`streamTypeFeature`](./feature-stream-type.md#streamType-state-streamType) | Current stream delivery type. Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display. |
+| `orientationLockType` | `'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary'` | [`orientationLockFeature`](./feature-orientation-lock.md#orientationLock-state-orientationLockType) | Screen orientation type locked while fullscreen is active. |
+| `setOrientationLockType` | `(value: 'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary' \| null \| undefined) => void` | [`orientationLockFeature`](./feature-orientation-lock.md#orientationLock-action-setOrientationLockType) | Sets the locked orientation type. A missing value, including an empty one, restores the default. |
+
+## Features by preset
+
+Each column is a preset's feature bundle. A feature no bundle includes is opt-in: add it to your [`createPlayer`](./html-create-player.md) features yourself.
+
+| Feature | `videoFeatures` | `audioFeatures` | `liveAudioFeatures` | `liveVideoFeatures` |
+| --- | --- | --- | --- | --- |
+| [`playbackFeature`](./feature-playback.md) | ✓ | ✓ | ✓ | ✓ |
+| [`timeFeature`](./feature-time.md) | ✓ | ✓ | ✓ | ✓ |
+| [`volumeFeature`](./feature-volume.md) | ✓ | ✓ | ✓ | ✓ |
+| [`fullscreenFeature`](./feature-fullscreen.md) | ✓ | – | – | ✓ |
+| [`controlsFeature`](./feature-controls.md) | ✓ | – | – | ✓ |
+| [`bufferFeature`](./feature-buffer.md) | ✓ | ✓ | ✓ | ✓ |
+| [`textTrackFeature`](./feature-text-tracks.md) | ✓ | – | – | ✓ |
+| [`playbackRateFeature`](./feature-playback-rate.md) | ✓ | ✓ | – | – |
+| [`pipFeature`](./feature-pip.md) | ✓ | – | – | ✓ |
+| [`errorFeature`](./feature-error.md) | ✓ | ✓ | ✓ | ✓ |
+| [`metadataFeature`](./feature-metadata.md) | ✓ | ✓ | ✓ | ✓ |
+| [`sourceFeature`](./feature-source.md) | ✓ | ✓ | ✓ | ✓ |
+| [`qualityFeature`](./feature-quality.md) | ✓ | – | – | – |
+| [`audioTrackFeature`](./feature-audio-track.md) | ✓ | – | – | – |
+| [`remotePlaybackFeature`](./feature-remote-playback.md) | ✓ | – | – | ✓ |
+| [`liveFeature`](./feature-live.md) | – | – | ✓ | ✓ |
+| [`streamTypeFeature`](./feature-stream-type.md) | – | – | – | – |
+| [`orientationLockFeature`](./feature-orientation-lock.md) | – | – | – | – |

package/docs/reference/api/preset-audio.md

@@ -0,0 +1,116 @@
+# Audio preset
+
+The audio-only preset — a player, feature bundle, skins, and media for on-demand audio
+
+`@videojs/html/audio` is the preset for on-demand audio. It bundles the `<audio-player>` element, the `audioFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
+
+## Import
+
+```ts
+import '@videojs/html/audio/player';
+import '@videojs/html/audio/skin';
+```
+
+Import `@videojs/html/audio/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/audio.js"></script>
+```
+
+`audio-neutral.js` registers the neutral skin instead, and `audio-player.js` registers `<audio-player>` alone.
+
+## Usage
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/audio/player';
+  import '@videojs/html/audio/skin';
+</script>
+
+<audio-player>
+  <audio-skin>
+    <audio src="audio.m4a"></audio>
+  </audio-skin>
+</audio-player>
+```
+
+## Player
+
+`@videojs/html/audio/player` registers `<audio-player>`, whose class is `AudioPlayerElement`. It is a [player](../components/player.md) element created by [`createPlayer`](./html-create-player.md) with `audioFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](../components/player-container.md) inside it.
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
+| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
+| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+
+`content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
+
+The preset root also exports a `PlayerController` bound to the audio player’s store. Use it from any custom element inside `<audio-player>`; see [`PlayerController`](./player-controller.md).
+
+## Feature bundle
+
+`audioFeatures` is the array of [features](../../guides/features.md) the player is configured with, a subset of the [video preset’s](./preset-video.md#feature-bundle) `videoFeatures`:
+
+| Feature | Description |
+| --- | --- |
+| [`playbackFeature`](./feature-playback.md) | Play/pause state and actions for the player store |
+| [`playbackRateFeature`](./feature-playback-rate.md) | Playback speed state and actions for the player store |
+| [`volumeFeature`](./feature-volume.md) | Volume level and mute state for the player store |
+| [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
+| [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
+| [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
+| [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |
+
+Its type, `AudioFeatures`, is the tuple of those features in order. Import it from the package root:
+
+```ts
+import type { AudioFeatures } from '@videojs/html';
+```
+
+To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.
+
+```ts
+import { createPlayer, remotePlaybackFeature } from '@videojs/html';
+import { audioFeatures } from '@videojs/html/audio';
+
+const { PlayerElement } = createPlayer({
+  features: [...audioFeatures, remotePlaybackFeature],
+});
+
+customElements.define('my-audio-player', PlayerElement);
+```
+
+## Skins
+
+- [AudioSkin](../components/audio-skin.md) — the default skin, with the modern, frosted look.
+- [NeutralAudioSkin](../components/audio-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+
+## Media
+
+The preset plays through a native [`<audio>`](../components/audio.md), so it registers no media element of its own. Swap it for any compatible [media element](../../guides/media-sources.md), such as [`<hls-audio>`](../components/hls-audio.md) for HLS.
+
+## Exports
+
+The preset root, `@videojs/html/audio`, has no side effects. Importing it never registers an element:
+
+| Export | Description |
+| --- | --- |
+| `AudioPlayerElement` | The [player](#player) element class. |
+| `PlayerController` | The player controller, bound to the audio player’s store. |
+| `audioFeatures` | The [feature bundle](#feature-bundle). |
+| `AudioSkinElement` | The default [skin](#skins) element class. |
+| `NeutralAudioSkinElement` | The neutral [skin](#skins) element class. |
+
+Registration entry points are side-effect-only:
+
+| Entry point | Registers |
+| --- | --- |
+| `@videojs/html/audio/player` | `<audio-player>` |
+| `@videojs/html/audio/skin` | `<audio-skin>`, `<media-container>`, and the UI elements the skin composes |
+| `@videojs/html/audio/neutral-skin` | `<audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
+| `@videojs/html/audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/preset-background.md

@@ -0,0 +1,103 @@
+# Background preset
+
+The background video preset — a player, feature bundle, skin, and media for ambient video with no controls
+
+`@videojs/html/background` is the preset for ambient background video with no user controls. It bundles the `<background-video-player>` element, the `backgroundFeatures` bundle it is configured with, one chrome-less skin, and the `<background-video>` media element, which autoplays, mutes, and loops. See [Presets](../../guides/presets.md) for how presets fit together and [Background video](../../guides/background-video.md) for building one.
+
+## Import
+
+```ts
+import '@videojs/html/background/player';
+import '@videojs/html/background/skin';
+import '@videojs/html/background/video';
+```
+
+Or load the [CDN](../../guides/cdn.md) bundle that registers all three:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/background.js"></script>
+```
+
+Unlike the other presets, the background preset has one bundle and no player-only bundle.
+
+## Usage
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/background/player';
+  import '@videojs/html/background/skin';
+  import '@videojs/html/background/video';
+</script>
+
+<background-video-player>
+  <background-video-skin>
+    <background-video src="hero.mp4"></background-video>
+  </background-video-skin>
+</background-video-player>
+```
+
+## Player
+
+`@videojs/html/background/player` registers `<background-video-player>`, whose class is `BackgroundVideoPlayerElement`. It is a [player](../components/player.md) element created by [`createPlayer`](./html-create-player.md) with `backgroundFeatures`. It owns the player store but no layout. Put the skin or a [`<media-container>`](../components/player-container.md) inside it.
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+
+The bundle has no feature that takes player inputs, so the element has no player-input attributes such as `content-title` or `poster`; `keep-alive` is the only attribute it reads. Its read-only `store` property returns its player store.
+
+The preset root also exports a `PlayerController` bound to the background player’s store. Use it from any custom element inside `<background-video-player>`; see [`PlayerController`](./player-controller.md).
+
+## Feature bundle
+
+`backgroundFeatures` is the array of [features](../../guides/features.md) the player is configured with. The background media element handles autoplay, muting, and looping on its own:
+
+`backgroundFeatures` is currently empty, so the player's store holds no feature state or actions.
+
+Its type, `BackgroundFeatures`, is the matching empty tuple. Import it from the package root:
+
+```ts
+import type { BackgroundFeatures } from '@videojs/html';
+```
+
+To add a feature, pass your own array to `createPlayer`. For example, add playback to drive a play button over the background video:
+
+```ts
+import { createPlayer, playbackFeature } from '@videojs/html';
+import { backgroundFeatures } from '@videojs/html/background';
+
+const { PlayerElement } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+customElements.define('my-background-player', PlayerElement);
+```
+
+## Skins
+
+- [BackgroundVideoSkin](../components/background-video-skin.md) — the only skin, a chrome-less surface that sizes the video and renders no controls.
+
+## Media
+
+`@videojs/html/background/video` registers [`<background-video>`](../components/background-video.md), which renders a `<video>` inside shadow DOM that is muted, looped, and autoplaying by default. It is the same registration as `@videojs/html/media/background-video`. For HLS or Mux sources, use [`<hls-background-video>`](../components/hls-background-video.md) or [`<mux-background-video>`](../components/mux-background-video.md) instead.
+
+## Exports
+
+The preset root, `@videojs/html/background`, has no side effects. Importing it never registers an element:
+
+| Export | Description |
+| --- | --- |
+| `BackgroundVideoPlayerElement` | The [player](#player) element class. |
+| `PlayerController` | The player controller, bound to the background player’s store. |
+| `backgroundFeatures` | The [feature bundle](#feature-bundle). |
+| `BackgroundVideoSkinElement` | The [skin](#skins) element class. |
+
+Registration entry points are side-effect-only:
+
+| Entry point | Registers |
+| --- | --- |
+| `@videojs/html/background/player` | `<background-video-player>` |
+| `@videojs/html/background/skin` | `<background-video-skin>` and `<media-container>` |
+| `@videojs/html/background/video` | `<background-video>` |

package/docs/reference/api/preset-live-audio.md

@@ -0,0 +1,119 @@
+# Live audio preset
+
+The live audio preset — a player, feature bundle, skins, and media for live audio streams
+
+`@videojs/html/live-audio` is the preset for live audio streams. It bundles the `<live-audio-player>` element, the `liveAudioFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
+
+## Import
+
+```ts
+import '@videojs/html/live-audio/player';
+import '@videojs/html/live-audio/skin';
+```
+
+Import `@videojs/html/live-audio/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/live-audio.js"></script>
+```
+
+`live-audio-neutral.js` registers the neutral skin instead, and `live-audio-player.js` registers `<live-audio-player>` alone.
+
+## Usage
+
+Live streams are usually HLS, so this example plays through an HLS media element instead of the preset’s native audio.
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/live-audio/player';
+  import '@videojs/html/live-audio/skin';
+  import '@videojs/html/media/hls-audio';
+</script>
+
+<live-audio-player>
+  <live-audio-skin>
+    <hls-audio src="https://example.com/live.m3u8"></hls-audio>
+  </live-audio-skin>
+</live-audio-player>
+```
+
+## Player
+
+`@videojs/html/live-audio/player` registers `<live-audio-player>`, whose class is `LiveAudioPlayerElement`. It is a [player](../components/player.md) element created by [`createPlayer`](./html-create-player.md) with `liveAudioFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](../components/player-container.md) inside it.
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
+| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
+| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+
+`content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
+
+The preset root also exports a `PlayerController` bound to the live audio player’s store. Use it from any custom element inside `<live-audio-player>`; see [`PlayerController`](./player-controller.md).
+
+## Feature bundle
+
+`liveAudioFeatures` is the array of [features](../../guides/features.md) the player is configured with. It is the [audio preset’s](./preset-audio.md#feature-bundle) `audioFeatures` without playback rate, plus the [live feature](./feature-live.md):
+
+| Feature | Description |
+| --- | --- |
+| [`playbackFeature`](./feature-playback.md) | Play/pause state and actions for the player store |
+| [`volumeFeature`](./feature-volume.md) | Volume level and mute state for the player store |
+| [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
+| [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
+| [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
+| [`liveFeature`](./feature-live.md) | Live edge state for the player store |
+| [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |
+
+Its type, `LiveAudioFeatures`, is the tuple of those features in order. Import it from the package root:
+
+```ts
+import type { LiveAudioFeatures } from '@videojs/html';
+```
+
+To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.
+
+```ts
+import { createPlayer, streamTypeFeature } from '@videojs/html';
+import { liveAudioFeatures } from '@videojs/html/live-audio';
+
+const { PlayerElement } = createPlayer({
+  features: [...liveAudioFeatures, streamTypeFeature],
+});
+
+customElements.define('my-live-audio-player', PlayerElement);
+```
+
+## Skins
+
+- [LiveAudioSkin](../components/live-audio-skin.md) — the default skin, which swaps the time controls for a Live button.
+- [NeutralLiveAudioSkin](../components/live-audio-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+
+## Media
+
+The preset plays through a native [`<audio>`](../components/audio.md), so it registers no media element of its own. Most browsers need a streaming [media element](../../guides/media-sources.md) to play a live source, such as [`<hls-audio>`](../components/hls-audio.md) for HLS.
+
+## Exports
+
+The preset root, `@videojs/html/live-audio`, has no side effects. Importing it never registers an element:
+
+| Export | Description |
+| --- | --- |
+| `LiveAudioPlayerElement` | The [player](#player) element class. |
+| `PlayerController` | The player controller, bound to the live audio player’s store. |
+| `liveAudioFeatures` | The [feature bundle](#feature-bundle). |
+| `LiveAudioSkinElement` | The default [skin](#skins) element class. |
+| `NeutralLiveAudioSkinElement` | The neutral [skin](#skins) element class. |
+
+Registration entry points are side-effect-only:
+
+| Entry point | Registers |
+| --- | --- |
+| `@videojs/html/live-audio/player` | `<live-audio-player>` |
+| `@videojs/html/live-audio/skin` | `<live-audio-skin>`, `<media-container>`, and the UI elements the skin composes |
+| `@videojs/html/live-audio/neutral-skin` | `<live-audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/live-audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
+| `@videojs/html/live-audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/preset-live-video.md

@@ -0,0 +1,124 @@
+# Live video preset
+
+The live video preset — a player, feature bundle, skins, and media for live video streams
+
+`@videojs/html/live-video` is the preset for live video streams. It bundles the `<live-video-player>` element, the `liveVideoFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
+
+## Import
+
+```ts
+import '@videojs/html/live-video/player';
+import '@videojs/html/live-video/skin';
+```
+
+Import `@videojs/html/live-video/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/live-video.js"></script>
+```
+
+`live-video-neutral.js` registers the neutral skin instead, and `live-video-player.js` registers `<live-video-player>` alone.
+
+## Usage
+
+Live streams are usually HLS, so this example plays through an HLS media element instead of the preset’s native video.
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/live-video/player';
+  import '@videojs/html/live-video/skin';
+  import '@videojs/html/media/hlsjs-video';
+</script>
+
+<live-video-player>
+  <live-video-skin>
+    <hlsjs-video src="https://example.com/live.m3u8"></hlsjs-video>
+  </live-video-skin>
+</live-video-player>
+```
+
+## Player
+
+`@videojs/html/live-video/player` registers `<live-video-player>`, whose class is `LiveVideoPlayerElement`. It is a [player](../components/player.md) element created by [`createPlayer`](./html-create-player.md) with `liveVideoFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](../components/player-container.md) inside it.
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
+| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
+| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+
+`content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
+
+The preset root also exports a `PlayerController` bound to the live video player’s store. Use it from any custom element inside `<live-video-player>`; see [`PlayerController`](./player-controller.md).
+
+## Feature bundle
+
+`liveVideoFeatures` is the array of [features](../../guides/features.md) the player is configured with. It is the [video preset’s](./preset-video.md#feature-bundle) `videoFeatures` without playback rate, quality, and audio-track selection, plus the [live feature](./feature-live.md):
+
+| Feature | Description |
+| --- | --- |
+| [`playbackFeature`](./feature-playback.md) | Play/pause state and actions for the player store |
+| [`volumeFeature`](./feature-volume.md) | Volume level and mute state for the player store |
+| [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
+| [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
+| [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`fullscreenFeature`](./feature-fullscreen.md) | Fullscreen state and actions for the player store |
+| [`pipFeature`](./feature-pip.md) | Picture-in-picture state and actions for the player store |
+| [`remotePlaybackFeature`](./feature-remote-playback.md) | Remote playback state and actions for the player store |
+| [`controlsFeature`](./feature-controls.md) | User activity and controls visibility state for the player store |
+| [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
+| [`liveFeature`](./feature-live.md) | Live edge state for the player store |
+| [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |
+
+Its type, `LiveVideoFeatures`, is the tuple of those features in order. Import it from the package root:
+
+```ts
+import type { LiveVideoFeatures } from '@videojs/html';
+```
+
+To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.
+
+```ts
+import { createPlayer, streamTypeFeature } from '@videojs/html';
+import { liveVideoFeatures } from '@videojs/html/live-video';
+
+const { PlayerElement } = createPlayer({
+  features: [...liveVideoFeatures, streamTypeFeature],
+});
+
+customElements.define('my-live-video-player', PlayerElement);
+```
+
+## Skins
+
+- [LiveVideoSkin](../components/live-video-skin.md) — the default skin, which swaps the time controls for a Live button.
+- [NeutralLiveVideoSkin](../components/live-video-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+
+## Media
+
+The preset plays through a native [`<video>`](../components/video.md), so it registers no media element of its own. Most browsers need a streaming [media element](../../guides/media-sources.md) to play a live source, such as [`<hlsjs-video>`](../components/hlsjs-video.md) for HLS.
+
+## Exports
+
+The preset root, `@videojs/html/live-video`, has no side effects. Importing it never registers an element:
+
+| Export | Description |
+| --- | --- |
+| `LiveVideoPlayerElement` | The [player](#player) element class. |
+| `PlayerController` | The player controller, bound to the live video player’s store. |
+| `liveVideoFeatures` | The [feature bundle](#feature-bundle). |
+| `LiveVideoSkinElement` | The default [skin](#skins) element class. |
+| `NeutralLiveVideoSkinElement` | The neutral [skin](#skins) element class. |
+
+Registration entry points are side-effect-only:
+
+| Entry point | Registers |
+| --- | --- |
+| `@videojs/html/live-video/player` | `<live-video-player>` |
+| `@videojs/html/live-video/skin` | `<live-video-skin>`, `<media-container>`, and the UI elements the skin composes |
+| `@videojs/html/live-video/neutral-skin` | `<live-video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/live-video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
+| `@videojs/html/live-video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |