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

package/docs/reference/feature-live.md

@@ -2,11 +2,18 @@
 
 Live edge state for the player store
 
-Exposes live-edge state so components can render a “jump to live” button, detect DVR vs. standard live, or hide live-only UI for on-demand sources.
+Tracks when playback is at the live edge and what kind of live window the stream provides.
 
-`liveEdgeStart` is the presentation time at which the Live Edge Window begins — playback is “at the live edge” when `currentTime >= liveEdgeStart`. `targetLiveWindow` reports the seekable range size: `0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown. Both values are `NaN` when the media doesn’t expose live-edge state (anything other than an HLS source today).
+*   `liveEdgeStart` is the playback time where the live edge begins. Playback counts as live when `currentTime` reaches this value.
+*   `targetLiveWindow` describes the kind of live window. Despite its name, it does not report a number of seconds: `0` means a sliding live window, `Infinity` means a live event with playback history, and `NaN` means on-demand or not known yet.
 
-The live feature is included by the `liveVideoFeatures` and `liveAudioFeatures` presets; apps that build a custom preset can compose it in directly.
+Both values are `NaN` when the media does not provide live-edge information.
+
+Use the [buffer feature](./feature-buffer.md) to find the times a viewer can seek to. Its `seekable` value contains `[start, end]` pairs. On a sliding live stream, the oldest and newest available times both move forward.
+
+The `liveVideoFeatures` and `liveAudioFeatures` presets include this feature. They do not include the [stream type feature](./feature-stream-type.md), so `selectStreamType` returns `undefined` unless you add it to a custom player.
+
+The [time feature](./feature-time.md) reports the end of the available live video as `duration`, even when the browser reports `Infinity`. To check for live playback, use `!Number.isNaN(targetLiveWindow)` instead of checking `duration`.
 
 ## API Reference
 
@@ -26,9 +33,9 @@ Details
 
 Description
 
-Presentation time marking the start of the Live Edge Window.
+Playback time where the live edge begins.
 
-Playing at the live edge when `currentTime >= liveEdgeStart`. `NaN` when the stream isn't live or the value is unknown.
+Playback is live when `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown.
 
 `targetLiveWindow`
 
@@ -38,9 +45,9 @@ Playing at the live edge when `currentTime >= liveEdgeStart`. `NaN` when the str
 
 Description
 
-Offset representing the seekable range size for live content.
+Describes the kind of live window available. This value is not a duration.
 
-`0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown.
+`0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown.
 
 ### Selector
 
@@ -59,4 +66,52 @@ function LiveEdgeIndicator() {
   const atEdge = time != null && time.currentTime >= live.liveEdgeStart;
   return <span className="live-indicator">{atEdge ? 'LIVE' : 'BEHIND LIVE'}</span>;
 }
+```
+
+## Jump to the live edge
+
+Use the packaged live button for the usual jump-to-live behavior. It combines the live, time, and buffer features, then seeks to the end of the last `seekable` range. It also manages its accessible label and disabled state.
+
+StationLiveButton.tsx
+
+```
+import { LiveButton } from '@videojs/react';
+
+export function StationLiveButton() {
+  return <LiveButton className="station-live-button">On air</LiveButton>;
+}
+```
+
+Put the button in your custom controls and style it there. Do not calculate the destination from `duration` or set `currentTime` to `Infinity`.
+
+If you need different behavior, you can combine the same public features yourself:
+
+*   Read `targetLiveWindow` from `selectLive` to check that the source is live.
+*   Read the newest available time from the last range returned by `selectBuffer`.
+*   Call the `seek()` action returned by `selectTime` with that time.
+
+CustomLiveButton.tsx
+
+```
+import { selectBuffer, selectLive, selectTime, usePlayer } from '@videojs/react';
+
+export function CustomLiveButton() {
+  const live = usePlayer(selectLive);
+  const time = usePlayer(selectTime);
+  const buffer = usePlayer(selectBuffer);
+  const newestTime = buffer?.seekable.at(-1)?.[1];
+
+  const jumpToLive = () => {
+    if (!time || newestTime === undefined || !Number.isFinite(newestTime)) return;
+    void time.seek(newestTime);
+  };
+
+  const disabled = !live || Number.isNaN(live.targetLiveWindow) || !Number.isFinite(newestTime);
+
+  return (
+    <button type="button" disabled={disabled} onClick={jumpToLive}>
+      Go live
+    </button>
+  );
+}
 ```

package/docs/reference/feature-metadata.md

@@ -26,7 +26,7 @@ Details
 
 `title`
 
-`undefined | null | string`
+`MediaContentValue`
 
 `—`
 
@@ -38,7 +38,7 @@ The title to display. Takes precedence over the title the media carries.
 
 `poster`
 
-`undefined | null | string`
+`MediaContentValue`
 
 `—`
 
@@ -78,6 +78,8 @@ The resolved poster URL, independent of the media element's own `poster`. Set it
 
 ### Selector
 
+To just show the name of what is playing, drop in the [Title component](./title.md) — it reads this feature for you. Reach for the selector when building your own UI.
+
 Pass `selectMetadata` to [`usePlayer`](./use-player.md) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.
 
 ContentTitle.tsx
@@ -97,7 +99,7 @@ function ContentTitle() {
 
 The store publishes the resolved values and takes no writes. A player input is the only way to set one.
 
-Every input is a prop on [`Player`](./player-provider.md). A player built without the metadata feature has none of them, and none is forwarded.
+Every input is a prop on [`Player`](./player.md). A player built without the metadata feature has none of them, and none is forwarded.
 
 App.tsx
 
@@ -126,4 +128,4 @@ The media tier comes from media that reports content data and announces changes
 
 `poster` is the feature’s own resolved value, not the media element’s `poster` attribute. Setting one does not set the other.
 
-A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](./poster.md) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it.
+A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](./poster.md) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it. [Add a poster and loading placeholder](../how-to/add-a-poster-and-loading-placeholder.md) walks through that technique for each framework.

package/docs/reference/feature-orientation-lock.md

@@ -58,7 +58,7 @@ Details
 
 `setOrientationLockType`
 
-`(value: undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary') => void`
+`(value: 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | null | undefined) => void`
 
 ▸
 

package/docs/reference/feature-quality.md

@@ -26,7 +26,7 @@ Video renditions available for manual quality selection.
 
 `activeVideoRendition`
 
-`null | MediaVideoRendition`
+`{ id?: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } | null`
 
 ▸
 

package/docs/reference/feature-remote-playback.md

@@ -4,7 +4,7 @@ Remote playback state and actions for the player store
 
 Controls remote playback to devices like Chromecast (Chromium) and AirPlay (Safari). Exits fullscreen before initiating a remote playback session.
 
-[Google Cast concept guide — setup, configuration, and HLS](../concepts/cast.md)
+[Cast to AirPlay and Chromecast](../how-to/cast-to-airplay-and-chromecast.md)
 
 ## API Reference
 

package/docs/reference/feature-source.md

@@ -16,7 +16,7 @@ Details
 
 `source`
 
-`null | string`
+`string | null`
 
 ▸
 

package/docs/reference/feature-stream-type.md

@@ -2,9 +2,13 @@
 
 Stream delivery type (live / on-demand) state for the player store
 
-Tracks the current stream delivery type so components can toggle live-specific UI (a live indicator, “jump to live edge” affordance, hiding the time display, etc.).
+Tracks whether the current source is live, on-demand, or not known yet. Use it to choose which controls to show.
 
-When the media exposes its own `streamType` (e.g. HLS sources derive it from the manifest), the feature syncs on `streamtypechange`. For plain media elements without that capability, it falls back to duration-based detection: an infinite `duration` reports `'live'`, a finite positive `duration` reports `'on-demand'`, and anything else reports `'unknown'`.
+`streamType` is `'live'`, `'on-demand'`, or `'unknown'`. It does not tell you how close playback is to the live edge or whether viewers can rewind.
+
+HLS media reads the stream type from the loaded playlist. If you set `streamType` yourself, your value takes priority until you set it back to `'unknown'`. Other media falls back to the browser’s duration: `Infinity` means live, a finite positive value means on-demand, and any other value means unknown.
+
+The packaged presets do not include this feature. Add `streamTypeFeature` to a custom player when you need `streamType` in player state. The live presets separately include the [live feature](./feature-live.md), which tracks the live edge.
 
 ## API Reference
 
@@ -18,7 +22,7 @@ Details
 
 `streamType`
 
-`'on-demand' | 'live' | 'unknown'`
+`(typeof MediaStreamTypes)[keyof typeof MediaStreamTypes]`
 
 ▸
 
@@ -26,7 +30,7 @@ Description
 
 Current stream delivery type.
 
-Components use this to toggle live-specific UI (e.g. a live indicator, a "jump to live edge" affordance, or hiding the time display).
+Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display.
 
 ### Selector
 
@@ -35,7 +39,12 @@ Pass `selectStreamType` to [`usePlayer`](./use-player.md) to subscribe to stream
 LiveIndicator.tsx
 
 ```
-import { selectStreamType, usePlayer } from '@videojs/react';
+import { createPlayer, selectStreamType, streamTypeFeature } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+
+const { Player, usePlayer } = createPlayer({
+  features: [...liveVideoFeatures, streamTypeFeature],
+});
 
 function LiveIndicator() {
   const stream = usePlayer(selectStreamType);

package/docs/reference/feature-text-tracks.md

@@ -6,6 +6,8 @@ Manages subtitles, captions, chapters, and thumbnail tracks.
 
 A default `kind="chapters"` track can also divide the [time slider](./time-slider.md) into chapter ranges and label the chapter at the current interaction position.
 
+When a thumbnail track is present, `thumbnailTrackCrossOrigin` reports the media element’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](./thumbnail.md) reads it to fetch sprite sheets the same way the browser fetched the track.
+
 ## API Reference
 
 ### State
@@ -38,7 +40,7 @@ Cues from the first `kind="metadata" label="thumbnails"` track.
 
 `thumbnailTrackSrc`
 
-`null | string`
+`string | null`
 
 ▸
 
@@ -48,7 +50,7 @@ The `<track>` element's `src` for resolving relative cue text URLs.
 
 `thumbnailTrackCrossOrigin`
 
-`null | 'anonymous' | 'use-credentials'`
+`'anonymous' | 'use-credentials' | null`
 
 ▸
 
@@ -58,7 +60,7 @@ The media element's CORS mode, mapped through the CORS-settings-attribute rules,
 
 `textTrackList`
 
-`MediaTextTrack<TextTrackKind>[]`
+`MediaTextTrack[]`
 
 ▸
 

package/docs/reference/feature-time.md

@@ -2,7 +2,7 @@
 
 Playback position and duration state for the player store
 
-Tracks playback position and duration.
+Tracks playback position and duration. During live playback, the browser may report `Infinity` as the duration. The player reports the end of the last available [seekable range](./feature-buffer.md) instead, so the value stays finite and moves forward with the stream. This is the newest available time, not the length of the rewindable window; its first available time may be greater than zero. Use [live state](./feature-live.md) or [stream type](./feature-stream-type.md) to check whether the source is live.
 
 ## API Reference
 

package/docs/reference/fullscreen-button.md

@@ -2,6 +2,14 @@
 
 Accessible fullscreen toggle button with keyboard support and state reflection
 
+## Import
+
+tsx
+
+```
+import { FullscreenButton } from '@videojs/react';
+```
+
 ## Anatomy
 
 tsx
@@ -122,7 +130,7 @@ Whether the button is disabled.
 
 `label`
 
-`Text | string | Text) | function`
+`object`
 
 `''`
 
@@ -134,7 +142,7 @@ Custom label for the button.
 
 Type
 
-`Text | string | ((state: FullscreenButtonState) => string | Text)`
+`{ key: string; text: string } | string | ((state: FullscreenButtonState) => Text | string)`
 
 ### State
 
@@ -146,31 +154,31 @@ Type
 
 Details
 
-`availability`
+`fullscreen`
 
-`'available' | 'unavailable' | 'unsupp...`
+`boolean`
 
 ▸
 
 Description
 
-Whether fullscreen can be requested on this platform.
+Whether fullscreen mode is currently active.
 
-Type
+`label`
 
-`'available' | 'unavailable' | 'unsupported'`
+`{ key: string; text: string } | string`
 
-`disabled`
+`availability`
 
-`boolean`
+`MediaFullscreenState['fullscreenAvailability']`
 
 ▸
 
 Description
 
-Non-interactive but still focusable (mirrors `aria-disabled`).
+Whether fullscreen can be requested on this platform.
 
-`hidden`
+`disabled`
 
 `boolean`
 
@@ -178,9 +186,9 @@ Non-interactive but still focusable (mirrors `aria-disabled`).
 
 Description
 
-Whether the button is hidden until fullscreen is available.
+Non-interactive but still focusable (mirrors `aria-disabled`).
 
-`fullscreen`
+`hidden`
 
 `boolean`
 
@@ -188,11 +196,7 @@ Whether the button is hidden until fullscreen is available.
 
 Description
 
-Whether fullscreen mode is currently active.
-
-`label`
-
-`Text | string`
+Whether the button is hidden until fullscreen is available.
 
 ### Data attributes
 
@@ -212,7 +216,7 @@ Present when fullscreen mode is active.
 
 `data-availability`
 
-`'available' | 'unavailable' | 'unsupp...`
+`MediaFullscreenState['fullscreenAvailability']`
 
 ▸
 
@@ -220,10 +224,6 @@ Description
 
 Indicates fullscreen availability (`available`, `unavailable`, `unsupported`).
 
-Type
-
-`'available' | 'unavailable' | 'unsupported'`
-
 `data-disabled`
 
 ▸

package/docs/reference/gesture.md

@@ -0,0 +1,201 @@
+# Gesture
+
+Map tap and double-tap gestures to player actions
+
+## Import
+
+tsx
+
+```
+import { Gesture } from '@videojs/react';
+```
+
+## Anatomy
+
+tsx
+
+```
+<Gesture type="doubletap" region="right" pointer="touch" action="seekStep" value={10} />
+```
+
+## Behavior
+
+`Gesture` is a behavior component: it renders no visible interface. Place it inside a [Container](./player-container.md) to map a `tap` or `doubletap` gesture to a player action. A tap must use the primary pointer and complete within 250 milliseconds. When a matching double-tap gesture exists, the first tap waits briefly to see whether a second tap follows.
+
+Use `pointer` to accept only `mouse`, `touch`, or `pen` input. Use `region` to divide the container horizontally:
+
+*   Left and right regions split the container into halves.
+*   Left, center, and right regions split it into thirds.
+*   A center-only region covers the full container.
+*   A single left or right region covers that half of the container.
+
+An unregional gesture acts as a fallback outside the active regions. When several registrations match the same gesture, the first registration wins.
+
+Choose a built-in `action` from the API reference below, or use an application-defined name to call a same-named action on the player store. Pass `value` as seconds for `seekStep` or as a volume delta such as `0.05` or `-0.05` for `volumeStep`. Unknown action names do nothing and warn in development.
+
+## Accessibility
+
+Gestures supplement visible, keyboard-operable controls; they should never be the only way to perform an action. Gestures ignore pointer activity that begins on interactive controls, links, form fields, menu items, or elements marked with `data-interactive`.
+
+## Examples
+
+### Basic Usage
+
+This example follows the common video-player pattern: click to play or pause, double-click the left or right side to seek ten seconds, and double-click the center to toggle fullscreen.
+
+Click: play/pause · Double-click: −10s · fullscreen · +10s
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, Gesture, PlayButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="react-gesture-basic">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+        <p className="react-gesture-basic__instructions">Click: play/pause · Double-click: −10s · fullscreen · +10s</p>
+        <PlayButton
+          className="react-gesture-basic__button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+        <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
+        <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
+        <Gesture type="doubletap" action="toggleFullscreen" region="center" />
+        <Gesture type="doubletap" action="seekStep" value={10} region="right" />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.react-gesture-basic {
+  position: relative;
+}
+
+.react-gesture-basic video {
+  width: 100%;
+}
+
+.react-gesture-basic__instructions {
+  position: absolute;
+  top: 10px;
+  left: 10px;
+  padding: 6px 10px;
+  margin: 0;
+  color: white;
+  pointer-events: none;
+  background: rgb(0 0 0 / 70%);
+  border-radius: 4px;
+}
+
+.react-gesture-basic__button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding: 8px 20px;
+  color: black;
+  cursor: pointer;
+  background: rgb(255 255 255 / 80%);
+  border: 1px solid rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`action*`
+
+`'togglePaused' | 'toggleMuted' | 'tog...`
+
+`—`
+
+▸
+
+Description
+
+Built-in player action or same-named custom store action to run when the gesture is recognized.
+
+Type
+
+`'togglePaused' | 'toggleMuted' | 'toggleFullscreen' | 'toggleSubtitles' | 'togglePictureInPicture' | 'toggleControls' | 'seekStep' | 'volumeStep' | 'speedUp' | 'speedDown' | string & object`
+
+`type*`
+
+`'tap' | 'doubletap'`
+
+`—`
+
+▸
+
+Description
+
+Gesture to recognize.
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the gesture is disabled.
+
+`pointer`
+
+`'mouse' | 'touch' | 'pen'`
+
+`—`
+
+▸
+
+Description
+
+Pointer type that may activate the gesture. All pointer types are accepted when omitted.
+
+`region`
+
+`'left' | 'center' | 'right'`
+
+`—`
+
+▸
+
+Description
+
+Optional horizontal part of the container that may activate the gesture.
+
+`value`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Numeric value passed to actions such as `seekStep` and `volumeStep`.

package/docs/reference/get-i18n-translations.md

@@ -4,7 +4,7 @@ Read the merged translation map for a locale using BCP 47 parent-chain fallback
 
 `getI18nTranslations` walks the BCP 47 lookup chain (`es-MX` → `es` → `en`) and merges registry layers into one map. Providers combine this map with lazy-loaded built-in packs and provider overrides. Call it directly when building custom UI outside built-in controls.
 
-See [Internationalization](../concepts/i18n.md) for merge order and fallback rules.
+See [Internationalize the player](../how-to/internationalize-the-player.md) for merge order and fallback rules.
 
 ts
 
@@ -29,7 +29,7 @@ Details
 
 `locale*`
 
-`string & object | 'ar' | 'az' | 'bs' ...`
+`(typeof LOCALES)[number] | string & o...`
 
 `—`
 
@@ -41,7 +41,7 @@ BCP 47 tag to resolve (e.g. `es-MX`, `zh-Hant-HK`).
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`(typeof LOCALES)[number] | string & object`
 
 ### Return Value
 
@@ -49,10 +49,10 @@ Type
 
 Details
 
-`object & Record<string, string | unde...`
+`object`
 
 ▸
 
 Type
 
-`object & Record<string, string | undefined>`
+`{ [Key in TranslationKey]?: TranslationParams[Key] extends never ? string : Key extends keyof ParametricTranslations ? ParametricTranslations[Key] : string; } & Record<string, string | undefined>`

package/docs/reference/google-cast.md

@@ -2,7 +2,7 @@
 
 Options for the Google Cast component that configures the receiver and load request
 
-Adds Google Cast support to the player’s media. It renders nothing — place it inside the player as a sibling of the media element, and pair it with a [CastButton](./cast-button.md). See [Google Cast](../concepts/cast.md) for how casting works.
+Adds Google Cast support to the player’s media. It renders nothing — place it inside the player as a sibling of the media element, and pair it with a [CastButton](./cast-button.md). See [Cast to AirPlay and Chromecast](../how-to/cast-to-airplay-and-chromecast.md) for the complete setup.
 
 ## Anatomy
 
@@ -58,11 +58,11 @@ When the Cast `src` is an HLS playlist, Video.js detects the segment format and
 
 [
 
-Google Cast
+Cast to AirPlay and Chromecast
 
-How casting works
+Add remote playback to a player
 
-](../concepts/cast.md)
+](../how-to/cast-to-airplay-and-chromecast.md)
 
 [CastButton component reference](./cast-button.md)
 

package/docs/reference/has-registered-locale.md

@@ -28,7 +28,7 @@ Details
 
 `locale*`
 
-`string & object | 'ar' | 'az' | 'bs' ...`
+`(typeof LOCALES)[number] | string & o...`
 
 `—`
 
@@ -40,7 +40,7 @@ BCP 47 tag to test.
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`(typeof LOCALES)[number] | string & object`
 
 ### Return Value