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

package/docs/how-to/play-live-streams.md

@@ -1,116 +0,0 @@
-# Play live streams
-
-Play live streams with live-edge tracking, DVR windows, and stream-type detection.
-
-Play live streams: show a live badge, jump to the live edge, and support DVR windows when the stream allows scrubbing back.
-
-Note
-
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
-
-## Installation
-
-The examples use HlsJsVideo, so install hls.js with the framework façade:
-
-bash
-
-```
-pnpm add @videojs/html @videojs/hlsjs-video
-```
-
-## Recommended approach
-
-Use the live feature bundle with a streaming media element, and give users a `LiveButton`: it shows whether playback is at the live edge and seeks back to it when activated.
-
-html
-
-```
-<live-video-player>
-  <media-container>
-    <hlsjs-video src="https://your-stream.example.com/live.m3u8" autoplay muted playsinline></hlsjs-video>
-    <media-live-button></media-live-button>
-  </media-container>
-</live-video-player>
-<script type="module">
-  import '@videojs/html/live-video/player';
-  import '@videojs/html/media/hlsjs-video';
-  import '@videojs/html/live-video/ui';
-</script>
-```
-
-The examples use [`HlsJsVideo`](../reference/hlsjs-video.md), but any streaming media component works here, including the smaller default [`HlsVideo`](../reference/hls-video.md). Start with the default and switch engines only if your stream needs it.
-
-The `liveVideoFeatures` bundle mirrors [`videoFeatures`](../concepts/features.md) but adds the live feature and drops playback rate (not meaningful for live), quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
-
-Both bundles are plain arrays, so extending one is a spread:
-
-ts
-
-```
-import { createPlayer, streamTypeFeature } from '@videojs/html';
-import { liveVideoFeatures } from '@videojs/html/live-video';
-
-const { ProviderMixin } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
-```
-
-## How it works
-
-Two features describe liveness:
-
-*   The [stream type feature](../reference/feature-stream-type.md) reports `streamType`: `'live'`, `'on-demand'`, or `'unknown'`. Streaming media derives it from manifest metadata; plain media elements fall back to duration-based detection. `liveVideoFeatures` does not include it; add `streamTypeFeature` to the player’s features when you need `streamType`.
-*   The [live feature](../reference/feature-live.md) reports two values:
-    *   `liveEdgeStart` is where “live” begins on the timeline. When the playhead is at or past this time, the viewer is watching live; behind it, they’re watching earlier moments of the stream.
-    *   `targetLiveWindow` is how far back the stream lets viewers rewind. `0` means a plain live stream that stays at the edge. `Infinity` means full DVR: rewind as far as the recording goes. `NaN` means the stream isn’t live, or the player doesn’t know yet.
-
-The [time feature](../reference/feature-time.md) adjusts for live playback: `duration` reports the live edge (the end of the seekable range) and keeps growing as the stream continues.
-
-LiveButton reads this state: it renders as an active “go to live” control while playback is behind the edge, seeks to the edge on activation, and goes inactive at the edge. Until the media reports a `seekable` range — before metadata loads, or for non-live media — the button is disabled (`data-disabled`) because there is no edge to seek to. Custom live UIs should treat “behind the edge” and “actionable” as separate states.
-
-## Availability and constraints
-
-*   `liveEdgeStart` and `targetLiveWindow` come from media that implements the live capability — the hls.js-based media elements. With plain media elements, stream type falls back to duration-based detection and `liveEdgeStart` stays `NaN`.
-*   Live playback drifts behind the edge when the network stalls or the tab is backgrounded. Always give users a path back to the edge.
-*   Seeking makes sense only for DVR streams (`targetLiveWindow` of `Infinity`). For standard-latency streams, omit the time slider.
-*   Playback rate control isn’t meaningful for live; `liveVideoFeatures` omits it.
-
-## Common variations
-
-### DVR: let users scrub back
-
-For streams with a DVR window, give users a [TimeSlider](../reference/time-slider.md). The live preset skins don’t include one, so add it to your own UI or [eject the skin](./customize-skins.md#eject-and-edit-a-skin). The slider tracks the sliding window automatically because `duration` follows the live edge.
-
-### Switch UI by stream type
-
-Render live or on-demand controls from `streamType` when one player handles both kinds of content. Add `streamTypeFeature` to the player’s features; `liveVideoFeatures` does not include it:
-
-`<media-live-button>` selects from the live, time, and buffer features and reflects live state. To swap larger parts of the UI on `streamType`, build a provider with [createPlayer](../reference/html-create-player.md) and add `streamTypeFeature` to its features (`<live-video-player>` uses `liveVideoFeatures`, which does not include it), then read `streamType` from the player store through the [player controller](../reference/player-controller.md).
-
-## Troubleshooting
-
-### The live badge never activates
-
-`streamType` isn’t `'live'`. Confirm the player’s features include `streamTypeFeature` (`liveVideoFeatures` does not include it, so `streamType` reads as `undefined`), the source is a live manifest, and it plays through a live-capable media element such as [HlsJsVideo](../reference/hlsjs-video.md).
-
-### Playback keeps falling behind the edge
-
-Network throughput can’t sustain the stream, or the tab was backgrounded. LiveButton returns users to the edge; for lower drift, review the stream’s latency configuration on the encoder side.
-
-### The time slider behaves oddly on a live stream
-
-Standard-latency live streams have no meaningful seek range. Show the slider only for DVR streams (`targetLiveWindow` of `Infinity`).
-
-## Related components
-
-*   [Time slider](../reference/time-slider.md)
-*   [Buffering indicator](../reference/buffering-indicator.md)
-
-## Related API
-
-*   [Live feature](../reference/feature-live.md)
-*   [Stream type feature](../reference/feature-stream-type.md)
-*   [Time feature](../reference/feature-time.md)
-*   [HlsJsVideo](../reference/hlsjs-video.md)
-
-## Related guides
-
-*   [Media sources](../concepts/media-sources.md)

package/docs/how-to/show-captions-and-subtitles.md

@@ -1,140 +0,0 @@
-# Show captions and subtitles
-
-Show captions and subtitles, and let users turn them on and pick a language.
-
-Add captions and subtitles to media, and let users turn them on and pick a language.
-
-Note
-
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
-
-## Recommended approach
-
-Add WebVTT tracks as `<track>` children of the media element, and give users a [CaptionsButton](../reference/captions-button.md) to toggle them.
-
- Captions Off Captions On
-
-index.html
-
-index.css
-
-index.ts
-
-```
-<video-player class="video-player">
-  <media-container>
-    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop>
-      <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srclang="en" label="English" default />
-    </video>
-    <media-captions-button class="media-captions-button">
-      <span class="active">Captions Off</span>
-      <span class="inactive">Captions On</span>
-    </media-captions-button>
-  </media-container>
-</video-player>
-```
-```
-.video-player {
-  position: relative;
-}
-
-.video-player video {
-  width: 100%;
-  aspect-ratio: 16 / 9;
-}
-
-.media-captions-button {
-  position: absolute;
-  bottom: 10px;
-  left: 10px;
-  padding-block: 8px;
-  padding-inline: 20px;
-  color: black;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.7);
-  border: 1px solid rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  backdrop-filter: blur(10px);
-}
-
-.media-captions-button .active {
-  display: none;
-}
-.media-captions-button .inactive {
-  display: none;
-}
-.media-captions-button[data-active] .active {
-  display: inline;
-}
-.media-captions-button:not([data-active]) .inactive {
-  display: inline;
-}
-```
-```
-import '@videojs/html/video/player';
-import '@videojs/html/ui/captions-button';
-```
-
-## How it works
-
-The [text track feature](../reference/feature-text-tracks.md) mirrors the media element’s `textTracks` into player state:
-
-*   `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
-*   `subtitlesShowing` is `true` when any caption or subtitle track is showing.
-*   `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
-*   `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
-
-Tracks don’t have to come from `<track>` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
-
-The browser renders the cues. Style them with the `::cue` pseudo-element.
-
-## Availability and constraints
-
-*   Captions availability is `'unavailable'` until the media has at least one caption or subtitle track; caption controls render nothing in that case.
-*   Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
-*   Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossOrigin` on the media element.
-*   Track selection UIs identify tracks by `label` and `language`; give every track both.
-*   `default` on a `<track>` makes the browser show it initially.
-
-## Common variations
-
-### Language selection menu
-
-For multiple languages, render a menu instead of a toggle.
-
-Use [`<media-captions-radio-group>`](../reference/captions-radio-group.md) inside a menu or popover for explicit track selection.
-
-## Troubleshooting
-
-### Captions don’t appear
-
-Confirm that:
-
-*   The track `kind` is `captions` or `subtitles`.
-*   The VTT file loads (check the network panel for the track request).
-*   The track is enabled: `default` on the track element, a CaptionsButton toggle, or `toggleSubtitles(true)`.
-
-### Captions work locally but not in production
-
-The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossOrigin` on the media element.
-
-### The selection menu is empty
-
-The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
-
-## Related components
-
-*   [Captions button](../reference/captions-button.md)
-*   [Captions radio group](../reference/captions-radio-group.md)
-*   [Menu](../reference/menu.md)
-
-## Related API
-
-*   [Text track feature](../reference/feature-text-tracks.md)
-*   [useCaptionsOptions](/docs/framework/react/reference/use-captions-options)
-
-## Related guides
-
-*   [Show timeline thumbnail previews](./show-timeline-thumbnail-previews.md)
-*   [Media sources](../concepts/media-sources.md)
-*   [Accessibility](../concepts/accessibility.md)

package/docs/how-to/show-timeline-thumbnail-previews.md

@@ -1,164 +0,0 @@
-# Show timeline thumbnail previews
-
-Preview frames along the timeline while the user scrubs, powered by a storyboard track.
-
-Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
-
-Using Mux?
-
-With [MuxVideo](../reference/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
-
-Note
-
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
-
-## Recommended approach
-
-Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [TimeSlider](../reference/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same props as the standalone [Thumbnail](../reference/thumbnail.md).
-
-`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child; set `crossorigin`, `loading`, or `fetchpriority` on the element itself.
-
-index.html
-
-index.css
-
-index.ts
-
-```
-<video-player class="video-player">
-  <media-container>
-    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop crossorigin="anonymous">
-      <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
-    </video>
-    <media-time-slider class="media-time-slider">
-      <media-slider-track class="media-slider-track">
-        <media-slider-fill class="media-slider-fill"></media-slider-fill>
-      </media-slider-track>
-      <media-slider-thumbnail class="media-slider-thumbnail"></media-slider-thumbnail>
-    </media-time-slider>
-  </media-container>
-</video-player>
-```
-```
-.video-player {
-  position: relative;
-  display: block;
-}
-
-.video-player video {
-  width: 100%;
-}
-
-.media-time-slider {
-  position: absolute;
-  right: 10px;
-  bottom: 6px;
-  left: 10px;
-  display: flex;
-  align-items: center;
-  height: 20px;
-  cursor: pointer;
-}
-
-.media-slider-track {
-  position: absolute;
-  right: 0;
-  left: 0;
-  height: 4px;
-  background: rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  transition: height 150ms ease;
-}
-
-.media-time-slider[data-interactive] .media-slider-track {
-  height: 6px;
-}
-
-.media-slider-fill {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: var(--media-slider-fill);
-  height: 100%;
-  background: white;
-  border-radius: 9999px;
-}
-
-/* Reveal the preview over the pointer while it is on the slider. */
-.media-slider-thumbnail {
-  position: absolute;
-  bottom: 100%;
-  left: var(--media-slider-pointer);
-  max-width: 160px;
-  margin-bottom: 8px;
-  pointer-events: none;
-  border-radius: 4px;
-  opacity: 0;
-  transform: translateX(-50%);
-  transition: opacity 150ms ease;
-}
-
-.media-time-slider[data-pointing] .media-slider-thumbnail {
-  opacity: 1;
-}
-
-.media-slider-thumbnail[data-hidden] {
-  display: none;
-}
-```
-```
-import '@videojs/html/video/player';
-import '@videojs/html/ui/time-slider';
-```
-
-## How it works
-
-*   Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
-*   The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the demo’s CSS uses them to reveal the preview and position it over the pointer.
-*   To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [Thumbnail](../reference/thumbnail.md) component with an explicit `time`.
-
-Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
-
-storyboard.vtt
-
-```
-WEBVTT
-
-00:00:00.000 --> 00:00:05.000
-storyboard.jpg#xywh=0,0,256,160
-
-00:00:05.000 --> 00:00:10.000
-storyboard.jpg#xywh=256,0,256,160
-```
-
-## Availability and constraints
-
-*   Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
-*   Cross-origin storyboards need CORS headers, and `crossOrigin` on the media element for the track to load.
-*   Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
-*   Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
-
-## Troubleshooting
-
-### Thumbnails don’t appear while scrubbing
-
-Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossOrigin` set on the media element.
-
-### Thumbnails are blurry or slow
-
-Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
-
-## Related components
-
-*   [Thumbnail](../reference/thumbnail.md)
-*   [Slider](../reference/slider.md)
-*   [Time slider](../reference/time-slider.md)
-
-## Related API
-
-*   [Text track feature](../reference/feature-text-tracks.md)
-
-## Related guides
-
-*   [Add a poster and loading placeholder](./add-a-poster-and-loading-placeholder.md)
-*   [Show captions and subtitles](./show-captions-and-subtitles.md)

package/docs/reference/aria-key-shortcuts-controller.md

@@ -1,117 +0,0 @@
-# AriaKeyShortcutsController
-
-Reactive controller that exposes registered hotkey shortcut metadata
-
-## Import
-
-ts
-
-```
-import { AriaKeyShortcutsController } from "@videojs/html";
-```
-
-## Usage
-
-Create the controller on a reactive element inside a player container. It follows the container’s hotkey registrations and requests a host update when they change.
-
-ts
-
-```
-class CustomPlayButton extends UIElement {
-  readonly #shortcut = new AriaKeyShortcutsController(this, "togglePaused");
-
-  get ariaKeyShortcuts() {
-    return this.#shortcut.aria;
-  }
-
-  get shortcutLabel() {
-    return this.#shortcut.shortcut;
-  }
-}
-```
-
-Use `aria` for the element’s `aria-keyshortcuts` value and `shortcut` for display text. Both are `undefined` until the matching action has a registered shortcut.
-
-## API Reference
-
-### Parameters
-
-Parameter
-
-Type
-
-Default
-
-Details
-
-`host*`
-
-`object`
-
-`—`
-
-▸
-
-Description
-
-Host element whose nearest player container supplies hotkey registrations.
-
-Type
-
-`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
-
-`action*`
-
-`string`
-
-`—`
-
-▸
-
-Description
-
-Registered hotkey action to look up.
-
-`options*`
-
-`unknown`
-
-`—`
-
-▸
-
-Description
-
-Optional value resolver for value-dependent shortcuts.
-
-### Return Value
-
-Property
-
-Type
-
-Details
-
-`value`
-
-`string | undefined`
-
-`aria`
-
-`string | undefined`
-
-`shortcut`
-
-`string | undefined`
-
-`details`
-
-`{ aria?: string; shortcut?: string }`
-
-`hostConnected`
-
-`(() => void)`
-
-`hostDisconnected`
-
-`(() => void)`

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

@@ -1,43 +0,0 @@
-# audio-minimal-skin
-
-The audio preset's visually lighter skin, closer to a classic control bar
-
-The minimal skin of the audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. [AudioSkin](./audio-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the audio preset ships.
-
-## Import
-
-ts
-
-```
-import '@videojs/html/audio/minimal-skin';
-```
-
-The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
-
-html
-
-```
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/audio-minimal.js"></script>
-```
-
-## Usage
-
-The skin goes between the player and the media element. It renders its controls around the media.
-
-html
-
-```
-<audio-player>
-  <audio-minimal-skin>
-    <audio src="audio.mp3"></audio>
-  </audio-minimal-skin>
-</audio-player>
-```
-
-## Styling
-
-Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
-
-## Eject the skin
-
-The `@videojs/audio-minimal` skin installs under `components/videojs/skins/audio/minimal`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

package/docs/reference/audio-skin.md

@@ -1,43 +0,0 @@
-# audio-skin
-
-The audio preset's default skin with the modern, frosted look
-
-The default skin of the audio preset: the control layout for on-demand audio with the modern, frosted look. [MinimalAudioSkin](./audio-minimal-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the audio preset ships.
-
-## Import
-
-ts
-
-```
-import '@videojs/html/audio/skin';
-```
-
-The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
-
-html
-
-```
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/audio.js"></script>
-```
-
-## Usage
-
-The skin goes between the player and the media element. It renders its controls around the media.
-
-html
-
-```
-<audio-player>
-  <audio-skin>
-    <audio src="audio.mp3"></audio>
-  </audio-skin>
-</audio-player>
-```
-
-## Styling
-
-Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
-
-## Eject the skin
-
-The `@videojs/audio` skin installs under `components/videojs/skins/audio`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

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

@@ -1,39 +0,0 @@
-# background-video-skin
-
-The background preset's chrome-less skin for ambient video
-
-The only skin of the background preset: a chrome-less surface that sizes ambient video with no visible controls. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the background preset ships.
-
-## Import
-
-ts
-
-```
-import '@videojs/html/background/skin';
-```
-
-The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
-
-html
-
-```
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/background.js"></script>
-```
-
-## Usage
-
-The skin goes between the player and the media element. It sizes the ambient video and renders no visible controls.
-
-html
-
-```
-<background-video-player>
-  <background-video-skin>
-    <background-video src="video.mp4"></background-video>
-  </background-video-skin>
-</background-video-player>
-```
-
-## Styling
-
-Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. The background video skin cannot be ejected.