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

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

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 (1994) hide show

package/docs/concepts/i18n.md ADDED Viewed

@@ -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.

package/docs/concepts/media-sources.md ADDED Viewed

@@ -0,0 +1,383 @@
+# Media sources
+Set what a media element plays and how its engine plays it with the structured source property
+Every media element takes a `src`. Elements that drive a playback engine also take `source`, a structured object that carries the URL alongside everything else about that source:
+tsx
+```
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/stream.m3u8',
+    preferPlayback: 'mse',
+    engine: { hlsJs: { maxBufferLength: 60 } },
+  }}
+/>
+```
+## Three tiers, three homes
+The shape answers one question: does this option describe the source, or how to play it?
+Tier
+Home
+Example
+Which source to play
+`source.src`, or an element’s own identity fields
+`src`, `MuxVideo`’s `playbackId`
+How to interpret it
+`source.type`
+`'video/mp4'`
+How Video.js plays it
+`source`, at the top level
+`preferPlayback`
+How a specific engine behaves
+`source.engine`, under that engine’s name
+hls.js’s `maxBufferLength`, in `source.engine.hlsJs`
+A side-car component’s own settings
+that component’s props
+[Mux Data](./mux-data.md), [Google Cast](./cast.md)
+`type` is worth reaching for when the URL lies about its contents. Video.js infers the content type from the file extension, so a manifest served from an extensionless or signed URL may need to say so explicitly:
+tsx
+```
+<HlsJsVideo source={{ src: 'https://example.com/asset?id=42', type: 'application/vnd.apple.mpegurl' }} />
+```
+## `src` and `source` stay in sync
+They are two views of the same thing, and writing either updates the other. Setting `source` derives `src`. Setting `src` replaces only the identity half and **keeps the rest, such as `type` and the engine options, intact**:
+tsx
+```
+<HlsJsVideo source={{ src: 'https://example.com/a.m3u8', preferPlayback: 'native' }} />
+```
+A `sourcechange` event fires whenever `source` changes, from either direction.
+## Assigning `source` replaces it
+`source` is not merged. A new object is a fresh start, and keys you leave out are dropped:
+tsx
+```
+<HlsJsVideo source={{ src, type: 'video/mp4', preferPlayback: 'native' }} />
+// later: type and preferPlayback are gone, because the new object omits them
+<HlsJsVideo source={{ src }} />
+```
+## Equivalent sources cost nothing
+Sources are compared **structurally**, not by reference. Reassigning an object with the same values is a no-op — no reload, and no engine teardown:
+tsx
+```
+// A fresh object literal on every render. Nothing reloads.
+<HlsJsVideo source={{ src, engine: { hlsJs: { maxBufferLength: 60 } } }} />
+```
+This is why you can write `source` inline. React hands the element a brand new object every render, and the element recognizes it as the same source. There’s no need to memoize it or spread the previous value to avoid clobbering anything.
+Only a change to the engine options, `preferPlayback`, or the resolved content type recreates the playback engine.
+Note
+`source` holds an object, so it’s a property, not an attribute — there is no `source=""` in HTML. `src` remains the attribute, and it’s the one to reach for when your markup only names a URL.
+## Engine options
+Engine options live under `source.engine`, **namespaced by engine**. Each key there holds that engine’s own configuration object, handed over untouched — there’s no Video.js wrapper around it, so whatever the engine documents works:
+Key
+Elements that read it
+It holds
+`engine.hlsJs`
+[HlsJsVideo](../reference/hlsjs-video.md), [MuxVideo](../reference/mux-video.md), [MuxAudio](../reference/mux-audio.md)
+an [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning)
+`engine.nativeHls`
+[NativeHlsVideo](../reference/native-hls-video.md), and the three above whenever the browser plays the manifest
+options for the browser’s own HLS support (today, [DRM](#licensing-one-engine-differently))
+`engine.dashJs`
+[DashVideo](../reference/dash-video.md)
+[dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html)
+`engine.vimeo`
+`VimeoVideo`
+[Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed)
+`engine.youtube`
+`YouTubeVideo`
+[YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters)
+Naming the engine rather than using one generic key matters where an element has more than one to choose from. `HlsJsVideo` plays through hls.js or through the browser depending on the platform and `preferPlayback`, and only one of them runs — so a single source can describe both paths without either engine reading the other’s options.
+hls.js reads its options when the engine is constructed, so changing them tears down the engine and builds a new one:
+tsx
+```
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/stream.m3u8',
+    engine: { hlsJs: { maxBufferLength: 60, enableWorker: false } },
+  }}
+/>
+```
+dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
+tsx
+```
+<DashVideo
+  source={{
+    src: 'https://example.com/manifest.mpd',
+    engine: { dashJs: { streaming: { abr: { maxBitrate: { video: 2000 } } } } },
+  }}
+/>
+```
+Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.
+### Options Video.js normalizes
+Where an option means the same thing across engines, it sits on `source` itself rather than inside an engine’s namespace.
+`preferPlayback` picks between [hls.js](https://github.com/video-dev/hls.js/) and the browser’s own HLS support:
+tsx
+```
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', preferPlayback: 'native' }} />
+```
+It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `HlsJsVideo`, `MuxVideo`, and `MuxAudio` accept it; DASH and Vimeo have no second playback path.
+## DRM protected sources
+Protected content is licensed through `source.drm`, keyed by EME key system id — alongside the URL rather than inside an engine’s namespace, because which engine plays the manifest is decided later and both paths read it:
+tsx
+```
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/protected.m3u8',
+    drm: {
+      'com.apple.fps': {
+        licenseUrl: 'https://license.example.com/fairplay',
+        serverCertificateUrl: 'https://license.example.com/fairplay-cert',
+      },
+      'com.widevine.alpha': { licenseUrl: 'https://license.example.com/widevine' },
+      'com.microsoft.playready': { licenseUrl: 'https://license.example.com/playready' },
+    },
+  }}
+/>
+```
+Name every system you hold a license server for — which one gets used is the browser’s choice. `serverCertificateUrl` is the DRM server (application) certificate FairPlay requires; Widevine and PlayReady ignore it.
+### What each path can license
+The same `drm` reaches both playback paths, and how far it gets is the one thing worth knowing about each:
+Path
+Key systems it negotiates
+What Video.js does with `drm`
+hls.js (MSE)
+FairPlay, Widevine, PlayReady
+Hands it to hls.js as `drmSystems`, with `emeEnabled` switched on
+The browser’s own HLS
+FairPlay
+Answers the element’s key requests itself: POSTs the CDM’s license request to `licenseUrl` and hands the response back
+So a source naming only Widevine plays through hls.js and cannot play on the native path — [NativeHlsVideo](../reference/native-hls-video.md), or any HLS element the browser ends up playing the manifest for. Video.js says so in development, and encrypted media that gets there with no `com.apple.fps` license server fails with a `MEDIA_ERR_ENCRYPTED` error rather than hanging.
+For Widevine on hls.js, Video.js asks for a hardware-backed CDM first, falling back to whatever robustness the browser offers, so content restricted to L1 devices plays where it can. Supplying your own `requestMediaKeySystemAccessFunc` replaces that entirely.
+### Licensing one engine differently
+An engine’s own `drmSystems` **replaces** `source.drm`, for that engine alone. Reach for it when one path licenses differently, or when you need more of [hls.js’s DRM configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#drmsystems) than `drm` covers:
+It replaces rather than merges, so the FairPlay server above is gone as far as hls.js is concerned. `engine.nativeHls.drmSystems` does the same for the native path.
+## Mux sources name a playback ID
+[MuxVideo](../reference/mux-video.md) and [MuxAudio](../reference/mux-audio.md) identify a source by `playbackId` rather than a URL, and derive `src` from it. Everything else works the same, engine options included:
+tsx
+```
+<MuxVideo
+  source={{
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    playback: { maxResolution: '1080p' },
+    engine: { hlsJs: { maxBufferLength: 60 } },
+  }}
+  playsInline
+/>
+```
+Setting a Mux stream URL as `src` works too — the element parses the playback ID and query params back out into `source`. To play something Mux doesn’t host, name it with `src` inside `source`; engine options still apply.
+Two more source params describe images rather than playback. `source.storyboard` and `source.poster` carry the modifiers for the storyboard VTT and the poster still — both belong to the source, since a signed token scopes them to one playback ID:
+tsx
+```
+<MuxVideo source={{ playbackId, storyboard: { format: 'jpg' }, poster: { time: 12 } }} playsInline />
+```
+`MuxVideo` uses the storyboard itself, adding the thumbnail `<track>` for you so hover previews work without extra markup. Live streams have no storyboard, so the track is dropped once the stream type is known, and signed playback without a matching storyboard token adds none.
+### Mux signs DRM with a token
+Mux serves FairPlay, Widevine, and PlayReady from URLs derived from a single license token, so `source.drm` takes that token in place of the license servers it would otherwise name. Mux fills the rest in for you, so protected media plays whichever path the browser takes:
+tsx
+```
+<MuxVideo
+  source={{
+    playbackId,
+    playback: { token: playbackToken },
+    drm: { token: drmToken },
+  }}
+  playsInline
+/>
+```
+DRM playback is always signed, so a `playback.token` belongs alongside it — and `poster.token` / `storyboard.token` for the images. Each is scoped to a different audience, so they are four separate tokens rather than one reused four times. Sign them on your server; see [Mux’s DRM guide](https://www.mux.com/docs/guides/protect-videos-with-drm) for how.
+A `drm.token` that isn’t scoped to DRM is ignored rather than sent, since the license request would be rejected. License servers named alongside the token win, key by key, for the systems Mux doesn’t license:
+`source.poster` gets no such treatment — it’s only data, and nothing applies it to the media. Both URLs are readable from `contentData`, keyed by what each one describes:
+ts
+```
+media.contentData;
+// {
+//   poster: 'https://image.mux.com/PLAYBACK_ID/thumbnail.webp?time=12',
+//   storyboard: 'https://image.mux.com/PLAYBACK_ID/storyboard.vtt?format=jpg',
+// }
+```
+It’s read-only and derived from `source`, so read it again after `sourcechange`. A key is missing when its URL can’t be built: no playback ID, or signed playback with no matching image token. Changing the URLs means changing the params they’re built from.
+`source.poster` takes the [full set of Mux image modifiers](https://www.mux.com/docs/guides/get-images-from-a-video), so a narrower still for a small viewport is a `width`:
+tsx
+```
+<MuxVideo source={{ playbackId, poster: { width: 320 } }} playsInline />
+```
+## Elements without engine options
+[HlsVideo](../reference/hls-video.md) and [HlsAudio](../reference/hls-audio.md) take `src` and the usual media attributes but expose no `source`. They run on our own playback engine, which does not accept configuration from the element yet.
+## Migrate from `config`
+Media elements used to take a `config` object: one untyped bag holding engine options, source overrides, and component settings at once. It’s gone, and each of its keys now has a specific home:
+Before
+After
+`config.preferPlayback`
+`source.preferPlayback`
+`config.contentType`
+`source.type`
+`config.hlsJs`
+`source.engine.hlsJs`
+`config.dashJs`
+`source.engine.dashJs`
+`config.muxData`
+the [Mux Data](./mux-data.md) component’s own props
+`config.googleCast`
+the [Google Cast](./cast.md) component’s own props
+`config` on VimeoVideo
+`source.engine.vimeo`
+The engine keys keep their names, so their contents move across unchanged — what moves is the object they sit in.
+tsx
+```
+// Before
+<HlsJsVideo src={src} config={{ preferPlayback: 'native', hlsJs: { maxBufferLength: 60 } }} />
+// After
+<HlsJsVideo source={{ src, preferPlayback: 'native', engine: { hlsJs: { maxBufferLength: 60 } } }} />
+```
+`<hls-video>` and `<hls-audio>` accepted a `config` that nothing read. Remove it — those elements never applied it.
+## See also
+[HlsJsVideo element reference](../reference/hlsjs-video.md)
+[MuxVideo element reference](../reference/mux-video.md)
+[DashVideo element reference](../reference/dash-video.md)