mirror of
https://github.com/zoriya/v10.git
synced 2026-08-15 10:23:32 +00:00
docs(site): add MuxData and GoogleCast API references; document status announcer and mux-video source API (#1902)
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -30,6 +30,14 @@ All interactive components support keyboard control. For example, buttons activa
|
||||
|
||||
Interactive elements are focusable when enabled and leave the [tab order](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) when disabled. Popover triggers link to their popups with `aria-controls` and `aria-expanded`.
|
||||
|
||||
The player container is focusable and labeled: it takes `role="group"`, `tabindex="0"`, and an `aria-label` you can override. Keyboard users can tab to the player as a whole, and screen readers announce it as a named group.
|
||||
|
||||
## Status announcements
|
||||
|
||||
The player announces confirmed state changes through a visually hidden live region (`role="status"`), so screen reader users hear when playback starts or pauses, captions turn on or off, fullscreen, picture-in-picture, playback rate, or volume change, and where a seek lands.
|
||||
|
||||
Announcements follow confirmed state from the player store rather than requested changes, so routine time updates never reach the live region. Rapid volume and seek changes are grouped into a single announcement, and the player stays quiet while one of its sliders has focus, since the slider already announces its own value. State the store tracks is covered for you; a custom control that tracks its own state needs its own live region.
|
||||
|
||||
## Captions and subtitles
|
||||
|
||||
The <DocsLink slug="reference/feature-text-tracks">text tracks feature</DocsLink> supports captions and subtitles. Closed captions in the U.S. are governed by the [FCC](https://www.fcc.gov/) under the [CVAA](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa), which requires both captioning and viewer control over caption appearance (font, size, color, opacity, and edge style). Non-compliance carries legal risk. The [WebKit Caption Display Settings explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings) tracks how browsers are bringing these customization preferences into the web platform natively.
|
||||
|
||||
@@ -73,8 +73,8 @@ Cast only works in Chromium-based browsers (Chrome, Edge, and others built on Bl
|
||||
|
||||
Cast uses a **sender / receiver** model:
|
||||
|
||||
- **Sender** — the browser tab. It sends the receiver a load request with the source URL and metadata, then issues playback commands (play, pause, seek, volume).
|
||||
- **Receiver** — the Chromecast device running a receiver application: Google's default media receiver, or a custom one you configure.
|
||||
- **Sender**: the browser tab. It sends the receiver a load request with the source URL and metadata, then issues playback commands (play, pause, seek, volume).
|
||||
- **Receiver**: the Chromecast device running a receiver application, either Google's default media receiver or a custom one you configure.
|
||||
|
||||
### Session lifecycle
|
||||
|
||||
@@ -86,7 +86,7 @@ A Cast session moves through three states, exposed by the <DocsLink slug="refere
|
||||
| `'connecting'` | Device picked; session starting |
|
||||
| `'connected'` | Session active; receiver has the media |
|
||||
|
||||
While `connected`, the media element's `play`, `pause`, `currentTime`, `volume`, `muted`, and `playbackRate` all proxy to the Cast receiver. Local playback is suspended.
|
||||
While `connected`, the media element's `play`, `pause`, `currentTime`, `volume`, `muted`, and `playbackRate` all forward to the Cast receiver. Local playback is suspended.
|
||||
|
||||
### The lazy-loaded SDK
|
||||
|
||||
@@ -108,58 +108,13 @@ Set `disableRemotePlayback` on the media element to opt out of remote playback e
|
||||
|
||||
## Configure Cast
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
Pass Cast options as props of the `GoogleCast` component.
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
Set Cast options as attributes on the `<google-cast>` element. Object-valued options (like `customData`) are properties only.
|
||||
</FrameworkCase>
|
||||
|
||||
### Custom receiver application ID
|
||||
|
||||
By default, Video.js casts to Google's [Default Media Receiver](https://developers.google.com/cast/docs/web_sender/integrate#default_media_web_receiver) (`CC1AD845`). To use your own receiver app, set `receiver`:
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
|
||||
<GoogleCast receiver="YOUR_APP_ID" /> // [!code focus]
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```html
|
||||
<hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></hlsjs-video>
|
||||
<google-cast receiver="YOUR_APP_ID"></google-cast> <!-- [!code focus] -->
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
### Custom data on load
|
||||
|
||||
Send extra data (auth tokens, user IDs) to the receiver with each load request via `customData`. The receiver app reads it from the load request's `customData` field:
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
|
||||
<GoogleCast customData={{ token: 'abc123', userId: 'u_789' }} /> // [!code focus]
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```ts
|
||||
const googleCast = document.querySelector('google-cast');
|
||||
googleCast.customData = { token: 'abc123', userId: 'u_789' }; // [!code focus]
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
### Cast a different source
|
||||
|
||||
By default the receiver loads the same URL the browser plays. Set `src` (and optionally `contentType`) to send the receiver a different one — for example, cast an HLS stream while the browser plays an MP4:
|
||||
By default, the receiver loads the same source the browser plays through Google's [Default Media Receiver](https://developers.google.com/cast/docs/web_sender/integrate#default_media_web_receiver). Point Cast at your own receiver app, send a different source, attach custom data to the load request, or override the stream type through the component's options:
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />
|
||||
<GoogleCast
|
||||
receiver="YOUR_APP_ID"
|
||||
src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
|
||||
contentType="application/x-mpegURL"
|
||||
/>
|
||||
@@ -170,31 +125,14 @@ By default the receiver loads the same URL the browser plays. Set `src` (and opt
|
||||
```html
|
||||
<hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"></hlsjs-video>
|
||||
<google-cast
|
||||
receiver="YOUR_APP_ID"
|
||||
src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
|
||||
content-type="application/x-mpegURL"
|
||||
></google-cast>
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
### HLS on the receiver
|
||||
|
||||
When the Cast source is an HLS playlist, Video.js inspects the playlist, detects the segment format (TS or fMP4), and sets `hlsSegmentFormat` / `hlsVideoSegmentFormat` on the Cast load request. The default media receiver plays HLS natively; no extra configuration needed.
|
||||
|
||||
Set `streamType` to tell the receiver whether the stream is `'on-demand'` or `'live'`. When unset, it falls back to the player's `streamType`:
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
|
||||
<GoogleCast streamType="live" /> // [!code focus]
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```html
|
||||
<hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></hlsjs-video>
|
||||
<google-cast stream-type="live"></google-cast> <!-- [!code focus] -->
|
||||
```
|
||||
</FrameworkCase>
|
||||
The <DocsLink slug="reference/google-cast">GoogleCast reference</DocsLink> documents every option. HLS sources need no extra receiver setup: Video.js detects the segment format and configures the load request, and the Default Media Receiver plays HLS natively.
|
||||
|
||||
## Read Cast state
|
||||
|
||||
@@ -225,40 +163,10 @@ class CastStatus extends HTMLElement {
|
||||
|
||||
## Browser availability
|
||||
|
||||
The Remote Playback feature reports availability as `'available'` (a device is on the network), `'unavailable'` (no device found), or `'unsupported'` (the browser can't cast). The `CastButton` keeps this raw value in `data-availability`, but handles presentation for you:
|
||||
|
||||
- When Cast is unsupported, the HTML custom element receives the native `hidden` attribute and the React component returns `null`.
|
||||
- When Cast is supported but no device is reachable, the button remains visible with `aria-disabled="true"` and `data-disabled`.
|
||||
|
||||
Use `data-disabled` to style the visible, non-interactive state:
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```css
|
||||
media-cast-button[data-disabled] {
|
||||
cursor: not-allowed;
|
||||
opacity: 0.5;
|
||||
}
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
`CastButton` renders a `<button>` element. Give it a `className` to target:
|
||||
|
||||
```tsx
|
||||
<CastButton className="cast-button" />
|
||||
```
|
||||
|
||||
```css
|
||||
.cast-button[data-disabled] {
|
||||
cursor: not-allowed;
|
||||
opacity: 0.5;
|
||||
}
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
Unsupported buttons hide automatically, so no availability selector or extra hiding CSS is required.
|
||||
The Remote Playback feature reports availability as `'available'` (a device is on the network), `'unavailable'` (no device found), or `'unsupported'` (the browser can't cast). A <DocsLink slug="reference/cast-button">CastButton</DocsLink> handles the presentation for you: it hides itself when Cast is unsupported, and shows a disabled state when Cast is supported but no device is reachable. See its reference for the data attributes and styling hooks.
|
||||
|
||||
## See also
|
||||
|
||||
<DocsLinkCard slug="reference/google-cast">GoogleCast reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/cast-button">CastButton component reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/feature-remote-playback">Remote Playback feature reference</DocsLinkCard>
|
||||
|
||||
@@ -8,7 +8,7 @@ import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
|
||||
import Aside from '@/components/Aside.astro';
|
||||
|
||||
[Mux Data](https://www.mux.com/data) measures playback quality — startup time, rebuffering, playback failures, and watch time. Add the Mux Data component to a player and it monitors whichever media that player is playing:
|
||||
[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data component to a player and it monitors whichever media that player is playing:
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx title="App.tsx"
|
||||
@@ -55,7 +55,7 @@ Mux Data is opt-in. No media element monitors playback on its own, Mux ones incl
|
||||
|
||||
Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view's `video_id`, and Mux attributes the view to the environment that owns that playback ID.
|
||||
|
||||
Set `envKey` when you monitor a source Mux doesn't host — a self-hosted HLS or DASH stream, for example. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
|
||||
Set `envKey` when you monitor a source Mux doesn't host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
@@ -96,40 +96,13 @@ muxData.metadata = { video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' }; /
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
## Options
|
||||
## Configuration
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
| 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 |
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
| Attribute | Property | Description |
|
||||
|---|---|---|
|
||||
| `env-key` | `envKey` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
|
||||
| — | `metadata` | Mux Data metadata for the view |
|
||||
| `player-software-name` | `playerSoftwareName` | Player name reported to Mux Data |
|
||||
| `player-software-version` | `playerSoftwareVersion` | Player version reported to Mux Data. Defaults to the Video.js version |
|
||||
| `player-init-time` | `playerInitTime` | Epoch milliseconds the player was initialized. Defaults to when the element was created |
|
||||
| `beacon-collection-domain` | `beaconCollectionDomain` | Custom domain the beacons are sent to |
|
||||
| `disable-cookies` | `disableCookies` | Stops the SDK from setting cookies |
|
||||
| `debug` | `debug` | Turns on SDK debug logging |
|
||||
| — | `MuxDataSdk` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |
|
||||
</FrameworkCase>
|
||||
|
||||
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.
|
||||
The <DocsLink slug="reference/mux-data">MuxData reference</DocsLink> lists every option: the metadata and software fields above, plus the beacon domain, cookie, debug, and SDK settings. Most options update the current view in place; changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, ending the current view and starting a new one.
|
||||
|
||||
## See also
|
||||
|
||||
<DocsLinkCard slug="reference/mux-data">MuxData reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/mux-video">MuxVideo element reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/mux-audio">MuxAudio element reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="concepts/cast">Google Cast — the other media component you compose onto a player</DocsLinkCard>
|
||||
<DocsLinkCard slug="concepts/cast" description="The other media component you compose onto a player">Google Cast</DocsLinkCard>
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: GoogleCast
|
||||
frameworkTitle:
|
||||
html: google-cast
|
||||
description: Options for the Google Cast component that configures the receiver and load request
|
||||
---
|
||||
|
||||
import FrameworkCase from '@/components/docs/FrameworkCase.astro';
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
|
||||
|
||||
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 <DocsLink slug="reference/cast-button">CastButton</DocsLink>. See <DocsLink slug="concepts/cast">Google Cast</DocsLink> for how casting works.
|
||||
|
||||
## Anatomy
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
import { GoogleCast } from '@videojs/react/media/google-cast';
|
||||
|
||||
<GoogleCast />
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```html
|
||||
<google-cast></google-cast>
|
||||
```
|
||||
|
||||
Register the element by importing `@videojs/html/media/google-cast`.
|
||||
</FrameworkCase>
|
||||
|
||||
## Options
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
| Prop | Type | Description |
|
||||
|---|---|---|
|
||||
| `receiver` | `string` | Cast receiver application ID. Defaults to Google's Default Media Receiver (`CC1AD845`) |
|
||||
| `src` | `string` | Source URL loaded on the receiver. Defaults to the source the browser is playing |
|
||||
| `contentType` | `string` | MIME type of the Cast source. When unset, the receiver infers it from the URL |
|
||||
| `streamType` | `'on-demand' \| 'live'` | Stream type reported to the receiver. Falls back to the player's stream type |
|
||||
| `customData` | `object` | Custom data sent to the receiver with each load request |
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
| Attribute | Property | Description |
|
||||
|---|---|---|
|
||||
| `receiver` | `receiver` | Cast receiver application ID. Defaults to Google's Default Media Receiver (`CC1AD845`) |
|
||||
| `src` | `src` | Source URL loaded on the receiver. Defaults to the source the browser is playing |
|
||||
| `content-type` | `contentType` | MIME type of the Cast source. When unset, the receiver infers it from the URL |
|
||||
| `stream-type` | `streamType` | Stream type reported to the receiver. Falls back to the player's stream type |
|
||||
| — | `customData` | Custom data sent to the receiver with each load request |
|
||||
|
||||
`customData` takes an object, so it's a property only, with no matching attribute.
|
||||
</FrameworkCase>
|
||||
|
||||
When the Cast `src` is an HLS playlist, Video.js detects the segment format and sets the receiver's `hlsSegmentFormat` and `hlsVideoSegmentFormat` load-request fields. The Default Media Receiver plays HLS natively, so no extra receiver setup is needed.
|
||||
|
||||
## See also
|
||||
|
||||
<DocsLinkCard slug="concepts/cast" description="How casting works">Google Cast</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/cast-button">CastButton component reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/feature-remote-playback">Remote Playback feature reference</DocsLinkCard>
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: MuxData
|
||||
frameworkTitle:
|
||||
html: mux-data
|
||||
description: Options for the Mux Data component that monitors playback quality
|
||||
---
|
||||
|
||||
import FrameworkCase from '@/components/docs/FrameworkCase.astro';
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
|
||||
|
||||
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 <DocsLink slug="concepts/mux-data">Mux Data</DocsLink> for how monitoring works.
|
||||
|
||||
## Anatomy
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
import { MuxData } from '@videojs/react/media/mux-data';
|
||||
|
||||
<MuxData />
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```html
|
||||
<mux-data></mux-data>
|
||||
```
|
||||
|
||||
Register the element by importing `@videojs/html/media/mux-data`.
|
||||
</FrameworkCase>
|
||||
|
||||
## Options
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
| 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 |
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
| Attribute | Property | Description |
|
||||
|---|---|---|
|
||||
| `env-key` | `envKey` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
|
||||
| — | `metadata` | Mux Data metadata for the view |
|
||||
| `player-software-name` | `playerSoftwareName` | Player name reported to Mux Data |
|
||||
| `player-software-version` | `playerSoftwareVersion` | Player version reported to Mux Data. Defaults to the Video.js version |
|
||||
| `player-init-time` | `playerInitTime` | Epoch milliseconds the player was initialized. Defaults to when the element was created |
|
||||
| `beacon-collection-domain` | `beaconCollectionDomain` | Custom domain the beacons are sent to |
|
||||
| `disable-cookies` | `disableCookies` | Stops the SDK from setting cookies |
|
||||
| `debug` | `debug` | Turns on SDK debug logging |
|
||||
| — | `MuxDataSdk` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |
|
||||
|
||||
`metadata` and `MuxDataSdk` take objects, so they're properties only, with no matching attribute.
|
||||
</FrameworkCase>
|
||||
|
||||
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
|
||||
|
||||
<DocsLinkCard slug="concepts/mux-data" description="How monitoring works">Mux Data</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/mux-video">MuxVideo element reference</DocsLinkCard>
|
||||
<DocsLinkCard slug="reference/mux-audio">MuxAudio element reference</DocsLinkCard>
|
||||
@@ -25,6 +25,89 @@ import basicUsageHtmlTs from "@/components/docs/demos/mux-video/html/css/BasicUs
|
||||
|
||||
Video element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
|
||||
|
||||
## Load a source
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
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.
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
|
||||
MuxVideo takes Mux content two ways: a stream URL through `src`, or a structured `source` object.
|
||||
|
||||
```html
|
||||
<mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-video>
|
||||
```
|
||||
|
||||
The `source` object 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`.
|
||||
|
||||
```ts
|
||||
const video = document.querySelector('mux-video');
|
||||
video.source = {
|
||||
playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
|
||||
customDomain: 'media.example.com',
|
||||
playback: { maxResolution: '1080p' },
|
||||
};
|
||||
```
|
||||
|
||||
MuxVideo fires a `sourcechange` event when the source actually changes. Setting the same values again doesn't fire it.
|
||||
</FrameworkCase>
|
||||
|
||||
## 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.
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
```tsx
|
||||
<MuxVideo
|
||||
source={{
|
||||
playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
|
||||
playback: { token: playbackToken },
|
||||
thumbnail: { token: thumbnailToken },
|
||||
storyboard: { token: storyboardToken },
|
||||
}}
|
||||
/>
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
```ts
|
||||
const video = document.querySelector('mux-video');
|
||||
video.source = {
|
||||
playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
|
||||
playback: { token: playbackToken },
|
||||
thumbnail: { token: thumbnailToken },
|
||||
storyboard: { token: storyboardToken },
|
||||
};
|
||||
```
|
||||
</FrameworkCase>
|
||||
|
||||
## Analytics and casting
|
||||
|
||||
MuxVideo plays Mux streams. It doesn't monitor them or cast them — <DocsLink slug="concepts/mux-data">Mux Data</DocsLink> and <DocsLink slug="concepts/cast">Google Cast</DocsLink> 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:
|
||||
@@ -51,8 +134,8 @@ import { MuxVideo } from '@videojs/react/media/mux-video';
|
||||
Register the elements by importing `@videojs/html/media/mux-data` and `@videojs/html/media/google-cast`.
|
||||
</FrameworkCase>
|
||||
|
||||
<DocsLinkCard slug="concepts/mux-data">Mux Data — metadata, options, and configuration</DocsLinkCard>
|
||||
<DocsLinkCard slug="concepts/cast">Google Cast — receivers, load requests, and session state</DocsLinkCard>
|
||||
<DocsLinkCard slug="concepts/mux-data" description="Metadata, options, and configuration">Mux Data</DocsLinkCard>
|
||||
<DocsLinkCard slug="concepts/cast" description="Receivers, load requests, and session state">Google Cast</DocsLinkCard>
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -71,8 +71,10 @@ export const sidebar: Sidebar = [
|
||||
{ slug: 'reference/cast-button' },
|
||||
{ slug: 'reference/controls' },
|
||||
{ slug: 'reference/fullscreen-button' },
|
||||
{ slug: 'reference/google-cast' },
|
||||
{ slug: 'reference/menu' },
|
||||
{ slug: 'reference/mute-button' },
|
||||
{ slug: 'reference/mux-data' },
|
||||
{ slug: 'reference/pip-button' },
|
||||
{ slug: 'reference/play-button' },
|
||||
{ slug: 'reference/playback-rate-button' },
|
||||
|
||||
Reference in New Issue
Block a user