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

package/docs/reference/mux-audio.md

@@ -4,6 +4,26 @@ Audio element for Mux-hosted HLS streams
 
 Audio element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
 
+## Analytics and casting
+
+MuxAudio plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](../concepts/mux-data.md) and [Google Cast](../concepts/cast.md) are separate components you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
+
+tsx
+
+```
+import { GoogleCast } from '@videojs/react/media/google-cast';
+import { MuxAudio } from '@videojs/react/media/mux-audio';
+import { MuxData } from '@videojs/react/media/mux-data';
+
+<MuxAudio source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} />
+<MuxData playerSoftwareName="mux-audio" />
+<GoogleCast />
+```
+
+[Mux Data — metadata, options, and configuration](../concepts/mux-data.md)
+
+[Google Cast — receivers, load requests, and session state](../concepts/cast.md)
+
 ## Examples
 
 ### Basic Usage
@@ -16,14 +36,7 @@ App.css
 import { MuxAudio } from '@videojs/react/media/mux-audio';
 
 export default function BasicUsage() {
-  return (
-    <MuxAudio
-      className="mux-audio"
-      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
-      crossOrigin="anonymous"
-      controls
-    />
-  );
+  return <MuxAudio className="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossOrigin="anonymous" controls />;
 }
 ```
 ```
@@ -35,9 +48,11 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Host Properties
+### Props
 
-Property
+Accepts the standard React props for a native `<audio>`, plus these Video.js-specific props:
+
+Prop
 
 Type
 
@@ -45,30 +60,6 @@ Default
 
 Details
 
-`audioRenditions`
-
-`AudioRenditionListLike | undefined`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
-`audioTracks`
-
-`AudioTrackListLike | undefined`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
 `config`
 
 `HlsMediaConfig`
@@ -81,61 +72,53 @@ Description
 
 Playback configuration: a preferred playback path, an explicit content type, and options forwarded to hls.js. Reassigning reloads the engine when an engine-relevant option changes.
 
-`engine`
+`preload`
 
-`Hls | null`
+`PreloadType`
 
-`—`
+`'metadata'`
 
 ▸
 
 Description
 
-Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+Preload type (`'none'` / `'metadata'` / `'auto'`).
 
-`error`
+`source`
 
-`(ErrorLike & MediaError) | null`
+`MuxSource | null`
 
-`—`
+`null`
 
 ▸
 
 Description
 
-Read-only.
+Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token.
 
-`liveEdgeStart`
+`src`
 
-`number`
+`string`
 
-`—`
+`''`
 
 ▸
 
 Description
 
-Read-only. Presentation time marking the start of the Live Edge Window.
+Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID and query params into `source`; other URLs pass through unchanged.
 
-Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live.
+`storyboard`
 
-`preload`
-
-`PreloadType`
+`string`
 
-`'metadata'`
+`''`
 
 ▸
 
 Description
 
-Preload type (`'none'` / `'metadata'` / `'auto'`).
-
-`src`
-
-`string`
-
-`''`
+Storyboard (thumbnail sprite) VTT URL. Falls back to one derived from `source`.
 
 `streamType`
 
@@ -149,70 +132,22 @@ Description
 
 Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
 
-`targetLiveWindow`
-
-`number`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate).
-
-`videoRenditions`
-
-`VideoRenditionListLike | undefined`
-
-`—`
-
-▸
+`thumbnail`
 
-Description
-
-Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
-`videoTracks`
-
-`VideoTrackListLike | undefined`
+`string`
 
-`—`
+`''`
 
 ▸
 
 Description
 
-Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
+Thumbnail image URL. Falls back to one derived from `source`.
 
-### Attributes
+### Ref
 
-Renders a native `<audio>` 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/audio): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+Forwards its ref to the rendered `<audio>`. The ref is an [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) and exposes its complete native property and method API.
 
 ### 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``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
-
-These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``removetrack`
-
-Beyond the media events above, this element emits:
-
-Event
-
-Description
-
-`streamtypechange`
-
-Fired when the detected stream type changes. Read \`streamType\` for the new value.
-
-`targetlivewindowchange`
-
-Fired when the target live window changes. Read \`targetLiveWindow\` for the new value.
-
-These events have no built-in React prop. Attach a listener to the element through a `ref` with `addEventListener`.
-
-### 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``load``pause``play`
-
-In React, call these through a `ref` to the element.
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

package/docs/reference/mux-data.md

@@ -0,0 +1,93 @@
+# MuxData
+
+Options for the Mux Data component that monitors playback quality
+
+Adds [Mux Data](https://data.mux.com) monitoring to the player’s media. It renders nothing — place it inside the player as a sibling of the media element. See [Mux Data](../concepts/mux-data.md) for how monitoring works.
+
+## Anatomy
+
+tsx
+
+```
+import { MuxData } from '@videojs/react/media/mux-data';
+
+<MuxData />
+```
+
+## Options
+
+Prop
+
+Type
+
+Description
+
+`envKey`
+
+`string`
+
+Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback
+
+`metadata`
+
+`object`
+
+Mux Data metadata for the view
+
+`playerSoftwareName`
+
+`string`
+
+Player name reported to Mux Data
+
+`playerSoftwareVersion`
+
+`string`
+
+Player version reported to Mux Data. Defaults to the Video.js version
+
+`playerInitTime`
+
+`number`
+
+Epoch milliseconds the player was initialized. Defaults to when the component was created
+
+`beaconCollectionDomain`
+
+`string`
+
+Custom domain the beacons are sent to
+
+`disableCookies`
+
+`boolean`
+
+Stops the SDK from setting cookies
+
+`debug`
+
+`boolean`
+
+Turns on SDK debug logging
+
+`MuxDataSdk`
+
+`object`
+
+SDK used for monitoring. Set it to `undefined` to switch monitoring off
+
+Changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, which ends the current view and starts a new one. The rest update the view in place.
+
+## See also
+
+[
+
+Mux Data
+
+How monitoring works
+
+](../concepts/mux-data.md)
+
+[MuxVideo element reference](./mux-video.md)
+
+[MuxAudio element reference](./mux-audio.md)

package/docs/reference/mux-video.md

@@ -4,6 +4,89 @@ Video element for Mux-hosted HLS streams
 
 Video element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
 
+## Load a source
+
+The `source` param builds the URL for you from a playback ID, an optional custom domain, and `playback` params. Playback params are just camelCased [Mux playback query params](https://www.mux.com/docs/api-reference/stream/streaming/get-hls-manifest); for example, `max_resolution` becomes `maxResolution`.
+
+tsx
+
+```
+<MuxVideo
+  source={{ 
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    customDomain: 'media.example.com',
+    playback: { maxResolution: '1080p' }
+  }} 
+/>
+```
+
+If for some reason you need a bit more control, you can use the `src` param with a plain ’ol URL, too:
+
+tsx
+
+```
+<MuxVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+/>
+```
+
+MuxVideo fires a `sourcechange` event when the source actually changes. Setting the same values again, like a fresh object on a React re-render, doesn’t fire it.
+
+## Thumbnails and storyboards
+
+`thumbnail` and `storyboard` default to URLs derived from `source`: the poster image and the storyboard VTT that drives hover previews on the time slider. MuxVideo injects the storyboard `<track>` automatically, skipping it for live streams. Set either prop to a URL to override the derived one.
+
+## Signed playback
+
+For [signed playback](https://www.mux.com/docs/guides/secure-video-playback), put the playback token on `source.playback.token`. The token replaces every other playback param, so bake modifiers like resolution and time bounds into the token when you sign it.
+
+Thumbnail and storyboard URLs need their own audience-scoped tokens, `source.thumbnail.token` (`aud: 't'`) and `source.storyboard.token` (`aud: 's'`). Without a matching image token, MuxVideo derives no thumbnail or storyboard URL, since an unsigned request would be rejected.
+
+tsx
+
+```
+<MuxVideo
+  source={{
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    playback: { token: playbackToken },
+    thumbnail: { token: thumbnailToken },
+    storyboard: { token: storyboardToken },
+  }}
+/>
+```
+
+## Analytics and casting
+
+MuxVideo plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](../concepts/mux-data.md) and [Google Cast](../concepts/cast.md) are separate components you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
+
+tsx
+
+```
+import { GoogleCast } from '@videojs/react/media/google-cast';
+import { MuxData } from '@videojs/react/media/mux-data';
+import { MuxVideo } from '@videojs/react/media/mux-video';
+
+<MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
+<MuxData playerSoftwareName="mux-video" />
+<GoogleCast />
+```
+
+[
+
+Mux Data
+
+Metadata, options, and configuration
+
+](../concepts/mux-data.md)
+
+[
+
+Google Cast
+
+Receivers, load requests, and session state
+
+](../concepts/cast.md)
+
 ## Examples
 
 ### Basic Usage
@@ -38,9 +121,11 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Host Properties
+### Props
 
-Property
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+Prop
 
 Type
 
@@ -48,30 +133,6 @@ Default
 
 Details
 
-`audioRenditions`
-
-`AudioRenditionListLike | undefined`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
-`audioTracks`
-
-`AudioTrackListLike | undefined`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
 `config`
 
 `HlsMediaConfig`
@@ -84,61 +145,53 @@ Description
 
 Playback configuration: a preferred playback path, an explicit content type, and options forwarded to hls.js. Reassigning reloads the engine when an engine-relevant option changes.
 
-`engine`
+`preload`
 
-`Hls | null`
+`PreloadType`
 
-`—`
+`'metadata'`
 
 ▸
 
 Description
 
-Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+Preload type (`'none'` / `'metadata'` / `'auto'`).
 
-`error`
+`source`
 
-`(ErrorLike & MediaError) | null`
+`MuxSource | null`
 
-`—`
+`null`
 
 ▸
 
 Description
 
-Read-only.
+Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token.
 
-`liveEdgeStart`
+`src`
 
-`number`
+`string`
 
-`—`
+`''`
 
 ▸
 
 Description
 
-Read-only. Presentation time marking the start of the Live Edge Window.
-
-Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live.
+Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID and query params into `source`; other URLs pass through unchanged.
 
-`preload`
+`storyboard`
 
-`PreloadType`
+`string`
 
-`'metadata'`
+`''`
 
 ▸
 
 Description
 
-Preload type (`'none'` / `'metadata'` / `'auto'`).
-
-`src`
-
-`string`
-
-`''`
+Storyboard (thumbnail sprite) VTT URL. Falls back to one derived from `source`.
 
 `streamType`
 
@@ -152,124 +205,22 @@ Description
 
 Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
 
-`targetLiveWindow`
-
-`number`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate).
-
-`videoRenditions`
+`thumbnail`
 
-`VideoRenditionListLike | undefined`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
-
-`videoTracks`
-
-`VideoTrackListLike | undefined`
+`string`
 
-`—`
+`''`
 
 ▸
 
 Description
 
-Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
+Thumbnail image URL. Falls back to one derived from `source`.
 
-### Attributes
+### Ref
 
-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`
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
 
 ### 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`
-
-Beyond the media events above, this element emits:
-
-Event
-
-Description
-
-`streamtypechange`
-
-Fired when the detected stream type changes. Read \`streamType\` for the new value.
-
-`targetlivewindowchange`
-
-Fired when the target live window changes. Read \`targetLiveWindow\` for the new value.
-
-These events have no built-in React prop. Attach a listener to the element through a `ref` with `addEventListener`.
-
-### 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.
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.