@videojs/html 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/how-to/build-your-own-component.md

@@ -0,0 +1,350 @@
+# Build your own UI component
+
+Create custom player controls that read state, dispatch actions, and stay accessible.
+
+Custom components subscribe to player state and dispatch actions, like built-in controls.
+
+## You might not need a custom component
+
+Before building from scratch, check if an existing approach covers your use case:
+
+*   **Restyle a control**: use CSS custom properties and data attributes. See [UI components](../concepts/ui-components.md).
+*   **Rearrange or remove controls**: eject a skin and modify it. See [Customize skins](./customize-skins.md#eject-and-edit-a-skin).
+
+Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+## Use player state and actions
+
+Need access to player state or actions? You’ll want to familiarize yourself with [features](../concepts/features.md). Each feature exposes a set. Here are some features you might reach for first:
+
+State
+
+Actions
+
+Feature
+
+`paused`, `ended`
+
+`play()`, `pause()`
+
+[Playback](../reference/feature-playback.md)
+
+`currentTime`, `duration`
+
+`seek()`
+
+[Time](../reference/feature-time.md)
+
+`volume`, `muted`
+
+`setVolume()`, `toggleMuted()`
+
+[Volume](../reference/feature-volume.md)
+
+`fullscreen`
+
+`requestFullscreen()`, `exitFullscreen()`
+
+[Fullscreen](../reference/feature-fullscreen.md)
+
+Browse the full list in the **Features** section of the sidebar.
+
+Features for platform-dependent capabilities also expose one or more **availability** properties (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
+
+Access state and actions with [`PlayerController`](../reference/player-controller.md) and a feature selector:
+
+ts
+
+```
+import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
+
+// Subscribe to a feature — triggers update() when its state changes
+#playback = new PlayerController(this, playerContext, selectPlayback);
+
+// In update():
+const playback = this.#playback.value;
+if (playback?.paused) {
+  playback.play();
+}
+```
+
+Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
+
+Without a selector, `PlayerController` returns the full store without subscribing to changes:
+
+ts
+
+```
+#store = new PlayerController(this, playerContext);
+
+// Call any action
+this.#store.value.play();
+this.#store.value.setVolume(0.5);
+```
+
+## Place your component in the player
+
+Your element needs to be inside [`<video-player>`](../reference/player.md) to access state. Place it inside [`<media-container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
+
+html
+
+```
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+    <skip-intro-button>Skip intro</skip-intro-button>
+  </video-skin>
+</video-player>
+```
+
+Extend `UIElement` from `@videojs/html` so `PlayerController` can schedule DOM updates when state changes:
+
+ts
+
+```
+import { UIElement, PlayerController, playerContext, selectTime, type PropertyValues } from '@videojs/html';
+
+class SkipIntroButtonElement extends UIElement {
+  #player = new PlayerController(this, playerContext, selectTime);
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#player.value;
+  }
+}
+```
+
+If your element starts listeners, observers, or other work, see [Custom element lifecycle](../concepts/custom-element-lifecycle.md) for how to clean it up when the element is removed from the page.
+
+## Make it accessible
+
+- [Learn more about accessibility in video players](../concepts/accessibility.md)
+
+## Full example
+
+A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
+
+skip-intro-button.ts
+
+skip-intro-button.css
+
+```
+import {
+  UIElement,
+  PlayerController,
+  playerContext,
+  selectTime,
+  selectPlayback,
+  type PropertyValues,
+} from '@videojs/html';
+
+class SkipIntroButtonElement extends UIElement {
+  #time = new PlayerController(this, playerContext, selectTime);
+  #playback = new PlayerController(this, playerContext, selectPlayback);
+  #disconnect: AbortController | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = new AbortController();
+    const { signal } = this.#disconnect;
+
+    this.setAttribute('role', 'button');
+    this.setAttribute('aria-label', 'Skip intro');
+    this.setAttribute('tabindex', '0');
+    this.addEventListener('click', this.#handleActivate, { signal });
+    this.addEventListener('keydown', this.#handleKeydown, { signal });
+    this.addEventListener('keyup', this.#handleKeyup, { signal });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // Removes all listeners registered with this signal
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#time.value;
+    const playback = this.#playback.value;
+
+    // Features are configured per-player, so a feature may not be available
+    if (!time || !playback) return;
+
+    const visible = time.currentTime < 30 && !playback.paused;
+    this.toggleAttribute('data-visible', visible);
+    this.setAttribute('tabindex', visible ? '0' : '-1');
+  }
+
+  #handleActivate = () => {
+    this.#time.value?.seek(30);
+  };
+
+  #handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      this.#handleActivate();
+    } else if (event.key === ' ') {
+      // Prevent Space from scrolling the page
+      event.preventDefault();
+    }
+  };
+
+  // ARIA button pattern: Space activates on keyup, not keydown
+  #handleKeyup = (event: KeyboardEvent) => {
+    if (event.key === ' ') {
+      this.#handleActivate();
+    }
+  };
+}
+
+customElements.define('skip-intro-button', SkipIntroButtonElement);
+```
+
+```
+skip-intro-button {
+  position: absolute;
+  bottom: 5rem;
+  right: 1rem;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 200ms;
+}
+
+skip-intro-button[data-visible] {
+  opacity: 1;
+  pointer-events: auto;
+}
+```
+
+Your element needs to be inside [`<video-player>`](../reference/player.md) to access state. Place it inside [`<media-container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
+
+html
+
+```
+<video-player>
+  <video-skin>
+    <video src="video.mp4"></video>
+    <skip-intro-button>Skip intro</skip-intro-button>
+  </video-skin>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/skin';
+  import './skip-intro-button.js';
+</script>
+```
+
+## How it works
+
+Custom components read player state and dispatch actions through [features](../concepts/features.md). Each feature exposes a set. Here are some features you might reach for first:
+
+State
+
+Actions
+
+Feature
+
+`paused`, `ended`
+
+`play()`, `pause()`
+
+[Playback](../reference/feature-playback.md)
+
+`currentTime`, `duration`
+
+`seek()`
+
+[Time](../reference/feature-time.md)
+
+`volume`, `muted`
+
+`setVolume()`, `toggleMuted()`
+
+[Volume](../reference/feature-volume.md)
+
+`fullscreen`
+
+`requestFullscreen()`, `exitFullscreen()`
+
+[Fullscreen](../reference/feature-fullscreen.md)
+
+Browse the full list in the **Features** section of the sidebar.
+
+Extend `MediaElement` from `@videojs/html` so [`PlayerController`](../reference/player-controller.md) can schedule DOM updates when state changes, and access state and actions with a feature selector:
+
+ts
+
+```
+import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
+
+// Subscribe to a feature — triggers update() when its state changes
+#playback = new PlayerController(this, playerContext, selectPlayback);
+
+// In update():
+const playback = this.#playback.value;
+if (playback?.paused) {
+  playback.play();
+}
+```
+
+Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
+
+Without a selector, `PlayerController` returns the full store without subscribing to changes. Create the controller with the typed context that [`createPlayer`](../reference/html-create-player.md) returns — the shared `playerContext` types the store’s members as `unknown` — and guard the value, which stays `undefined` until a player provides the store:
+
+ts
+
+```
+import { createPlayer, PlayerController } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { context } = createPlayer({ features: videoFeatures });
+
+#store = new PlayerController(this, context);
+
+// Call any action
+this.#store.value?.play();
+this.#store.value?.setVolume(0.5);
+```
+
+Custom controls also need real button semantics — the examples above set the accessible name, keyboard focus, and (in HTML, where there is no native `<button>`) the ARIA button pattern by hand.
+
+- [Learn more about accessibility in video players](../concepts/accessibility.md)
+
+## Availability and constraints
+
+*   Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
+*   Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
+
+## Common variations
+
+Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+### Restyle a control
+
+Use CSS custom properties and data attributes. See [UI components](../concepts/ui-components.md).
+
+### Rearrange or remove controls
+
+Eject a skin and modify it. See [Customize skins](./customize-skins.md#eject-and-edit-a-skin).
+
+## Troubleshooting
+
+### State and actions are typed as `unknown`
+
+You’re using the standalone `usePlayer` export or the shared `playerContext`, which don’t know which features your player has. In React, import `usePlayer` from your player’s preset (for example `@videojs/react/video`), or use the hook returned by `createPlayer` if you built the player with a custom feature set. In HTML, use the typed `context` returned by `createPlayer`.
+
+### The component renders but never updates
+
+In React, the component sits outside the player (such as `<VideoPlayer>`), so `usePlayer` has no store to subscribe to. In HTML, the element sits outside `<video-player>`, or the class doesn’t extend `MediaElement`, so `PlayerController` has nothing to schedule updates on.
+
+## Related API
+
+*   [usePlayer](/docs/framework/react/reference/use-player)
+*   [PlayerController](../reference/player-controller.md)
+*   [createPlayer](/docs/framework/react/reference/create-player)
+*   [Player container](../reference/player-container.md)
+
+## Related guides
+
+*   [Customize skins](./customize-skins.md)

package/docs/how-to/cast-to-airplay-and-chromecast.md

@@ -0,0 +1,179 @@
+# Cast to AirPlay and Chromecast
+
+Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
+
+Send playback to an Apple TV over AirPlay or a Chromecast over Google Cast while the browser stays in control.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Use the [GoogleCast extension](../reference/google-cast.md) with a [CastButton](../reference/cast-button.md), and add an [AirPlayButton](../reference/airplay-button.md) for Safari. The prebuilt skins already include both buttons; add `GoogleCast` next to a streaming media component to enable the configurable Cast route.
+
+Stop AirPlay Start AirPlay Stop casting Start casting
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+  <media-container>
+    <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
+    <google-cast></google-cast>
+    <div class="media-remote-buttons">
+      <media-airplay-button class="media-airplay-button">
+        <span class="connected">Stop AirPlay</span>
+        <span class="not-connected">Start AirPlay</span>
+      </media-airplay-button>
+      <media-cast-button class="media-cast-button">
+        <span class="connected">Stop casting</span>
+        <span class="disconnected">Start casting</span>
+      </media-cast-button>
+    </div>
+  </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-remote-buttons {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  display: flex;
+  gap: 8px;
+}
+
+.media-airplay-button,
+.media-cast-button {
+  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-airplay-button .connected,
+.media-airplay-button .not-connected,
+.media-cast-button .connected,
+.media-cast-button .disconnected {
+  display: none;
+}
+
+/* AirPlay: swap label on connection state */
+.media-airplay-button[data-airplay-state="connected"] .connected {
+  display: inline;
+}
+.media-airplay-button:not([data-airplay-state="connected"]) .not-connected {
+  display: inline;
+}
+
+/* Cast: swap label on connection state */
+.media-cast-button[data-cast-state="connected"] .connected {
+  display: inline;
+}
+.media-cast-button:not([data-cast-state="connected"]) .disconnected {
+  display: inline;
+}
+
+/* Explicitly disabled while the route is unavailable. */
+.media-airplay-button[data-disabled],
+.media-cast-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/extensions/google-cast';
+import '@videojs/html/media/hlsjs-video';
+import '@videojs/html/ui/airplay-button';
+import '@videojs/html/ui/cast-button';
+```
+
+The demo pairs the streaming media component with the `GoogleCast` extension in React or `<google-cast>` in HTML. Without that extension, `CastButton` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
+
+## How it works
+
+The [remote playback feature](../reference/feature-remote-playback.md) gives AirPlay and Google Cast one state shape:
+
+*   `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
+*   `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
+*   `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
+
+AirPlay uses WebKit’s presentation APIs. Google Cast uses a sender and receiver: the browser sends the receiver a media URL and then controls playback. Your UI reads the same Video.js state for either route.
+
+While connected, playback actions — play, pause, seek, volume — proxy to the remote device, and player state keeps reflecting the remote session. Local playback is suspended.
+
+The Google Cast SDK loads only when the `GoogleCast` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
+
+## Availability and constraints
+
+*   Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
+*   Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
+*   AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
+*   The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
+*   Set `disableRemotePlayback` on the media element to opt out entirely.
+
+## Common variations
+
+### Custom Cast receiver
+
+By default, Video.js sends the current source to Google’s Default Media Receiver. Set `receiver` when you have your own receiver application:
+
+html
+
+```
+<google-cast receiver="YOUR_APP_ID"></google-cast>
+```
+
+Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [GoogleCast reference](../reference/google-cast.md) for the exact option types and HTML property mapping.
+
+### Read connection state
+
+Use `remotePlaybackAvailability` to decide whether to offer a route and `remotePlaybackState` to show whether it is disconnected, connecting, or connected. `CastButton` and `AirPlayButton` already apply these states to their presentation; read them directly only when another part of your app needs them.
+
+## Troubleshooting
+
+### The cast button doesn’t render, or renders disabled
+
+The Cast button hides when the route is unsupported. In Chromium with no Cast device reachable, it stays visible but disabled. The AirPlay button hides unless Safari reports an AirPlay device.
+
+### Casting starts but the device shows an error
+
+The receiver cannot fetch the media. Confirm the source URL is reachable from the device and served with CORS headers, including caption tracks.
+
+### The UI freezes on “connecting”
+
+The user dismissed the picker or the device disconnected. `remotePlaybackState` returns to `'disconnected'`; drive your UI from that state.
+
+## Related components
+
+*   [Cast button](../reference/cast-button.md)
+*   [AirPlay button](../reference/airplay-button.md)
+*   [GoogleCast](../reference/google-cast.md)
+
+## Related API
+
+*   [Remote playback feature](../reference/feature-remote-playback.md)
+*   [HlsJsVideo](../reference/hlsjs-video.md)
+
+## Related guides
+
+*   [Media sources](../concepts/media-sources.md)