@videojs/react 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/guides/captions.md

@@ -0,0 +1,155 @@
+# Show captions and subtitles
+
+Show captions and subtitles, and let users turn them on and pick a language.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Recommended approach
+
+Add WebVTT tracks as `<track>` children of the media element, and give users a [CaptionsButton](../reference/components/captions-button.md) to toggle them.
+
+**App.tsx**
+
+```tsx
+import { CaptionsButton, Container } 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 loop>
+          <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srcLang="en" label="English" default />
+        </Video>
+        <CaptionsButton
+          className="media-captions-button"
+          render={(props, state) => (
+            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
+          )}
+        />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container 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);
+}
+```
+
+## How it works
+
+The [text track feature](../reference/api/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.
+
+`useCaptionsOptions` provides the option list (including “Off”), the selected value, and availability:
+
+```tsx
+import { Menu, useCaptionsOptions } from '@videojs/react';
+
+function CaptionsMenu() {
+  const captions = useCaptionsOptions();
+  if (captions?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger render={<button type="button" />}>Captions</Menu.Trigger>
+      <Menu.Content>
+        <Menu.RadioGroup value={captions.value} onValueChange={captions.setValue} aria-label="Captions">
+          {captions.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+              {option.label}
+            </Menu.RadioItem>
+          ))}
+        </Menu.RadioGroup>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+```
+
+See the [CaptionsRadioGroup](../reference/components/captions-radio-group.md) reference for the complete pattern.
+
+## 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 pages
+
+### Components
+
+- [CaptionsButton](../reference/components/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [CaptionsRadioGroup](../reference/components/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [Menu](../reference/components/menu.md): A composable menu component for settings, option selection, and actions
+
+### API
+
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [useCaptionsOptions](../reference/api/use-captions-options.md): Hook to build captions menu options from the player text track state
+
+### Guides
+
+- [Show timeline thumbnail previews](./thumbnails.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

package/docs/guides/casting.md

@@ -0,0 +1,159 @@
+# Cast to AirPlay and Chromecast
+
+Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
+
+Send playback to an Apple TV over AirPlay or a Chromecast over Google Cast while the browser stays in control.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Recommended approach
+
+Use the [GoogleCast extension](../reference/components/google-cast.md) with a [CastButton](../reference/components/cast-button.md), and add an [AirPlayButton](../reference/components/airplay-button.md) for Safari. The prebuilt skins already include both buttons; add `GoogleCast` next to a streaming media component to enable the configurable Cast route.
+
+**App.tsx**
+
+```tsx
+import { AirPlayButton, CastButton, Container, createPlayer } from '@videojs/react';
+import { GoogleCast } from '@videojs/react/extensions/google-cast';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
+        <GoogleCast />
+        <div className="media-remote-buttons">
+          <AirPlayButton
+            className="media-airplay-button"
+            render={(props, state) => (
+              <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
+            )}
+          />
+          <CastButton
+            className="media-cast-button"
+            render={(props, state) => (
+              <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
+            )}
+          />
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-remote-buttons {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  display: flex;
+  gap: 8px;
+}
+
+.media-airplay-button,
+.media-cast-button {
+  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-airplay-button[data-disabled],
+.media-cast-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
+}
+```
+
+The demo pairs the streaming media component with the `GoogleCast` extension. Without that extension, `CastButton` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
+
+## How it works
+
+The [remote playback feature](../reference/api/feature-remote-playback.md) gives AirPlay and Google Cast one state shape:
+
+- `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
+- `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
+- `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
+
+AirPlay uses WebKit’s presentation APIs. Google Cast uses a sender and receiver: the browser sends the receiver a media URL and then controls playback. Your UI reads the same Video.js state for either route.
+
+While connected, playback actions — play, pause, seek, volume — proxy to the remote device, and player state keeps reflecting the remote session. Local playback is suspended.
+
+The Google Cast SDK loads only when the `GoogleCast` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
+
+## Availability and constraints
+
+- Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
+- Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
+- AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
+- The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
+- Set `disableRemotePlayback` on the media element to opt out entirely.
+
+## Common variations
+
+### Custom Cast receiver
+
+By default, Video.js sends the current source to Google’s Default Media Receiver. Set `receiver` when you have your own receiver application:
+
+```tsx
+<GoogleCast receiver="YOUR_APP_ID" />
+```
+
+Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [GoogleCast reference](../reference/components/google-cast.md) for the exact option types.
+
+### Read connection state
+
+Use `remotePlaybackAvailability` to decide whether to offer a route and `remotePlaybackState` to show whether it is disconnected, connecting, or connected. `CastButton` and `AirPlayButton` already apply these states to their presentation; read them directly only when another part of your app needs them.
+
+## Troubleshooting
+
+### The cast button doesn’t render, or renders disabled
+
+The Cast button hides when the route is unsupported. In Chromium with no Cast device reachable, it stays visible but disabled. The AirPlay button hides unless Safari reports an AirPlay device.
+
+### Casting starts but the device shows an error
+
+The receiver cannot fetch the media. Confirm the source URL is reachable from the device and served with CORS headers, including caption tracks.
+
+### The UI freezes on “connecting”
+
+The user dismissed the picker or the device disconnected. `remotePlaybackState` returns to `'disconnected'`; drive your UI from that state.
+
+## Related pages
+
+### Components
+
+- [CastButton](../reference/components/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
+- [AirPlayButton](../reference/components/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [GoogleCast](../reference/components/google-cast.md): Options for the Google Cast extension that configures the receiver and load request
+
+### API
+
+- [Remote Playback](../reference/api/feature-remote-playback.md): Remote playback state and actions for the player store
+- [HlsJsVideo](../reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property

package/docs/guides/content-security-policy.md

@@ -0,0 +1,36 @@
+# Content Security Policy
+
+Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
+
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+
+## Allow player resources
+
+- `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 required for some player UI.
+
+## Recommended policy
+
+```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:;
+```
+
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls

package/docs/guides/controls.md

@@ -0,0 +1,179 @@
+# Automatically show and hide controls
+
+Show controls while the user is active, hide them during playback, and toggle them by touch.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Recommended approach
+
+Wrap your control UI in [Controls](../reference/components/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
+
+**App.tsx**
+
+```tsx
+import { Container, Controls, createPlayer, PlayButton, Time } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+
+        <Controls.Root>
+          <Controls.Backdrop className="controls-backdrop" />
+          <Controls.Content className="media-controls">
+            <Controls.Group className="controls-group" aria-label="Playback controls">
+              <PlayButton
+                className="button"
+                render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+              />
+
+              <Time.Value type="current" className="time" />
+            </Controls.Group>
+          </Controls.Content>
+        </Controls.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-controls {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  padding: 12px;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  opacity: 1;
+  transition: opacity 0.35s;
+}
+
+.controls-backdrop:not([data-visible]),
+.media-controls:not([data-visible]) {
+  opacity: 0;
+}
+
+.controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  pointer-events: auto;
+}
+
+.time {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button {
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## How it works
+
+The [controls feature](../reference/api/feature-controls.md) tracks activity on the player container:
+
+- `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
+- `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
+- `toggleControls()` flips visibility, for wiring to custom triggers.
+
+On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
+
+The feature needs the player container for activity tracking; without a container it stays inactive and warns in development.
+
+## Availability and constraints
+
+- Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
+- Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
+- Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
+- The idle delay is fixed at two seconds.
+
+## Common variations
+
+### Always-visible controls
+
+Set `visibility="always"` on [Controls](../reference/components/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
+
+```tsx
+<Controls.Root visibility="always">
+  <Controls.Content className="controls">...</Controls.Content>
+</Controls.Root>
+```
+
+### Custom show/hide styling
+
+Controls hide by state, so you own the transition. Style the visible and hidden states in CSS — fade, slide, or scale — driven by the component’s rendered state rather than re-implementing the idle timer.
+
+## Troubleshooting
+
+### Controls never hide
+
+The media is paused (controls intentionally stay visible), a remote playback session is active, an open menu or popover holds a controls lock, or something keeps triggering activity — for example a focused element inside the container receiving repeated events.
+
+### Controls don’t come back on touch
+
+A tap on the media toggles controls. If a custom overlay covers the media and swallows pointer events, taps never reach the container; let pointer events pass through decorative overlays.
+
+### Controls flicker on Android while tapping
+
+Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
+
+## Related pages
+
+### Components
+
+- [Controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [Container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+### API
+
+- [Controls](../reference/api/feature-controls.md): User activity and controls visibility state for the player store
+
+### Guides
+
+- [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player