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

package/docs/how-to/installation.md

@@ -0,0 +1,165 @@
+# Installation
+
+Install Video.js and build your first player with streaming support and accessible controls
+
+Beta Software
+
+Video.js v10 is currently in *beta*. The API may evolve with [feedback🙏](https://github.com/videojs/v10/issues). See the [Changelog](https://github.com/videojs/v10/blob/main/CHANGELOG.md) for recent updates and the [Roadmap](../concepts/v10-roadmap.md) for more details on what’s coming.
+
+Video.js is an **HTML video player built on custom elements**: lightweight, framework-free components for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
+
+<!-- cli:omit installation -->
+
+
+This guide has code examples tailored to your use case. To generate this guide with tailored code examples, run `npx @videojs/cli docs how-to/installation`. If you run it without flags, it will allow you to interactively configure your player. Or, you can run it with flags:
+
+bash
+
+```
+npx @videojs/cli docs how-to/installation \
+  --framework <html|react> \
+  --preset <video|audio|live-video|live-audio|background-video> \
+  --skin <default|minimal|none> \
+  --media <html5-video|html5-audio|hls|dash|mux-video|mux-audio|vimeo|youtube|cloudflare|tiktok|twitch|spotify|background-video> \
+  --source-url <url> \
+  --install-method <cdn|npm|pnpm|yarn|bun>
+```
+
+The CLI does not currently detect non-interactive stdin. In automation, agents, and CI, include `--framework` and all five installation flags so no prompt starts. Pass `--source-url ''` to use the built-in demo without prompting.
+
+Here’s what the flags mean:
+
+*   *Framework*: Pick whether you’re working in React or if you’d like to use HTML custom elements. (More to come!)
+*   *Preset*: Pick a pre-built player. The default presets work well for general website playback; the live presets add a Live button and drop the on-demand time displays.
+*   *Skin*: Pick what your player looks like
+*   *Media*: Pick what kind of media you have. The `live-video` preset supports HLS and Mux video; `live-audio` supports Mux audio.
+*   *Source URL*: Define where your media comes from. In an interactive terminal, omit it to choose a sample URL. In automation, pass an empty value to choose the sample without prompting.
+*   *Install method*: How do you want to install your package? (CDN is HTML-only.)
+
+If you’re an agent, interview your user and offer to run the CLI for them, or offer them a precomposed CLI command.
+
+
+<!-- /cli:omit installation -->
+
+If a preset and skin do not meet your user’s requirements, follow [Customize skins](./customize-skins.md#eject-and-edit-a-skin) to eject the closest skin. As you develop with Video.js, rely heavily on [llms.txt](../llms.txt) to make sure you always have the latest information.
+
+<!-- cli:replace installation -->
+
+
+## Install Video.js
+
+cdn
+
+npm
+
+pnpm
+
+yarn
+
+bun
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+```
+
+```
+npm install @videojs/html
+```
+
+```
+pnpm add @videojs/html
+```
+
+```
+yarn add @videojs/html
+```
+
+```
+bun add @videojs/html
+```
+
+## Use your player
+
+HTML
+
+```
+<!--
+  The player element owns and shares state between the UI
+  components and Media. Put layout on the skin or container.
+ -->
+<video-player>
+  <!--
+    Skins contain the entire player UI and are easily swappable.
+    They can each be "ejected" for full control and customization
+    of UI components.
+   -->
+  <video-skin>
+    <!--
+        Media are players without UIs, handling networking
+        and display of the media. They are easily swappable
+        to handle different sources.
+      -->
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
+  </video-skin>
+</video-player>
+```
+
+Load your script as a module
+
+When using a bundler (npm, pnpm, yarn, bun), load the resulting bundle with `type="module"`:
+
+html
+
+```
+<script type="module" src="/dist/player.js"></script>
+```
+
+Some bundlers default to an IIFE output format. Loading that bundle without `type="module"` will cause a `StoreError: NO_TARGET` error when interacting with the player. The CDN install path already uses `type="module"` — bundled installs need the same.
+
+
+
+
+
+
+
+
+
+
+
+
+<!-- /cli:replace installation -->
+
+That’s it! You now have a working Video.js player.
+
+## Change the skin’s controls or layout
+
+To add, remove, or rearrange the skin you selected, eject it into your project. If your project does not have a `components.json` file, [set up the CLI first](./customize-skins.md#set-up-the-shadcn-cli). Then choose how you want the skin’s styles written and run the command below to copy its files:
+
+HTML skins install as vanilla CSS.
+
+npm
+
+```
+npx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/html/{name}.json
+npx shadcn@latest add @videojs/video
+```
+
+- [Customize skins](./customize-skins.md#eject-and-edit-a-skin): Learn which files to edit and how to update your copy later
+
+## Choose what to do next
+
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Change colors, typography, sizing, and poster presentation
+- [UI components](../concepts/overview.md#ui-components): Explore the building blocks used by skins and custom controls
+- [Build your own component](./build-your-own-component.md): Connect custom UI to player state and actions
+
+## Prepare for production
+
+- [Browser support](../concepts/browser-support.md): Check supported browsers and rendering environments
+- [TypeScript](../concepts/typescript.md): Configure TypeScript for Video.js packages
+- [Bundlers](../concepts/bundlers.md): Check bundler compatibility
+- [Content Security Policy](../concepts/security.md): Configure Content Security Policy for your player
+
+- [CDN](../concepts/cdn.md): See every bundle the CDN serves and the layout rules behind the URLs
+- [Self-host the player](./self-host-the-player.md): Serve the player from your own origin for offline or restricted-network deployments
+
+Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](/html5-video-support).

package/docs/how-to/internationalize-the-player.md

@@ -0,0 +1,340 @@
+# Internationalize the player
+
+Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
+
+Translate every player label, tooltip, and screen-reader announcement. The player ships translations for more than 50 locales and loads them on demand.
+
+## Recommended approach
+
+Wrap the player in the i18n provider. It resolves the locale from your page’s `lang` attribute (or an explicit override), lazy-loads the matching locale pack, and every component label follows.
+
+html
+
+```
+<media-i18n lang="ja">
+  <video-player>
+    <media-container>
+      <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+    </media-container>
+  </video-player>
+</media-i18n>
+<script type="module">
+  import '@videojs/html/i18n';
+  import '@videojs/html/video/player';
+</script>
+```
+
+Omit the `lang` attribute on `<media-i18n>` to follow the nearest ancestor `lang` (usually `<html lang>`).
+
+Pick a language and every label follows — no remount:
+
+Language
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<div class="html-i18n-language">
+  <label>
+    Language
+    <select></select>
+  </label>
+  <media-i18n lang="en">
+    <video-player>
+      <video-skin>
+        <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+      </video-skin>
+    </video-player>
+  </media-i18n>
+</div>
+```
+```
+.html-i18n-language {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.html-i18n-language label {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.html-i18n-language select {
+  padding: 4px 8px;
+}
+
+.html-i18n-language video-skin,
+.html-i18n-language video {
+  display: block;
+  width: 100%;
+}
+
+.html-i18n-language video-skin {
+  aspect-ratio: 16 / 9;
+}
+```
+```
+import { LOCALES } from '@videojs/html/i18n';
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+
+const root = document.querySelector<HTMLElement>('.html-i18n-language');
+const select = root?.querySelector('select');
+const provider = root?.querySelector('media-i18n');
+const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });
+
+for (const locale of ['en', ...LOCALES]) {
+  const option = document.createElement('option');
+
+  option.value = locale;
+  option.textContent = languageNames.of(locale) ?? locale;
+  select?.append(option);
+}
+
+select?.addEventListener('change', () => {
+  provider?.setAttribute('lang', select.value);
+});
+```
+
+## How it works
+
+*   Component labels are text descriptors — a translation key plus its English default — so everything renders in English with no setup and switches language when a translator is present. Keys are stable: `buttons.play` stays `buttons.play` even if the English wording changes.
+*   The provider resolves the locale: explicit `locale` (React) or `lang` (HTML) first, then the nearest ancestor `lang` attribute, then `'en'`. It re-resolves when the page’s `lang` changes.
+*   The provider lazy-loads the pack for the resolved locale automatically and keeps it in a layer above the shared registry ([`registerI18n`](../reference/register-i18n.md)). Translations merge along a fallback chain that follows the [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent tags — `es-MX` checks `es`, then `en` — so a regional pack only has to carry the text that differs from its parent.
+*   Each piece of text resolves from the first source that has it:
+    1.  Overrides supplied to the current player (React `translations` prop)
+    2.  Registered custom translations
+    3.  A built-in locale pack
+    4.  The component’s English fallback
+*   `registerI18n(locale, translations)` **merges**: each call adds or replaces keys for that locale without wiping prior registrations, and later registrations win for the same key. Register a locale before the provider resolves it — a pack the provider already lazy-loaded sits above the registry and hides registry entries for that locale. Overriding a handful of strings is the same call as registering a full locale.
+*   When no shipped pack matches the locale, the provider can fall back to the browser’s on-device Translation API to machine-translate the English catalogue, with placeholders preserved.
+
+Translate your own UI with the same machinery:
+
+html
+
+```
+<media-text token="buttons.play">Play</media-text>
+```
+
+The element’s text content is the English default; the `token` selects the translation.
+
+## Availability and constraints
+
+*   English is built in; every other locale is a lazy-loaded pack. Server rendering needs an explicit `locale` (React) since there’s no DOM to resolve from.
+*   Locale tags are [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) (`es`, `pt-BR`).
+*   Translation keys are namespaced strings (`buttons.play`, `errors.network`, `menu.quality`); the full list lives at [Translation keys](../reference/translation-phrases.md) and is typed, so typos in `registerI18n` objects fail in TypeScript. The translator itself accepts any string; a mistyped `t()` key falls back to its `default`.
+*   Some strings interpolate parameters; custom translations must keep the placeholders:
+
+ts
+
+```
+// ✅
+registerI18n('es', { seek: { forward: 'Adelantar {seconds} segundos' } });
+
+// ❌ The interpolated value is lost
+registerI18n('es', { seek: { forward: 'Adelantar' } });
+```
+
+*   The Browser Translation API fallback needs Chrome with `globalThis.Translator` and downloads an on-device model on first use. It’s best-effort; ship a real pack for languages you support officially.
+
+## Common variations
+
+### Override specific strings
+
+js
+
+```
+import '@videojs/html/i18n/locales/ja/register';
+import { registerI18n } from '@videojs/html/i18n';
+
+registerI18n('ja', { buttons: { play: '再生', pause: '一時停止' } });
+```
+
+Only the keys you pass change; the rest of the `ja` pack stays intact. Keep the `/register` import first: it must run before `<media-i18n>` upgrades, or the provider lazy-loads the shipped pack and that pack hides your overrides.
+
+### Register your own locale
+
+Registered packs are partial: missing keys fall back through the locale chain to a shipped pack or English.
+
+ts
+
+```
+import { registerI18n, type Translations } from '@videojs/html/i18n';
+
+const es = {
+  buttons: {
+    play: 'Reproducir',
+    pause: 'Pausa',
+    mute: 'Silenciar',
+    unmute: 'Activar sonido',
+  },
+} satisfies Partial<Translations>;
+
+registerI18n('es', es);
+```
+
+### Register a pack with the bundle
+
+Skip lazy loading by registering a shipped locale at startup with a side-effect import. First paint is synchronous in that language:
+
+ts
+
+```
+import '@videojs/html/i18n/locales/ja/register';
+```
+
+### Load locales from the CDN
+
+CDN locale modules call `registerI18n` on import. Pin every URL to the same version:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+```
+
+For custom strings, import `registerI18n` from the version-pinned `i18n.js` that matches your player script. The player’s chunks import that exact URL, so a different or unversioned URL loads a second copy of the module with its own registry, and your strings never reach the player. Load your module before the player script so the strings are registered when the elements upgrade:
+
+my-locale.js
+
+```
+import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/i18n.js';
+
+registerI18n('es', { buttons: { play: 'Reproducir', pause: 'Pausa' } });
+```
+
+html
+
+```
+<script type="module" src="/my-locale.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+```
+
+### Switch locale at runtime
+
+The simplest switch updates the document language and lets providers pick it up — no remount required:
+
+ts
+
+```
+document.documentElement.lang = 'fr';
+```
+
+Ambient switching only applies when `<media-i18n>` has no explicit `lang` attribute. To switch explicitly, set the provider’s `lang`:
+
+js
+
+```
+document.querySelector('media-i18n').lang = 'fr';
+```
+
+Switching lazy-loads the pack, which can briefly show English. Preload the locales your picker offers with side-effect imports:
+
+ts
+
+```
+import '@videojs/html/i18n/locales/es/register';
+import '@videojs/html/i18n/locales/fr/register';
+```
+
+### Set text direction
+
+`lang` identifies the content language. `dir` controls text and layout direction. Browsers do not infer one from the other, so set both when the locale applies to the whole document:
+
+ts
+
+```
+document.documentElement.lang = 'ar';
+document.documentElement.dir = 'rtl';
+```
+
+Set `dir` back to `ltr` when you switch to a left-to-right language. This prevents the previous direction from remaining active.
+
+`<media-i18n lang>` sets the provider locale and derives its direction. An explicit `dir` on `<media-i18n>` overrides that derived direction.
+
+Providers without an explicit locale inherit ambient document language and direction. In that case, set `lang` and `dir` on `<html>` or another ancestor:
+
+html
+
+```
+<html lang="ar" dir="rtl">
+```
+
+RTL preserves playback control ordering and time-semantic media icons while mirroring menu motion and navigation chevrons. Horizontal time and volume sliders retain a physical left-to-right value scale: Left Arrow decreases the value, Right Arrow increases it, and the minimum remains on the left.
+
+### Replace a component’s visible text
+
+Translation overrides change built-in labels everywhere they appear. To replace only one component’s visible content, set its children — and use the translation machinery when that content should still follow the active locale:
+
+html
+
+```
+<media-live-button>
+  <media-text token="live.badge">On air</media-text>
+</media-live-button>
+```
+
+For state-dependent text, add one `<media-text>` per state and show or hide them with the component’s `data-*` state attributes (the same pattern used for icons).
+
+The component still derives its accessible name from media state unless you also set its label API. Keep custom visible text consistent with that name.
+
+### Server rendering
+
+Render the document language on the server (`<html lang="es">`) and make translations available before first paint so labels match on server and client:
+
+Emit `lang`, wrap the player with `<media-i18n>`, and register packs in the entry module loaded before custom elements upgrade:
+
+ts
+
+```
+import '@videojs/html/video/player';
+import '@videojs/html/i18n/locales/es/register';
+```
+
+Caution
+
+Don’t rely on browser-only translation APIs during SSR. Ship packs or register strings explicitly.
+
+## Troubleshooting
+
+### Labels stay in English
+
+No provider is mounted, or the locale never resolved: check the `locale`/`lang` value and that it matches a shipped pack (regional tags fall back — `pt-BR` works; a bare unknown tag falls through to English).
+
+### Some strings are translated, others aren’t
+
+A partial override or partial pack: missing keys fall back through the locale chain to English. Fill in the missing keys with `registerI18n`.
+
+### Translations flash in after load or after switching
+
+The lazy pack loads after first paint (or after the switch). Register the pack with the bundle (the `/register` side-effect import), or prefetch and register before changing the locale.
+
+### Server-rendered labels don’t match the client
+
+The provider resolved different locales on server and client. Pass an explicit `locale` and first-render `translations` instead of relying on ambient `lang`.
+
+## Related components
+
+*   [I18nProvider](/docs/framework/react/reference/i18n-provider)
+*   [media-i18n](../reference/media-i18n.md)
+*   [media-text](../reference/media-text.md)
+
+## Related API
+
+*   [registerI18n](../reference/register-i18n.md)
+*   [Translation keys](../reference/translation-phrases.md)
+*   [useTranslator](/docs/framework/react/reference/use-translator)
+*   [useLocale](/docs/framework/react/reference/use-locale)
+*   [getI18nTranslations](../reference/get-i18n-translations.md)
+
+## Related guides
+
+*   [Show captions and subtitles](./show-captions-and-subtitles.md)
+*   [Accessibility](../concepts/accessibility.md)