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

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

@@ -1,147 +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/react @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.
-
-tsx
-
-```
-import { Container, LiveButton } from '@videojs/react';
-import { LiveVideoPlayer } from '@videojs/react/live-video';
-import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
-
-export default function App() {
-  return (
-    <LiveVideoPlayer>
-      <Container>
-        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
-        <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />
-      </Container>
-    </LiveVideoPlayer>
-  );
-}
-```
-
-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:
-
-tsx
-
-```
-import { createPlayer, streamTypeFeature } from '@videojs/react';
-import { liveVideoFeatures } from '@videojs/react/live-video';
-
-const { Player } = 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.
-
-## 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:
-
-The preset `LiveVideoPlayer` comes with a fixed feature set. To change it, build the player yourself with [`createPlayer`](../reference/create-player.md) — the escape hatch for custom feature sets:
-
-tsx
-
-```
-import { Container, createPlayer, LiveButton, streamTypeFeature } from '@videojs/react';
-import { liveVideoFeatures } from '@videojs/react/live-video';
-import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
-
-const { Player, usePlayer } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
-
-function LiveBadge() {
-  const streamType = usePlayer((s) => s.streamType);
-  if (streamType !== 'live') return null;
-
-  return <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />;
-}
-
-export default function App() {
-  return (
-    <Player>
-      <Container>
-        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
-        <LiveBadge />
-      </Container>
-    </Player>
-  );
-}
-```
-
-## 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/remember-user-preferences.md

@@ -1,180 +0,0 @@
-# Remember user preferences
-
-Persist volume, caption, and quality preferences across sessions by subscribing to player state.
-
-Persist player preferences — volume, muted, captions, quality — so returning users get the setup they left with.
-
-The player doesn’t persist preferences itself today. Player state gives you everything needed to wire persistence to the storage you choose — local storage, your backend, or per-profile settings.
-
-## Recommended approach
-
-Subscribe to the state you want to remember, write it to storage when it changes, and restore it once the store attaches to the media.
-
-tsx
-
-```
-import { useEffect, useRef, useState } from 'react';
-import { Container } from '@videojs/react';
-import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
-
-const STORAGE_KEY = 'player:volume';
-
-// Local storage can be unavailable (private modes), so guard reads and writes.
-function readSaved() {
-  try {
-    return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
-  } catch {
-    return null;
-  }
-}
-
-function save(prefs: { volume: number; muted: boolean }) {
-  try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
-  } catch {
-    // Storage unavailable; skip persistence.
-  }
-}
-
-function VolumePersistence() {
-  const store = usePlayer();
-  const { volume, muted } = usePlayer((s) => ({ volume: s.volume, muted: s.muted }));
-  // Read the saved value once, before the save effect below can write.
-  const [saved] = useState(readSaved);
-  const restored = useRef(false);
-
-  // Save on change, once the restore has run.
-  useEffect(() => {
-    if (!restored.current) return;
-    save({ volume, muted });
-  }, [volume, muted]);
-
-  // Restore once the store attaches to the media; actions throw before that.
-  useEffect(() => {
-    const restore = () => {
-      if (!store.target) return false;
-      if (saved) {
-        store.setVolume(saved.volume);
-        // setVolume above zero unmutes, so mute again if that's the saved preference.
-        // At volume zero the player already counts as muted, and toggling would unmute.
-        if (saved.muted && saved.volume > 0) store.toggleMuted();
-      }
-      restored.current = true;
-      return true;
-    };
-    if (restore()) return;
-    const unsubscribe = store.subscribe(() => {
-      if (restore()) unsubscribe();
-    });
-    return unsubscribe;
-  }, [store, saved]);
-
-  return null;
-}
-
-export default function App() {
-  return (
-    <VideoPlayer>
-      <Container>
-        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
-        <VolumePersistence />
-      </Container>
-    </VideoPlayer>
-  );
-}
-```
-
-## How it works
-
-*   Player state is the single source of truth: it already reflects every change, whatever caused it — your UI, keyboard shortcuts, native controls, or scripts.
-*   `store.subscribe(callback)` fires on any state change. Notifications are batched per microtask, so rapid changes (a volume drag) produce one callback per tick, which keeps storage writes cheap. There is no per-key subscription on the store: read the state and diff the slice you care about.
-*   In React, `usePlayer(selector)` re-renders only when the selected value changes; pairing it with an effect is the idiomatic save path.
-*   Feature selectors exported by `@videojs/html` and `@videojs/react` (`selectVolume`, `selectTextTrack`, `selectQuality`, and the rest) read a feature’s slice from any store, returning `undefined` when the feature isn’t present.
-*   Restore through the feature actions (`setVolume`, `toggleMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
-*   Actions need an attached media target: calling one before the store attaches throws. Check `store.target` and defer the restore until it is set, as the examples do.
-
-## Availability and constraints
-
-*   Nothing persists by default: volume resets to the media element’s value, captions to the track markup, quality to automatic, on every load.
-*   `setVolume` clamps to 0–1 and unmutes when setting a value above zero; restore volume first, then toggle `muted` back on when the saved preference is muted, as the examples do. Skip the toggle when the saved volume is zero: the player treats volume zero as muted, so toggling would unmute and raise the volume. Don’t compare against store state right after calling an action: notifications batch per microtask, so that state is still stale.
-*   Restore track and quality selections after the media exposes them: track and rendition lists arrive when the media loads, not at player creation. Subscribe and apply when the saved entry appears in the list.
-*   Programmatic volume control is unavailable on some platforms (after attach, iOS Safari reports `volumeAvailability: 'unsupported'`); volume persistence quietly does nothing there.
-*   Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
-
-## Common variations
-
-### Persist caption preference
-
-Save the showing track’s `language` (not its generated id, which can change between sources), or `'off'` when the user turns captions off. Restoring is two phases: while the media loads, assert the saved preference whenever the track modes drift from it, because browsers can auto-enable a track of their own during loading. Once the media can play (`canPlay`), treat every change as the user’s choice and save it. A restore that re-runs forever would keep overriding the user; one that runs only once can get overridden by the browser.
-
-tsx
-
-```
-function CaptionsPersistence() {
-  const store = usePlayer();
-  const { tracks, canPlay } = usePlayer((s) => ({ tracks: s.textTrackList, canPlay: s.canPlay }));
-  const [saved] = useState(() => localStorage.getItem('player:captions'));
-  const restored = useRef(false);
-
-  useEffect(() => {
-    const subtitles = tracks.filter((t) => t.kind === 'captions' || t.kind === 'subtitles');
-    if (!subtitles.length) return;
-
-    // Restore phase: assert the saved preference until the media can play.
-    if (!restored.current) {
-      const desired = saved === 'off' ? undefined : subtitles.find((t) => t.language === saved);
-      if (saved && (desired || saved === 'off')) {
-        const applied = subtitles.every((t) => (t.mode === 'showing') === (t.id === desired?.id));
-        if (!applied) {
-          store.selectSubtitlesTrack(desired?.id ?? 'off');
-          return;
-        }
-      }
-      if (!canPlay) return;
-      restored.current = true;
-    }
-
-    // Save phase: the showing track's language, or 'off'.
-    const showing = subtitles.find((t) => t.mode === 'showing');
-    localStorage.setItem('player:captions', showing ? showing.language : 'off');
-  }, [store, tracks, canPlay, saved]);
-
-  return null;
-}
-```
-
-### Persist to your backend
-
-Swap `localStorage` for an API call; the subscription pattern is identical. Debounce writes beyond the built-in microtask batching if your storage is remote.
-
-## Troubleshooting
-
-### The saved volume doesn’t apply
-
-Restore runs before the store attaches, or the platform doesn’t allow programmatic volume (check `volumeAvailability`). Apply after `store.target` is set, as in the examples.
-
-### The saved caption track doesn’t select
-
-The track list wasn’t loaded yet when you restored, or you saved a generated track id instead of a stable property like `language`. React to `textTrackList` changes and match on language.
-
-### Storage writes fire constantly while dragging the volume slider
-
-Notifications batch per microtask, but a drag still produces many ticks. Debounce the write if the churn matters for your storage target.
-
-## Related components
-
-*   [Volume slider](../reference/volume-slider.md)
-*   [Captions radio group](../reference/captions-radio-group.md)
-*   [Quality radio group](../reference/quality-radio-group.md)
-
-## Related API
-
-*   [usePlayer](../reference/use-player.md)
-*   [useStore](../reference/use-store.md)
-*   [Volume feature](../reference/feature-volume.md)
-*   [Text track feature](../reference/feature-text-tracks.md)
-
-## Related guides
-
-*   [Show captions and subtitles](./show-captions-and-subtitles.md)
-*   [Add a quality selector](./add-quality-selector.md)

package/docs/how-to/show-and-hide-controls.md

@@ -1,174 +0,0 @@
-# Automatically show and hide controls
-
-Show controls while the user is active, hide them during playback, and toggle them by touch.
-
-Show controls while the user is active, fade them out during undisturbed playback, and bring them back on interaction.
-
-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
-
-Wrap your control UI in [Controls](../reference/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
-
-Play0:00
-
-App.tsx
-
-App.css
-
-```
-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>
-  );
-}
-```
-```
-.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/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
-
-Skip the visibility wiring: render your controls without consuming `controlsVisible`. State still tracks activity for anything else that needs it.
-
-### 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](./add-keyboard-shortcuts-and-gestures.md).
-
-## Related components
-
-*   [Controls](../reference/controls.md)
-*   [Player container](../reference/player-container.md)
-
-## Related API
-
-*   [Controls feature](../reference/feature-controls.md)
-
-## Related guides
-
-*   [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md)
-*   [Accessibility](../concepts/accessibility.md)

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

@@ -1,156 +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.
-
-App.tsx
-
-App.css
-
-```
-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>
-  );
-}
-```
-```
-.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/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/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 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](../reference/use-captions-options.md)
-
-## Related guides
-
-*   [Show timeline thumbnail previews](./show-timeline-thumbnail-previews.md)
-*   [Media sources](../concepts/media-sources.md)
-*   [Accessibility](../concepts/accessibility.md)