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

package/docs/how-to/show-captions-and-subtitles.md

@@ -0,0 +1,140 @@
+# Show captions and subtitles
+
+Show captions and subtitles, and let users turn them on and pick a language.
+
+Add captions and subtitles to media, and let users turn them on and pick a language.
+
+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 WebVTT tracks as `<track>` children of the media element, and give users a [CaptionsButton](../reference/captions-button.md) to toggle them.
+
+ Captions Off Captions On
+
+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>
+      <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srclang="en" label="English" default />
+    </video>
+    <media-captions-button class="media-captions-button">
+      <span class="active">Captions Off</span>
+      <span class="inactive">Captions On</span>
+    </media-captions-button>
+  </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.media-captions-button {
+  position: absolute;
+  bottom: 10px;
+  left: 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-captions-button .active {
+  display: none;
+}
+.media-captions-button .inactive {
+  display: none;
+}
+.media-captions-button[data-active] .active {
+  display: inline;
+}
+.media-captions-button:not([data-active]) .inactive {
+  display: inline;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/captions-button';
+```
+
+## How it works
+
+The [text track feature](../reference/feature-text-tracks.md) mirrors the media element’s `textTracks` into player state:
+
+*   `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
+*   `subtitlesShowing` is `true` when any caption or subtitle track is showing.
+*   `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
+*   `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
+
+Tracks don’t have to come from `<track>` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
+
+The browser renders the cues. Style them with the `::cue` pseudo-element.
+
+## Availability and constraints
+
+*   Captions availability is `'unavailable'` until the media has at least one caption or subtitle track; caption controls render nothing in that case.
+*   Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
+*   Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossOrigin` on the media element.
+*   Track selection UIs identify tracks by `label` and `language`; give every track both.
+*   `default` on a `<track>` makes the browser show it initially.
+
+## Common variations
+
+### Language selection menu
+
+For multiple languages, render a menu instead of a toggle.
+
+Use [`<media-captions-radio-group>`](../reference/captions-radio-group.md) inside a menu or popover for explicit track selection.
+
+## Troubleshooting
+
+### Captions don’t appear
+
+Confirm that:
+
+*   The track `kind` is `captions` or `subtitles`.
+*   The VTT file loads (check the network panel for the track request).
+*   The track is enabled: `default` on the track element, a CaptionsButton toggle, or `toggleSubtitles(true)`.
+
+### Captions work locally but not in production
+
+The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossOrigin` on the media element.
+
+### The selection menu is empty
+
+The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
+
+## Related components
+
+*   [Captions button](../reference/captions-button.md)
+*   [Captions radio group](../reference/captions-radio-group.md)
+*   [Menu](../reference/menu.md)
+
+## Related API
+
+*   [Text track feature](../reference/feature-text-tracks.md)
+*   [useCaptionsOptions](/docs/framework/react/reference/use-captions-options)
+
+## Related guides
+
+*   [Show timeline thumbnail previews](./show-timeline-thumbnail-previews.md)
+*   [Media sources](../concepts/media-sources.md)
+*   [Accessibility](../concepts/accessibility.md)

package/docs/how-to/show-timeline-thumbnail-previews.md

@@ -0,0 +1,164 @@
+# Show timeline thumbnail previews
+
+Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+
+Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
+
+Using Mux?
+
+With [MuxVideo](../reference/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
+
+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 `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [TimeSlider](../reference/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same props as the standalone [Thumbnail](../reference/thumbnail.md).
+
+`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child; set `crossorigin`, `loading`, or `fetchpriority` on the element itself.
+
+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 crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+    </video>
+    <media-time-slider class="media-time-slider">
+      <media-slider-track class="media-slider-track">
+        <media-slider-fill class="media-slider-fill"></media-slider-fill>
+      </media-slider-track>
+      <media-slider-thumbnail class="media-slider-thumbnail"></media-slider-thumbnail>
+    </media-time-slider>
+  </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 6px;
+  left: 10px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+/* Reveal the preview over the pointer while it is on the slider. */
+.media-slider-thumbnail {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  max-width: 160px;
+  margin-bottom: 8px;
+  pointer-events: none;
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-thumbnail {
+  opacity: 1;
+}
+
+.media-slider-thumbnail[data-hidden] {
+  display: none;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time-slider';
+```
+
+## How it works
+
+*   Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+*   The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the demo’s CSS uses them to reveal the preview and position it over the pointer.
+*   To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [Thumbnail](../reference/thumbnail.md) component with an explicit `time`.
+
+Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
+
+storyboard.vtt
+
+```
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+storyboard.jpg#xywh=0,0,256,160
+
+00:00:05.000 --> 00:00:10.000
+storyboard.jpg#xywh=256,0,256,160
+```
+
+## Availability and constraints
+
+*   Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
+*   Cross-origin storyboards need CORS headers, and `crossOrigin` on the media element for the track to load.
+*   Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
+*   Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
+
+## Troubleshooting
+
+### Thumbnails don’t appear while scrubbing
+
+Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossOrigin` set on the media element.
+
+### Thumbnails are blurry or slow
+
+Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
+
+## Related components
+
+*   [Thumbnail](../reference/thumbnail.md)
+*   [Slider](../reference/slider.md)
+*   [Time slider](../reference/time-slider.md)
+
+## Related API
+
+*   [Text track feature](../reference/feature-text-tracks.md)
+
+## Related guides
+
+*   [Add a poster and loading placeholder](./add-a-poster-and-loading-placeholder.md)
+*   [Show captions and subtitles](./show-captions-and-subtitles.md)

package/docs/how-to/use-picture-in-picture.md

@@ -0,0 +1,151 @@
+# Use picture-in-picture
+
+Pop the video into a floating window, with availability detection and state that tracks every entry path.
+
+Pop the video into a floating always-on-top window so it keeps playing while the user does something else.
+
+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 [PiPButton](../reference/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
+
+Exit PiP Enter PiP
+
+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-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>
+```
+```
+.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;
+}
+```
+```
+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/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'`. PiPButton 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 components
+
+*   [PiP button](../reference/pip-button.md)
+
+## Related API
+
+*   [Picture-in-picture feature](../reference/feature-pip.md)
+
+## Related guides
+
+*   [Go fullscreen and lock orientation](./go-fullscreen-and-lock-orientation.md)
+*   [Cast to AirPlay and Chromecast](./cast-to-airplay-and-chromecast.md)

package/docs/how-to/use-videojs-with-svelte.md

@@ -0,0 +1,108 @@
+# Use Video.js with Svelte and SvelteKit
+
+Add Video.js to a Svelte or SvelteKit app
+
+Follow the [installation guide](./installation.md) first. Keep its `@videojs/html` imports and player markup in your Svelte component, then apply the Svelte-specific patterns below.
+
+## Read player state in `onMount`
+
+If your component needs to react to player state or call a player action, wait until Svelte has mounted and bound `<video-player>`. The React API’s `usePlayer` hook is not part of `@videojs/html`, so bind the element to a variable and subscribe to its store in `onMount`:
+
+svelte
+
+```
+<script lang="ts">
+  import type { VideoPlayerElement } from '@videojs/html/video';
+  import { onMount } from 'svelte';
+
+  let player: VideoPlayerElement;
+  let paused = true;
+
+  onMount(() => {
+    const sync = () => (paused = player.store.paused);
+    sync();
+    return player.store.subscribe(sync);
+  });
+</script>
+
+<video-player bind:this={player}><!-- skin and media --></video-player>
+<p>{paused ? 'Paused' : 'Playing'}</p>
+```
+
+Return the store’s unsubscribe function from `onMount` so Svelte cleans up the subscription. Use the store for player state and actions.
+
+When you need the native event itself, attach a listener to the `<video>`, `<audio>`, or media custom element:
+
+svelte
+
+```
+<script lang="ts">
+  function handleLoadedMetadata(event: Event) {
+    const media = event.currentTarget as HTMLVideoElement;
+    console.log(`Duration: ${media.duration} seconds`);
+  }
+</script>
+
+<video onloadedmetadata={handleLoadedMetadata}><!-- sources and tracks --></video>
+```
+
+## Keep runtime styles global
+
+If a style depends on a Video.js `data-*` state, Svelte may remove its selector because that attribute is not present in your component markup. Wrap these runtime-state selectors in Svelte’s [`:global(...)`](https://svelte.dev/docs/svelte/global-styles#global) modifier:
+
+svelte
+
+```
+<style>
+  :global(media-mute-button:not(:defined)) {
+    visibility: hidden;
+  }
+
+  :global(media-mute-button:defined[data-muted]) {
+    color: var(--muted-control-color);
+  }
+</style>
+```
+
+`:defined` applies the state style only after the browser loads the element. These selectors matter when you eject a skin or compose controls yourself. Styles cannot reach controls inside a packaged skin; use its CSS custom properties, or [eject the skin](./customize-skins.md#eject-and-edit-a-skin) to change its markup and CSS.
+
+## Pass objects as properties
+
+If you need to pass structured data, such as a Mux source, an HTML attribute will not work because attributes contain text. Pass the object directly, and Svelte assigns it to the custom element’s JavaScript property:
+
+The Mux media ships as its own adapter package, so add it to the HTML installation used by this example:
+
+bash
+
+```
+pnpm add @videojs/html @videojs/mux-video
+```
+
+svelte
+
+```
+<script lang="ts">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+  import '@videojs/html/media/mux-video';
+</script>
+
+<video-player>
+  <video-skin>
+    <mux-video
+      source={{
+        playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+        playback: { maxResolution: '1080p' },
+      }}
+    ></mux-video>
+  </video-skin>
+</video-player>
+```
+
+Keep the static element import with the component so `<mux-video>` is registered before Svelte assigns the property.
+
+## Use SvelteKit
+
+If you use server rendering, keep the element imports from the installation guide static. SvelteKit renders the custom-element markup on the server, and the browser upgrades it when the page loads. Put code that needs the bound element or browser APIs in `onMount`, as shown above.
+
+If you intentionally import Video.js later from `onMount`, wait for `customElements.whenDefined('video-player')` before reading its store or calling its methods. If Svelte reports a type error for a custom tag or event, add it to `SvelteHTMLElements` by following Svelte’s [DOM type guidance](https://svelte.dev/docs/svelte/typescript#enhancing-built-in-dom-types).