From fa768da75777e4931e04f94db14c3c7e09e83398 Mon Sep 17 00:00:00 2001
From: Manuel Calleriza <mcalleriza@mux.com>
Date: Thu, 18 Jun 2026 15:42:19 -0300
Subject: [PATCH] docs(site): add Google Cast documentation (#1681)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../cast-button/html/css/BasicUsage.astro     |   9 +
 .../demos/cast-button/html/css/BasicUsage.css |  39 +++
 .../cast-button/html/css/BasicUsage.html      |  15 ++
 .../demos/cast-button/html/css/BasicUsage.ts  |   3 +
 .../cast-button/react/css/BasicUsage.css      |  25 ++
 .../cast-button/react/css/BasicUsage.tsx      |  27 +++
 site/src/content/docs/concepts/cast.mdx       | 225 ++++++++++++++++++
 .../content/docs/reference/cast-button.mdx    | 117 +++++++++
 .../reference/feature-remote-playback.mdx     |   3 +
 site/src/docs.config.ts                       |   2 +
 10 files changed, 465 insertions(+)
 create mode 100644 site/src/components/docs/demos/cast-button/html/css/BasicUsage.astro
 create mode 100644 site/src/components/docs/demos/cast-button/html/css/BasicUsage.css
 create mode 100644 site/src/components/docs/demos/cast-button/html/css/BasicUsage.html
 create mode 100644 site/src/components/docs/demos/cast-button/html/css/BasicUsage.ts
 create mode 100644 site/src/components/docs/demos/cast-button/react/css/BasicUsage.css
 create mode 100644 site/src/components/docs/demos/cast-button/react/css/BasicUsage.tsx
 create mode 100644 site/src/content/docs/concepts/cast.mdx
 create mode 100644 site/src/content/docs/reference/cast-button.mdx

diff --git a/site/src/components/docs/demos/cast-button/html/css/BasicUsage.astro b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.astro
new file mode 100644
index 00000000..c515bacd
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.astro
@@ -0,0 +1,9 @@
+---
+import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
+import html from './BasicUsage.html?raw';
+---
+
+<HtmlDemo html={html} />
+<script>
+  import "./BasicUsage.ts";
+</script>
diff --git a/site/src/components/docs/demos/cast-button/html/css/BasicUsage.css b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.css
new file mode 100644
index 00000000..fb784796
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.css
@@ -0,0 +1,39 @@
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player 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;
+}
+
+.media-cast-button .connected {
+  display: none;
+}
+.media-cast-button .disconnected {
+  display: none;
+}
+.media-cast-button[data-cast-state="connected"] .connected {
+  display: inline;
+}
+.media-cast-button:not([data-cast-state="connected"]) .disconnected {
+  display: inline;
+}
diff --git a/site/src/components/docs/demos/cast-button/html/css/BasicUsage.html b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.html
new file mode 100644
index 00000000..7badc5e9
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.html
@@ -0,0 +1,15 @@
+<video-player class="video-player">
+    <media-container>
+        <hls-video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></hls-video>
+        <media-cast-button class="media-cast-button">
+            <span class="connected">Stop casting</span>
+            <span class="disconnected">Start casting</span>
+        </media-cast-button>
+    </media-container>
+</video-player>
diff --git a/site/src/components/docs/demos/cast-button/html/css/BasicUsage.ts b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.ts
new file mode 100644
index 00000000..77a1999f
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/html/css/BasicUsage.ts
@@ -0,0 +1,3 @@
+import '@videojs/html/video/player';
+import '@videojs/html/media/hls-video';
+import '@videojs/html/ui/cast-button';
diff --git a/site/src/components/docs/demos/cast-button/react/css/BasicUsage.css b/site/src/components/docs/demos/cast-button/react/css/BasicUsage.css
new file mode 100644
index 00000000..ca5562b7
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/react/css/BasicUsage.css
@@ -0,0 +1,25 @@
+.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;
+}
diff --git a/site/src/components/docs/demos/cast-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/cast-button/react/css/BasicUsage.tsx
new file mode 100644
index 00000000..72ac1769
--- /dev/null
+++ b/site/src/components/docs/demos/cast-button/react/css/BasicUsage.tsx
@@ -0,0 +1,27 @@
+import { CastButton, createPlayer } from '@videojs/react';
+import { HlsVideo } from '@videojs/react/media/hls-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <HlsVideo
+          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>
+  );
+}
diff --git a/site/src/content/docs/concepts/cast.mdx b/site/src/content/docs/concepts/cast.mdx
new file mode 100644
index 00000000..a3907ee5
--- /dev/null
+++ b/site/src/content/docs/concepts/cast.mdx
@@ -0,0 +1,225 @@
+---
+title: Google Cast
+description: How to add Chromecast support to your Video.js player — lazy SDK loading, session lifecycle, and configuration options
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+import Aside from '@/components/Aside.astro';
+
+Video.js has built-in Google Cast support for HLS and DASH media elements. When a Chromecast device is on the same network, a Cast button appears automatically in Chromium browsers. Tapping it starts a session that moves playback to the TV while the browser stays in control.
+
+<Aside type="note">
+Cast is only available in Chromium-based browsers (Chrome, Edge, and others built on Blink). On other browsers, `remotePlaybackAvailability` is `'unsupported'`.
+</Aside>
+
+## How Cast works
+
+Cast uses a **sender / receiver** model:
+
+- **Sender** — the browser tab. It controls playback commands (play, pause, seek, volume) and sends a load request to the receiver with the source URL and metadata.
+- **Receiver** — the Chromecast device running the default media receiver application (or a custom receiver you configure).
+
+### Session lifecycle
+
+A Cast session moves through three states, exposed via the <DocsLink slug="reference/feature-remote-playback">Remote Playback</DocsLink> feature:
+
+| State | Meaning |
+|---|---|
+| `'disconnected'` | No active session |
+| `'connecting'` | User accepted; session negotiating |
+| `'connected'` | Receiver is playing |
+
+While `connected`, the media element's `play`, `pause`, `currentTime`, `volume`, `muted`, and `playbackRate` all proxy to the Cast receiver. Local playback is suspended.
+
+### The lazy-loaded SDK
+
+The Cast SDK (`cast_sender.js`) is injected into the page as a `<script>` tag the first time a Cast-capable media element is created in a Chromium browser. No SDK cost is paid on browsers that don't support Cast.
+
+Set `disableRemotePlayback` on the media element to opt out:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<HlsVideo disableRemotePlayback />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<hls-video disableremoteplayback></hls-video>
+```
+</FrameworkCase>
+
+## Minimal setup
+
+Cast works out of the box with the `videoFeatures` preset — no extra configuration needed. Add a `CastButton` to give users a way to start and stop a session:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { createPlayer, CastButton } from '@videojs/react';
+import { HlsVideo } from '@videojs/react/media/hls-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function App() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <HlsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
+        <CastButton />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <media-container>
+    <hls-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hls-video>
+    <media-cast-button></media-cast-button>
+  </media-container>
+</video-player>
+```
+</FrameworkCase>
+
+## Configuring Cast
+
+All Cast configuration is set via the `config.googleCast` property. In React, pass it as a declarative prop. In HTML, set it as a JavaScript property; HTML attributes are not supported.
+
+### Custom receiver application ID
+
+By default, Video.js uses 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
+<HlsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" config={{ googleCast: { receiver: 'YOUR_APP_ID' } }} />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+const video = document.querySelector('hls-video');
+video.config = { googleCast: { receiver: 'YOUR_APP_ID' } };
+```
+</FrameworkCase>
+
+### Custom data on load
+
+Pass arbitrary data to the receiver with each load request via `customData`. The receiver app reads it from the `customData` field of the load request:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<HlsVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+  config={{ googleCast: { customData: { token: 'abc123', userId: 'u_789' } } }}
+/>
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+const video = document.querySelector('hls-video');
+video.config = { googleCast: { customData: { token: 'abc123', userId: 'u_789' } } };
+```
+</FrameworkCase>
+
+### Cast source override
+
+By default the receiver loads the same URL as the browser. Use `src` (and optionally `contentType`) to send a different URL, for example, a separate manifest or CDN-edge URL accessible from the TV network:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<HlsVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+  config={{ googleCast: { src: 'https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8', contentType: 'application/x-mpegURL' } }}
+/>
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+const video = document.querySelector('hls-video');
+video.config = {
+  googleCast: {
+    src: 'https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8',
+    contentType: 'application/x-mpegURL',
+  },
+};
+```
+</FrameworkCase>
+
+### HLS on the receiver
+
+When the source (or `config.googleCast.src`) is an HLS playlist, Video.js automatically detects the segment format (TS or fMP4) by inspecting the playlist and sets `hlsSegmentFormat` / `hlsVideoSegmentFormat` on the Cast load request. The default media receiver handles HLS natively, so no extra configuration is needed.
+
+Use `streamType` to tell the receiver whether the stream is `'on-demand'` or `'live'` (falls back to the player's `streamType` when unset):
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<HlsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" config={{ googleCast: { streamType: 'live' } }} />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+const video = document.querySelector('hls-video');
+video.config = { googleCast: { streamType: 'live' } };
+```
+</FrameworkCase>
+
+## Cast state and selectors
+
+Cast session state lives in the <DocsLink slug="reference/feature-remote-playback">Remote Playback</DocsLink> feature slice. Use `selectRemotePlayback` to subscribe:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { selectRemotePlayback, usePlayer } from '@videojs/react';
+
+function CastStatus() {
+  const remotePlayback = usePlayer(selectRemotePlayback);
+  if (!remotePlayback) return null;
+
+  return <span>{remotePlayback.remotePlaybackState}</span>;
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+import { PlayerController, playerContext, selectRemotePlayback } from '@videojs/html';
+
+class CastStatus extends HTMLElement {
+  readonly #remotePlayback = new PlayerController(this, playerContext, selectRemotePlayback);
+}
+```
+</FrameworkCase>
+
+## Browser availability
+
+Cast availability is surfaced as `remotePlaybackAvailability` on the remote playback feature. Hide the button when unsupported:
+
+<FrameworkCase frameworks={["html"]}>
+```css
+media-cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```css
+.cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+</FrameworkCase>
+
+## See also
+
+<DocsLinkCard slug="reference/cast-button">CastButton component reference</DocsLinkCard>
+<DocsLinkCard slug="reference/feature-remote-playback">Remote Playback feature reference</DocsLinkCard>
diff --git a/site/src/content/docs/reference/cast-button.mdx b/site/src/content/docs/reference/cast-button.mdx
new file mode 100644
index 00000000..b7697fdf
--- /dev/null
+++ b/site/src/content/docs/reference/cast-button.mdx
@@ -0,0 +1,117 @@
+---
+title: CastButton
+frameworkTitle:
+  html: media-cast-button
+description: Accessible Cast toggle button with state reflection and keyboard support
+---
+
+import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import StyleCase from "@/components/docs/StyleCase.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
+
+{/* React demos */}
+import BasicUsageDemoReact from "@/components/docs/demos/cast-button/react/css/BasicUsage";
+import basicUsageReactTsx from "@/components/docs/demos/cast-button/react/css/BasicUsage.tsx?raw";
+import basicUsageReactCss from "@/components/docs/demos/cast-button/react/css/BasicUsage.css?raw";
+
+{/* HTML demos */}
+import BasicUsageDemoHtml from "@/components/docs/demos/cast-button/html/css/BasicUsage.astro";
+import basicUsageHtml from "@/components/docs/demos/cast-button/html/css/BasicUsage.html?raw";
+import basicUsageHtmlCss from "@/components/docs/demos/cast-button/html/css/BasicUsage.css?raw";
+import basicUsageHtmlTs from "@/components/docs/demos/cast-button/html/css/BasicUsage.ts?raw";
+
+## Anatomy
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<CastButton />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-cast-button></media-cast-button>
+```
+</FrameworkCase>
+
+## 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:
+
+<FrameworkCase frameworks={["html"]}>
+```css
+/* During an active session */
+media-cast-button[data-cast-state="connected"] {
+  color: blue;
+}
+
+/* Hide when Cast is unsupported (non-Chromium browsers) */
+media-cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+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;
+}
+```
+</FrameworkCase>
+
+## 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: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
+## Examples
+
+### Basic Usage
+
+<FrameworkCase frameworks={["react"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
+      { title: "App.css", code: basicUsageReactCss, lang: "css" },
+    ]}>
+      <BasicUsageDemoReact client:idle />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "index.html", code: basicUsageHtml, lang: "html" },
+      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
+      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
+    ]}>
+      <BasicUsageDemoHtml />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
+<ComponentReference component="CastButton" />
diff --git a/site/src/content/docs/reference/feature-remote-playback.mdx b/site/src/content/docs/reference/feature-remote-playback.mdx
index f459f973..fa512919 100644
--- a/site/src/content/docs/reference/feature-remote-playback.mdx
+++ b/site/src/content/docs/reference/feature-remote-playback.mdx
@@ -5,10 +5,13 @@ description: Remote playback state and actions for the player store
 
 import FeatureReference from "@/components/docs/api-reference/FeatureReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
+import DocsLinkCard from "@/components/docs/DocsLinkCard.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 Controls remote playback to devices like Chromecast (Chromium) and AirPlay (Safari). Exits fullscreen before initiating a remote playback session.
 
+<DocsLinkCard slug="concepts/cast">Google Cast concept guide — setup, configuration, and HLS</DocsLinkCard>
+
 <FeatureReference feature="remotePlayback" />
 
 ### Selector
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index c299efaf..64cc3731 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -35,6 +35,7 @@ export const sidebar: Sidebar = [
     llmsDescription:
       'Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.',
     contents: [
+      { slug: 'concepts/cast', sidebarLabel: 'Google Cast' },
       { slug: 'concepts/features' },
       { slug: 'concepts/skins' },
       { slug: 'concepts/presets' },
@@ -62,6 +63,7 @@ export const sidebar: Sidebar = [
       { slug: 'reference/airplay-button' },
       { slug: 'reference/buffering-indicator' },
       { slug: 'reference/captions-button' },
+      { slug: 'reference/cast-button' },
       { slug: 'reference/controls' },
       { slug: 'reference/fullscreen-button' },
       { slug: 'reference/mute-button' },