` and its track, fill, and thumb ``s | `` with ``, ``, `` |
+| ``, `` | ``, `` |
+| ``, ``, `` | Same tags |
+| `` | ``, or `` |
+| ``, ``, ``, ``, `` | No equivalent |
+| ``, ``, `` | A `` trigger, `` as the popup, and `` |
+| ``, `` | ``, ``; radio groups work inside menus only |
+| `` | Not needed; menus render in the top layer |
+| ``, `` | Same tags |
+| ``, `` | ``, `` |
+| ``, `` | No equivalent |
+
+**Popups aren't wrappers anymore.** Vidstack's `` and `` wrapped a trigger and its content. In Video.js, `` and `` *are* the popups, and a trigger points at one by ID:
+
+```html
+
+
+
+
+
+ Play
+
+
+
+
+
+
+
+```
+
+`` fills in the button's current label, such as "Play" or "Pause", unless you write your own text. Submenus become sibling `` elements opened by a ``.
+
+
+A few behaviors changed across the board:
+
+- **Unsupported controls hide themselves.** Vidstack kept them in the DOM without `data-supported`, and you hid them with CSS. Video.js buttons expose `data-availability` and hide when the feature is unsupported.
+- **Sliders take focus on the thumb.** Keyboard control moved from the slider root to its thumb, so a slider without a thumb can't be used from the keyboard.
+- **Toggle buttons change their label instead of setting `aria-pressed`.** A play button announces "Play" or "Pause" depending on state.
+- **Placement is two props.** `placement="top center"` becomes `side="top"` and `align="center"`, and the rendered placement is reflected as `data-side` and `data-align`.
+- **No request events.** Controls call player actions directly, so there's nothing to intercept with `preventDefault()`.
+
+## Read player state
+
+Vidstack's media store becomes the player store. Two differences catch most migrations:
+
+- **State keys come from features.** Every Vidstack key always existed. In Video.js, a key exists only when its feature is part of the player, and some live in no preset.
+- **Subscriptions don't track what you read.** Vidstack's `subscribe` re-ran only when the keys you read changed. The Video.js store notifies on any change; selectors give you change-only updates.
+
+The player store reference lists every state field and action, grouped by the feature that adds it.
+
+
+| Vidstack | Video.js 10 |
+|---|---|
+| `useMediaState('paused')` | `usePlayer((state) => state.paused)` |
+| `useMediaStore()` | `usePlayer((state) => ({ currentTime: state.currentTime, duration: state.duration }))` |
+| `useMediaState('paused', playerRef)`, outside the player | Render `VideoPlayer` higher, around the component that reads state |
+| `useMediaRemote()` | `usePlayer((state) => state.seek)`, or any other action |
+| `useMediaPlayer()` | `usePlayer()` for state and actions, `useContainer()` for the element |
+| `useMediaProvider()` | `useMedia()` |
+| `player.subscribe(callback)` | `usePlayer().subscribe(callback)`, reading values off the store inside |
+
+```tsx
+// Vidstack
+import { useMediaRemote, useMediaState } from '@vidstack/react';
+
+function SkipIntro() {
+ const currentTime = useMediaState('currentTime');
+ const remote = useMediaRemote();
+ if (currentTime > 30) return null;
+ return remote.seek(30, event.nativeEvent)}>Skip intro ;
+}
+```
+
+```tsx
+// Video.js 10
+import { usePlayer } from '@videojs/react/video';
+
+function SkipIntro() {
+ const currentTime = usePlayer((state) => state.currentTime);
+ const seek = usePlayer((state) => state.seek);
+ if (currentTime > 30) return null;
+ return seek(30)}>Skip intro ;
+}
+```
+
+`usePlayer()` with no selector returns the store without subscribing, so `const { paused } = usePlayer()` never re-renders. Always pass a selector for values you render. The preset's `usePlayer` from `@videojs/react/video` is typed to the preset's features; `createPlayer` returns a typed pair for a custom feature list.
+
+`VideoPlayer` renders no DOM, so wrapping more of your page in it is free. That replaces the ref you passed to `useMediaState` to read state from outside the player.
+
+
+
+The store lives on the player element as `store`. State values and actions are properties of it, and `subscribe` reports changes:
+
+```js
+// Vidstack
+const player = document.querySelector('media-player');
+
+player.subscribe(({ paused, currentTime }) => {
+ console.log(paused, currentTime);
+});
+```
+
+```js
+// Video.js 10
+const player = document.querySelector('video-player');
+const { store } = player;
+
+let lastPaused = store.paused;
+store.subscribe(() => {
+ if (store.paused === lastPaused) return;
+ lastPaused = store.paused;
+ console.log(store.paused);
+});
+```
+
+The callback receives no arguments and runs after any state change, batched once per microtask, so compare the values you care about.
+
+Inside a custom element, use a player controller with a selector instead. It updates your element only when the selected state changes. See Build your own UI component .
+
+
+### Drive playback
+
+Vidstack's remote control dispatched request events that the player satisfied. Video.js actions call the media directly. They aren't queued, so most fail until the player has attached to its media, `seek()` included; once attached, `seek()` waits for metadata. Their promises reject where Vidstack fired `play-fail` or `fullscreen-error`.
+
+| Vidstack | Video.js 10 action |
+|---|---|
+| `play()`, `pause()`, `togglePaused()` | `play()`, `pause()` |
+| `seek(time)` | `seek(time)` |
+| `seekToLiveEdge()` | Use `LiveButton`, or seek to the end of the last `seekable` range |
+| `changeVolume(volume)` | `setVolume(volume)`; a value above 0 also unmutes |
+| `mute()`, `unmute()`, `toggleMuted()` | `setMuted(muted)` |
+| `changePlaybackRate(rate)` | `setPlaybackRate(rate)` |
+| `enterFullscreen(target)`, `exitFullscreen()`, `toggleFullscreen()` | `requestFullscreen()`, `exitFullscreen()`; there's no target |
+| `enterPictureInPicture()`, `exitPictureInPicture()`, `togglePictureInPicture()` | `requestPictureInPicture()`, `exitPictureInPicture()` |
+| `toggleCaptions()`, `showCaptions()`, `disableCaptions()` | `toggleSubtitles()`, `toggleSubtitles(true)`, `toggleSubtitles(false)` |
+| `changeTextTrackMode(index, mode)` | `selectSubtitlesTrack(id)`, or `selectSubtitlesTrack(null)` to turn them off |
+| `changeQuality(index)`, `requestAutoQuality()` | `selectVideoRendition(id)`, `selectVideoRendition('auto')` |
+| `changeAudioTrack(index)` | `selectAudioTrack(id)` |
+| `pauseControls()`, `resumeControls()` | `requestControlsLock()`, which returns a release function |
+| `toggleControls()` | `toggleControls()` |
+| `requestAirPlay()`, `requestGoogleCast()` | `promptRemotePlayback()` |
+| `startLoading()`, `startLoadingPoster()`, `changeDuration()`, `changeClipStart()`, `changeAudioGain()`, `seeking()` | No equivalent |
+
+The store has no toggles apart from `toggleSubtitles()` and `toggleControls()`, so call the pair you need, as in `paused ? play() : pause()`. Hotkeys and gestures keep the toggle names, so `togglePaused` still works as their action.
+
+Vidstack methods took an optional trigger event as their last argument. Video.js actions don't, so wrap them in a handler, as in `onClick={() => seek(30)}`. Passing an action straight to `onClick` would hand it the click event.
+
+State keys follow the same pattern. The common renames:
+
+| Vidstack | Video.js 10 |
+|---|---|
+| `canFullscreen`, `canPictureInPicture`, `canSetVolume` | `fullscreenAvailability`, `pictureInPictureAvailability`, `volumeAvailability` |
+| `fullscreen`, `pictureInPicture` | `isFullscreen`, `isPictureInPicture` |
+| `canAirPlay`, `canGoogleCast` | `remotePlaybackAvailability` |
+| `qualities`, `quality`, `autoQuality` | `videoRenditionList`, `activeVideoRendition`; auto is on when no rendition is `selected` |
+| `audioTracks`, `audioTrack` | `audioTrackList`, the entry with `enabled` |
+| `textTracks`, `textTrack` | `textTrackList`, the caption or subtitle entry with `mode: 'showing'`; `subtitlesShowing` says whether there is one |
+| `buffered`, `seekable` | The same names, as arrays of `[start, end]` pairs |
+| `live`, `liveEdge`, `userBehindLiveEdge` | `targetLiveWindow` and `liveEdgeStart`, in the live presets; `LiveButton` computes the live edge |
+| `streamType` | `streamType`, once you add `streamTypeFeature`; only `live`, `on-demand`, and `unknown` |
+| `playing`, `canSeek`, `autoPlayError`, `mediaType`, `viewType`, `orientation`, `pointer`, `width`, `height` | No store key |
+
+Two keys behave differently. `started` can turn off again after the media is reset or sits paused at the start, and `currentTime` follows native `timeupdate`, about four times a second, where Vidstack updated it every animation frame.
+
+### Events
+
+Vidstack fired a normalized set of events on ``, including state-change events such as `fullscreen-change` and `controls-change`. Video.js fires no player events of its own.
+
+
+Put standard media event props on the media component: `onPlay`, `onCanPlay`, `onTimeUpdate`, `onEnded`, and so on. They receive React's synthetic event on media that renders a ``, and a plain `Event` on the embeds, where Vidstack's callbacks received a detail and the event. The embeds route the same prop names. For anything that isn't a media event, read the state:
+
+```tsx
+// Vidstack
+ track(isFullscreen)} />
+
+// Video.js 10
+function FullscreenTracker() {
+ const isFullscreen = usePlayer((state) => state.isFullscreen);
+ // Unlike onFullscreenChange, this also runs once on mount.
+ useEffect(() => track(isFullscreen), [isFullscreen]);
+ return null;
+}
+```
+
+
+
+Listen on the media element with native event names: `canplay` for `can-play`, `loadedmetadata` for `loaded-metadata`, and so on. Media events don't bubble, so a listener on `` won't hear them. For anything that isn't a media event, subscribe to the store and compare values, as in [Read player state](#read-player-state).
+
+
+| Vidstack event | Video.js 10 |
+|---|---|
+| `can-play`, `loaded-metadata`, `time-update`, `duration-change`, `volume-change`, `rate-change` | `canplay`, `loadedmetadata`, `timeupdate`, `durationchange`, `volumechange`, `ratechange` on the media |
+| `fullscreen-change`, `picture-in-picture-change`, `controls-change`, `remote-playback-change` | The `isFullscreen`, `isPictureInPicture`, `controlsVisible`, and `remotePlaybackState` state |
+| `quality-change`, `audio-track-change`, `text-track-change` | The `activeVideoRendition`, `audioTrackList`, and `textTrackList` state |
+| `provider-change`, `provider-setup` | The media's `source`, and its `engine` |
+| `play-fail`, `fullscreen-error`, `picture-in-picture-error` | A rejected action promise |
+| `auto-play-fail` | No event; see [Autoplay](#autoplay) |
+| `media-*-request` | No equivalent |
+| `replay`, `end`, `destroy`, `stream-type-change`, `orientation-change` | No equivalent |
+
+Event triggers, `originEvent`, and `isOriginTrusted` have no equivalent. Check `event.isTrusted` in your own handler before calling an action if you need to know a person started it.
+
+## Captions, chapters, and thumbnails
+
+### Captions
+
+Caption `` elements move from `` to the media. Video.js reads captions and subtitles from those tracks and from streaming manifests.
+
+The browser parses and renders the cues, so:
+
+- **Only WebVTT works.** Vidstack parsed SRT, SSA/ASS, and JSON with `type` ([#3037](https://github.com/videojs/v10/issues/3037)). Convert them to WebVTT at build time or on your server.
+- **Style captions with `::cue`.** ``, its `data-part` selectors, and the `--media-cue-*` variables have no equivalent ([#3038](https://github.com/videojs/v10/issues/3038)). The skins keep native captions clear of the controls in Chromium and WebKit browsers.
+- **There's no caption style menu** for viewers to pick fonts, colors, and backgrounds ([#1437](https://github.com/videojs/v10/issues/1437)). Viewers can still set caption preferences in their operating system or browser.
+- **Adding tracks from code is native.** `textTracks.add()` becomes a `` element, or `addTextTrack()` and `VTTCue` on a plain ``.
+
+The captions toggle picks a track differently. Vidstack restored the last track shown, then the `default` track, then the first one. Video.js restores the last track shown, then one that matches the browser's language, then the first track. See Captions .
+
+### Chapters
+
+A `` still segments the time slider, and the chapter under the pointer shows in the preview. Vidstack's chapters menu, `ChapterTitle` outside the slider, and `useChapterOptions` have no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). To add chapters from code, use the native track APIs described under [Captions](#captions); there's no dedicated chapters API yet ([#1268](https://github.com/videojs/v10/issues/1268)). For a current-chapter label elsewhere, find the cue in the `chaptersCues` state that contains `currentTime`.
+
+### Thumbnails
+
+
+The `thumbnails` layout prop and `Thumbnail`'s `src` become a track on the media, and the skin picks it up:
+
+```tsx
+
+
+
+```
+
+`default` is required, or the cues never load. Set `crossOrigin` on the media when the storyboard comes from another origin. A cross-origin track only loads in CORS mode, and the thumbnail images load in the same mode, so their host needs CORS headers too. Vidstack also accepted JSON and Mux `storyboard.json` URLs ([#3044](https://github.com/videojs/v10/issues/3044)); fetch and convert those yourself and pass the result to the `thumbnails` prop on `Thumbnail.Root`, or use `MuxVideo`, which adds the storyboard track for you. See Thumbnails .
+
+
+
+The `thumbnails` layout attribute and `` become a track on the media, and the skin picks it up:
+
+```html
+
+
+
+```
+
+`default` is required, or the cues never load. Set `crossorigin` on the media when the storyboard comes from another origin. A cross-origin track only loads in CORS mode, and the thumbnail images load in the same mode, so their host needs CORS headers too. Vidstack also accepted JSON and Mux `storyboard.json` URLs ([#3044](https://github.com/videojs/v10/issues/3044)); fetch and convert those yourself and assign the result to the `thumbnails` property on ``, or use ``, which adds the storyboard track for you. See Thumbnails .
+
+
+## Keyboard shortcuts and gestures
+
+### Keyboard shortcuts
+
+The packaged video skins ship a default set close to Vidstack's: Space and `k` to play, `m` to mute, `f` for fullscreen, `c` for captions, `i` for picture-in-picture, arrow keys and `j`/`l` to seek and change volume, `0`–`9` to jump, and `<`/`>` for speed. They also add Home and End. The live skins leave out seeking, jumping, Home and End, and speed, and the audio skins leave out `f`, `c`, and `i`.
+
+Two defaults differ. Seeking moves 10 seconds with or without Shift, where Vidstack's Default Layout moved 10 seconds, or 20 with Shift. And the speed keys step through the fixed rate list and wrap around instead of moving by 0.25.
+
+The `keyShortcuts` prop becomes one hotkey per shortcut in a layout you compose or in skin source. Each takes a single key pattern, so `togglePaused: 'k Space'` becomes two hotkeys:
+
+
+```tsx
+// Vidstack
+
+
+// Video.js 10, inside a Container
+
+
+
+
+```
+
+Shortcuts with custom callbacks become the `useHotkey` hook: `useHotkey({ keys: 'n', onActivate: playNext })`.
+
+
+
+```html
+
+
+
+
+
+```
+
+Shortcuts with custom callbacks become `createHotkey(container, { keys: 'n', onActivate: playNext })`, imported from `@videojs/html`.
+
+
+| Vidstack action | Video.js 10 action |
+|---|---|
+| `togglePaused`, `toggleMuted`, `toggleFullscreen`, `togglePictureInPicture` | Same names |
+| `toggleCaptions` | `toggleSubtitles` |
+| `seekBackward`, `seekForward` | `seekStep` with a negative or positive `value` in seconds |
+| `volumeDown`, `volumeUp` | `volumeStep` with a negative or positive `value` |
+| `speedUp`, `slowDown` | `speedUp`, `speedDown` |
+| Digit keys | `keys="0-9"` with `seekToPercent` |
+
+`keyTarget="document"` becomes `target="document"` on each hotkey. With several players on a page, the first one registered handles the key; Vidstack sent it to the last player you used. `keyDisabled` has no player-wide switch, and packaged skins always include their hotkeys, so remove them in skin source. A tooltip's `Shortcut` part shows the key bound to its button, and buttons set `aria-keyshortcuts` from the registered hotkeys. Writing `aria-keyshortcuts` yourself no longer creates a shortcut. See Keyboard shortcuts .
+
+### Gestures
+
+Vidstack's gestures listened for any DOM event and took their hit area from their own box. Video.js gestures recognize taps and double taps, divide the player into regions, and can be limited to one pointer type:
+
+| Vidstack | Video.js 10 |
+|---|---|
+| `event="pointerup" action="toggle:paused"` | `type="tap" action="togglePaused" pointer="mouse"` |
+| `event="pointerup" action="toggle:controls"` | `type="tap" action="toggleControls" pointer="touch"` |
+| `event="dblpointerup" action="toggle:fullscreen"` | `type="doubletap" action="toggleFullscreen" region="center"` |
+| `event="dblpointerup" action="seek:-10"` on the left edge | `type="doubletap" action="seekStep" value="-10" region="left"` |
+| `event="dblpointerup" action="seek:10"` on the right edge | `type="doubletap" action="seekStep" value="10" region="right"` |
+| Other events, such as `mouseleave` | No equivalent |
+| `will-trigger` and `trigger` events | Use `useTapGesture` or `useDoubleTapGesture` in React, or `createTapGesture` and `createDoubleTapGesture` in HTML, and decide in the callback |
+
+The packaged video skins already bind these defaults. Vidstack's swipe-to-scrub gesture has no equivalent ([#3046](https://github.com/videojs/v10/issues/3046)).
+
+## Fullscreen and orientation
+
+Fullscreen targets the skin's container, falling back to the video element on iPhone. There's no `target` option; to take only the video fullscreen, call the native method on it yourself.
+
+Vidstack locked the screen to landscape in fullscreen by default. Video.js presets don't. Add `orientationLockFeature` to a player built with `createPlayer` to lock it again. Turning Vidstack's fullscreen orientation off just means leaving the feature out. Vidstack's screen orientation state and `lockScreenOrientation()` have no equivalent; use `screen.orientation`.
+
+## Live streams
+
+Vidstack switched the Default Layout to live controls by `streamType`. Video.js has separate live presets, whose skins show a live button and no time slider:
+
+
+```tsx
+import '@videojs/react/live-video/skin.css';
+import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+
+
+
+
+
+```
+
+
+
+```js
+import '@videojs/html/live-video/player';
+import '@videojs/html/live-video/skin';
+import '@videojs/html/media/hlsjs-video';
+```
+
+```html
+
+
+
+
+
+```
+
+
+- **DVR comes from the stream.** `live:dvr` becomes `targetLiveWindow === Infinity`, which the media reports for event playlists. There's no way to force DVR on a sliding window. Add a time slider in skin source to let viewers seek.
+- **The live edge moved to the live button.** `liveEdge`, `userBehindLiveEdge`, and `seekToLiveEdge()` become the live button's state and behavior. It counts playback as live within 5 seconds of the stream's live edge start, which already sits behind the seekable end by the playlist's hold-back. Vidstack counted the last `liveEdgeTolerance` seconds before the seekable end, 10 by default and configurable ([#1730](https://github.com/videojs/v10/issues/1730)).
+- **`streamType` needs a feature.** No preset includes `streamTypeFeature`; add it to a custom player when one player switches between live and on-demand UI.
+- **Live presets are narrower.** They leave out playback rate, quality, and audio-track state. Build a player from a feature list to add them back.
+
+See Live streams .
+
+## AirPlay and Google Cast
+
+The video skins include AirPlay and Cast buttons. Both call one action, `promptRemotePlayback()`, and each button shows only on the platform that supports it. Without the Google Cast extension, the Cast button uses the browser's Remote Playback API.
+
+
+Vidstack's `googleCast` prop becomes the `GoogleCast` extension, placed next to the media:
+
+```tsx
+import { GoogleCast } from '@videojs/react/extensions/google-cast';
+
+
+
+
+
+
+
+```
+
+
+
+Vidstack's `googleCast` property becomes the `` extension, placed next to the media:
+
+```html
+
+
+
+
+```
+
+Register it with `import '@videojs/html/extensions/google-cast'`.
+
+
+Only the receiver ID carries over from Vidstack's Cast options, and the Cast prompt events have no equivalent ([#3048](https://github.com/videojs/v10/issues/3048)). There's no device name or `remotePlaybackType` either ([#3047](https://github.com/videojs/v10/issues/3047)). See Cast to AirPlay and Chromecast .
+
+## Languages
+
+Vidstack layouts took a `translations` object keyed by English strings, and you supplied every language yourself. Video.js ships locale packs for around 50 languages. Wrap the player in the i18n provider and it loads the pack for the nearest `lang` attribute; without one, the controls use English. Override strings with namespaced keys:
+
+
+```tsx
+// Vidstack
+
+
+// Video.js 10
+import { I18nProvider } from '@videojs/react/i18n';
+
+
+ {/* … */}
+
+```
+
+
+
+```js
+import { registerI18n } from '@videojs/html/i18n';
+
+registerI18n('en', {
+ buttons: { play: 'Start video' },
+ menu: { settings: 'Options' },
+});
+```
+
+HTML overrides are global per locale; there's no per-player `translations`. The provider is ``.
+
+
+Strings for the chapters menu, caption styles, audio boost, and download button have no keys, because those features don't exist yet. See Internationalize the player for the full key list.
+
+## Preferences and autoplay
+
+### Saved preferences
+
+Vidstack's `storage` saved volume, mute, captions, language, playback rate, quality, audio gain, and playback position. Video.js doesn't save anything between visits yet ([#944](https://github.com/videojs/v10/issues/944)). Remember user preferences shows how to restore and save volume and caption choices yourself.
+
+### Autoplay
+
+
+Move `autoPlay` from `MediaPlayer` to the media component, along with `muted` and `playsInline`. There's no `auto-play-fail` event or `autoPlayError` state; a blocked autoplay looks like media that never started. To react to it, leave out `autoPlay`, call `play()` once the player attaches, and catch the rejection. See Autoplay .
+
+
+
+Move `autoplay` from `` to the media element, along with `muted` and `playsinline`. There's no `auto-play-fail` event or `autoPlayError` state; a blocked autoplay looks like media that never started. To react to it, leave out `autoplay`, call `play()` once the player attaches, and catch the rejection. See Autoplay .
+
+
+
+
+## Angular and Solid
+
+Vidstack documented Angular and Solid through its web components. Use `@videojs/html` the same way: register the elements with the same imports, and write the same markup.
+
+In Angular, add `CUSTOM_ELEMENTS_SCHEMA` to the `schemas` of the component that renders the player, and bind object values such as `source` as properties with `[source]`. In Solid, set objects with `prop:source`. Solid's JSX types don't read the element types Video.js registers, so declare the tags you use in `JSX.IntrinsicElements`, the way Vidstack's `vidstack/solid` types did. Neither framework has a dedicated installation guide yet; follow the HTML installation guide for the imports.
+
+## Element lifecycle
+
+Vidstack elements destroyed themselves when they were removed from the page and not put back within a frame, unless they carried `keep-alive`, which the player passed down to its children. Video.js keeps the attribute but doesn't pass it down: set it on each element you plan to move. When you're done with them, call `destroy()` on the player and UI elements, and `adapter.destroy()` on media elements. Packaged skins don't pass it to their controls either ([#3036](https://github.com/videojs/v10/issues/3036)), so move a player that uses one synchronously. See the player's lifecycle .
+
+
+
+## Behavior changes to check
+
+These changes don't throw errors, so test for them:
+
+- **Loading.** Media loads as soon as it attaches, not when the player scrolls into view, and embeds don't preconnect.
+- **Size.** There's no default 16:9 box; set `aspect-ratio` on the skin.
+- **Fullscreen.** Presets don't lock the screen to landscape, and media that isn't set to play inline no longer enters fullscreen when it starts on Android and iPad. iPhone Safari still plays it fullscreen natively.
+- **Controls.** They hide as soon as the pointer leaves the player during playback, where Vidstack waited for its 2-second idle delay.
+- **Hotkeys.** Shift no longer doubles the 10-second seek step, and the speed keys wrap around a fixed list.
+- **Captions.** The captions toggle prefers the browser's language over the `default` track.
+- **Embeds.** YouTube URLs and Vimeo no longer use their privacy-enhanced modes by default; `youtube/ID` shorthands still do.
+- **Time.** `currentTime` updates about four times a second instead of every frame.
+- **Live.** Playback counts as live within 5 seconds of the stream's live edge start, not 10 seconds of the seekable end, and live skins have no time slider, quality, audio track, or rate menu.
+- **Volume.** `setVolume()` above 0 also unmutes, and unmuting at 0 restores 25%. Vidstack's controls did the same, but setting its `volume` or `muted` properties didn't.
+- **System integration.** Nothing is saved between visits, and Video.js doesn't set Media Session metadata for lock screens and hardware keys.
+- **Tooltips.** They open after 600 ms instead of 700 ms.
+
+## Known gaps
+
+Ordered roughly by how likely each is to block a Vidstack migration. Follow [Vidstack Parity](https://github.com/videojs/v10/issues/3035) for progress.
+
+- **No automatic provider selection.** `resolveAdapterType` tells you which media component plays a URL, but you render it yourself ([#2160](https://github.com/videojs/v10/issues/2160)).
+- **Nothing persists** between visits: volume, captions, language, rate, quality, or position ([#944](https://github.com/videojs/v10/issues/944)).
+- **No caption style settings** ([#1437](https://github.com/videojs/v10/issues/1437)), no custom caption renderer ([#3038](https://github.com/videojs/v10/issues/3038)), and WebVTT only: no SRT, SSA/ASS, or JSON captions ([#3037](https://github.com/videojs/v10/issues/3037)). Audio players don't show captions ([#3039](https://github.com/videojs/v10/issues/3039)).
+- **No chapters menu** or chapter title outside the time slider ([#1873](https://github.com/videojs/v10/issues/1873)), and no dedicated API for chapters from code ([#1268](https://github.com/videojs/v10/issues/1268)). Cue points and markers aren't implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
+- **Fixed playback rates**: `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` ([#1404](https://github.com/videojs/v10/issues/1404)). No speed or quality sliders ([#3052](https://github.com/videojs/v10/issues/3052)).
+- **No audio gain or boost** ([#1135](https://github.com/videojs/v10/issues/1135)).
+- **No load strategies.** Vidstack's media and poster loading strategies and `startLoading()` have no equivalent ([#3043](https://github.com/videojs/v10/issues/3043)), and embeds don't preconnect ([#1433](https://github.com/videojs/v10/issues/1433)).
+- **No clipping.** Vidstack's clip start and end times have no equivalent ([#3040](https://github.com/videojs/v10/issues/3040)).
+- **No download button** ([#3041](https://github.com/videojs/v10/issues/3041)).
+- **No Remotion provider** or Remotion components ([#3053](https://github.com/videojs/v10/issues/3053)).
+- **No Media Session** metadata from `title`, `artist`, and `artwork` ([#3042](https://github.com/videojs/v10/issues/3042)).
+- **Fixed timing.** The controls hide delay ([#1728](https://github.com/videojs/v10/issues/1728)) and the live edge tolerance ([#1730](https://github.com/videojs/v10/issues/1730)) aren't configurable, and there's no duration override ([#1729](https://github.com/videojs/v10/issues/1729)).
+- **No debug logging** to replace Vidstack's log level ([#1406](https://github.com/videojs/v10/issues/1406)).
+- **Fewer embed conveniences.** No automatic embed posters ([#3049](https://github.com/videojs/v10/issues/3049)), Vimeo chapters ([#3050](https://github.com/videojs/v10/issues/3050)), or Vimeo quality selection ([#3051](https://github.com/videojs/v10/issues/3051)).
+- **Less remote playback detail.** No route type or device name ([#3047](https://github.com/videojs/v10/issues/3047)), and no Cast prompt events or Cast options beyond the receiver ID ([#3048](https://github.com/videojs/v10/issues/3048)).
+- **Fewer time slider and gesture extras.** No video preview in the time slider ([#3045](https://github.com/videojs/v10/issues/3045)), JSON thumbnail storyboards ([#3044](https://github.com/videojs/v10/issues/3044)), or swipe to scrub ([#3046](https://github.com/videojs/v10/issues/3046)).
+- **No request events**, event triggers, or ways to cancel a request, by design.
+- **No light theme for video skins** ([#3054](https://github.com/videojs/v10/issues/3054)), no Plyr-style skin ([#181](https://github.com/videojs/v10/issues/181)), and no Tailwind skin source for HTML ([#3055](https://github.com/videojs/v10/issues/3055)).
+- **No ads** ([#3056](https://github.com/videojs/v10/issues/3056)), which are on the roadmap for late 2026.
+
+## See also
+
+- Build with AI
+- Features and Presets
+- Media sources
+- Skins and Customize skins
+- Migrate from Plyr
diff --git a/site/src/content/docs/guides/v10-roadmap.mdx b/site/src/content/docs/guides/v10-roadmap.mdx
index e0703551d4..c8298751da 100644
--- a/site/src/content/docs/guides/v10-roadmap.mdx
+++ b/site/src/content/docs/guides/v10-roadmap.mdx
@@ -54,7 +54,7 @@ Feature-complete release ahead of GA.
- Core feature parity with v8 in terms of fundamentals
- Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
-- Community encouraged to begin full reintegration projects, following the migration guides for Video.js 8 , Mux Player , Plyr , and Media Chrome
+- Community encouraged to begin full reintegration projects, following the migration guides for Video.js 8 , Mux Player , Plyr , Media Chrome , and Vidstack
- Plugin ecosystem migration begins in earnest
### Engine development focus
diff --git a/site/src/content/docs/reference/components/player.mdx b/site/src/content/docs/reference/components/player.mdx
index a5ab3237ce..0a7aefc20e 100644
--- a/site/src/content/docs/reference/components/player.mdx
+++ b/site/src/content/docs/reference/components/player.mdx
@@ -235,3 +235,26 @@ The player's scope can extend beyond the fullscreen target. Playlists, transcrip
```
+
+
+
+## Lifecycle
+
+Video.js elements clean up after themselves when you remove them from the page:
+
+- `` and the UI elements destroy themselves two animation frames after they're removed. Destroying the player also destroys its store.
+- Media elements such as `` tear down their playback engine in a microtask after they're removed.
+
+Moving an element synchronously, removing it and inserting it elsewhere with no `await` in between, triggers neither. To keep an element through a longer move, add the `keep-alive` attribute:
+
+```html
+
+
+
+
+
+```
+
+`keep-alive` applies only to the element that carries it; descendants don't inherit it. Set it on every Video.js element in the tree you move. Packaged skins don't pass it to the controls inside them, so move a player that uses a packaged skin synchronously. An element with `keep-alive` is never destroyed automatically. When you're finished with it, call `destroy()` on the player and UI elements, and `adapter.destroy()` on media elements, which release their engine that way. A destroyed element can't be reconnected; create a new one instead.
+
+
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index c7c73d7baf..f3f648600a 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -147,6 +147,7 @@ export const sidebar: Sidebar = [
{ slug: 'guides/migrate-from-mux-player', sidebarLabel: 'Mux Player' },
{ slug: 'guides/migrate-from-plyr', sidebarLabel: 'Plyr' },
{ slug: 'guides/migrate-from-media-chrome', sidebarLabel: 'Media Chrome' },
+ { slug: 'guides/migrate-from-vidstack', sidebarLabel: 'Vidstack' },
],
},
],