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

package/docs/guides/picture-in-picture.md

@@ -0,0 +1,149 @@
+# Use picture-in-picture
+
+Pop the video into a floating window, with availability detection and state that tracks every entry path.
+
+> **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
+
+Add a [`<media-pip-button>`](../reference/components/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <media-pip-button class="media-pip-button">
+      <span class="pip">Exit PiP</span>
+      <span class="not-pip">Enter PiP</span>
+    </media-pip-button>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player media-container video {
+  width: 100%;
+}
+
+.media-pip-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-pip-button .pip {
+  display: none;
+}
+.media-pip-button .not-pip {
+  display: none;
+}
+.media-pip-button[data-pip] .pip {
+  display: inline;
+}
+.media-pip-button:not([data-pip]) .not-pip {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/pip-button';
+```
+
+## How it works
+
+The [picture-in-picture feature](../reference/api/feature-pip.md) puts three things in player state.
+
+`pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
+
+`pipAvailability` answers “can I offer this?” It starts as `'unavailable'`. Once the feature attaches to a media element, it settles to `'available'` or `'unsupported'`.
+
+`requestPictureInPicture()`, `exitPictureInPicture()`, and `togglePictureInPicture()` change the presentation. If the browser blocks a request, the returned promise rejects. In a browser with no picture-in-picture API, the actions resolve without changing anything.
+
+Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.
+
+## Availability and constraints
+
+- Show picture-in-picture controls only when `pipAvailability` is `'available'`. `<media-pip-button>` handles this for you.
+- Requests must come from a user gesture; browsers reject requests outside one.
+- Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
+- On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
+- The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
+- The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
+
+## Common variations
+
+### Request picture-in-picture from app logic
+
+Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+  </media-container>
+</video-player>
+<button type="button" id="watch-elsewhere">Keep watching while you browse</button>
+<script type="module">
+  import '@videojs/html/video/player';
+
+  document.querySelector('#watch-elsewhere').addEventListener('click', () => {
+    const video = document.querySelector('video');
+    if (typeof video.requestPictureInPicture !== 'function') return; // Unsupported.
+    video.requestPictureInPicture().catch(() => {
+      // Rejected: no video data yet, or blocked by the browser.
+    });
+  });
+</script>
+```
+
+## Troubleshooting
+
+### The picture-in-picture button doesn’t render
+
+`pipAvailability` is `'unsupported'` — the browser has no programmatic picture-in-picture API (Firefox before 153), or the media isn’t a video.
+
+### The request rejects
+
+The video has no data yet (wait for it to be ready), the call wasn’t tied to a user gesture, or the browser blocked it. Handle the rejection rather than assuming entry succeeded.
+
+### State is wrong after the user closes the floating window
+
+Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
+
+## Related pages
+
+### Components
+
+- [media-pip-button](../reference/components/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+
+### API
+
+- [Picture-in-picture](../reference/api/feature-pip.md): Picture-in-picture state and actions for the player store
+
+### Guides
+
+- [Go fullscreen and lock orientation](./fullscreen.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

package/docs/guides/playback-errors.md

@@ -0,0 +1,129 @@
+# Handle playback errors
+
+Display playback failures, report them, and choose a useful recovery action.
+
+Display playback failures instead of leaving a dead player, report the failure when you need diagnostics, and give users a useful next step.
+
+> **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
+
+Render a [`<media-error-dialog>`](../reference/components/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-dialog-popup>
+        <media-dialog-title></media-dialog-title>
+        <media-dialog-description></media-dialog-description>
+        <media-dialog-close></media-dialog-close>
+      </media-dialog-popup>
+    </media-error-dialog>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/ui/error-dialog';
+  import '@videojs/html/ui/dialog-popup';
+  import '@videojs/html/ui/dialog-title';
+  import '@videojs/html/ui/dialog-description';
+  import '@videojs/html/ui/dialog-close';
+</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/api/feature-error.md) mirrors the media element’s error into player state:
+
+- `error` holds the media’s error — `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
+
+- For a terminal failure, load a new or refreshed source to recover. An aborted load or an adapter-specific error may have different behavior.
+- Standard media error codes distinguish broad classes — aborted, network, decode, and source-not-supported — rather than root causes. A media adapter can report its own numeric code too.
+- 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 `<media-error-dialog>`; the dialog can close after your application has handled it.
+
+### Report errors to monitoring
+
+Subscribe to error state and forward new errors to your monitoring service with the source URL and `error.code`. A media error does not automatically appear in JavaScript exception monitoring.
+
+Subscribe after the player element has registered. Compare the current error with the previous one because the store also notifies for unrelated state changes:
+
+```ts
+import '@videojs/html/video/player';
+import { selectError } from '@videojs/html';
+
+const player = document.querySelector('video-player');
+if (!player) throw new Error('Missing video-player');
+
+let previousError: { code: number; message: string } | null = null;
+
+function reportNewError() {
+  const error = selectError(player.store.state)?.error ?? null;
+  if (error === previousError) return;
+
+  previousError = error;
+  if (error) console.error('Playback failed', error.code, error.message);
+}
+
+const unsubscribe = player.store.subscribe(reportNewError);
+reportNewError();
+// Call unsubscribe() when this player is removed.
+```
+
+Replace the `console.error` call with your monitoring service and include the current source URL.
+
+### Diagnose a reported failure
+
+Start with `error.code` and the affected source URL. Check the browser’s network panel for failed media requests, response status, redirects, CORS headers, and expired credentials. If requests succeed, check the file’s container and codecs against the chosen media component. For HLS or DASH, inspect the streaming engine’s diagnostics for segment and manifest failures; the player error often names only the final outcome.
+
+## 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. If `play()` rejects with `NotAllowedError`, see [Autoplay](./autoplay.md).
+
+### A `VJS8_LEGACY_*` exception appears
+
+These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](../reference/api/error-codes.md) for its trigger and v10 equivalent. The player `error` state covered in this guide receives media playback errors after setup.
+
+### 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](./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 pages
+
+### Components
+
+- [media-buffering-indicator](../reference/components/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+
+### API
+
+- [Error](../reference/api/feature-error.md): Media error state and actions for the player store
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Autoplay](./autoplay.md): Start playback automatically and handle browser autoplay restrictions.

package/docs/guides/poster.md

@@ -0,0 +1,146 @@
+# Add a poster and loading placeholder
+
+Set the image shown before playback, then add a lightweight placeholder while it loads
+
+A poster is the image shown before your video plays. There are several places to set one, so work down this list and stop at the first step that fits:
+
+1. **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
+2. **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
+3. **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
+4. **Keep it working after [adding the skin source to your project](./customize-skins.md#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
+
+## Let the media provide a poster
+
+Some media components choose a poster for you. For example, `<mux-video>` creates one from its playback ID:
+
+Install the HTML façade and the Mux playback adapter:
+
+```bash
+pnpm add @videojs/html @videojs/mux-video
+```
+
+```html
+<video-player>
+  <video-skin>
+    <mux-video
+      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+      poster-time="2"
+      playsinline
+    ></mux-video>
+  </video-skin>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+  import '@videojs/html/media/mux-video';
+</script>
+```
+
+## Set a poster on the player
+
+When the media has no poster of its own, set the player’s `poster` to an image URL:
+
+```html
+<video-player poster="/poster.jpg">
+  <video-skin>
+    <video src="/video.mp4" playsinline></video>
+  </video-skin>
+</video-player>
+```
+
+If you use a ready-made skin, it includes [`<media-poster>`](../reference/components/poster.md) and shows the image automatically. If you build your own UI, add `<media-poster>` yourself. It hides after the user plays or seeks.
+
+When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/api/feature-metadata.md) for how the player combines those values.
+
+Posters are decorative by default, with an empty `alt`. If the image communicates something that is not available elsewhere, add `alt` text when you customize the poster image.
+
+## Take control of the poster image
+
+The packaged skins also accept an image of your own, for when a plain `<img>` is not enough:
+
+Add your image to the skin’s `poster` slot. Leave off `src` and Video.js fills in the player’s poster. Provide a `src`, a `srcset`, or `<picture>` sources and Video.js leaves the image alone:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="/video.mp4" playsinline></video>
+    <picture slot="poster">
+      <source media="(min-width: 1200px)" srcset="/poster-1080.jpg" />
+      <img src="/poster-480.jpg" alt="" />
+    </picture>
+  </video-skin>
+</video-player>
+```
+
+## Add a loading placeholder
+
+A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include with the page, such as a short data URL. Add it to the customized image from the previous section.
+
+### Add an image to the poster slot
+
+Add an image to the skin’s `poster` slot with the placeholder as its background. Leave off `src`: Video.js adds the poster URL, while the background appears immediately.
+
+```html
+<video-player poster="/poster.jpg">
+  <video-skin>
+    <video src="/video.mp4" playsinline></video>
+    <img
+      slot="poster"
+      alt=""
+      style="background: url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat"
+    >
+  </video-skin>
+</video-player>
+```
+
+The examples use `contain` for both images. Use `cover` for both when the poster should fill the player. Keeping the same size and position prevents the image from jumping when the poster appears.
+
+## Set the poster after adding skin source
+
+Adding the skin source to your project changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [`<media-poster>`](../reference/components/poster.md) element your skin renders.
+
+`<media-poster>` fills the `src` of the image inside it. Give that image a `src`, a `srcset`, or `<picture>` sources instead and Video.js leaves it untouched — set the source at this level when the poster should bypass player state entirely.
+
+For a placeholder, put the background on the image inside `<media-poster>`:
+
+```html
+<media-poster>
+  <img
+    alt=""
+    style="background: url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat"
+  >
+</media-poster>
+```
+
+## Troubleshooting
+
+### No poster appears
+
+Check that the player has a `poster` or that the media component can create one from its source.
+
+### The final poster never appears
+
+Leave off `src`, `srcset`, and any parent `<picture>` sources when you want Video.js to add the poster URL. If you provide one of those values, Video.js leaves it unchanged.
+
+### The placeholder and poster use different crops
+
+Use the same fit for both images: pair `background-size: contain` with `object-fit: contain`, or use `cover` for both.
+
+### The placeholder adds too much page weight
+
+Use fewer pixels and stronger compression. The placeholder only needs to suggest the poster’s color and shape until the full image appears.
+
+## Related pages
+
+### Components
+
+- [media-poster](../reference/components/poster.md): Poster image component that displays a thumbnail until video playback starts
+
+### API
+
+- [Metadata](../reference/api/feature-metadata.md): Resolved title and poster values for the player store
+
+### Guides
+
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.

package/docs/guides/presets.md

@@ -0,0 +1,111 @@
+# Presets
+
+Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+
+A **preset** packages what you need for a specific player use case. It can include special [state management](./features.md), one or more [skins](./skins.md) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
+
+For example, the `@videojs/html/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/background/player';
+  import '@videojs/html/background/video';
+  import '@videojs/html/background/skin';
+</script>
+
+<background-video-player>
+  <background-video-skin>
+    <background-video src="hero.mp4"></background-video>
+  </background-video-skin>
+</background-video-player>
+```
+
+## Available presets
+
+The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
+
+| Import | Description | Details |
+| --- | --- | --- |
+| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-minimal-skin>`, `<video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-minimal-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<background-video-skin>`; **Default media element:** `<background-video>` |
+| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-minimal-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-minimal-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
+
+## What’s in a preset
+
+Each HTML preset provides registration entry points for a preconfigured player element, its skins, and any preset-specific media element, plus the feature bundle needed to compose your own player. For example, `@videojs/html/video/player` registers `<video-player>`, while `@videojs/html/video/skin` registers `<video-skin>`.
+
+These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
+
+HTML preset roots are side-effect-free modules for importing the configured classes, typed controller, and feature bundle:
+
+```ts
+import {
+  PlayerController,
+  VideoPlayerElement,
+  VideoSkinElement,
+  videoFeatures,
+} from '@videojs/html/video';
+```
+
+Registration is explicit, so importing a value never changes the custom element registry. Registration entry points are side-effect-only; import classes, controllers, and types from the preset root:
+
+```ts
+import '@videojs/html/video/player'; // <video-player> only
+import '@videojs/html/video/skin';   // <video-skin> + container + video UI
+// Import '@videojs/html/video/minimal-skin' instead for the minimal skin.
+```
+
+A complete player imports `video/player` and one skin. Each skin registration includes its container and UI dependencies but does not register the player.
+
+## Customizing a preset
+
+You can customize a preset in three ways: extend its feature bundle, add its skin source to your project, or swap its media element.
+
+### Extend the feature bundle
+
+Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
+
+**index.html**
+
+```html
+<script type="module">
+  import { createPlayer, playbackFeature } from '@videojs/html';
+  import { backgroundFeatures } from '@videojs/html/background';
+  import '@videojs/html/background/video';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/ui/play-button';
+
+  const { PlayerElement: MyPlayer } = createPlayer({
+    features: [...backgroundFeatures, playbackFeature],
+  });
+
+  customElements.define('my-player', MyPlayer);
+</script>
+
+<my-player>
+  <media-container>
+    <background-video src="hero.mp4"></background-video>
+    <media-play-button>Play / Pause</media-play-button>
+  </media-container>
+</my-player>
+```
+
+### Skin source
+
+If a preset’s skin is close but not quite right, [add its source to your project](./customize-skins.md#style-skin-source) and customize its components and styles.
+
+### Swap the media element
+
+A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
+
+```html
+<video-player>
+  <video-skin>
+    <hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
+  </video-skin>
+</video-player>
+```