@videojs/react 10.0.0-beta.30 → 10.0.0-beta.32

package/docs/how-to/add-quality-selector.md

@@ -0,0 +1,249 @@
+# Add a quality selector
+
+Read available renditions, let the engine adapt automatically, and offer manual quality selection.
+
+Read the renditions a stream offers, let the streaming engine adapt quality automatically, and give users manual control when they want it.
+
+Quality selection applies to streaming sources. A progressive MP4 plays at one fixed quality and exposes no renditions; HLS and DASH streams offer several. See [Media sources](../concepts/media-sources.md).
+
+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
+
+Let automatic quality selection do its job by default, and offer a quality menu for users who want to pin a rendition. Render the menu only when quality selection is available.
+
+Quality
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, Menu, QualityRadioGroup } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
+
+function QualityMenu(): ReactNode {
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Quality
+      </Menu.Trigger>
+      <Menu.Popup className="menu">
+        <Menu.Content>
+          <QualityRadioGroup
+            className="menu-group"
+            renderItem={(props, item) => (
+              <Menu.RadioItem {...props} className="menu-item">
+                <span>
+                  {item.label}
+                  {item.tier ? <sup className="menu-tier">{item.tier}</sup> : null}
+                </span>
+                {item.badge ? <span className="menu-badge">{item.badge}</span> : null}
+                <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
+                  ✓
+                </Menu.ItemIndicator>
+              </Menu.RadioItem>
+            )}
+          />
+        </Menu.Content>
+      </Menu.Popup>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
+        <div className="menu-bar">
+          <QualityMenu />
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  display: grid;
+  gap: 2px;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-tier {
+  margin-left: 2px;
+  font-size: 10px;
+}
+
+.menu-badge {
+  margin-left: auto;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```
+
+## How it works
+
+The [quality feature](../reference/feature-quality.md) mirrors the media element’s video renditions into player state:
+
+*   `videoRenditionList` holds each rendition’s `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and whether it’s `selected`.
+*   `activeVideoRendition` is the rendition currently playing. When the engine doesn’t report one directly, the player matches it from the video’s current dimensions.
+*   `selectVideoRendition(value)` pins one rendition; pass `'auto'` to return control to the engine’s adaptive selection.
+
+[`useQualityOptions`](../reference/use-quality-options.md) turns this state into ready-made menu options — labels like “1080p”, an “Auto” entry, and `availability` — as shown in the demo above.
+
+Selecting “Auto” keeps adaptive bitrate switching active: the engine picks the best rendition for current bandwidth and viewport. Pinning a rendition disables adaptation until the user selects “Auto” again.
+
+## Availability and constraints
+
+*   Quality availability is `'unavailable'` for media that doesn’t offer a choice — progressive files, streams before the manifest loads, and single-rendition streams. Render quality UI conditionally; the demo’s availability check does this.
+*   Renditions come from the streaming engine, so the list depends on what the manifest declares. A single-rendition stream offers no meaningful selection, so availability stays `'unavailable'`.
+*   Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
+*   Rendition lists change on source change; selection resets with them.
+
+## Common variations
+
+### Auto quality only
+
+If you don’t want to expose manual selection, do nothing: adaptive selection is on by default and needs no UI.
+
+### Cap or pin quality programmatically
+
+tsx
+
+```
+import { Container } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { usePlayer, VideoPlayer } from '@videojs/react/video';
+
+function PinLowestRendition() {
+  const store = usePlayer();
+  const renditions = usePlayer((s) => s.videoRenditionList);
+
+  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];
+
+  return (
+    <button type="button" onClick={() => lowest?.id && store.selectVideoRendition(lowest.id)}>
+      Data saver
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" muted playsInline />
+        <PinLowestRendition />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## Troubleshooting
+
+### The quality menu doesn’t render
+
+Quality availability is `'unavailable'`. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media element doesn’t support renditions. Use a streaming media element such as [HlsJsVideo](../reference/hlsjs-video.md).
+
+### The menu doesn’t render for a single-rendition stream
+
+The manifest declares a single rendition, so quality availability stays `'unavailable'` — one entry offers no choice. Encode the stream as a multi-rendition ladder to give the engine and users something to choose between.
+
+### Playback buffers after selecting a quality
+
+The pinned rendition exceeds available bandwidth. Selecting “Auto” lets the engine step down again.
+
+## Related components
+
+*   [Quality radio group](../reference/quality-radio-group.md)
+*   [Menu](../reference/menu.md)
+
+## Related API
+
+*   [Quality feature](../reference/feature-quality.md)
+*   [useQualityOptions](../reference/use-quality-options.md)
+*   [HlsJsVideo](../reference/hlsjs-video.md)
+*   [DashVideo](../reference/dash-video.md)
+
+## Related guides
+
+*   [Media sources](../concepts/media-sources.md)

package/docs/how-to/autoplay.md

@@ -0,0 +1,172 @@
+# Autoplay
+
+Start playback automatically and handle browser autoplay restrictions.
+
+Start playback automatically when the media is ready.
+
+For the best chance of autoplay succeeding, start playback muted and enable inline playback. Autoplay is a request, not a guarantee: browsers can block it based on audio state, prior interaction with your site, browser settings, and platform policy.
+
+## Recommended approach
+
+Set autoplay, muted, and inline playback on the media element, and keep a manual play control available for when autoplay is blocked.
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { Container, PlayButton } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function BasicUsage() {
+  return (
+    <VideoPlayer>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.media-play-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);
+}
+```
+
+## How it works
+
+The `autoPlay`, `muted`, and `playsInline` props on [`Video`](../reference/create-player.md) and similar media components pass through to the underlying media element. When the media element supports them, they’re applied, and playback is requested as soon as the media has enough data.
+
+The [playback feature](../reference/feature-playback.md) reflects the result in player state. When autoplay succeeds, `paused` becomes `false` and `started` becomes `true`. When the browser blocks autoplay, the player stays `paused: true` with `started: false`, and the [Play button](../reference/play-button.md) renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.
+
+Calling `play()` from player state returns the native promise from the media element. When the browser blocks playback, that promise rejects with a `NotAllowedError`.
+
+## Availability and constraints
+
+*   Autoplay can fail. Browsers decide per page load based on audio state, whether the user has interacted with your site before, browser settings, and platform policy.
+*   Muted autoplay is broadly allowed. Unmuted autoplay is blocked on first visit in most browsers; do not rely on it.
+*   Without inline playback, iPhone Safari opens the video in fullscreen when playback starts.
+*   Low-power mode and data-saver settings can block even muted autoplay. This is why the recommended approach keeps a manual play control.
+*   Programmatic volume control is unsupported on some platforms. The [volume feature](../reference/feature-volume.md) exposes this as `volumeAvailability: 'available' | 'unavailable' | 'unsupported'`; iOS Safari reports `'unsupported'`, and `'unavailable'` means the feature hasn’t attached to a media element yet.
+*   This guide applies to media components that render a video element (Video, HlsJsVideo, DashVideo, MuxVideo, and the like). Embed components (YouTube, Vimeo, TikTok, Twitch) forward autoplay to the third-party player, which applies its own autoplay rules; muted and inline behavior varies by provider.
+
+## Common variations
+
+### Background video
+
+Background video autoplays, loops, stays muted, and omits interactive controls. Use `HlsBackgroundVideo` instead of configuring these behaviors yourself: it applies them by default and streams an HLS source, picking one rendition that fits the screen for the whole session.
+
+tsx
+
+```
+import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';
+
+export default function Hero() {
+  return <HlsBackgroundVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />;
+}
+```
+
+If you have a progressive MP4 or WebM file instead of an HLS stream, `BackgroundVideo` is the same component without the streaming engine. See [BackgroundVideo](../reference/background-video.md) for opt-out attributes and sizing.
+
+### Autoplay with sound
+
+Do not rely on unmuted autoplay for a user’s first visit. Start playback from an explicit user action instead.
+
+Call `play()` from the player store returned by [`usePlayer`](../reference/use-player.md):
+
+tsx
+
+```
+import { Container } from '@videojs/react';
+import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
+
+function StartPlaybackButton() {
+  const store = usePlayer();
+
+  return (
+    <button type="button" onClick={() => store.play()}>
+      Play video
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
+        <StartPlaybackButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+Because playback starts from a user gesture, the browser allows it unmuted.
+
+## Troubleshooting
+
+### Playback does not start
+
+Confirm that:
+
+*   The media is muted.
+*   Inline playback is enabled.
+*   The source loads (check the network panel).
+*   A manual play control is available as a fallback.
+
+If autoplay is blocked, the player stays paused and the Play button remains in its play state; there is no error state to handle.
+
+### The video opens fullscreen on iPhone
+
+Enable inline playback with the `playsInline` prop on the media component.
+
+### The video starts without sound
+
+Expected with muted autoplay. Let the user unmute through a [Mute button](../reference/mute-button.md) or [Volume slider](../reference/volume-slider.md) rather than unmuting programmatically; programmatic volume changes are unsupported on some platforms.
+
+## Related components
+
+*   [Play button](../reference/play-button.md)
+*   [Mute button](../reference/mute-button.md)
+*   [BackgroundVideo](../reference/background-video.md)
+*   [Controls](../reference/controls.md)
+
+## Related API
+
+*   [Playback feature](../reference/feature-playback.md)
+*   [Volume feature](../reference/feature-volume.md)
+*   [usePlayer](../reference/use-player.md)
+
+## Related guides
+
+*   [Features](../concepts/features.md)
+*   [Browser support](../concepts/browser-support.md)

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

@@ -16,7 +16,7 @@ Every doc page is available as markdown, so you can provide your model with focu
     
 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)
+    ![Fetching a doc URL returns 188.7KB of HTML; fetching the same URL with the Accept: text/markdown header 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/react/reference/play-button.md`](../reference/play-button.md).
     
@@ -31,7 +31,7 @@ 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.
+*   **Cursor**: reference the `llms.txt` URL in a project [rule](https://cursor.com/docs/rules) so Cursor knows where to find Video.js docs.
 *   **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

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

@@ -73,7 +73,7 @@ store.seek(30);
 
 ## Place your component in the player
 
-Your component needs to be inside [`<Player>`](../reference/player-provider.md) to access state. Place it inside [`<Container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity:
+Your component needs to be inside [`<Player>`](../reference/player.md) to access state. Place it inside [`<Container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity:
 
 tsx
 
@@ -103,9 +103,10 @@ SkipIntroButton.tsx
 SkipIntroButton.css
 
 ```
-import { usePlayer } from '@videojs/react';
+// The preset's usePlayer is typed for its feature bundle
+import { usePlayer } from '@videojs/react/video';
 
-function SkipIntroButton() {
+export function SkipIntroButton() {
   const store = usePlayer();
   const currentTime = usePlayer((s) => s.currentTime);
   const paused = usePlayer((s) => s.paused);
@@ -141,4 +142,130 @@ function SkipIntroButton() {
   opacity: 1;
   pointer-events: auto;
 }
-```
+```
+
+Your component needs to be inside a player, such as [`<VideoPlayer>`](../reference/player.md), to access state. Place it inside [`<Container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity:
+
+tsx
+
+```
+import { Container } from '@videojs/react';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/skin.css';
+
+import { SkipIntroButton } from './SkipIntroButton';
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <VideoSkin>
+          <Video src="video.mp4" />
+        </VideoSkin>
+        <SkipIntroButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+Custom components read player state and dispatch actions through [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.
+
+Access state and actions with the [`usePlayer`](../reference/use-player.md) hook from your player’s preset. It knows which features that preset has, so state and actions are typed. (The standalone `usePlayer` export from `@videojs/react` returns an untyped store, so its values are `unknown` in TypeScript.) If you built the player with a custom feature set through [`createPlayer`](../reference/create-player.md) — the escape hatch for custom feature sets — use the `usePlayer` it returns instead.
+
+tsx
+
+```
+import { usePlayer } from '@videojs/react/video';
+
+// Subscribe to state — re-renders only when selected values change
+const paused = usePlayer((s) => s.paused);
+const currentTime = usePlayer((s) => s.currentTime);
+
+// Get the store for dispatching actions (does not subscribe)
+const store = usePlayer();
+
+await store.play();
+store.setVolume(0.5);
+store.seek(30);
+```
+
+Custom controls also need real button semantics — the examples above set the accessible name, keyboard focus, and (in HTML, where there is no native `<button>`) the ARIA button pattern by hand.
+
+[Learn more about accessibility in video players](../concepts/accessibility.md)
+
+## Availability and constraints
+
+*   Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
+*   Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
+
+## Common variations
+
+Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+### Change what a built-in control renders
+
+Use the `render` prop on any built-in component. See [UI components](../concepts/ui-components.md).
+
+### 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).
+
+## Troubleshooting
+
+### State and actions are typed as `unknown`
+
+You’re using the standalone `usePlayer` export or the shared `playerContext`, which don’t know which features your player has. In React, import `usePlayer` from your player’s preset (for example `@videojs/react/video`), or use the hook returned by `createPlayer` if you built the player with a custom feature set. In HTML, use the typed `context` returned by `createPlayer`.
+
+### The component renders but never updates
+
+In React, the component sits outside the player (such as `<VideoPlayer>`), so `usePlayer` has no store to subscribe to. In HTML, the element sits outside `<video-player>`, or the class doesn’t extend `MediaElement`, so `PlayerController` has nothing to schedule updates on.
+
+## Related API
+
+*   [usePlayer](../reference/use-player.md)
+*   [PlayerController](/docs/framework/html/reference/player-controller)
+*   [createPlayer](../reference/create-player.md)
+*   [Player container](../reference/player-container.md)
+
+## Related guides
+
+*   [Customize skins](./customize-skins.md)