@videojs/html 10.0.0-beta.23 → 10.0.0-beta.24

package/docs/how-to/installation.md

@@ -0,0 +1,172 @@
+# Installation
+
+Install Video.js and build your first player with streaming support and accessible controls
+
+Beta Software
+
+Video.js v10 is currently in *beta* . The API may evolve with [feedback🙏](https://github.com/videojs/v10/issues). See the [Changelog](https://github.com/videojs/v10/blob/main/CHANGELOG.md) for recent updates and the [Roadmap](../concepts/v10-roadmap.md) for more details on what’s coming.
+
+Video.js is an **HTML video player built on custom elements** : lightweight, framework-free components for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
+
+<!-- cli:omit installation -->
+
+
+This guide has code examples tailored to your use case. To generate this guide with tailored code examples, run `npx @videojs/cli docs how-to/installation`. If you run it without flags, it will allow you to interactively configure your player. Or, you can run it with flags:
+
+bash
+
+```
+npx @videojs/cli docs how-to/installation \
+  --framework <html|react> \
+  --preset <video|audio|background-video> \
+  --skin <default|minimal> \
+  --media <html5-video|html5-audio|hls|background-video> \
+  --source-url <url> \
+  --install-method <cdn|npm|pnpm|yarn|bun>
+```
+
+Here’s what the flags mean:
+
+*   *Framework* : Pick whether you’re working in React or if you’d like to use HTML custom elements. (More to come!)
+*   *Preset* : Pick a pre-built player. The default presets work well for general website playback.
+*   *Skin* : Pick what your player looks like
+*   *Media* : Pick what kind of media you have
+*   *Source URL* : Define where your media comes from (or omit for a sample URL)
+*   *Install method* : How do you want to install your package? (CDN is HTML-only)
+
+If you’re an agent, interview your user and offer to run the CLI for them, or offer them a precomposed CLI command.
+
+
+<!-- /cli:omit installation -->
+
+If your user’s requirements can’t be met by a preset/skin, [eject](./customize-skins.md) and customize an existing preset/skin for your needs. As you develop with Video.js, rely heavily on [llms.txt](../llms.txt) to make sure you always have the latest information.
+
+<!-- cli:replace installation -->
+
+
+## Install Video.js
+
+cdn
+
+npm
+
+pnpm
+
+yarn
+
+bun
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/html/cdn/video.js"></script>
+```
+
+```
+npm install @videojs/html
+```
+
+```
+pnpm add @videojs/html
+```
+
+```
+yarn add @videojs/html
+```
+
+```
+bun add @videojs/html
+```
+
+## Use your player
+
+HTML
+
+```
+<!--
+  The PlayerProvider passes state between the UI components
+  and Media, and makes fully custom UIs possible.
+  It does not have layout by default (display:contents)
+ -->
+<video-player>
+  <!--
+    Skins contain the entire player UI and are easily swappable.
+    They can each be "ejected" for full control and customization
+    of UI components.
+   -->
+  <video-skin>
+    <!--
+      Media are players without UIs, handling networking
+      and display of the media. They are easily swappable
+      to handle different sources.
+    -->
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
+  </video-skin>
+</video-player>
+```
+
+Load your script as a module
+
+When using a bundler (npm, pnpm, yarn, bun), load the resulting bundle with `type="module"`:
+
+html
+
+```
+<script type="module" src="/dist/player.js"></script>
+```
+
+Some bundlers default to an IIFE output format. Loading that bundle without `type="module"` will cause a `StoreError: NO_TARGET` error when interacting with the player. The CDN install path already uses `type="module"` — bundled installs need the same.
+
+
+
+
+
+
+
+
+
+
+
+
+<!-- /cli:replace installation -->
+
+## CSP
+
+If your application uses a Content Security Policy, you may need to allow additional sources for player features to work correctly.
+
+### Common requirements
+
+*   `media-src` must allow your media URLs.
+*   `img-src` must allow any poster or thumbnail image URLs.
+*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+*   `worker-src blob:` is required when using the `hls.js` player variants.
+*   `style-src 'unsafe-inline'` is currently required for some player UI and HTML player styling behavior.
+
+### Example
+
+http
+
+```
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+## See also
+
+[
+
+Skins
+
+Some skins expose CSS custom properties
+
+](../concepts/skins.md)
+
+* * *
+
+That’s it! You now have a fully functional Video.js player. Go forth and play.
+
+Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](/html5-video-support).

package/docs/llms.txt

@@ -0,0 +1,88 @@
+# Video.js v10 — Html Documentation
+
+## Getting started
+
+Installation, project setup, and introductory guides.
+
+- [Installation](./how-to/installation.md): Install Video.js and build your first player with streaming support and accessible controls
+- [Why Video.js?](./concepts/why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Overview](./concepts/overview.md): How Video.js players are structured — state, UI, and media
+- [Build with AI](./how-to/build-with-ai.md): How to give AI tools the context they need to build Video.js players alongside you
+- [v10 Roadmap](./concepts/v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
+- [Browser Support](./concepts/browser-support.md): Which browsers Video.js 10 supports and how it handles newer platform features
+
+## Concepts
+
+Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
+
+- [Features](./concepts/features.md): The state and actions each feature adds to the player
+- [Skins](./concepts/skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+- [UI components](./concepts/ui-components.md): How Video.js UI components work — one element per component, data attributes for state, and compound composition.
+- [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+
+## How to
+
+Task-oriented guides with step-by-step instructions to achieve a specific outcome by applying one or more concepts. Each guide may assume you already understand the relevant concepts.
+
+- [Customize skins](./how-to/customize-skins.md): Learn how to customize Video.js v10 skins by copying and modifying them
+- [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+
+## Components
+
+API Reference for UI components for building media player interfaces.
+
+- [video-player](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
+- [media-container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+- [media-buffering-indicator](./reference/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+- [media-captions-button](./reference/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [media-controls](./reference/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [media-fullscreen-button](./reference/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [media-mute-button](./reference/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [media-pip-button](./reference/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+- [media-play-button](./reference/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
+- [media-playback-rate-button](./reference/playback-rate-button.md): A button that cycles through playback speed rates
+- [media-popover](./reference/popover.md): A popover component for displaying contextual content anchored to a trigger
+- [media-poster](./reference/poster.md): Poster image component that displays a thumbnail until video playback starts
+- [media-seek-button](./reference/seek-button.md): Accessible seek button for skipping forward or backward by a configurable number of seconds
+- [media-slider](./reference/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [media-thumbnail](./reference/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [media-time](./reference/time.md): Time display components for showing current time, duration, and remaining time in a video player
+- [media-time-slider](./reference/time-slider.md): A slider component for seeking through media playback time
+- [media-tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
+- [media-volume-slider](./reference/volume-slider.md): A slider component for controlling media playback volume
+
+## Controllers & Mixins
+
+API Reference for controllers and mixins for HTML custom element integration.
+
+- [createPlayer](./reference/html-create-player.md): Factory function that creates a player instance with typed store, mixins, and controller for HTML custom elements
+- [PlayerController](./reference/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+### Advanced
+
+- [ContainerMixin](./reference/container-mixin.md): Mixin that consumes player context and registers the element as the media container
+- [MediaAttachMixin](./reference/media-attach-mixin.md): Mixin for custom media elements to register themselves with the provider via context
+- [playerContext](./reference/player-context.md): The default player context instance for consuming the player store in controllers
+- [ProviderMixin](./reference/provider-mixin.md): Mixin that creates the player store and manages the full media attach lifecycle
+- [SnapshotController](./reference/snapshot-controller.md): Reactive controller for subscribing to a State container in HTML custom elements
+- [StoreController](./reference/store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
+
+## Features
+
+API reference for feature modules that provide player capabilities and state.
+
+- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
+- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
+- [Error](./reference/feature-error.md): Media error state and actions for the player store
+- [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Live](./reference/feature-live.md): Live edge state for the player store
+- [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
+- [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
+- [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
+- [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
+- [Source](./reference/feature-source.md): Media source state and actions for the player store
+- [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./reference/feature-time.md): Playback position and duration state for the player store
+- [Volume](./reference/feature-volume.md): Volume level and mute state for the player store

package/docs/reference/buffering-indicator.md

@@ -0,0 +1,152 @@
+# media-buffering-indicator
+
+Loading indicator that displays when the video player is buffering or waiting for data
+
+## Anatomy
+
+html
+
+```
+<media-buffering-indicator></media-buffering-indicator>
+```
+
+## Behavior
+
+Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.
+
+## Styling
+
+Hide and show the indicator based on the `data-visible` attribute.
+
+## Examples
+
+### Basic Usage
+
+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
+        ></video>
+        <media-buffering-indicator class="media-buffering-indicator">
+            <div class="spinner"></div>
+        </media-buffering-indicator>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+  display: flex;
+  width: 100%;
+  height: 100%;
+}
+
+.media-buffering-indicator {
+  position: absolute;
+  inset: 0;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+
+.spinner {
+  display: none;
+  width: 48px;
+  height: 48px;
+  border: 4px solid rgba(255, 255, 255, 0.3);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: buffering-spin 0.8s linear infinite;
+}
+
+.media-buffering-indicator[data-visible] .spinner {
+  display: block;
+}
+
+@keyframes buffering-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/buffering-indicator';
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`delay`
+
+`number`
+
+`500`
+
+▸
+
+Attribute
+
+`delay`
+
+Description
+
+Delay in milliseconds before the indicator becomes visible.
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`visible`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused.
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when the buffering indicator is visible (after delay).

package/docs/reference/captions-button.md

@@ -0,0 +1,216 @@
+# media-captions-button
+
+Accessible captions toggle button with availability detection and state reflection
+
+## Anatomy
+
+html
+
+```
+<media-captions-button></media-captions-button>
+```
+
+## Behavior
+
+Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"` and reflects availability via `data-availability`.
+
+When no caption or subtitle tracks are present, `data-availability="unavailable"` is set. Use this to hide the button when there are no tracks to toggle.
+
+## Styling
+
+Style the button based on active state:
+
+css
+
+```
+media-captions-button[data-active] .icon-on { display: inline; }
+media-captions-button:not([data-active]) .icon-off { display: inline; }
+```
+
+Hide when no caption tracks are available:
+
+css
+
+```
+media-captions-button[data-availability="unavailable"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Disable captions” when active, “Enable captions” when inactive. Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+ 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/captions-button/captions.vtt" srclang="en" label="English" />
+        </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%;
+}
+
+.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';
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: CaptionsButtonState) => string)`
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable'`
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-active`
+
+▸
+
+Description
+
+Present when captions are enabled.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates captions availability (`available` or `unavailable`).

package/docs/reference/container-mixin.md

@@ -0,0 +1,69 @@
+# ContainerMixin
+
+Mixin that consumes player context and registers the element as the media container
+
+`ContainerMixin` creates a class that consumes the player store from context and registers itself as the media container with the [provider](./provider-mixin.md). The provider uses this reference as the fullscreen target and passes it to `store.attach()`.
+
+### What ContainerMixin does
+
+On `connectedCallback`, the element registers itself with the provider via `containerContext`. The provider stores the container reference and uses it when calling `store.attach({ media, container })`. On `disconnectedCallback`, the element deregisters itself.
+
+Media discovery is owned by the provider — `ContainerMixin` does not search for or attach media elements.
+
+### When to use ContainerMixin
+
+Use `ContainerMixin` when the [provider](./provider-mixin.md) and container live in different elements. This is common when the store owner sits higher in the tree (e.g., a layout shell) while the media element sits deeper in a content area.
+
+For a single element that both owns the store and attaches the container, compose both mixins on the same base class:
+
+ts
+
+```
+const { ProviderMixin, ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class VideoPlayer extends ProviderMixin(ContainerMixin(MediaElement)) {}
+```
+
+### Split composition
+
+Pair `ContainerMixin` with [`ProviderMixin`](./provider-mixin.md) when the store owner is a different element from the container:
+
+ts
+
+```
+const { ProviderMixin, ContainerMixin } = createPlayer({ features: videoFeatures });
+
+// Provider owns the store, sits at the top
+class PlayerShell extends ProviderMixin(MediaElement) {}
+
+// Container registers as the layout/fullscreen target
+class MediaRegion extends ContainerMixin(MediaElement) {}
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`ContainerMixinConfig<PlayerStore>`
+
+`—`
+
+▸
+
+Description
+
+Container configuration with player and container contexts.
+
+### Return Value
+
+`ContainerMixin<PlayerStore>`