@videojs/html 10.0.0-rc.4 → 10.0.0-rc.5

package/docs/guides/live-streams.md

@@ -32,9 +32,9 @@ Use the live feature bundle with a streaming media element, and give users a `<m
 </script>
 ```
 
-The examples use [`<hlsjs-video>`](../reference/components/hlsjs-video.md) for broad compatibility, but any streaming media component works here, including the smaller [`<hls-video>`](../reference/components/hls-video.md). Use `<hls-video>` when its supported feature set fits your stream.
+The examples use [`<hlsjs-video>`](../reference/components/hlsjs-video.md). The smaller [`<hls-video>`](../reference/components/hls-video.md) also reports live state; use it when its supported feature set fits your stream.
 
-The `liveVideoFeatures` bundle mirrors [`videoFeatures`](./features.md) but adds the live feature and drops playback rate (not meaningful for live), quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
+The `liveVideoFeatures` bundle starts from [`videoFeatures`](./features.md), adds the live feature, and omits playback rate, quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
 
 Both bundles are plain arrays, so extending one is a spread:
 
@@ -42,9 +42,13 @@ Both bundles are plain arrays, so extending one is a spread:
 import { createPlayer, streamTypeFeature } from '@videojs/html';
 import { liveVideoFeatures } from '@videojs/html/live-video';
 
-const { ProviderMixin } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+const { PlayerElement } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+
+customElements.define('custom-live-player', PlayerElement);
 ```
 
+Use `<custom-live-player>` in place of `<live-video-player>` for this configuration.
+
 ## How it works
 
 Two features describe liveness:
@@ -52,36 +56,70 @@ Two features describe liveness:
 - The [stream type feature](../reference/api/feature-stream-type.md) reports `streamType`: `'live'`, `'on-demand'`, or `'unknown'`. Streaming media derives it from manifest metadata; plain media elements fall back to duration-based detection. `liveVideoFeatures` does not include it; add `streamTypeFeature` to the player’s features when you need `streamType`.
 - The [live feature](../reference/api/feature-live.md) reports two values:
   - `liveEdgeStart` is where “live” begins on the timeline. When the playhead is at or past this time, the viewer is watching live; behind it, they’re watching earlier moments of the stream.
-  - `targetLiveWindow` is how far back the stream lets viewers rewind. `0` means a plain live stream that stays at the edge. `Infinity` means full DVR: rewind as far as the recording goes. `NaN` means the stream isn’t live, or the player doesn’t know yet.
+  - `targetLiveWindow` describes the kind of live window: `0` for a sliding window, `Infinity` for an event with playback history, and `NaN` for on-demand or unknown content. Read `seekable` to find the actual times viewers can rewind to.
 
-The [time feature](../reference/api/feature-time.md) adjusts for live playback: `duration` reports the live edge (the end of the seekable range) and keeps growing as the stream continues.
+The [time feature](../reference/api/feature-time.md) replaces an infinite media duration with the end of the seekable range. That end advances as new segments become available; the start can also advance as old segments expire.
 
-`<media-live-button>` reads this state: it renders as an active “go to live” control while playback is behind the edge, seeks to the edge on activation, and goes inactive at the edge. Until the media reports a `seekable` range — before metadata loads, or for non-live media — the button is disabled (`data-disabled`) because there is no edge to seek to. Custom live UIs should treat “behind the edge” and “actionable” as separate states.
+`<media-live-button>` treats playback as live when the playhead is no more than five seconds behind `liveEdgeStart`. If `liveEdgeStart` is unknown, the button uses the last ten seconds of the seekable range instead. When playback is farther behind, activating the button seeks to the seekable end. The button is disabled (`data-disabled`) when the media is not live or has no finite seekable end. At the edge, it is inactive (`aria-disabled="true"`).
 
 ## Availability and constraints
 
-- `liveEdgeStart` and `targetLiveWindow` come from media that implements the live capability — the hls.js-based media elements. With plain media elements, stream type falls back to duration-based detection and `liveEdgeStart` stays `NaN`.
+- `liveEdgeStart` and `targetLiveWindow` require media that implements the live capability. Examples include [hls.js video](../reference/components/hlsjs-video.md), [SPF HLS video](../reference/components/hls-video.md), [native HLS video](../reference/components/native-hls-video.md), and [Shaka video](../reference/components/shaka-video.md). Native HLS video requires browser HLS support. A plain `<video>` can report a live `streamType` from its duration, but its live-window values stay `NaN`.
 - Live playback drifts behind the edge when the network stalls or the tab is backgrounded. Always give users a path back to the edge.
-- Seeking makes sense only for DVR streams (`targetLiveWindow` of `Infinity`). For standard-latency streams, omit the time slider.
-- Playback rate control isn’t meaningful for live; `liveVideoFeatures` omits it.
+- Both sliding live windows and growing event histories can support seeking. Check `seekable` for the available range. The built-in time slider starts at zero, so use it only while the seekable history starts at zero; a moving start requires a custom slider.
+- `liveVideoFeatures` omits playback rate control. Add it explicitly if your DVR UI needs it.
 
 ## Common variations
 
 ### DVR: let users scrub back
 
-For streams with a DVR window, give users a [`<media-time-slider>`](../reference/components/time-slider.md). The live preset skins don’t include one, so add it to your custom UI or [add the live skin source to your project](./customize-skins.md#style-skin-source). The slider tracks the sliding window automatically because `duration` follows the live edge.
+For a live event whose seekable history starts at zero, add a [`<media-time-slider>`](../reference/components/time-slider.md) to your custom UI or [customized live skin](./customize-skins.md#style-skin-source). Its maximum follows the seekable end. For a sliding window whose start moves forward, build a slider from the current `seekable` start and end; the built-in slider would include expired times.
 
 ### Switch UI by stream type
 
 Render live or on-demand controls from `streamType` when one player handles both kinds of content. Add `streamTypeFeature` to the player’s features; `liveVideoFeatures` does not include it:
 
-`<media-live-button>` selects from the live, time, and buffer features and reflects live state. To swap larger parts of the UI on `streamType`, build a provider with [createPlayer](../reference/api/html-create-player.md) and add `streamTypeFeature` to its features (`<live-video-player>` uses `liveVideoFeatures`, which does not include it), then read `streamType` from the player store through the [player controller](../reference/api/player-controller.md).
+`<media-live-button>` already reflects live state. To show a whole group of controls only for live streams, compose a custom player and subscribe to its store:
+
+```html
+<stream-type-player>
+  <media-container>
+    <hlsjs-video src="https://your-stream.example.com/live.m3u8" autoplay muted playsinline></hlsjs-video>
+    <div id="live-controls" hidden>
+      <media-live-button></media-live-button>
+    </div>
+  </media-container>
+</stream-type-player>
+<script type="module">
+  import { createPlayer, selectStreamType, streamTypeFeature } from '@videojs/html';
+  import { liveVideoFeatures } from '@videojs/html/live-video';
+  import '@videojs/html/media/hlsjs-video';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/ui/live-button';
+
+  const { PlayerElement } = createPlayer({
+    features: [...liveVideoFeatures, streamTypeFeature],
+  });
+  customElements.define('stream-type-player', PlayerElement);
+
+  const player = document.querySelector('stream-type-player');
+  const store = player.store;
+  const controls = document.querySelector('#live-controls');
+  const update = () => {
+    controls.hidden = selectStreamType(store.state)?.streamType !== 'live';
+  };
+
+  const unsubscribe = store.subscribe(update);
+  update();
+  // Call unsubscribe() when this player is removed.
+</script>
+```
 
 ## Troubleshooting
 
 ### The live badge never activates
 
-`streamType` isn’t `'live'`. Confirm the player’s features include `streamTypeFeature` (`liveVideoFeatures` does not include it, so `streamType` reads as `undefined`), the source is a live manifest, and it plays through a live-capable media element such as [`<hlsjs-video>`](../reference/components/hlsjs-video.md).
+`<media-live-button>` reads `targetLiveWindow`, `currentTime`, and `seekable`. Confirm that `targetLiveWindow` is `0` or `Infinity` and that `seekable` has a finite end. Use a live-capable media element such as [`<hlsjs-video>`](../reference/components/hlsjs-video.md). The live button does not need `streamTypeFeature`; add it only when your own UI reads `streamType`.
 
 ### Playback keeps falling behind the edge
 
@@ -89,7 +127,7 @@ Network throughput can’t sustain the stream, or the tab was backgrounded. `<me
 
 ### The time slider behaves oddly on a live stream
 
-Standard-latency live streams have no meaningful seek range. Show the slider only for DVR streams (`targetLiveWindow` of `Infinity`).
+Compare the slider’s range with `seekable`. The built-in slider always starts at zero. Once a sliding window moves past zero, the slider’s range includes expired history. Use a custom slider that follows both range bounds, or keep the live button without a timeline.
 
 ## Related pages
 

package/docs/guides/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML Guides
 
-> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/html` v10.0.0-rc.4. Links are relative paths to files in this directory.
+> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/html` v10.0.0-rc.5. Links are relative paths to files in this directory.
 
 ## Getting Started
 
@@ -15,7 +15,7 @@ Install Video.js, customize a skin, understand its main pieces, check browser an
 - [Architecture](./architecture.md): How Video.js players are structured — state, UI, media, and extensions
 - [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
 - [Why Video.js?](./why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
-- [Browser support](./browser-support.md): Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
+- [Browser support](./browser-support.md): Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them
 - [Build with AI](./build-with-ai.md): Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
 - [v10 Roadmap](./v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
 - [Contribute to Video.js](https://github.com/videojs/v10/blob/main/CONTRIBUTING.md)
@@ -64,7 +64,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Show timeline thumbnail previews](./thumbnails.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
 - [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
 - [Handle playback errors](./playback-errors.md): Display playback failures, report them, and choose a useful recovery action.
-- [Remember user preferences](./user-preferences.md): Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+- [Remember user preferences](./user-preferences.md): Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.
 - [Add a background video](./background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
 - [Internationalize the player](./internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
 - [Monitor playback with Mux Data](./mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
@@ -74,6 +74,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 Guides for moving an existing player integration to Video.js v10, one per player you might be coming from.
 
 - [Migrate from Video.js 8](./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](./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 Mux Player](./migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10 using a player, media component, skin, and analytics extension
 - [Migrate from Plyr](./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](./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
+- [Migrate from Media Chrome](./migrate-from-media-chrome.md): Move a Media Chrome player to Video.js v10, mapping its controller, controls, styles, and imperative calls
+- [Migrate from Vidstack](./migrate-from-vidstack.md): Move a Vidstack Player integration to Video.js 10, mapping the player, providers, layouts, and media store onto composed components

package/docs/guides/media-sources.md

@@ -14,7 +14,7 @@ video.source = {
 };
 ```
 
-## Three tiers, three homes
+## Where source options belong
 
 The shape answers one question: does this option describe the source, or how to play it?
 
@@ -69,7 +69,7 @@ video.source = { src, engine: { hlsJs: { maxBufferLength: 60 } } };
 video.source = { src, engine: { hlsJs: { maxBufferLength: 60 } } }; // no-op
 ```
 
-Only a change to the engine options, `preferPlayback`, or the resolved content type recreates the playback engine.
+The hls.js adapter recreates its playback engine when `source.engine`, `source.drm`, `source.preferPlayback`, or the resolved content type changes. A new URL with the same resolved type reuses the engine when those options are unchanged. dash.js and Shaka apply changes to their engine settings in place.
 
 > **Note**
 >
@@ -84,6 +84,7 @@ Engine options live under `source.engine`, **namespaced by engine**. Each key th
 | `engine.hlsJs` | [`<hlsjs-video>`](../reference/components/hlsjs-video.md), [`<mux-video>`](../reference/components/mux-video.md), [`<mux-audio>`](../reference/components/mux-audio.md) | an [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) |
 | `engine.nativeHls` | [`<native-hls-video>`](../reference/components/native-hls-video.md), and the three above whenever the browser plays the manifest | options for the browser’s own HLS support (today, [DRM](#licensing-one-engine-differently)) |
 | `engine.dashJs` | [`<dash-video>`](../reference/components/dash-video.md) | [dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) |
+| `engine.shaka` | [`<shaka-video>`](../reference/components/shaka-video.md) | a [Shaka Player configuration](https://shaka-project.github.io/shaka-player/docs/api/shaka.extern.html#.PlayerConfiguration) |
 | `engine.vimeo` | [`<vimeo-video>`](../reference/components/vimeo-video.md) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
 | `engine.youtube` | [`<youtube-video>`](../reference/components/youtube-video.md) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
 | `engine.cloudflare` | [`<cloudflare-video>`](../reference/components/cloudflare-video.md) | [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) |
@@ -102,7 +103,7 @@ video.source = {
 };
 ```
 
-dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
+dash.js applies `engine.dashJs` settings to the running player:
 
 ```ts
 const video = document.querySelector('dash-video');
@@ -115,6 +116,8 @@ video.source = {
 
 Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.
 
+Shaka also applies `engine.shaka` configuration to the running player without recreating it. Dropping a key restores its default. Video.js enables `abr.restrictToElementSize` by default to limit adaptation to the player size.
+
 ### Options Video.js normalizes
 
 Where an option means the same thing across engines, it sits on `source` itself rather than inside an engine’s namespace.
@@ -262,7 +265,7 @@ video.source = {
 };
 ```
 
-DRM playback is always signed, so a `playback.token` belongs alongside it — and `poster.token` / `storyboard.token` for the images. Each is scoped to a different audience, so they are four separate tokens rather than one reused four times. Sign them on your server; see [Mux’s DRM guide](https://www.mux.com/docs/guides/protect-videos-with-drm) for how.
+DRM playback is always signed, so a `playback.token` belongs alongside it — and `poster.token` / `storyboard.token` for the images. Each is scoped to a different audience, so they are four separate tokens rather than one reused four times. Sign them on your server; see [Mux’s DRM guide](https://www.mux.com/docs/guides/protect-videos-with-drm?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) for how.
 
 A `drm.token` that isn’t scoped to DRM is ignored rather than sent, since the license request would be rejected. License servers named alongside the token win, key by key, for the systems Mux doesn’t license:
 
@@ -292,7 +295,7 @@ It’s read-only and derived from `source`, so read it again after `sourcechange
 
 One more key arrives later. Mux publishes a small metadata document for each asset, and the media loads it alongside the stream, so `contentData.title` fills in with the asset’s title once it does — `contentdatachange` announces it. The player reads it as the fallback for its own title, so a Mux asset titled in the dashboard names itself without a `content-title` on the player. Any other entries the document carries ride along under their own keys. An untitled asset adds nothing.
 
-`source.poster` takes the [full set of Mux image modifiers](https://www.mux.com/docs/guides/get-images-from-a-video), so a narrower still for a small viewport is a `width`:
+`source.poster` takes the [full set of Mux image modifiers](https://www.mux.com/docs/guides/get-images-from-a-video?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content), so a narrower still for a small viewport is a `width`:
 
 ```ts
 video.source = { ...video.source, poster: { width: 320 } };