npm - @videojs/react - Versions diffs - 10.0.0-beta.25 → 10.0.0-beta.26 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1594) hide show

package/docs/concepts/i18n.md ADDED Viewed

@@ -0,0 +1,327 @@
+# 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 GaelicGalicianHebrewHindiCroatianHungarianItalianJapaneseKoreanLatvianMarathiNorwegian BokmålDutchNorwegian NynorskNepaliOccitanPolishBrazilian PortugueseEuropean PortugueseRomanianRussianSlovakSlovenianSerbianSwedishTeluguThaiTurkishUkrainianVietnameseChinese (China)Chinese (Taiwan)
+0:00
+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.Provider>
+        <I18nProvider locale={locale}>
+          <VideoSkin className="react-i18n-language__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+          </VideoSkin>
+        </I18nProvider>
+      </Player.Provider>
+    </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
+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.Provider>
+      <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.Provider>
+  );
+}
+```
+0:00
+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.Provider>
+      <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.Provider>
+  );
+}
+```
+0:00
+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.Provider>
+      <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.Provider>
+  );
+}
+```
+0:00
+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.Provider>
+      <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.Provider>
+  );
+}
+```
+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.

package/docs/concepts/mux-data.md ADDED Viewed

@@ -0,0 +1,84 @@
+# Mux Data
+Monitor playback quality and viewer experience by adding the Mux Data component to a player
+[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:
+App.tsx
+```
+import { createPlayer } from '@videojs/react';
+import { MuxData } from '@videojs/react/media/mux-data';
+import { MuxVideo } from '@videojs/react/media/mux-video';
+import { videoFeatures } from '@videojs/react/video';
+const Player = createPlayer({ features: videoFeatures });
+export default function App() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
+        <MuxData />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+That’s the whole setup for Mux-hosted playback — no environment key required. The component renders nothing; place it inside the player, as a sibling of the media element.
+Note
+Mux Data is opt-in. No media element monitors playback on its own, Mux ones included, so nothing is measured and no beacons are sent until you add this component.
+## Environment key
+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, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
+tsx
+```
+<HlsJsVideo src="https://example.com/stream.m3u8" />
+<MuxData envKey="YOUR_ENV_KEY" />
+```
+An explicit key always wins, so set one to send Mux-hosted views to a specific environment.
+## Any media element works
+The component attaches to the media the player is using, not to a specific element type, so it monitors [MuxVideo](../reference/mux-video.md), [HlsJsVideo](../reference/hlsjs-video.md), [DashVideo](../reference/dash-video.md), and the rest alike. When the media exposes an [hls.js](https://github.com/video-dev/hls.js/) engine, the component hands that engine to the Mux Data SDK so it can report stream-level detail alongside the playback metrics.
+The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.
+## Describe the view
+Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:
+tsx
+```
+<MuxData metadata={{ video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' }} />
+```
+## Configuration
+The [MuxData reference](../reference/mux-data.md) 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
+[MuxData reference](../reference/mux-data.md)
+[MuxVideo element reference](../reference/mux-video.md)
+[MuxAudio element reference](../reference/mux-audio.md)
+[
+Google Cast
+The other media component you compose onto a player
+](./cast.md)

package/docs/concepts/security.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Security
+How to configure Content Security Policy for your video player
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+## Allow player resources
+*   `media-src` must allow your media URLs.
+*   `img-src` must allow any poster or thumbnail image URLs.
+*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+*   `worker-src blob:` is required when using the `hls.js` player variants.
+*   `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
+## Example
+http
+```
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.