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

package/docs/guides/installation.md

@@ -0,0 +1,166 @@
+# React Installation Guide
+
+Install Video.js in React and build an accessible, customizable video player with composable controls
+
+Video.js is a **React video player component library**: composable primitives, hooks, and TypeScript types for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
+
+> **Note: Release Candidate**
+>
+> Video.js v10 is a *release candidate*. We feel the API is stable and ready to build with. With your [feedback](https://github.com/videojs/v10/issues), a few documentation updates, and any final fixes, we look forward to shipping 10.0.0 soon. [Read the Release Candidate blog post](https://videojs.org/blog/videojs-v10-release-candidate).
+
+> **Tip: Coming from another player?**
+>
+> Follow the migration guide for [Video.js 8](./migrate-from-video-js-8.md), [Mux Player](./migrate-from-mux-player.md), [Plyr](./migrate-from-plyr.md), or [Media Chrome](./migrate-from-media-chrome.md). Each maps your existing setup onto Video.js v10 instead of starting from scratch.
+
+## AI Quickstart
+
+Paste this prompt into your coding agent:
+
+```
+Install the Video.js skill: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill for this project. When installation details are needed, run `npx @videojs/cli agents init --framework react` to print the version-matched choices and instructions without changing files.
+```
+
+## Installation options for coding agents
+
+The web Markdown page contains the default installation. Add the query parameters below to its `.md` URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.
+
+This page fixes the installation method to `packaged` and the framework to `react`.
+
+```sh
+npx @videojs/cli agents init
+```
+
+### Query parameters
+
+- `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
+- `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
+- `skin`: The visual skin. Minimal has cleaner surfaces and the same controls as Default. Values: `default`, `minimal`, `none`. Default: default. Applies when preset is not background-video.
+- `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
+- `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
+- `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
+- `package-manager`: The command runner used for app setup, packages, Shadcn, and the development server. Values: `npm`, `pnpm`, `yarn`, `bun`. Default: pnpm. Applies when method is not cdn with template none.
+- `template`: The app setup and file layout. Values: `next`, `vite`, `start`, `react-router`, `astro`, `laravel`. Default: next.
+
+Run the command above without flags to see the corresponding CLI flags for every framework.
+
+### Decide in this order
+
+1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
+2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
+3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses minimal; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
+6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
+7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
+8. **Return one explicit plan.** Confirm the choices once, then pass every applicable query parameter, including `extensions=none` when no extension is needed and `source-url=demo` when there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.
+
+### Compatible media sources by preset
+
+- `video`: `html5-video`, `hls`, `dash`, `mux-video`, `vimeo`, `youtube`, `cloudflare`, `tiktok`, `twitch`
+- `audio`: `html5-audio`, `mux-audio`, `spotify`
+- `live-video`: `hls`, `mux-video`
+- `live-audio`: `mux-audio`
+- `background-video`: `background-video`, `hls-background-video`, `mux-background-video`
+
+### App setup by framework
+
+- `react`: templates `next`, `vite`, `start`, `react-router`, `astro`, `laravel`
+
+### Installation pages
+
+- [Packaged modules: React](./installation.md)
+- [Packaged modules: HTML](https://videojs.org/docs/guides/installation/html.md)
+- [Packaged modules: Vue](https://videojs.org/docs/guides/installation/vue.md)
+- [Packaged modules: Svelte](https://videojs.org/docs/guides/installation/svelte.md)
+- [Editable Shadcn source: React source](./installation-shadcn.md)
+- [Editable Shadcn source: HTML source](https://videojs.org/docs/guides/installation/shadcn.md?framework=html)
+- [CDN: HTML from jsDelivr](https://videojs.org/docs/guides/installation/cdn.md)
+
+If a preset and skin do not meet your user’s requirements, follow [Customize skins](./customize-skins.md#style-skin-source) to add the files for the closest skin to the project. As you develop with Video.js, rely heavily on [llms.txt](../llms.txt) to make sure you always have the latest information.
+
+## Selected options
+
+- `method`: `packaged`
+- `framework`: `react`
+- `project`: `existing`
+- `preset`: `video`
+- `skin`: `default`
+- `media`: `html5-video`
+- `extensions`: `none`
+- `source-url`: `https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4`
+- `package-manager`: `pnpm`
+- `template`: `next`
+
+Defaulted options: project, preset, skin, source-url, media, extensions, template, package-manager.
+
+## Reproduce or change these instructions
+
+```sh
+npx @videojs/cli@10.0.0-rc.3 agents init --method packaged --framework react --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template next
+```
+
+## Install the packages
+
+```bash
+pnpm add @videojs/react@10.0.0-rc.3
+```
+
+## Add your player
+
+Merge the example into the existing Next.js route or component that should render the player, and preserve unrelated content.
+
+### `app/page.tsx`
+
+_Merge this into the existing file, or create the file when it is missing._
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
+
+export default function Page() {
+  return (
+    <VideoPlayer>
+      <VideoSkin style={{ width: '100%', aspectRatio: '16 / 9' }}>
+        <Video src={"https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"} playsInline />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+## Run your app
+
+Start the development server and verify that the selected media plays.
+
+_Long-running: start it in the background, verify the result, then stop it._
+
+```bash
+pnpm dev
+```
+
+> These are instructions only. Review and run the commands in your project; no files were modified.
+
+That’s it! You now have a working Video.js player.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](./installation-shadcn.md): Add editable skin source and build a working React or HTML player
+
+## Choose what to do next
+
+### Customize
+
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Change colors, typography, sizing, and poster presentation
+- [UI components](./architecture.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
+
+### Deploy
+
+- [Browser support](./browser-support.md): Check supported browsers and rendering environments
+- [TypeScript](./typescript.md): Configure TypeScript for Video.js packages
+- [Bundlers](./bundlers.md): Check bundler compatibility
+- [Content Security Policy](./content-security-policy.md): Configure Content Security Policy for your player
+
+Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](https://videojs.org/html5-video-support).

package/docs/guides/internationalization.md

@@ -0,0 +1,323 @@
+# 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.
+
+```tsx
+import { Container } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function App() {
+  return (
+    <I18nProvider locale="ja">
+      <VideoPlayer>
+        <Container>
+          <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+        </Container>
+      </VideoPlayer>
+    </I18nProvider>
+  );
+}
+```
+
+Omit `locale` to follow the nearest ancestor `lang` attribute (usually `<html lang>`).
+
+Pick a language and every label follows — no remount:
+
+**App.tsx**
+
+```tsx
+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>
+  );
+}
+```
+
+**App.css**
+
+```css
+.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;
+}
+```
+
+## 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` 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. Overrides supplied to the current player (the `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:
+
+```tsx
+import { useTranslator } from '@videojs/react/i18n';
+
+function StartButton() {
+  const t = useTranslator();
+  return <button type="button">{t('buttons.play', { default: 'Play' })}</button>;
+}
+```
+
+The `default` is the English text — English ships inside component descriptors, not as a pack, so a bare `t(key)` renders the key itself under `en`. The key selects the translation once a pack is active.
+
+## Availability and constraints
+
+- English is built in; every other locale is a lazy-loaded pack. Server rendering needs an explicit `locale` 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 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
+
+Pass `translations` on [`I18nProvider`](../reference/api/i18n-provider.md) to scope overrides to one subtree. This layer sits above the registry and lazy packs:
+
+```tsx
+<I18nProvider locale="ja" translations={{ buttons: { play: '再生', pause: '一時停止' } }}>
+  {/* player */}
+</I18nProvider>
+```
+
+Nested providers inherit the parent locale when you only pass `translations`. For global overrides, call `registerI18n` instead — it merges, so only the keys you pass change.
+
+### 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/react/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/react/i18n/locales/ja/register';
+```
+
+### 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 `I18nProvider` has no explicit `locale`. To drive it from state:
+
+```tsx
+const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');
+
+<I18nProvider locale={locale}>{/* player */}</I18nProvider>
+```
+
+Changing `locale` lazy-loads the pack, which can briefly show English. Preload the locales your picker offers:
+
+```tsx
+import '@videojs/react/i18n/locales/es/register';
+import '@videojs/react/i18n/locales/fr/register';
+```
+
+Or prefetch and register right before switching when you can’t register everything up front:
+
+```tsx
+import { registerI18n } from '@videojs/react/i18n';
+
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+
+async function switchTo(next: keyof typeof loaders) {
+  const { default: translations } = await loaders[next]();
+  registerI18n(next, translations);
+  setLocale(next);
+}
+```
+
+### 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.
+
+When `I18nProvider` has an explicit `locale`, the player applies its resolved `lang` and `dir` to the container. A `lang` or `dir` passed to that container overrides the rendered DOM boundary only; translations still come from `I18nProvider locale`.
+
+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:
+
+```tsx
+import { LiveButton } from '@videojs/react';
+
+<LiveButton>On air</LiveButton>
+```
+
+Authored children are literal; use `useTranslator` when custom children also need localization. For state-dependent text, render one element 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:
+
+Import the pack on the server and pass it to the provider — `translations` on first render skips the async lazy layer entirely:
+
+```tsx
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+
+export async function Player({ locale }: { locale: string }) {
+  const load = loaders[locale as keyof typeof loaders];
+  if (!load) throw new Error(`Unsupported locale: ${locale}`);
+  const { default: translations } = await load();
+
+  return (
+    <I18nProvider locale={locale} translations={translations}>
+      {/* player */}
+    </I18nProvider>
+  );
+}
+```
+
+Pass `locale` explicitly on the server — there’s no DOM to resolve `lang` from, and an explicit value avoids hydration mismatches. With app routers, pass the tag your framework negotiates (for next-intl, `await getLocale()`); Video.js doesn’t replace framework i18n, it consumes the tag you give it.
+
+## 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
+
+- [I18nProvider](../reference/api/i18n-provider.md): React provider that resolves locale and supplies a typed translator to descendants
+
+### 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
+- [useTranslator](../reference/api/use-translator.md): React hook that returns the typed translator for the nearest I18nProvider
+- [useLocale](../reference/api/use-locale.md): React hook that returns the active BCP 47 locale from the nearest I18nProvider
+- [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,97 @@
+# 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 `Hotkey` and gestures with `Gesture` inside the player container. Each maps an input to a player action; the prebuilt skins ship a full set.
+
+```tsx
+import { Container, Gesture, Hotkey } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+
+        <Hotkey keys="Space" action="togglePaused" />
+        <Hotkey keys="m" action="toggleMuted" />
+        <Hotkey keys="f" action="toggleFullscreen" />
+        <Hotkey keys="ArrowRight" action="seekStep" value={5} />
+        <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
+
+        <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
+        <Gesture type="tap" action="toggleControls" pointer="touch" />
+        <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
+        <Gesture type="doubletap" action="seekStep" value={10} region="right" />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+- `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.
+- `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.
+- `StatusAnnouncer` 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 `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 `StatusAnnouncer` and the indicator components from the skin source to a custom UI.
+
+## Related pages
+
+### Components
+
+- [Controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [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