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

package/docs/how-to/go-fullscreen-and-lock-orientation.md

@@ -1,147 +0,0 @@
-# Go fullscreen and lock orientation
-
-Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
-
-Present the player fullscreen, with your custom controls intact, and optionally lock screen orientation while fullscreen on mobile.
-
-Note
-
-Using a pre-built [skin](../concepts/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](../concepts/ui-components.md).
-
-## Recommended approach
-
-Add a [FullscreenButton](../reference/fullscreen-button.md) inside the player container. It requests fullscreen on the container, so everything inside it — controls, captions, overlays — stays visible in the fullscreen presentation.
-
-Exit Fullscreen Fullscreen
-
-index.html
-
-index.css
-
-index.ts
-
-```
-<video-player class="video-player">
-  <media-container>
-    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
-    <media-fullscreen-button class="media-fullscreen-button">
-      <span class="fullscreen">Exit Fullscreen</span>
-      <span class="not-fullscreen">Fullscreen</span>
-    </media-fullscreen-button>
-  </media-container>
-</video-player>
-```
-```
-.video-player media-container {
-  position: relative;
-  display: block;
-}
-
-.video-player media-container video {
-  width: 100%;
-}
-
-.media-fullscreen-button {
-  position: absolute;
-  right: 10px;
-  bottom: 10px;
-  padding-block: 8px;
-  padding-inline: 20px;
-  color: black;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.7);
-  border: 1px solid rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  backdrop-filter: blur(10px);
-}
-
-.media-fullscreen-button .fullscreen {
-  display: none;
-}
-.media-fullscreen-button .not-fullscreen {
-  display: none;
-}
-.media-fullscreen-button[data-fullscreen] .fullscreen {
-  display: inline;
-}
-.media-fullscreen-button:not([data-fullscreen]) .not-fullscreen {
-  display: inline;
-}
-```
-```
-import '@videojs/html/video/player';
-import '@videojs/html/ui/container';
-import '@videojs/html/ui/fullscreen-button';
-```
-
-## How it works
-
-The [fullscreen feature](../reference/feature-fullscreen.md) tracks fullscreen state and provides the actions:
-
-*   `fullscreen` is `true` while the player is fullscreen, from any path — your button, native controls, or the platform presentation.
-*   `fullscreenAvailability` is `'available'`, `'unavailable'`, or `'unsupported'`. It starts as `'unavailable'`, then settles to `'available'` or `'unsupported'` when the feature attaches to a media element.
-*   `requestFullscreen()`, `exitFullscreen()`, and `toggleFullscreen()` change the presentation. Requests target the player container when the Fullscreen API is available, falling back to the media element’s native presentation otherwise.
-
-Fullscreen and picture-in-picture are exclusive: requesting fullscreen exits an active picture-in-picture presentation first.
-
-Style fullscreen state through the container’s `:fullscreen` pseudo-class, or through the `fullscreen` state in components.
-
-## Availability and constraints
-
-*   Fullscreen requests must come from a user gesture; browsers reject requests outside one.
-*   iPhone Safari has no element Fullscreen API. The player falls back to the video’s native fullscreen presentation, which shows the system player UI instead of your custom controls. iPads support element fullscreen.
-*   Orientation locking requires the Screen Orientation API with lock support — in practice, Android browsers in fullscreen. iOS doesn’t support programmatic orientation lock.
-*   Inside iframes, fullscreen needs `allow="fullscreen"` on the embedding iframe.
-
-## Common variations
-
-### Lock orientation while fullscreen
-
-Add `orientationLockFeature` to lock screen orientation while the player is fullscreen. It isn’t part of `videoFeatures`, so the preset `VideoPlayer` doesn’t include it. It locks to `landscape` by default and unlocks on exit.
-
-Compose a player with `orientationLockFeature` in its feature list through [`createPlayer`](../reference/html-create-player.md); the prebuilt `<video-player>` element doesn’t include it.
-
-To lock to something other than `landscape`, set `orientationLockType` on the player (the `orientation-lock-type` attribute in HTML). See the [orientation lock feature](../reference/feature-orientation-lock.md) reference for details.
-
-### Double-click to toggle
-
-Use the `Gesture` component — the default skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.
-
-html
-
-```
-<media-gesture type="doubletap" action="toggleFullscreen" region="center"></media-gesture>
-<script type="module">
-  import '@videojs/html/ui/gesture';
-</script>
-```
-
-`region="center"` keeps the gesture off the left and right thirds, which the default skins reserve for double-tap seeking. See [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md) for the full gesture surface.
-
-## Troubleshooting
-
-### The fullscreen request is rejected
-
-The request didn’t come from a user gesture, fullscreen is unsupported, or an embedding iframe lacks `allow="fullscreen"`.
-
-### Custom controls disappear in fullscreen on iPhone
-
-Expected: iPhone Safari uses the native video presentation, which replaces custom UI with system controls. Design mobile controls assuming this fallback.
-
-### Orientation doesn’t lock
-
-Orientation lock works in fullscreen on Android browsers; iOS doesn’t support it. Confirm `orientationLockFeature` is in your feature list.
-
-## Related components
-
-*   [Fullscreen button](../reference/fullscreen-button.md)
-*   [Player container](../reference/player-container.md)
-
-## Related API
-
-*   [Fullscreen feature](../reference/feature-fullscreen.md)
-*   [Orientation lock feature](../reference/feature-orientation-lock.md)
-
-## Related guides
-
-*   [Use picture-in-picture](./use-picture-in-picture.md)

package/docs/how-to/handle-playback-errors.md

@@ -1,88 +0,0 @@
-# Handle playback errors
-
-Surface terminal playback errors and give users a useful next step.
-
-Surface terminal playback errors instead of leaving a dead player, and give users a useful next step.
-
-Note
-
-Using a pre-built [skin](../concepts/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](../concepts/ui-components.md).
-
-## Recommended approach
-
-Render an [ErrorDialog](../reference/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
-
-html
-
-```
-<video-player>
-  <media-container>
-    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
-    <media-error-dialog>
-      <media-alert-dialog-title></media-alert-dialog-title>
-      <media-alert-dialog-description></media-alert-dialog-description>
-      <media-alert-dialog-close></media-alert-dialog-close>
-    </media-error-dialog>
-  </media-container>
-</video-player>
-<script type="module">
-  import '@videojs/html/video/player';
-  import '@videojs/html/ui/error-dialog';
-</script>
-```
-
-The dialog renders its text into the child parts — a title, the error description, and a dismiss button — and fills each empty part with default copy. Write your own text inside a part to replace the default. Without the child parts, the dialog opens with nothing to show.
-
-## How it works
-
-The [error feature](../reference/feature-error.md) mirrors the media element’s error into player state:
-
-*   `error` holds the media’s `MediaError` — `code`, `message` — or `null` when there is none.
-*   `dismissError()` clears the error from player state (the media element keeps its own error until a new load).
-*   Loading a new source resets `error` to `null` automatically.
-
-The dialog owns presentation, not recovery. Decide the next step in your application: let the user dismiss the message, choose another item, refresh an expired URL, or contact support.
-
-## Availability and constraints
-
-*   A media error is terminal for the current load: playback won’t resume without loading a source again.
-*   `MediaError.code` distinguishes broad classes — aborted, network, decode, and source-not-supported — not root causes. Check the network panel for the real story (404, CORS, codec).
-*   Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
-*   Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
-
-## Common variations
-
-### Offer an application-specific next step
-
-Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `ErrorDialog`; the dialog can close after your application has handled it.
-
-### Report errors to monitoring
-
-Subscribe to error state and forward it to your error tracker with the source URL and `error.code`; media errors are invisible in JavaScript error monitoring unless you send them.
-
-## Troubleshooting
-
-### The player is black and silent with no error
-
-Not every dead player is a media error — autoplay blocking and an unset source produce no error. Check `error`, `source`, and `paused` in player state to tell them apart.
-
-### Error code says the source isn’t supported
-
-The browser can’t play the format through this media element. HLS in a plain video element outside Safari is the classic case; use the matching streaming media element. See [Media sources](../concepts/media-sources.md).
-
-### Reopening the source produces the same error
-
-The failure is probably permanent for that source, such as a 404, revoked token, unsupported codec, or CORS response. Fix or replace the source instead of repeatedly loading the same URL.
-
-## Related components
-
-*   [Buffering indicator](../reference/buffering-indicator.md)
-
-## Related API
-
-*   [Error feature](../reference/feature-error.md)
-
-## Related guides
-
-*   [Media sources](../concepts/media-sources.md)
-*   [Autoplay](./autoplay.md)

package/docs/how-to/installation.md

@@ -1,165 +0,0 @@
-# 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.2/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).