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

package/docs/concepts/ui-components.md

@@ -0,0 +1,59 @@
+# UI components
+
+How Video.js UI components work — one element per component, data attributes for state, and compound composition.
+
+UI components are controls like buttons, sliders, and time displays.
+
+Every UI component renders exactly one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you.
+
+## Where to put your components
+
+UI Components can go anywhere inside a [`<video-player>`](../reference/player-provider.md).
+
+However, you should consider placing your components in `<player-container>`. Components in `<player-container>` will go fullscreen with the player, respond to user activity, and more.
+
+[Read more about `<player-container>`](../reference/player-container.md)
+
+## Styling and customization
+
+Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
+
+This lets you style state changes in pure CSS:
+
+html
+
+```
+<media-play-button class="my-play-button">
+  <span class="play-icon">Play</span>
+  <span class="pause-icon">Pause</span>
+</media-play-button>
+```
+
+css
+
+```
+media-play-button .play-icon  { display: none; }
+media-play-button .pause-icon { display: none; }
+
+media-play-button[data-paused] .play-icon        { display: inline; }
+media-play-button:not([data-paused]) .pause-icon  { display: inline; }
+```
+
+Each component’s reference page documents its full set of data attributes.
+
+Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
+
+## Compound components
+
+Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each part is still one element.
+
+html
+
+```
+<media-volume-slider orientation="vertical">
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-slider-thumb></media-slider-thumb>
+</media-volume-slider>
+```

package/docs/concepts/v10-roadmap.md

@@ -0,0 +1,75 @@
+# v10 Roadmap
+
+Timeline and milestones for Video.js v10 rebuild and the future of v8
+
+Video.js v10 is a complete rebuild from the ground up, designed to be more modular, framework-flexible, and aligned with modern web development practices.
+
+## Current versions
+
+### Version 8
+
+*   Maintained with bug fixes and critical security patches only
+*   No new features will be planned
+*   Community contributions still welcome
+*   Documentation available at [legacy.videojs.org](https://legacy.videojs.org)
+
+### Version 9
+
+*   Reserved only for urgent API-breaking changes that cannot be avoided
+
+## March 2026: v10 Beta Release
+
+Wider testing release to the community.
+
+### Core feature parity target
+
+*   Basic control set (play, pause, seek, volume, fullscreen)
+*   Adaptive streaming support via existing community engines
+*   No plugin migrations yet, without plugin author contribution
+
+### What to expect
+
+*   Close to stable, but API changes are still possible
+*   Intended for experimental adoption in real-world projects
+*   Developers encouraged to try it out and report issues
+
+## Mid-2026: v10 GA Release
+
+**Stable release** of Video.js v10
+
+### Feature targets
+
+*   Core feature parity with v8 in terms of fundamentals
+*   Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
+*   Community encouraged to begin full reintegration projects
+*   Plugin ecosystem migration begins in earnest
+
+### Engine development focus
+
+*   Lightweight adaptive streaming
+*   MoQ (Media over QUIC) support
+
+## Late-2026: Feature parity with v8 Contrib
+
+**Extended feature parity** with Video.js “contrib” plugins:
+
+*   Ads integration
+*   Analytics support
+*   Further community plugin migration dependent on contributions
+
+## End-of-life plan for Video.js v8
+
+### Mid-2026
+
+*   v8/v9 moved to “video.js-legacy” repository and package
+*   Documentation preserved at [legacy.videojs.org](https://legacy.videojs.org)
+*   Hosted CDN copies will remain available
+
+### 2027 and beyond
+
+*   Security patches only
+*   Community contributions de-prioritized
+
+* * *
+
+**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved in the rebuild

package/docs/concepts/why-videojs.md

@@ -0,0 +1,113 @@
+# Why Video.js?
+
+The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+
+Video.js is the open-source video player for the web. It makes web video easy, performant, accessible, and customizable.
+
+Let’s dig into when you’d want to use Video.js, starting with the the question we hear most…
+
+## Why not `<video>`?
+
+The native `<video>` tag is great if you can describe your video as an image with a play button. Past that, the gaps show up quickly.
+
+### Cross-browser inconsistency
+
+Chrome, Safari, and Firefox each render the default `<video>` controls differently. You can hide them, but you can’t deeply style or rearrange them. Building UI that matches your product means starting from scratch.
+
+![Chrome's default video controls](/_astro/chrome-default-controls.D2ybhMTL.png)
+
+Chrome
+
+![Safari's default video controls](/_astro/safari-default-controls.CPUt6ekS.png)
+
+Safari
+
+![Firefox's default video controls](/_astro/firefox-default-controls.CYiJeU98.png)
+
+Firefox
+
+### Video interactions
+
+Video often involves a lot more than an MP4 in `src`. Rich playback features (like thumbnail previews, adaptive bitrate, quality selection, chapters, audio track switching, control localization, error UI, live-streaming UI, analytics, ads, 360 video, Chromecast, AirPlay, DRM, and more) are *possible* with the video element but require complex wiring and deep consideration for maintainabilty and [accessibility](./accessibility.md).
+
+Video.js aims to handle this all out of the box. (Though some features are still under development. Stay tuned!)
+
+### Streaming formats and sources
+
+Behind features like adaptive bitrate and quality selection are video formats like HLS or DASH — videos broken into segments that can be selected according to bandwidth and preferences. Not every browser supports HLS, and DASH support is even more limited. Video.js closes the gap so the same `src` works everywhere.
+
+Of course, your video might not be coming from a `src` like that. It might be provided by a service. However, services like YouTube, Vimeo, and Mux each speak their own API. Switching from a self-hosted file to a hosted service shouldn’t mean switching players. Video.js abstracts the source so you can change where the video comes from without rewriting the surrounding code.
+
+Video.js even considers sources like canvas-based MoQ or animated GIFs, all with the same components.
+
+## Why Video.js?
+
+Video.js is built at Mux by the teams behind Video.js, Plyr, Vidstack, and Media Chrome, with contributions from engineers across other player projects. Between us, our projects have served tens of billions of monthly video plays. Most of the choices on this page came from things we got wrong the first time, then the second, then the fifth. We’ve been supporting your edge cases for over a decade. Now we’re shipping the player we always wanted to build.
+
+Let’s dig into some of the design principles that help explain why we built Video.js and why it may be the best choice for your project or team.
+
+### Add only what you need
+
+Most player libraries ship every feature in one bundle, so you carry code you don’t run. If your video doesn’t need a feature like DRM, why ship that code? Video.js turns features into independent, *composable* modules. You hand `createPlayer` the array you actually want, and what you don’t import doesn’t ship.
+
+ts
+
+```
+import { createPlayer, playbackFeature, timeFeature } from '@videojs/html';
+
+const { ProviderMixin, PlayerController, context } = createPlayer({
+  features: [playbackFeature, timeFeature],
+});
+```
+
+[Learn more about features](./features.md)
+
+Of course, you don’t have to think about every feature you’re going to need if you don’t want to. Pre-built feature bundles are still there if you’d rather not assemble the list by hand.
+
+[Learn more about presets](./presets.md)
+
+### Framework-native
+
+Many player libraries wrap a single web component for every framework. That works, until you reach the seams: refs you can’t pass through, state that doesn’t reconcile, prop names that aren’t quite React or HTML. Video.js ships idiomatic APIs in each framework: React components and hooks for React, custom elements and controllers for HTML. (And we plan on supporting more frameworks in the futrue!)
+
+The player feels like the rest of your app.
+
+React
+
+HTML
+
+```
+import { Player, Video, VideoSkin } from '@videojs/react/video';
+
+function MyPlayer() {
+  return (
+    <Player.Provider>
+      <VideoSkin>
+        <Video src="movie.mp4" />
+      </VideoSkin>
+    </Player.Provider>
+  );
+}
+```
+
+```
+<script type="module" src="@videojs/html/video/player"></script>
+
+<video-player>
+  <video-skin>
+    <video src="movie.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+### Eject and own
+
+Most player libraries draw a line between “configurable through props” and “fork the source.” Cross the line and you’re on your own. Video.js lets you eject any skin and walk away with the source: components in your framework’s language that you can read and change. The skin you ship is yours; the rest of the player keeps working underneath it.
+
+[Customize skins](../how-to/customize-skins.md)
+
+### AI-native DX
+
+Documentation aimed at human readers usually doesn’t help an agent. Video.js publishes an `llms.txt` index, ships every docs page as both HTML and Markdown, and has a dedicated guide for building with AI assistants. Drop the player into a Claude or Cursor session and the docs come along for the ride.
+
+[Build with AI](../how-to/build-with-ai.md)

package/docs/how-to/build-with-ai.md

@@ -0,0 +1,39 @@
+# Build with AI
+
+How to give AI tools the context they need to build Video.js players alongside you
+
+Video.js publishes all of its documentation in AI-friendly formats. This page covers how to feed that documentation to your tools.
+
+## Give your AI context
+
+AI tools might not know the Video.js API out of the box. You need to give them documentation.
+
+### Markdown documentation
+
+Every doc page is available as markdown, so you can provide your model with focused content instead of HTML. Three ways to get it:
+
+1.  **Copy button** : each page has a “Copy Markdown” button in its header. Grab the pages relevant to your task and paste them in. It looks something like this…
+    
+2.  **`Accept: text/markdown` header** : AI tools that send this header when fetching a Video.js doc URL will receive markdown instead of HTML.
+    
+    ![Fetching a doc URL returns 188.7KB of HTML; fetching the same URL with .md returns 3.4KB of markdown](/.netlify/images?url=_astro%2Fmarkdown-negotiation.2TkZPhhc.png&w=1470&h=680)
+    
+3.  **Add `.md` to any URL** : append `.md` to any doc URL to get its markdown directly. For example, the PlayButton reference is available at [`videojs.org/docs/framework/html/reference/play-button.md`](../reference/play-button.md).
+    
+
+### llms.txt
+
+[`videojs.org/docs/framework/html/llms.txt`](../llms.txt) is an index of the full documentation: every page with a title and description. Add it to your project’s context so your AI knows what’s available.
+
+## Set up your tools
+
+How you use these resources depends on your tool:
+
+*   **Any AI chat** : copy markdown from a doc page and paste it into the conversation.
+*   **Claude Code** : reference doc URLs in your project’s [`CLAUDE.md`](https://docs.anthropic.com/en/docs/claude-code/overview) so the agent knows where to find Video.js docs when it needs them.
+*   **Cursor** : add the `llms.txt` URL via the [`@Docs`](https://docs.cursor.com/context/@-symbols/@-docs) feature for indexed search across the documentation.
+*   **Other coding agents** : reference doc URLs or `llms.txt` in your project’s [`AGENTS.md`](https://agents.md) or equivalent context file.
+
+## What’s next for AI and Video.js
+
+We’re exploring additional ways to integrate with AI tools, including MCP servers and agent skills. If you have ideas or want to share how you’re using AI with Video.js, we’d love to hear from you in [GitHub Discussions](https://github.com/videojs/v10/discussions).

package/docs/how-to/build-your-own-component.md

@@ -0,0 +1,217 @@
+# Build your own UI component
+
+Create custom player controls that read state, dispatch actions, and stay accessible.
+
+Custom components subscribe to player state and dispatch actions, like built-in controls.
+
+## You might not need a custom component
+
+Before building from scratch, check if an existing approach covers your use case:
+
+*   **Restyle a control** : use CSS custom properties and data attributes. See [UI components](../concepts/ui-components.md).
+*   **Rearrange or remove controls** : eject a skin and modify it. See [Customize skins](./customize-skins.md).
+
+Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+## Use player state and actions
+
+Need access to player state or actions? You’ll want to familiarize yourself with [features](../concepts/features.md). Each feature exposes a set. Here are some features you might reach for first:
+
+State
+
+Actions
+
+Feature
+
+`paused`, `ended`
+
+`play()`, `pause()`
+
+[Playback](../reference/feature-playback.md)
+
+`currentTime`, `duration`
+
+`seek()`
+
+[Time](../reference/feature-time.md)
+
+`volume`, `muted`
+
+`setVolume()`, `toggleMuted()`
+
+[Volume](../reference/feature-volume.md)
+
+`fullscreen`
+
+`requestFullscreen()`, `exitFullscreen()`
+
+[Fullscreen](../reference/feature-fullscreen.md)
+
+Browse the full list in the **Features** section of the sidebar.
+
+Each feature also has an **availability** property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
+
+Access state and actions with [`PlayerController`](../reference/player-controller.md) and a feature selector:
+
+ts
+
+```
+import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
+
+// Subscribe to a feature — triggers update() when its state changes
+#playback = new PlayerController(this, playerContext, selectPlayback);
+
+// In update():
+const playback = this.#playback.value;
+if (playback?.paused) {
+  playback.play();
+}
+```
+
+Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
+
+Without a selector, `PlayerController` returns the full store without subscribing to changes:
+
+ts
+
+```
+#store = new PlayerController(this, playerContext);
+
+// Call any action
+this.#store.value.play();
+this.#store.value.setVolume(0.5);
+```
+
+## Place your component in the player
+
+Your element needs to be inside [`<video-player>`](../reference/player-provider.md) to access state. Place it inside [`<media-container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
+
+html
+
+```
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+    <skip-intro-button>Skip intro</skip-intro-button>
+  </video-skin>
+</video-player>
+```
+
+Extend `MediaElement` from `@videojs/html` so `PlayerController` can schedule DOM updates when state changes:
+
+ts
+
+```
+import { MediaElement, PlayerController, playerContext, selectTime, type PropertyValues } from '@videojs/html';
+
+class SkipIntroButtonElement extends MediaElement {
+  #player = new PlayerController(this, playerContext, selectTime);
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#player.value;
+  }
+}
+```
+
+## Make it accessible
+
+[Learn more about accessibility in video players](../concepts/accessibility.md)
+
+## Full example
+
+A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
+
+skip-intro-button.ts
+
+skip-intro-button.css
+
+```
+import {
+  MediaElement,
+  PlayerController,
+  playerContext,
+  selectTime,
+  selectPlayback,
+  type PropertyValues,
+} from '@videojs/html';
+
+class SkipIntroButtonElement extends MediaElement {
+  #time = new PlayerController(this, playerContext, selectTime);
+  #playback = new PlayerController(this, playerContext, selectPlayback);
+  #disconnect: AbortController | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = new AbortController();
+    const { signal } = this.#disconnect;
+
+    this.setAttribute('role', 'button');
+    this.setAttribute('aria-label', 'Skip intro');
+    this.setAttribute('tabindex', '0');
+    this.addEventListener('click', this.#handleActivate, { signal });
+    this.addEventListener('keydown', this.#handleKeydown, { signal });
+    this.addEventListener('keyup', this.#handleKeyup, { signal });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // Removes all listeners registered with this signal
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#time.value;
+    const playback = this.#playback.value;
+
+    // Features are configured per-player, so a feature may not be available
+    if (!time || !playback) return;
+
+    const visible = time.currentTime < 30 && !playback.paused;
+    this.toggleAttribute('data-visible', visible);
+    this.setAttribute('tabindex', visible ? '0' : '-1');
+  }
+
+  #handleActivate = () => {
+    this.#time.value?.seek(30);
+  };
+
+  #handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      this.#handleActivate();
+    } else if (event.key === ' ') {
+      // Prevent Space from scrolling the page
+      event.preventDefault();
+    }
+  };
+
+  // ARIA button pattern: Space activates on keyup, not keydown
+  #handleKeyup = (event: KeyboardEvent) => {
+    if (event.key === ' ') {
+      this.#handleActivate();
+    }
+  };
+}
+
+customElements.define('skip-intro-button', SkipIntroButtonElement);
+```
+
+```
+skip-intro-button {
+  position: absolute;
+  bottom: 5rem;
+  right: 1rem;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 200ms;
+}
+
+skip-intro-button[data-visible] {
+  opacity: 1;
+  pointer-events: auto;
+}
+```