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

package/docs/how-to/migrate-from-video-js-8.md

@@ -2,9 +2,9 @@
 
 Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
 
-Same name, different shape. Video.js 8 gives you one function, `videojs()`, and one big options object. You enhance a `<video>` element, pass configuration, and get back a player with a control bar, a plugin system, and a component tree you can reach into.
+Video.js 8 gives you one function, `videojs()`, and one large options object. It enhances a `<video>` element and returns a player with a control bar, plugin system, and component tree.
 
-Video.js v10 is a rebuild rather than a release. There’s no `videojs()` call, no options object, and no plugin registry. You compose a player out of a few named pieces instead, and the result is smaller, easier to restyle, and a lot easier to use from React.
+Video.js v10 is a rebuild, not a drop-in version bump. There is no `videojs()` call, options object, or plugin registry. You compose a player from a few named pieces instead.
 
 Caution
 
@@ -91,8 +91,8 @@ import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
 
 export function MyPlayer() {
   return (
-    <VideoPlayer>
-      <VideoSkin className="aspect-video" poster="/poster.jpg">
+    <VideoPlayer poster="/poster.jpg">
+      <VideoSkin className="aspect-video">
         <Video src="/video.mp4" preload="auto" playsInline>
           <track kind="captions" src="/captions/en.vtt" srclang="en" label="English" default />
           <track kind="metadata" src="/storyboard.vtt" label="thumbnails" default />
@@ -109,7 +109,7 @@ Three differences worth understanding, because each one is a pattern you’ll se
 
 *   **No `videojs()` call and no effect.** `VideoPlayer` owns the lifecycle.
 *   **No `controls` prop.** The skin *is* the controls. Rendering a skin is how you ask for them, which is also how you opt out.
-*   **The poster is a skin prop, not a media attribute.** That’s what lets the skin control how it appears, rather than the browser.
+*   **The poster is player metadata, not a media attribute.** Pass it to `VideoPlayer`, and the skin controls how it appears.
 
 The `'use client'` directive is there because the player owns browser state. There’s also a minimal skin, closer to v8’s control bar, if the default’s frosted look is too much of a change.
 
@@ -118,7 +118,7 @@ The `'use client'` directive is there because the player owns browser state. The
 The v8 options object is gone, and its contents scattered in four directions. This is the biggest conceptual step, so it’s worth understanding the four buckets before you go looking for a specific option.
 
 1.  **Media attributes.** Anything the browser itself understands stays exactly where it was, on your media element.
-2.  **Skin attributes.** The poster belongs to the skin, because the skin is what paints it.
+2.  **Player metadata.** The title and poster belong to player state, which lets the skin or your custom UI render them.
 3.  **Your CSS.** Sizing, aspect ratio, and responsive behavior are layout, and layout is yours.
 4.  **Composition.** Which controls exist, which shortcuts fire, which language you’re in. You express these by choosing components rather than by setting flags.
 
@@ -142,7 +142,7 @@ the same attributes on your media
 
 `disablepictureinpicture`
 
-### Skin attributes
+### Player metadata
 
 Video.js 8
 
@@ -150,27 +150,29 @@ Video.js v10
 
 `poster`
 
-the skin’s poster
+`poster` on `<video-player>` or `VideoPlayer`
 
 `posterImage: false`
 
-leave the poster unset
+leave the player’s poster unset
 
 the title in `TitleBar`
 
-`content-title` on the player, with no built-in UI yet
+`content-title` on `<video-player>` or `title` on `VideoPlayer`, rendered with the Title component
 
-The poster belongs to the skin rather than the media, which is what lets the skin control how it appears:
+The poster belongs to player state rather than the media, which lets the skin control how it appears:
 
 jsx
 
 ```
-<VideoSkin poster="/poster.jpg">
-  <Video src="/video.mp4" />
-</VideoSkin>
+<VideoPlayer poster="/poster.jpg">
+  <VideoSkin>
+    <Video src="/video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
 ```
 
-`content-title` is the closest thing to v8’s `TitleBar`, and it does reach player state, so your own UI can read it. No packaged skin draws it, so v8’s `TitleBar` has no visual equivalent ([#1123](https://github.com/videojs/v10/issues/1123)). See the [Poster](../reference/poster.md) reference for the poster component itself.
+The packaged skins do not place the title in their default layouts. Add the [Title](../reference/title.md) component as a child of the skin, or place it in an ejected or custom layout. See the [Poster](../reference/poster.md) reference for poster rendering options.
 
 ### Your CSS
 
@@ -260,6 +262,10 @@ not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728))
 
 the skins include an error dialog
 
+`ModalDialog`
+
+compose a [Dialog](../reference/dialog.md); your application controls media playback when it opens and closes
+
 ## Techs become media components
 
 v8’s tech system was one of its harder ideas: an abstraction layer with a registry, a resolution order, and source handlers on top. Getting HLS meant getting VHS, which meant reasoning about `overrideNative` and hoping the right thing won.
@@ -342,7 +348,7 @@ In v8, customizing meant three different techniques depending on what you wanted
 
 The default skin is a modern, frosted look. The minimal skin is closer to v8’s control bar. Both bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Skins](../concepts/skins.md).
 
-Both also include AirPlay and [Cast](../concepts/cast.md) buttons, which v8 had no answer for. Remote playback is a feature you compose in rather than a plugin you install.
+Both also include AirPlay and Cast buttons, which v8 had no answer for. Follow [Cast to AirPlay and Chromecast](./cast-to-airplay-and-chromecast.md) to add the Google Cast integration. Remote playback is a feature you compose in rather than a plugin you install.
 
 ### Level 2: restyle it
 
@@ -385,16 +391,18 @@ export function MyPlayer() {
         <Video src="/video.mp4" playsInline />
 
         <Controls.Root>
-          <PlayButton />
-          <MuteButton />
-          <TimeSlider.Root>
-            <TimeSlider.Track>
-              <TimeSlider.Fill />
-              <TimeSlider.Buffer />
-            </TimeSlider.Track>
-            <TimeSlider.Thumb />
-          </TimeSlider.Root>
-          {/* No PiPButton, so no picture-in-picture control renders. */}
+          <Controls.Content>
+            <PlayButton />
+            <MuteButton />
+            <TimeSlider.Root>
+              <TimeSlider.Track>
+                <TimeSlider.Fill />
+                <TimeSlider.Buffer />
+              </TimeSlider.Track>
+              <TimeSlider.Thumb />
+            </TimeSlider.Root>
+            {/* No PiPButton, so no picture-in-picture control renders. */}
+          </Controls.Content>
         </Controls.Root>
 
         <Hotkey keys="Space" action="togglePaused" />
@@ -446,7 +454,7 @@ One category doesn’t survive that translation, because those were never media
 
 ### Player state
 
-There are **no `on*` props**. Read state through the preset’s [`usePlayer`](../reference/use-player.md) hook, typed to that preset’s features:
+Put standard media event props such as `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` on `Video` or your chosen media component. Read player state through the preset’s [`usePlayer`](../reference/use-player.md) hook, typed to that preset’s features:
 
 tsx
 
@@ -515,7 +523,7 @@ remove the element, or unmount the component
 
 `player.tech()`
 
-`.host.engine` on engine-backed media, where one exists
+the media component’s public `engine` escape hatch, where one exists; in React, reach it through `useMedia()`
 
 `videojs.getPlayer(id)`
 
@@ -525,7 +533,7 @@ Swapping sources is the change most likely to surprise you. There’s no `player
 
 ## Languages
 
-v8 shipped one language and asked you to register more with `videojs.addLanguage`. v10 ships locale packs for around 50 languages, so most apps need no setup at all. See [Internationalization](../concepts/i18n.md).
+v8 shipped one language and asked you to register more with `videojs.addLanguage`. v10 ships locale packs for around 50 languages, so most apps need no setup at all. See [Internationalize the player](./internationalize-the-player.md).
 
 To override individual strings, use [`I18nProvider`](../reference/i18n-provider.md) when you want them scoped to a subtree:
 
@@ -539,7 +547,7 @@ import { I18nProvider } from '@videojs/react/i18n';
 </I18nProvider>
 ```
 
-See [Override translations](./i18n-override-translations.md).
+See [Internationalize the player](./internationalize-the-player.md) for scoped overrides, custom locales, and runtime switching.
 
 ## Live and audio-only
 
@@ -548,6 +556,7 @@ v8 turned live UI on with a `liveui` flag, and audio-only on with `audioOnlyMode
 tsx
 
 ```
+import '@videojs/react/live-video/skin.css';
 import { HlsVideo } from '@videojs/react/media/hls-video';
 import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
 
@@ -560,9 +569,9 @@ import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
 
 For audio, use the audio preset, or the live audio one. There’s also a background video preset for muted, chrome-free background video, which v8 had no answer for.
 
-You get `streamType`, `targetLiveWindow`, and `liveEdgeStart` in state, plus a live button that jumps to the live edge. v8’s `liveTracker` tuning has no equivalent ([#1730](https://github.com/videojs/v10/issues/1730)).
+You get `targetLiveWindow` and `liveEdgeStart` in state, plus a live button that jumps to the live edge. The live preset does not include `streamType`; add the stream type feature to a custom player when you need it. v8’s `liveTracker` tuning has no equivalent ([#1730](https://github.com/videojs/v10/issues/1730)).
 
-The live composition is deliberately narrower than the video one. It leaves out playback rate, quality, and audio-track state, so those controls don’t appear in a live skin’s settings menu. If you need one of them on a live player, build your own player from a feature list rather than taking the preset’s.
+The live composition is deliberately narrower than the video one. It leaves out playback rate, quality, and audio-track state, so those controls don’t appear in a live skin’s settings menu. If you need an omitted feature on a live player, build your own player from a feature list rather than taking the preset’s.
 
 That’s what [`createPlayer`](../reference/create-player.md) is for. Hand it a feature list and you get back a `Player` component and a `usePlayer` hook, the same pair every preset is built from.
 
@@ -573,13 +582,12 @@ Ordered roughly by how likely each is to block a v8 migration.
 *   **No ads support.** v8’s IMA and ad-plugin ecosystem has no v10 equivalent. This is the most common hard blocker.
 *   **No playlist support.** No `videojs-playlist` equivalent.
 *   **No plugin system**, by design. Budget for rebuilding UI plugins as components. See [Plugins](#plugins).
-*   No skin draws `content-title`, so v8’s `TitleBar` has no visual equivalent ([#1123](https://github.com/videojs/v10/issues/1123)).
 *   Playback rates are a fixed set — `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` — so v8’s `playbackRates` has no equivalent yet ([#1404](https://github.com/videojs/v10/issues/1404)).
 *   No text-track settings dialog. v8’s `textTrackSettings` let viewers restyle captions; v10 exposes only the positioning custom properties its skins define.
 *   No spatial navigation. v8’s `spatialNavigation` for TV and D-pad remotes has no equivalent.
 *   Nothing persists between sessions: volume, captions language, speed, quality. That’s out of scope for GA ([#944](https://github.com/videojs/v10/issues/944)). Default subtitle language is tracked at [#1423](https://github.com/videojs/v10/issues/1423).
 *   No VHS-equivalent tuning surface. Engine settings belong to the engine you chose, and the default HLS component deliberately exposes few of them.
-*   Chapters render in the time slider from a `<track kind="chapters">`, but there’s no chapter menu to navigate from and no active-chapter state, so v8’s chapters menu has no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). Cue points aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
+*   Chapters render in the time slider from a `<track kind="chapters">`, and its segments reflect `data-active`. There is no player-level active chapter value or chapter menu, so v8’s chapters menu has no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). Cue points aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
 *   The controls auto-hide delay isn’t configurable, so v8’s `inactivityTimeout` has no equivalent ([#1728](https://github.com/videojs/v10/issues/1728)).
 *   No full-window fullscreen fallback. v8 had one for browsers without the Fullscreen API; [support is around 96%](https://caniuse.com/fullscreen) now.
 *   Multiple `<source>` elements with `size` metadata don’t become a quality menu. Use HLS or DASH for adaptive quality; picking renditions by resolution won’t be added ([#1415](https://github.com/videojs/v10/issues/1415)).

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

@@ -0,0 +1,135 @@
+# 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).
+
+## 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 `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 duration and current-time displays.
+
+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, keep a [TimeSlider](../reference/time-slider.md) in the UI. 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

@@ -0,0 +1,180 @@
+# 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)