@videojs/react 10.0.0-beta.24 → 10.0.0-beta.25

package/docs/reference/cast-button.md

@@ -0,0 +1,236 @@
+# CastButton
+
+Accessible Cast toggle button with state reflection and keyboard support
+
+## Anatomy
+
+tsx
+
+```
+<CastButton />
+```
+
+## Behavior
+
+Toggles a Google Cast session. Clicking the button while `disconnected` opens the Cast device picker; clicking while `connected` ends the session.
+
+The button does nothing when `availability` is not `'available'` — for example, when no Chromecast is on the network, or on browsers that don’t support Cast.
+
+## Styling
+
+Style based on cast state and availability:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* During an active session */
+.cast-button[data-cast-state="connected"] {
+  color: blue;
+}
+
+/* Hide when Cast is unsupported (non-Chromium browsers) */
+.cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`:
+
+Cast state
+
+Default label
+
+`'disconnected'`
+
+“Start casting”
+
+`'connecting'`
+
+“Connecting”
+
+`'connected'`
+
+“Stop casting”
+
+Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+Start casting
+
+App.tsx
+
+App.css
+
+```
+import { CastButton, createPlayer } from '@videojs/react';
+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.Provider>
+      <Player.Container className="media-container">
+        <HlsJsVideo
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <CastButton
+          className="media-cast-button"
+          render={(props, state) => (
+            <button {...props}>{state.castState === 'connected' ? 'Stop casting' : 'Start casting'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-cast-button {
+  position: absolute;
+  right: 10px;
+  bottom: 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);
+}
+
+.media-cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: CastButtonState) => string)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`castState`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-cast-state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current remote playback connection state. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state)
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether remote playback can be requested on this platform. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback)
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`

package/docs/reference/dash-video.md

@@ -0,0 +1,138 @@
+# DashVideo
+
+DASH video element powered by dash.js for adaptive bitrate streaming
+
+DASH video element powered by [dash.js](https://github.com/Dash-Industry-Forum/dash.js/) for MPEG-DASH adaptive bitrate streaming.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { DashVideo } from '@videojs/react/media/dash-video';
+
+export default function BasicUsage() {
+  return (
+    <DashVideo
+      className="dash-video"
+      src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd"
+      autoPlay
+      muted
+      playsInline
+      loop
+    />
+  );
+}
+```
+```
+.dash-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Host Properties
+
+Property
+
+Type
+
+Default
+
+Details
+
+`engine`
+
+`MediaPlayerClass`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Underlying playback engine — the dash.js `MediaPlayerClass` instance. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+
+`src`
+
+`string`
+
+`''`
+
+### Attributes
+
+Renders a native `<video>` element and accepts these media attributes as React props. The standard ones behave as described in the [MDN media attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+
+### Events
+
+Handle these media events with React event props (e.g. `onPlay`, `onTimeUpdate`). See [media events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events): `abort``canplay``canplaythrough``durationchange``emptied``ended``error``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``resize``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
+
+These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``enterpictureinpicture``leavepictureinpicture``removetrack`
+
+This element dispatches no events beyond the media events above.
+
+### Methods
+
+Supports these methods from the native media API. See [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) for the core methods: `addTextTrack``canPlayType``exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
+
+In React, call these through a `ref` to the element.
+
+### CSS Custom Properties
+
+Variable
+
+Details
+
+`--media-video-border-radius`
+
+▸
+
+Description
+
+Border radius of the video element.
+
+`--media-object-fit`
+
+▸
+
+Description
+
+Object fit for the video.
+
+`--media-object-position`
+
+▸
+
+Description
+
+Object position for the video.
+
+`--media-caption-track-duration`
+
+▸
+
+Description
+
+Duration of the caption track transition.
+
+`--media-caption-track-delay`
+
+▸
+
+Description
+
+Delay before the caption track transition.
+
+`--media-caption-track-y`
+
+▸
+
+Description
+
+Vertical offset of the caption track.

package/docs/reference/feature-audio-track.md

@@ -0,0 +1,60 @@
+# Audio track
+
+Audio track state and actions for the player store
+
+Tracks available audio tracks and selects the enabled track.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`audioTrackList`
+
+`MediaAudioTrack[]`
+
+▸
+
+Description
+
+Audio tracks available for manual track selection.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`selectAudioTrack`
+
+`(value: string) => void`
+
+▸
+
+Description
+
+Select an audio track by menu value.
+
+### Selector
+
+Pass `selectAudioTrack` to [`usePlayer`](./use-player.md) to subscribe to audio track state. Returns `undefined` if the audio track feature is not configured.
+
+AudioTrackInfo.tsx
+
+```
+import { selectAudioTrack, usePlayer } from '@videojs/react';
+
+function AudioTrackInfo() {
+  const audioTrack = usePlayer(selectAudioTrack);
+  if (!audioTrack) return null;
+
+  return <span>{audioTrack.audioTrackList.length} audio tracks</span>;
+}
+```

package/docs/reference/feature-fullscreen.md

@@ -83,12 +83,29 @@ import { selectFullscreen, usePlayer } from '@videojs/react';
 
 function FullscreenButton() {
   const fs = usePlayer(selectFullscreen);
-  if (!fs || fs.availability !== 'available') return null;
+  if (!fs || fs.fullscreenAvailability !== 'available') return null;
 
   return (
-    <button onClick={fs.toggle}>
-      {fs.active ? 'Exit fullscreen' : 'Fullscreen'}
+    <button onClick={fs.toggleFullscreen}>
+      {fs.fullscreen ? 'Exit fullscreen' : 'Fullscreen'}
     </button>
   );
 }
+```
+
+### Screen orientation
+
+Add [`features.orientationLock`](./feature-orientation-lock.md) to lock screen orientation while fullscreen is active. Unsupported browsers and rejected lock requests are ignored, so iOS Safari continues to use its normal fullscreen behavior.
+
+By default, the feature locks to `landscape`. Pass a Screen Orientation API type to customize it:
+
+ts
+
+```
+import { createPlayer, features } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
+});
 ```

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

@@ -0,0 +1,35 @@
+# Orientation lock
+
+Screen orientation locking while fullscreen is active
+
+Locks screen orientation while fullscreen is active. Add it explicitly to a feature list; it is not included in the default video presets.
+
+## API Reference
+
+### Usage
+
+By default, the feature locks to `landscape`. Pass a Screen Orientation API type to customize it.
+
+player.tsx
+
+```
+import { createPlayer, features } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+export const Player = createPlayer({
+  features: [...videoFeatures, features.orientationLock],
+});
+```
+
+portrait-player.tsx
+
+```
+import { createPlayer, features } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+export const Player = createPlayer({
+  features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
+});
+```
+
+Unsupported browsers and rejected lock requests are ignored.

package/docs/reference/feature-quality.md

@@ -0,0 +1,70 @@
+# Quality
+
+Video rendition state and actions for the player store
+
+Tracks video renditions and selects a manual rendition or automatic adaptive bitrate.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`videoRenditionList`
+
+`MediaVideoRendition[]`
+
+▸
+
+Description
+
+Video renditions available for manual quality selection.
+
+`activeVideoRendition`
+
+`null | MediaVideoRendition`
+
+▸
+
+Description
+
+Video rendition currently playing, including when automatic ABR is selected.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`selectVideoRendition`
+
+`(value: string) => void`
+
+▸
+
+Description
+
+Select a video rendition by menu value, or automatic ABR with `"auto"`.
+
+### Selector
+
+Pass `selectQuality` to [`usePlayer`](./use-player.md) to subscribe to quality state. Returns `undefined` if the quality feature is not configured.
+
+QualityInfo.tsx
+
+```
+import { selectQuality, usePlayer } from '@videojs/react';
+
+function QualityInfo() {
+  const quality = usePlayer(selectQuality);
+  if (!quality) return null;
+
+  return <span>{quality.videoRenditionList.length} renditions</span>;
+}
+```

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

@@ -2,7 +2,9 @@
 
 Remote playback state and actions for the player store
 
-Controls remote playback to devices like Chromecast. Exits fullscreen before initiating a remote playback session.
+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)
 
 ## API Reference
 

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

@@ -82,6 +82,16 @@ Description
 
 Toggle captions/subtitles visibility. Returns the new enabled value.
 
+`selectSubtitlesTrack`
+
+`(value: string) => void`
+
+▸
+
+Description
+
+Select a captions/subtitles track by menu value, or disable with `"off"`.
+
 ### Selector
 
 Pass `selectTextTracks` to [`usePlayer`](./use-player.md) to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.