@videojs/html 10.0.0-beta.8 → 10.0.0-rc.1

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

@@ -0,0 +1,159 @@
+# Use Video.js with Vue and Nuxt
+
+Add Video.js to a Vue or Nuxt app
+
+Follow the [installation guide](./installation.md) first. Keep its `@videojs/html` imports and player markup in your Vue component, then apply the Vue-specific configuration below.
+
+## Configure custom element tags
+
+If Vue warns that it cannot resolve a Video.js tag, the compiler is treating that tag as a Vue component. Use Vue’s [`isCustomElement`](https://vuejs.org/guide/extras/web-components.html#skipping-component-resolution) option to identify the exact Video.js tags in your templates.
+
+For a Vue app built with Vite:
+
+vite.config.ts
+
+```
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+const videoJsElements = new Set(['video-player', 'video-skin', 'mux-video']);
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => videoJsElements.has(tag),
+        },
+      },
+    }),
+  ],
+});
+```
+
+For Nuxt:
+
+nuxt.config.ts
+
+```
+const videoJsElements = new Set(['video-player', 'video-skin', 'mux-video']);
+
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => videoJsElements.has(tag),
+    },
+  },
+});
+```
+
+List only the tags that appear in your templates. Avoid broad rules such as allowing every hyphenated tag or every tag with one prefix: Video.js uses several tag families, and broad rules can also hide misspelled Vue components.
+
+## Read player state
+
+If your Vue component needs to react to player state or call a player action, wait until Vue has mounted `<video-player>`. The React API’s `usePlayer` hook is not part of `@videojs/html`, so use a template ref and subscribe to the element’s store:
+
+vue
+
+```
+<script setup lang="ts">
+import type { VideoPlayerElement } from '@videojs/html/video';
+import { onMounted, onUnmounted, ref } from 'vue';
+
+const player = ref<VideoPlayerElement | null>(null);
+const paused = ref(true);
+let unsubscribe = () => {};
+
+onMounted(() => {
+  const store = player.value!.store;
+  const sync = () => (paused.value = store.paused);
+  sync();
+  unsubscribe = store.subscribe(sync);
+});
+
+onUnmounted(() => unsubscribe());
+</script>
+
+<template>
+  <video-player ref="player"><!-- skin and media --></video-player>
+  <p>{{ paused ? 'Paused' : 'Playing' }}</p>
+</template>
+```
+
+Use the store for player state and actions. Unsubscribe in `onUnmounted`.
+
+When you need the native event itself, attach a listener to the `<video>`, `<audio>`, or media custom element:
+
+vue
+
+```
+<script setup lang="ts">
+function handleLoadedMetadata(event: Event) {
+  const media = event.currentTarget as HTMLVideoElement;
+  console.log(`Duration: ${media.duration} seconds`);
+}
+</script>
+
+<template>
+  <video @loadedmetadata="handleLoadedMetadata"><!-- sources and tracks --></video>
+</template>
+```
+
+## Style Vue components
+
+If you want to hide an element until the browser loads it, use `:defined` in your component’s scoped styles:
+
+vue
+
+```
+<style scoped>
+video-skin:not(:defined) {
+  visibility: hidden;
+}
+</style>
+```
+
+Scoped 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. Vue’s [`.prop` modifier](https://vuejs.org/api/built-in-directives.html#v-bind) assigns the value to the 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
+```
+
+vue
+
+```
+<script setup lang="ts">
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+import '@videojs/html/media/mux-video';
+
+const source = {
+  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+  playback: { maxResolution: '1080p' },
+} as const;
+</script>
+
+<template>
+  <video-player>
+    <video-skin>
+      <mux-video :source.prop="source"></mux-video>
+    </video-skin>
+  </video-player>
+</template>
+```
+
+Use `.prop` explicitly. An ordinary binding or render-function prop can become an attribute if Vue runs before the custom element finishes loading. Video.js preserves explicitly assigned properties during that upgrade.
+
+## Use Nuxt
+
+If you use server rendering, keep the element imports from the installation guide static. Nuxt renders the custom-element markup on the server, and the browser upgrades it when the page loads.
+
+If you intentionally keep registration client-only, import the elements from a `.client.ts` plugin and wait for `customElements.whenDefined('video-player')` before reading its store or calling its methods. For custom tag or event types, follow Vue’s [TypeScript guidance for non-Vue custom elements](https://vuejs.org/guide/extras/web-components.html#non-vue-web-components-and-typescript).

package/docs/llms.txt

@@ -0,0 +1,221 @@
+# Video.js v10 — Html Documentation
+
+## Start here
+
+Install Video.js, understand its main pieces, or move an existing player to Video.js 10.
+
+- [Installation](./how-to/installation.md): Install Video.js and build your first player with streaming support and accessible controls
+- [Overview](./concepts/overview.md): How Video.js players are structured — state, UI, media, and extensions
+- [Why Video.js?](./concepts/why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [v10 Roadmap](./concepts/v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
+### Migrate to Video.js 10
+
+Guides for moving an existing player integration to Video.js v10, one per player you might be coming from.
+
+- [Migrate from Video.js 8](./how-to/migrate-from-video-js-8.md): Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
+- [Migrate from Mux Player](./how-to/migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
+- [Migrate from Plyr](./how-to/migrate-from-plyr.md): Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
+- [Migrate from Media Chrome](./how-to/migrate-from-media-chrome.md): Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
+
+## Tooling
+
+Guidance for AI tools, browser support, TypeScript, bundlers, and loading Video.js from a CDN.
+
+- [Build with AI](./how-to/build-with-ai.md): How to give AI tools the context they need to build Video.js players alongside you
+- [Browser support](./concepts/browser-support.md): Browsers and rendering environments supported by Video.js 10
+- [TypeScript](./concepts/typescript.md): TypeScript version and module resolution requirements for Video.js packages
+- [Bundlers](./concepts/bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries
+- [CDN](./concepts/cdn.md): The files the Video.js CDN serves and the layout rules behind their URLs
+
+## Concepts
+
+Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
+
+- [Features](./concepts/features.md): The state and actions each feature adds to the player
+- [Skins](./concepts/skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+- [UI components](./concepts/ui-components.md): How Video.js UI components use focused elements, data attributes for state, and compound composition.
+- [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Media sources](./concepts/media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Mux Data](./concepts/mux-data.md): Monitor playback quality and viewer experience by adding the Mux Data extension to a player
+- [Security](./concepts/security.md): How to configure Content Security Policy for your video player
+- [Custom element lifecycle](./concepts/custom-element-lifecycle.md): Choose the right Video.js HTML base class and clean up custom elements when they leave the page.
+
+## How to
+
+Task-oriented guides that each answer one goal in the reader's words. Some cover custom player UI; others configure a preset, skin, media component, or extension. Guides lead with the recommended path, then the constraints and variations needed to apply it.
+
+- [Customize skins](./how-to/customize-skins.md): Style a packaged Video.js skin or copy its source to change controls, layout, styles, and interactions
+- [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+- [Add a poster and loading placeholder](./how-to/add-a-poster-and-loading-placeholder.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+### Integrate with a framework
+
+Guides for using the HTML version of Video.js with Vue, Nuxt, Svelte, or SvelteKit.
+
+- [Use Video.js with Vue and Nuxt](./how-to/use-videojs-with-vue.md): Add Video.js to a Vue or Nuxt app
+- [Use Video.js with Svelte and SvelteKit](./how-to/use-videojs-with-svelte.md): Add Video.js to a Svelte or SvelteKit app
+
+- [Autoplay](./how-to/autoplay.md): Start playback automatically and handle browser autoplay restrictions.
+- [Automatically show and hide controls](./how-to/show-and-hide-controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
+- [Show captions and subtitles](./how-to/show-captions-and-subtitles.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Add keyboard shortcuts and gestures](./how-to/add-keyboard-shortcuts-and-gestures.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Play live streams](./how-to/play-live-streams.md): Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+- [Add a quality selector](./how-to/add-quality-selector.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
+- [Go fullscreen and lock orientation](./how-to/go-fullscreen-and-lock-orientation.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Use picture-in-picture](./how-to/use-picture-in-picture.md): Pop the video into a floating window, with availability detection and state that tracks every entry path.
+- [Show timeline thumbnail previews](./how-to/show-timeline-thumbnail-previews.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+- [Cast to AirPlay and Chromecast](./how-to/cast-to-airplay-and-chromecast.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
+- [Handle playback errors](./how-to/handle-playback-errors.md): Surface terminal playback errors and give users a useful next step.
+- [Remember user preferences](./how-to/remember-user-preferences.md): Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+- [Add a background video](./how-to/add-a-background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
+- [Internationalize the player](./how-to/internationalize-the-player.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
+- [Self-host the player](./how-to/self-host-the-player.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments
+
+## Components
+
+API reference for skins, interface components, media components, and service integrations.
+
+### Skins
+
+API reference for the packaged skins each preset ships.
+
+- [video-skin](./reference/video-skin.md): The video preset's default skin with the modern, frosted look
+- [video-minimal-skin](./reference/video-minimal-skin.md): The video preset's visually lighter skin, closer to a classic control bar
+- [audio-skin](./reference/audio-skin.md): The audio preset's default skin with the modern, frosted look
+- [audio-minimal-skin](./reference/audio-minimal-skin.md): The audio preset's visually lighter skin, closer to a classic control bar
+- [live-video-skin](./reference/live-video-skin.md): The live video preset's default skin, which swaps time controls for a Live button
+- [live-video-minimal-skin](./reference/live-video-minimal-skin.md): The live video preset's visually lighter skin, closer to a classic control bar
+- [live-audio-skin](./reference/live-audio-skin.md): The live audio preset's default skin, which swaps time controls for a Live button
+- [live-audio-minimal-skin](./reference/live-audio-minimal-skin.md): The live audio preset's visually lighter skin, closer to a classic control bar
+- [background-video-skin](./reference/background-video-skin.md): The background preset's chrome-less skin for ambient video
+
+### UI
+
+API reference for components used to build a media player interface.
+
+- [video-player](./reference/player.md): The state boundary — creates a store and broadcasts it to all descendants.
+- [media-container](./reference/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+- [media-airplay-button](./reference/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [media-alert-dialog](./reference/alert-dialog.md): A modal alert dialog for urgent messages that require acknowledgement
+- [media-audio-track-radio-group](./reference/audio-track-radio-group.md): A menu radio group for selecting an audio track
+- [media-buffering-indicator](./reference/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+- [media-captions-button](./reference/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [media-captions-radio-group](./reference/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [media-cast-button](./reference/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
+- [media-controls](./reference/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [media-dialog](./reference/dialog.md): A modal dialog for application content, including players opened from a thumbnail
+- [media-error-dialog](./reference/error-dialog.md): An alert dialog that presents and dismisses playback errors
+- [media-fullscreen-button](./reference/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [media-gesture](./reference/gesture.md): Map tap and double-tap gestures to player actions
+- [media-hotkey](./reference/hotkey.md): Register a keyboard shortcut that invokes a player action
+- [media-live-button](./reference/live-button.md): Accessible live indicator button that seeks to the live edge when pressed
+- [media-menu](./reference/menu.md): A composable menu component for settings, option selection, and actions
+- [media-mute-button](./reference/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [media-pip-button](./reference/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+- [media-play-button](./reference/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
+- [media-playback-rate-button](./reference/playback-rate-button.md): A button that cycles through playback speed rates
+- [media-playback-rate-radio-group](./reference/playback-rate-radio-group.md): A menu radio group for selecting playback speed
+- [media-popover](./reference/popover.md): A popover component for displaying contextual content anchored to a trigger
+- [media-poster](./reference/poster.md): Poster image component that displays a thumbnail until video playback starts
+- [media-quality-radio-group](./reference/quality-radio-group.md): A menu radio group for selecting video quality
+- [media-seek-button](./reference/seek-button.md): Accessible seek button for skipping forward or backward by a configurable number of seconds
+- [media-seek-indicator](./reference/seek-indicator.md): A temporary visual indicator for keyboard and gesture seeking
+- [media-slider](./reference/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [media-status-announcer](./reference/status-announcer.md): Announce player state changes through a persistent status live region
+- [media-status-indicator](./reference/status-indicator.md): Display temporary visual feedback for keyboard and gesture actions
+- [media-thumbnail](./reference/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [media-time](./reference/time.md): Time display components for showing current time, duration, and remaining time in a video player
+- [media-time-slider](./reference/time-slider.md): A slider component for seeking through media playback time
+- [media-title](./reference/title.md): Displays the resolved content title for the current media
+- [media-tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
+- [media-volume-indicator](./reference/volume-indicator.md): Display temporary visual feedback for keyboard and gesture volume actions
+- [media-volume-popover](./reference/volume-popover.md): A volume-aware popover that keeps mute available when volume level controls are unavailable
+- [media-volume-slider](./reference/volume-slider.md): A slider component for controlling media playback volume
+
+### Media
+
+API reference for media components that handle streaming protocols and playback.
+
+- [audio](./reference/audio.md): Native audio playback that can provide media to a Video.js player
+- [background-video](./reference/background-video.md): Decorative background video element with automatic muting and looping
+- [cloudflare-video](./reference/cloudflare-video.md): Video component that plays Cloudflare Stream videos through the Stream player
+- [dash-video](./reference/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+- [hls-audio](./reference/hls-audio.md): Audio-only HLS element that plays the audio rendition of an HLS stream
+- [hls-background-video](./reference/hls-background-video.md): HLS background video without controls, audio, captions, or adaptive quality
+- [hls-video](./reference/hls-video.md): Lightweight HLS video element with minimal bundle size
+- [hlsjs-video](./reference/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [mux-audio](./reference/mux-audio.md): Audio element for Mux-hosted HLS streams
+- [mux-background-video](./reference/mux-background-video.md): Mux-specific name for the HLS background video component
+- [mux-video](./reference/mux-video.md): Video element for Mux-hosted HLS streams
+- [native-hls-video](./reference/native-hls-video.md): HLS video element using the browser's built-in HLS support
+- [shaka-video](./reference/shaka-video.md): Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+- [spotify-audio](./reference/spotify-audio.md): Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed
+- [tiktok-video](./reference/tiktok-video.md): Video component that plays TikTok videos through the TikTok embed player
+- [twitch-video](./reference/twitch-video.md): Video component that plays Twitch videos and live channels through the Twitch embed player
+- [video](./reference/video.md): Native video playback that can provide media to a Video.js player
+- [vimeo-video](./reference/vimeo-video.md): Video component that plays Vimeo videos and live events through the Vimeo player
+- [wistia-video](./reference/wistia-video.md): Video component that plays Wistia-hosted videos through Wistia's web component
+- [youtube-video](./reference/youtube-video.md): Video component that plays YouTube videos and playlists through the YouTube IFrame player
+
+### Extensions
+
+API reference for extensions that connect external services to the player.
+
+- [google-cast](./reference/google-cast.md): Options for the Google Cast extension that configures the receiver and load request
+- [mux-data](./reference/mux-data.md): Options for the Mux Data extension that monitors playback quality
+
+## Helpers
+
+Reference for player features and lower-level tools used to build or extend a player.
+
+### Player Features
+
+API reference for the feature modules passed to createPlayer, which provide player capabilities and state.
+
+- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
+- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
+- [Error](./reference/feature-error.md): Media error state and actions for the player store
+- [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Live](./reference/feature-live.md): Live edge state for the player store
+- [Metadata](./reference/feature-metadata.md): Resolved title and poster values for the player store
+- [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
+- [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
+- [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
+- [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
+- [Quality](./reference/feature-quality.md): Video rendition state and actions for the player store
+- [Audio track](./reference/feature-audio-track.md): Audio track state and actions for the player store
+- [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
+- [Source](./reference/feature-source.md): Media source state and actions for the player store
+- [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./reference/feature-time.md): Playback position and duration state for the player store
+- [Volume](./reference/feature-volume.md): Volume level and mute state for the player store
+
+### Utilities
+
+API reference for the hooks, utilities, controllers, and mixins used to integrate a player into an application.
+
+- [createPlayer](./reference/html-create-player.md): Factory function that creates a typed player element and controller for HTML custom elements
+- [PlayerController](./reference/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [createI18n](./reference/create-i18n.md): Factory that creates framework i18n helpers with custom loading options
+- [media-i18n](./reference/media-i18n.md): HTML custom element that resolves locale and supplies translations to descendants
+- [media-text](./reference/media-text.md): HTML custom element that renders a translated string by semantic key
+#### Advanced
+
+Lower-level translation, player context, lifecycle, attachment, and state tools.
+
+- [Translation phrases](./reference/translation-phrases.md): Semantic i18n keys, their English defaults, and the player UI that uses them
+- [registerI18n](./reference/register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+- [getI18nTranslations](./reference/get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
+- [hasRegisteredLocale](./reference/has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
+- [onI18nRegistryChange](./reference/on-i18n-registry-change.md): Subscribe to global i18n registry mutations
+- [createTranslator](./reference/create-translator.md): Build a typed translator from a resolved translation map
+- [i18nContext](./reference/html-i-18-n-context.md): Default HTML context carrying the active translator and locale
+- [I18nController](./reference/i-18-n-controller.md): Reactive controller for consuming translator and locale values from an HTML i18n context
+- [AriaKeyShortcutsController](./reference/aria-key-shortcuts-controller.md): Reactive controller that exposes registered hotkey shortcut metadata
+- [MediaAttachMixin](./reference/media-attach-mixin.md): Mixin for custom media elements to register themselves with the provider via context
+- [playerContext](./reference/player-context.md): The default player context instance for consuming the player store in controllers
+- [SnapshotController](./reference/snapshot-controller.md): Reactive controller for subscribing to a State container in HTML custom elements
+- [StoreController](./reference/store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
+- [SubscriptionController](./reference/subscription-controller.md): Reactive controller that resolves a store and manages a derived subscription