@videojs/html 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/guides/internationalization.md

@@ -0,0 +1,321 @@
+# 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:
+
+**index.html**
+
+```html
+<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>
+```
+
+**index.css**
+
+```css
+.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;
+}
+```
+
+**index.ts**
+
+```ts
+import { LOCALES } from '@videojs/html/i18n';
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+
+const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });
+const initializedDemos = new WeakSet<HTMLElement>();
+
+function initializeDemos(): void {
+  document.querySelectorAll<HTMLElement>('.html-i18n-language').forEach((demo) => {
+    if (initializedDemos.has(demo)) return;
+
+    initializedDemos.add(demo);
+
+    const select = demo.querySelector('select');
+    const provider = demo.querySelector('media-i18n');
+
+    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);
+    });
+  });
+}
+
+initializeDemos();
+document.addEventListener('astro:page-load', initializeDemos);
+```
+
+## 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 `lang` on `<media-i18n>` 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/api/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. Registered custom translations
+  2. A built-in locale pack
+  3. 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.
+- 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 phrases](../reference/api/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.3/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/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**
+
+```js
+import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/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.3/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 pages
+
+### Components
+
+- [media-i18n](../reference/api/media-i18n.md): HTML custom element that resolves locale and supplies translations to descendants
+- [media-text](../reference/api/media-text.md): HTML custom element that renders a translated string by semantic key
+
+### API
+
+- [registerI18n](../reference/api/register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+- [Translation phrases](../reference/api/translation-phrases.md): Semantic i18n keys, their English defaults, and the player UI that uses them
+- [I18nController](../reference/api/i18n-controller.md): Reactive controller for consuming translator and locale values from an HTML i18n context
+- [getI18nTranslations](../reference/api/get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
+
+### Guides
+
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

package/docs/guides/keyboard-shortcuts.md

@@ -0,0 +1,98 @@
+# Add keyboard shortcuts and gestures
+
+Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+
+Add keyboard shortcuts and pointer gestures to the player declaratively, with on-screen feedback and screen-reader announcements.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Recommended approach
+
+Declare shortcuts with `<media-hotkey>` and gestures with `<media-gesture>` inside the player container. Each maps an input to a player action; the prebuilt skins ship a full set.
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+
+    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
+    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
+    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
+    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
+    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
+
+    <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
+    <media-gesture type="tap" action="toggleControls" pointer="touch"></media-gesture>
+    <media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
+    <media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/hotkey';
+  import { GestureElement } from '@videojs/html';
+
+  // Gesture has no standalone define entry; register the element directly.
+  customElements.define(GestureElement.tagName, GestureElement);
+</script>
+```
+
+## How it works
+
+- `<media-hotkey>` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. Step actions have shared defaults and accept a custom `value`. The actions call the same feature state actions your components use.
+- `<media-gesture>` binds pointer input — `tap` and `doubletap` — to the same actions, minus `seekToPercent` and plus `toggleControls`. Bindings are scoped by `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`) — regions split the container’s width, not the rendered video’s — so double-tap-left rewinds while double-tap-right skips forward.
+- `<media-status-announcer>` announces action results to screen readers, and the input indicator components render transient on-screen feedback (volume level, captions on/off) the way native players do. The prebuilt skins wire these up.
+
+The prebuilt skins bind the conventional set: Space and `k` toggle playback, `m` mutes, `f` fullscreens, `c` toggles captions, `i` toggles picture-in-picture, arrows seek and change volume, `j`/`l` seek in larger steps, `0`–`9` jump to a percentage, and `<`/`>` change speed.
+
+## Availability and constraints
+
+- Hotkeys listen on the player container by default, so multiple players on a page don’t fight over keys. Pass `target="document"` on a hotkey to make it page-wide — appropriate only when one player owns the page.
+- Typing is protected: while focus is in an editable field, single-key bindings are skipped automatically. Modifier combinations (for example `Ctrl+Shift+f`) still fire.
+- Repeatable actions (seeking, volume) fire on held keys; toggle actions don’t repeat.
+- Touch tap-to-toggle-controls and tap-to-pause are mutually exclusive per pointer type — the skins pause on mouse tap and toggle controls on touch tap, matching platform conventions.
+- Gestures and the built-in touch handling coordinate through one recognizer; register gestures declaratively instead of adding raw pointer listeners next to them.
+
+## Common variations
+
+### Customize a shortcut
+
+Render your own `<media-hotkey>` set instead of a skin’s: every binding is just an element, so add, remove, or re-key them freely.
+
+### Seek step size
+
+`seekStep` takes its step from `value` — match your content: 5 seconds for short clips, 15 or 30 for long-form.
+
+## Troubleshooting
+
+### Shortcuts don’t fire
+
+Focus is outside the player container. Click the player first, or move focus into it; hotkeys are player-scoped by design.
+
+### Double-tap seek also toggles pause
+
+Regions overlap: keep single-tap `togglePaused` on `center` only, and double-tap seek on `left` and `right`, as in the skin defaults.
+
+### No visual feedback on keyboard actions
+
+The input indicator components render that feedback; use a prebuilt skin or add `<media-status-announcer>` and the indicator components from the skin source to a custom UI.
+
+## Related pages
+
+### Components
+
+- [media-controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [media-tooltip](../reference/components/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
+
+### API
+
+- [Playback](../reference/api/feature-playback.md): Play/pause state and actions for the player store
+- [Volume](../reference/api/feature-volume.md): Volume level and mute state for the player store
+- [Fullscreen](../reference/api/feature-fullscreen.md): Fullscreen state and actions for the player store
+
+### Guides
+
+- [Automatically show and hide controls](./controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

package/docs/guides/live-streams.md

@@ -0,0 +1,110 @@
+# Play live streams
+
+Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Installation
+
+The examples use `<hlsjs-video>`, so install hls.js with the framework façade:
+
+```bash
+pnpm add @videojs/html @videojs/hlsjs-video
+```
+
+## Recommended approach
+
+Use the live feature bundle with a streaming media element, and give users a `<media-live-button>`: it shows whether playback is at the live edge and seeks back to it when activated.
+
+```html
+<live-video-player>
+  <media-container>
+    <hlsjs-video src="https://your-stream.example.com/live.m3u8" autoplay muted playsinline></hlsjs-video>
+    <media-live-button></media-live-button>
+  </media-container>
+</live-video-player>
+<script type="module">
+  import '@videojs/html/live-video/player';
+  import '@videojs/html/media/hlsjs-video';
+  import '@videojs/html/live-video/ui';
+</script>
+```
+
+The examples use [`<hlsjs-video>`](../reference/components/hlsjs-video.md) for broad compatibility, but any streaming media component works here, including the smaller [`<hls-video>`](../reference/components/hls-video.md). Use `<hls-video>` when its supported feature set fits your stream.
+
+The `liveVideoFeatures` bundle mirrors [`videoFeatures`](./features.md) but adds the live feature and drops playback rate (not meaningful for live), quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
+
+Both bundles are plain arrays, so extending one is a spread:
+
+```ts
+import { createPlayer, streamTypeFeature } from '@videojs/html';
+import { liveVideoFeatures } from '@videojs/html/live-video';
+
+const { ProviderMixin } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+```
+
+## How it works
+
+Two features describe liveness:
+
+- The [stream type feature](../reference/api/feature-stream-type.md) reports `streamType`: `'live'`, `'on-demand'`, or `'unknown'`. Streaming media derives it from manifest metadata; plain media elements fall back to duration-based detection. `liveVideoFeatures` does not include it; add `streamTypeFeature` to the player’s features when you need `streamType`.
+- The [live feature](../reference/api/feature-live.md) reports two values:
+  - `liveEdgeStart` is where “live” begins on the timeline. When the playhead is at or past this time, the viewer is watching live; behind it, they’re watching earlier moments of the stream.
+  - `targetLiveWindow` is how far back the stream lets viewers rewind. `0` means a plain live stream that stays at the edge. `Infinity` means full DVR: rewind as far as the recording goes. `NaN` means the stream isn’t live, or the player doesn’t know yet.
+
+The [time feature](../reference/api/feature-time.md) adjusts for live playback: `duration` reports the live edge (the end of the seekable range) and keeps growing as the stream continues.
+
+`<media-live-button>` reads this state: it renders as an active “go to live” control while playback is behind the edge, seeks to the edge on activation, and goes inactive at the edge. Until the media reports a `seekable` range — before metadata loads, or for non-live media — the button is disabled (`data-disabled`) because there is no edge to seek to. Custom live UIs should treat “behind the edge” and “actionable” as separate states.
+
+## Availability and constraints
+
+- `liveEdgeStart` and `targetLiveWindow` come from media that implements the live capability — the hls.js-based media elements. With plain media elements, stream type falls back to duration-based detection and `liveEdgeStart` stays `NaN`.
+- Live playback drifts behind the edge when the network stalls or the tab is backgrounded. Always give users a path back to the edge.
+- Seeking makes sense only for DVR streams (`targetLiveWindow` of `Infinity`). For standard-latency streams, omit the time slider.
+- Playback rate control isn’t meaningful for live; `liveVideoFeatures` omits it.
+
+## Common variations
+
+### DVR: let users scrub back
+
+For streams with a DVR window, give users a [`<media-time-slider>`](../reference/components/time-slider.md). The live preset skins don’t include one, so add it to your custom UI or [add the live skin source to your project](./customize-skins.md#style-skin-source). The slider tracks the sliding window automatically because `duration` follows the live edge.
+
+### Switch UI by stream type
+
+Render live or on-demand controls from `streamType` when one player handles both kinds of content. Add `streamTypeFeature` to the player’s features; `liveVideoFeatures` does not include it:
+
+`<media-live-button>` selects from the live, time, and buffer features and reflects live state. To swap larger parts of the UI on `streamType`, build a provider with [createPlayer](../reference/api/html-create-player.md) and add `streamTypeFeature` to its features (`<live-video-player>` uses `liveVideoFeatures`, which does not include it), then read `streamType` from the player store through the [player controller](../reference/api/player-controller.md).
+
+## Troubleshooting
+
+### The live badge never activates
+
+`streamType` isn’t `'live'`. Confirm the player’s features include `streamTypeFeature` (`liveVideoFeatures` does not include it, so `streamType` reads as `undefined`), the source is a live manifest, and it plays through a live-capable media element such as [`<hlsjs-video>`](../reference/components/hlsjs-video.md).
+
+### Playback keeps falling behind the edge
+
+Network throughput can’t sustain the stream, or the tab was backgrounded. `<media-live-button>` returns users to the edge; for lower drift, review the stream’s latency configuration on the encoder side.
+
+### The time slider behaves oddly on a live stream
+
+Standard-latency live streams have no meaningful seek range. Show the slider only for DVR streams (`targetLiveWindow` of `Infinity`).
+
+## Related pages
+
+### Components
+
+- [media-time-slider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+- [media-buffering-indicator](../reference/components/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+
+### API
+
+- [Live](../reference/api/feature-live.md): Live edge state for the player store
+- [Stream type](../reference/api/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Time](../reference/api/feature-time.md): Playback position and duration state for the player store
+- [hlsjs-video](../reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property

package/docs/guides/llms.txt

@@ -0,0 +1,79 @@
+# Video.js v10 — HTML Guides
+
+> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/html` v10.0.0-rc.3. Links are relative paths to files in this directory.
+
+## Getting Started
+
+Install Video.js, customize a skin, understand its main pieces, check browser and AI tool support, and contribute.
+
+- [HTML Installation Guide](./installation.md): Install Video.js with HTML custom elements and build an accessible, customizable video player
+- [Vue Installation Guide](./installation-vue.md): Install Video.js in Vue or Nuxt and build a video player with HTML custom elements
+- [Svelte Installation Guide](./installation-svelte.md): Install Video.js in Svelte or SvelteKit and build a video player with HTML custom elements
+- [Shadcn Installation Guide](./installation-shadcn.md): Add editable React or HTML skin source with the Shadcn registry
+- [CDN Installation Guide](./installation-cdn.md): Load Video.js from jsDelivr and build an HTML video player without installing Video.js packages
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+- [Architecture](./architecture.md): How Video.js players are structured — state, UI, media, and extensions
+- [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+- [Why Video.js?](./why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Browser support](./browser-support.md): Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
+- [Build with AI](./build-with-ai.md): Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
+- [v10 Roadmap](./v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
+- [Contribute to Video.js](https://github.com/videojs/v10/blob/main/CONTRIBUTING.md)
+
+## Frameworks
+
+Guides for using the HTML version of Video.js with Vue, Nuxt, Svelte, or SvelteKit.
+
+- [Vue](./vue.md): Add Video.js to a Vue or Nuxt app
+- [Svelte](./svelte.md): Add Video.js to a Svelte or SvelteKit app
+
+## Environment
+
+TypeScript, bundlers, the CDN, self-hosting, and Content Security Policy.
+
+- [TypeScript](./typescript.md): TypeScript version and module resolution requirements for Video.js packages
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries
+- [CDN](./cdn.md): Understand the browser-ready bundles, stylesheets, and URL layout published by the Video.js CDN
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments
+- [Content Security Policy](./content-security-policy.md): Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
+
+## Concepts
+
+Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
+
+- [Features](./features.md): The state and actions each feature adds to the player
+- [Skins](./skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+- [UI components](./ui-components.md): How Video.js UI components use focused elements, data attributes for state, and compound composition.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+
+## Playback
+
+Guides for one player capability each: the recommended setup, how it works, browser constraints, variations, and troubleshooting.
+
+- [Autoplay](./autoplay.md): Start playback automatically and handle browser autoplay restrictions.
+- [Automatically show and hide controls](./controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
+- [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Play live streams](./live-streams.md): Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+- [Add a quality selector](./quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
+- [Go fullscreen and lock orientation](./fullscreen.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Use picture-in-picture](./picture-in-picture.md): Pop the video into a floating window, with availability detection and state that tracks every entry path.
+- [Show timeline thumbnail previews](./thumbnails.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+- [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
+- [Handle playback errors](./playback-errors.md): Display playback failures, report them, and choose a useful recovery action.
+- [Remember user preferences](./user-preferences.md): Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+- [Add a background video](./background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
+- [Internationalize the player](./internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
+- [Monitor playback with Mux Data](./mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
+
+## Migrate
+
+Guides for moving an existing player integration to Video.js v10, one per player you might be coming from.
+
+- [Migrate from Video.js 8](./migrate-from-video-js-8.md): Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
+- [Migrate from Mux Player](./migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
+- [Migrate from Plyr](./migrate-from-plyr.md): Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
+- [Migrate from Media Chrome](./migrate-from-media-chrome.md): Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting