@videojs/react 10.0.0-beta.3 → 10.0.0-beta.30

package/docs/concepts/cast.md

@@ -0,0 +1,131 @@
+# Google Cast
+
+Cast playback to Chromecast devices with the Google Cast component, and configure the receiver and load request
+
+Add Google Cast to any Video.js streaming media element (HLS and DASH) by placing the Google Cast component next to it. Pair it with a [CastButton](../reference/cast-button.md) and users can move playback to a Chromecast device while the browser stays in control:
+
+App.tsx
+
+```
+import { CastButton, Container, createPlayer } from '@videojs/react';
+import { GoogleCast } from '@videojs/react/media/google-cast';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function App() {
+  return (
+    <Player>
+      <Container>
+        <HlsJsVideo
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <GoogleCast />
+        <CastButton />
+      </Container>
+    </Player>
+  );
+}
+```
+
+The component registers Google Cast with whichever media the player is using, so it works with any of the streaming media elements. The pre-built [skins](./skins.md) include a Cast button already. It appears when a Chromecast device is on the network and stays hidden otherwise.
+
+Caution
+
+Casting needs this component. Without it, [CastButton](../reference/cast-button.md) drives the browser’s native Remote Playback API rather than a Cast session, so receivers and load requests don’t apply.
+
+Note
+
+Cast only works in Chromium-based browsers (Chrome, Edge, and others built on Blink). On other browsers, `remotePlaybackAvailability` is `'unsupported'`.
+
+## How Cast works
+
+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, either Google’s default media receiver or a custom one you configure.
+
+### Session lifecycle
+
+A Cast session moves through three states, exposed by the [Remote Playback](../reference/feature-remote-playback.md) feature:
+
+State
+
+Meaning
+
+`'disconnected'`
+
+No active session
+
+`'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 forward to the Cast receiver. Local playback is suspended.
+
+### The lazy-loaded SDK
+
+Video.js injects the Cast SDK (`cast_sender.js`) as a `<script>` tag the first time a Google Cast component is added in a Chromium browser. Browsers that can’t cast — and players without the component — never load the SDK.
+
+Set `disableRemotePlayback` on the media element to opt out of remote playback entirely:
+
+tsx
+
+```
+<HlsJsVideo disableRemotePlayback />
+```
+
+## Configure Cast
+
+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:
+
+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"
+/>
+```
+
+The [GoogleCast reference](../reference/google-cast.md) 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
+
+Cast session state lives in the [Remote Playback](../reference/feature-remote-playback.md) feature slice. Subscribe with `selectRemotePlayback`:
+
+tsx
+
+```
+import { selectRemotePlayback, usePlayer } from '@videojs/react';
+
+function CastStatus() {
+  const remotePlayback = usePlayer(selectRemotePlayback);
+  if (!remotePlayback) return null;
+
+  return <span>{remotePlayback.remotePlaybackState}</span>;
+}
+```
+
+## 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). A [CastButton](../reference/cast-button.md) 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
+
+[GoogleCast reference](../reference/google-cast.md)
+
+[CastButton component reference](../reference/cast-button.md)
+
+[Remote Playback feature reference](../reference/feature-remote-playback.md)

package/docs/concepts/features.md

@@ -0,0 +1,142 @@
+# Features
+
+The state and actions each feature adds to the player
+
+Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
+
+## Using features
+
+### Feature bundles and presets
+
+You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
+
+For example, the `/video` preset configures `VideoPlayer` with `videoFeatures`, which bundles playback, volume, time, fullscreen, and more — everything a general video player needs:
+
+tsx
+
+```
+import { VideoPlayer, Video, VideoSkin } from '@videojs/react/video';
+
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="movie.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
+
+[Learn more about presets](./presets.md)
+
+### Create a player with individual features
+
+If you’re not using presets, you can create a player that has individual features.
+
+tsx
+
+```
+import { createPlayer, playbackFeature, volumeFeature, timeFeature, controlsFeature } from '@videojs/react';
+
+const { Player } = createPlayer({
+  features: [playbackFeature, volumeFeature, timeFeature, controlsFeature],
+});
+```
+
+### Extending a feature bundle
+
+Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
+
+tsx
+
+```
+import { createPlayer, playbackFeature } from '@videojs/react';
+import { backgroundFeatures } from '@videojs/react/background';
+
+const { Player } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+```
+
+### Access features in components
+
+You access feature state and actions through [`usePlayer`](../reference/use-player.md):
+
+tsx
+
+```
+// Subscribe to state (re-renders when selected values change)
+const { paused, volume } = usePlayer((s) => ({
+  paused: s.paused,
+  volume: s.volume,
+}));
+
+// Call actions
+const store = usePlayer();
+store.play();
+store.setVolume(0.8);
+```
+
+### Feature selectors
+
+Each feature also has a pre-built selector (e.g. [`selectPlayback`](../reference/feature-playback.md), [`selectVolume`](../reference/feature-volume.md)) that returns just that feature’s state and actions:
+
+tsx
+
+```
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+const playback = usePlayer(selectPlayback);
+playback?.play();
+```
+
+### Checking for feature support
+
+Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
+
+Value
+
+Meaning
+
+`'available'`
+
+Ready to use
+
+`'unavailable'`
+
+Could work, not ready yet
+
+`'unsupported'`
+
+Platform can never do this
+
+Components that depend on availability (like [`MuteButton`](../reference/mute-button.md), [`PiPButton`](../reference/pip-button.md), and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
+
+*   **`unsupported`** — the HTML custom element receives the native `hidden` attribute (and `data-hidden`); React buttons return `null`. No CSS needed.
+*   **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
+*   **`disabled` prop** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
+*   **`available`** — fully interactive.
+
+Use `data-disabled` to style the non-interactive state:
+
+css
+
+```
+.pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+You can also check availability in JS:
+
+PiPControl.tsx
+
+```
+function PiPControl() {
+  const availability = usePlayer((s) => s.pipAvailability);
+
+  if (availability !== 'available') return null;
+
+  return <PiPButton />;
+}
+```

package/docs/concepts/i18n.md

@@ -0,0 +1,317 @@
+# Internationalization
+
+How Video.js chooses a language and translates built-in player text
+
+Video.js displays its controls in English by default. Use internationalization when the player should match another language used by your site or application.
+
+Set the page language and add an internationalization provider around the player. Video.js then translates built-in labels, tooltips, status messages, and error text.
+
+## Choose the player language
+
+The provider reads the nearest `lang` attribute unless you give it a language directly. Setting `<html lang="es">` lets the page and player share Spanish.
+
+Mount `I18nProvider` inside the player `Provider`. Choose any shipped language to lazy-load its translations and update the player’s control labels.
+
+LanguageEnglishArabicAzerbaijaniBosnianBulgarianBanglaCatalanCzechWelshDanishGermanGreekSpanishEstonianBasquePersianFinnishFrenchScottish GaelicGalicianHebrewHindiCroatianHungarianIndonesianItalianJapaneseKoreanLithuanianLatvianMarathiNorwegian BokmålDutchNorwegian NynorskNepaliOccitanPolishBrazilian PortugueseEuropean PortugueseRomanianRussianSlovakSlovenianSerbianSwedishTeluguThaiTurkishUkrainianVietnameseChinese (China)Chinese (Taiwan)
+
+0:00
+
+0:00
+
+0:00
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider, LOCALES } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+import { useState } from 'react';
+
+import '@videojs/react/video/skin.css';
+import './Language.css';
+
+const { Player } = createPlayer({ features: videoFeatures });
+const locales = ['en', ...LOCALES] as const;
+type Locale = (typeof locales)[number];
+const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });
+
+export default function Language() {
+  const [locale, setLocale] = useState<Locale>('en');
+
+  return (
+    <div className="react-i18n-language">
+      <label>
+        Language
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          {locales.map((value) => (
+            <option key={value} value={value}>
+              {languageNames.of(value) ?? value}
+            </option>
+          ))}
+        </select>
+      </label>
+      <Player>
+        <I18nProvider locale={locale}>
+          <VideoSkin className="react-i18n-language__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+          </VideoSkin>
+        </I18nProvider>
+      </Player>
+    </div>
+  );
+}
+```
+```
+.react-i18n-language {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-i18n-language label {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-i18n-language select {
+  padding: 4px 8px;
+}
+
+.react-i18n-language__player {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+Pass `locale="es"` to `I18nProvider` when one player needs a different language from the rest of the page.
+
+Changing the active language updates mounted controls without remounting the player. See [Switch locale dynamically](../how-to/i18n-switch-locale.md) for complete examples.
+
+## How translated text works
+
+Each built-in piece of text has two parts:
+
+*   A stable key that identifies its meaning, such as `buttons.play`
+*   English fallback text, such as `Play`
+
+Translation packs replace the fallback for a language:
+
+ts
+
+```
+{
+  buttons: {
+    play: 'Reproducir',
+  },
+}
+```
+
+You can count on this key staying the same, even if we change the English wording. For example, if we changed “Play” to “Banana” in the UI, the key would still be `buttons.play`.
+
+You don’t have to include every key in a translation. Missing keys display their readable English fallback.
+
+Some translations include values supplied by the component. For example, `seek.forward` uses the English fallback `Seek forward {seconds} seconds`. When you write a translation, make sure to include `{seconds}` where the number should appear.
+
+See [Translation keys](../reference/translation-phrases.md) for the complete list of keys, English defaults, and the controls that use them.
+
+## Where translations come from
+
+Video.js looks for translated text in these places:
+
+1.  Overrides supplied to the current player
+2.  Registered custom translations
+3.  A built-in locale pack
+4.  The component’s English fallback
+
+Choose a source, then hover the play button to see its resolved label.
+
+Player override
+
+Registered
+
+Built-in
+
+Fallback
+
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function Override() {
+  return (
+    <Player>
+      <I18nProvider locale="en" translations={{ buttons: { play: 'Player override' } }}>
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider, registerI18n } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+registerI18n('en-x-demo', {
+  buttons: {
+    play: 'Registered custom translation',
+  },
+});
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function Registered() {
+  return (
+    <Player>
+      <I18nProvider locale="en-x-demo">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BuiltIn() {
+  return (
+    <Player>
+      <I18nProvider locale="es">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function Fallback() {
+  return (
+    <Player>
+      <I18nProvider locale="en">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player>
+  );
+}
+```
+
+Built-in packs load when the provider first encounters their language. You do not need to import Spanish, French, or another shipped language for normal client-rendered players.
+
+The `translations` prop on `I18nProvider` overrides text for that provider subtree:
+
+tsx
+
+```
+<I18nProvider locale="es" translations={{ buttons: { play: 'Comenzar' } }}>
+  <VideoSkin>...</VideoSkin>
+</I18nProvider>
+```
+
+Use [`registerI18n`](../reference/register-i18n.md) when you have a custom locale or want an override to apply across players:
+
+ts
+
+```
+registerI18n('es', {
+  buttons: {
+    play: 'Comenzar',
+  },
+});
+```
+
+If registered and built-in translations still leave text missing, Video.js automatically tries Chrome’s [Browser Translation API](https://developer.mozilla.org/en-US/docs/Web/API/Translator). You do not need to call the API. This fallback only runs when Chrome exposes the API and the required on-device model is already installed. Video.js does not download the model. Use reviewed locale packs for production-critical text.
+
+## Locale fallback
+
+Language tags follow the [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent chain. A player using Mexican Spanish checks `es-MX`, then `es`, before falling back to English:
+
+txt
+
+```
+es-MX → es → en
+```
+
+This lets a regional pack override only the text that differs from its parent language.
+
+## Avoid a flash of English
+
+Built-in packs normally load after the provider mounts. A player can briefly show English during server rendering or the first switch to a language.
+
+Preload or register translations before rendering when the first translated paint matters:
+
+[Render translated text during SSR](../how-to/i18n-ssr.md)
+
+[Preload languages before switching](../how-to/i18n-switch-locale.md)
+
+Tip
+
+Use [Override translations](../how-to/i18n-override-translations.md) to customize built-in text or provide your own visible component text.