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

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

@@ -1,140 +0,0 @@
-# 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

@@ -1,161 +0,0 @@
-# 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 thumbnail reads the pointer time from the slider, so it takes no props.
-
-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)
-*   [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

@@ -1,151 +0,0 @@
-# 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

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