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

package/docs/guides/live-streams.md

@@ -0,0 +1,139 @@
+# Play live streams
+
+Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+
+> **Note**
+>
+> Using a pre-built [skin](./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](./ui-components.md).
+
+## Installation
+
+The examples use HlsJsVideo, so install hls.js with the framework façade:
+
+```bash
+pnpm add @videojs/react @videojs/hlsjs-video
+```
+
+## Recommended approach
+
+Use the live feature bundle with a streaming media element, and give users a `LiveButton`: it shows whether playback is at the live edge and seeks back to it when activated.
+
+```tsx
+import { Container, LiveButton } from '@videojs/react';
+import { LiveVideoPlayer } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+export default function App() {
+  return (
+    <LiveVideoPlayer>
+      <Container>
+        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
+        <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />
+      </Container>
+    </LiveVideoPlayer>
+  );
+}
+```
+
+The examples use [`HlsJsVideo`](../reference/components/hlsjs-video.md) for broad compatibility, but any streaming media component works here, including the smaller [`HlsVideo`](../reference/components/hls-video.md). Use `HlsVideo` 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.
+
+Both bundles are plain arrays, so extending one is a spread:
+
+```tsx
+import { createPlayer, streamTypeFeature } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+
+const { Player } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+```
+
+## How it works
+
+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.
+
+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.
+
+LiveButton 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.
+
+## 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`.
+- 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.
+
+## Common variations
+
+### DVR: let users scrub back
+
+For streams with a DVR window, give users a [TimeSlider](../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.
+
+### 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:
+
+The preset `LiveVideoPlayer` comes with a fixed feature set. To change it, build the player yourself with [`createPlayer`](../reference/api/create-player.md) — the escape hatch for custom feature sets:
+
+```tsx
+import { Container, createPlayer, LiveButton, streamTypeFeature } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+const { Player, usePlayer } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+
+function LiveBadge() {
+  const streamType = usePlayer((s) => s.streamType);
+  if (streamType !== 'live') return null;
+
+  return <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />;
+}
+
+export default function App() {
+  return (
+    <Player>
+      <Container>
+        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
+        <LiveBadge />
+      </Container>
+    </Player>
+  );
+}
+```
+
+## 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 [HlsJsVideo](../reference/components/hlsjs-video.md).
+
+### Playback keeps falling behind the edge
+
+Network throughput can’t sustain the stream, or the tab was backgrounded. LiveButton returns users to the edge; for lower drift, review the stream’s latency configuration on the encoder side.
+
+### 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`).
+
+## Related pages
+
+### Components
+
+- [TimeSlider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+- [BufferingIndicator](../reference/components/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+
+### API
+
+- [Live](../reference/api/feature-live.md): Live edge state for the player store
+- [Stream type](../reference/api/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Time](../reference/api/feature-time.md): Playback position and duration state for the player store
+- [HlsJsVideo](../reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property

package/docs/guides/llms.txt

@@ -0,0 +1,67 @@
+# Video.js v10 — React Guides
+
+> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/react` v10.0.0-rc.3. Links are relative paths to files in this directory.
+
+## Getting Started
+
+Install Video.js, customize a skin, understand its main pieces, check browser and AI tool support, and contribute.
+
+- [React Installation Guide](./installation.md): Install Video.js in React and build an accessible, customizable video player with composable controls
+- [Shadcn Installation Guide](./installation-shadcn.md): Add editable React or HTML skin source with the Shadcn registry
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+- [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
+- [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)
+
+## Environment
+
+TypeScript, bundlers, and Content Security Policy.
+
+- [TypeScript](./typescript.md): TypeScript version and module resolution requirements for Video.js packages
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries
+- [Content Security Policy](./content-security-policy.md): Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
+
+## Concepts
+
+Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
+
+- [Features](./features.md): The state and actions each feature adds to the player
+- [Skins](./skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+- [UI components](./ui-components.md): How Video.js UI components use focused elements, data attributes for state, and compound composition.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+
+## Playback
+
+Guides for one player capability each: the recommended setup, how it works, browser constraints, variations, and troubleshooting.
+
+- [Autoplay](./autoplay.md): Start playback automatically and handle browser autoplay restrictions.
+- [Automatically show and hide controls](./controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
+- [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Play live streams](./live-streams.md): Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+- [Add a quality selector](./quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
+- [Go fullscreen and lock orientation](./fullscreen.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Use picture-in-picture](./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](./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.
+- [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
+
+## Migrate
+
+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 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

package/docs/guides/media-sources.md

@@ -0,0 +1,312 @@
+# Media sources
+
+Set what a media element plays and how its engine plays it with the structured source property
+
+Every media element takes a `src`. Elements that drive a playback engine also take `source`, a structured object that carries the URL alongside everything else about that source:
+
+```tsx
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/stream.m3u8',
+    preferPlayback: 'mse',
+    engine: { hlsJs: { maxBufferLength: 60 } },
+  }}
+/>
+```
+
+## Three tiers, three homes
+
+The shape answers one question: does this option describe the source, or how to play it?
+
+| Tier | Home | Example |
+| --- | --- | --- |
+| Which source to play | `source.src`, or an element’s own identity fields | `src`, `MuxVideo`’s `playbackId` |
+| How to interpret it | `source.type` | `'video/mp4'` |
+| How Video.js plays it | `source`, at the top level | `preferPlayback`, `maxAutoResolution`, `capRenditionToPlayerSize` |
+| How a specific engine behaves | `source.engine`, under that engine’s name | hls.js’s `maxBufferLength`, in `source.engine.hlsJs` |
+| An extension’s own settings | that extension’s props | [Mux Data](./mux-data.md), [GoogleCast](../reference/components/google-cast.md) |
+
+`type` is worth reaching for when the URL lies about its contents. Video.js infers the content type from the file extension, so a manifest served from an extensionless or signed URL may need to say so explicitly:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/asset?id=42', type: 'application/vnd.apple.mpegurl' }} />
+```
+
+The legacy HLS spelling `application/x-mpegURL` is accepted as an alias, and matching is case-insensitive. An HLS source whose `type` isn’t recognized is handed to the browser as-is rather than to hls.js, which leaves quality and audio-track selection unavailable.
+
+## `src` and `source` stay in sync
+
+They are two views of the same thing, and writing either updates the other. Setting `source` derives `src`. Setting `src` replaces only the identity half and **keeps the rest, such as `type` and the engine options, intact**:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/a.m3u8', preferPlayback: 'native' }} />
+```
+
+A `sourcechange` event fires whenever `source` changes, from either direction.
+
+## Assigning `source` replaces it
+
+`source` is not merged. A new object is a fresh start, and keys you leave out are dropped:
+
+```tsx
+<HlsJsVideo source={{ src, type: 'video/mp4', preferPlayback: 'native' }} />
+
+// later: type and preferPlayback are gone, because the new object omits them
+<HlsJsVideo source={{ src }} />
+```
+
+## Equivalent sources cost nothing
+
+Sources are compared **structurally**, not by reference. Reassigning an object with the same values is a no-op — no reload, and no engine teardown:
+
+```tsx
+// A fresh object literal on every render. Nothing reloads.
+<HlsJsVideo source={{ src, engine: { hlsJs: { maxBufferLength: 60 } } }} />
+```
+
+This is why you can write `source` inline. React hands the element a brand new object every render, and the element recognizes it as the same source. There’s no need to memoize it or spread the previous value to avoid clobbering anything.
+
+Only a change to the engine options, `preferPlayback`, or the resolved content type recreates the playback engine.
+
+## Engine options
+
+Engine options live under `source.engine`, **namespaced by engine**. Each key there holds that engine’s own configuration object, handed over untouched — there’s no Video.js wrapper around it, so whatever the engine documents works:
+
+| Key | Elements that read it | It holds |
+| --- | --- | --- |
+| `engine.hlsJs` | [HlsJsVideo](../reference/components/hlsjs-video.md), [MuxVideo](../reference/components/mux-video.md), [MuxAudio](../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` | [NativeHlsVideo](../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` | [DashVideo](../reference/components/dash-video.md) | [dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) |
+| `engine.vimeo` | [VimeoVideo](../reference/components/vimeo-video.md) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
+| `engine.youtube` | [YouTubeVideo](../reference/components/youtube-video.md) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
+| `engine.cloudflare` | [CloudflareVideo](../reference/components/cloudflare-video.md) | [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) |
+| `engine.spotify` | [SpotifyAudio](../reference/components/spotify-audio.md) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
+| `engine.tiktok` | [TikTokVideo](../reference/components/tiktok-video.md) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
+| `engine.twitch` | [TwitchVideo](../reference/components/twitch-video.md) | [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) |
+
+Naming the engine rather than using one generic key matters where an element has more than one to choose from. `HlsJsVideo` plays through hls.js or through the browser depending on the platform and `preferPlayback`, and only one of them runs — so a single source can describe both paths without either engine reading the other’s options.
+
+hls.js reads its options when the engine is constructed, so changing them tears down the engine and builds a new one:
+
+```tsx
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/stream.m3u8',
+    engine: { hlsJs: { maxBufferLength: 60, enableWorker: false } },
+  }}
+/>
+```
+
+dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
+
+```tsx
+<DashVideo
+  source={{
+    src: 'https://example.com/manifest.mpd',
+    engine: { dashJs: { streaming: { abr: { maxBitrate: { video: 2000 } } } } },
+  }}
+/>
+```
+
+Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.
+
+### 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.
+
+`preferPlayback` picks between [hls.js](https://github.com/video-dev/hls.js/) and the browser’s own HLS support:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', preferPlayback: 'native' }} />
+```
+
+It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `HlsJsVideo`, `MuxVideo`, and `MuxAudio` accept it; DASH and Vimeo have no second playback path.
+
+`maxAutoResolution` caps the highest rendition adaptive bitrate selection reaches for on its own:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', maxAutoResolution: '720p' }} />
+```
+
+The cap limits automatic selection without hiding anything. Renditions above it stay in `videoRenditions`, so a viewer can still choose 1080p by hand. Reach for it to hold down bandwidth on a stream that would otherwise climb to 4K, or to keep a background or thumbnail player cheap.
+
+Renditions are matched on pixel area rather than height, which keeps unusual aspect ratios honest: an ultrawide 2560×1080 rendition carries more pixels than 16:9 1080p, so a `'1080p'` cap leaves it out. When every rendition sits above the cap, the smallest one plays.
+
+Changing the cap applies to the running engine, so playback continues uninterrupted. It needs the hls.js engine — native HLS playback ignores it, and audio-only streams have no video renditions to cap.
+
+### Capping to the player’s size
+
+A 400px-wide player has no use for a 4K rendition, so `capRenditionToPlayerSize` holds automatic selection to the smallest rendition that still covers the element. It defaults to `true`, and the cap follows the element as it’s resized:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', capRenditionToPlayerSize: false }} />
+```
+
+The element is measured in device pixels, so a `2` device pixel ratio asks for twice the rendition a CSS measurement would — a 640px-wide player on a retina screen still gets 720p. Switch the cap off for a player whose layout size understates what it needs, such as one that goes fullscreen without a resize.
+
+`minAutoResolution` bounds how far down that cap can reach, and defaults to `'720p'`:
+
+```tsx
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', minAutoResolution: '480p' }} />
+```
+
+**It is not a quality floor.** It bounds the size-derived cap and nothing else. When bandwidth is poor, adaptive selection still drops below it — the cap is a ceiling, and selection stays free underneath. It also never raises an explicit `maxAutoResolution`: ask for at most `'360p'` alongside a `'720p'` floor and you get `'360p'`.
+
+The default is there because the low rungs of a ladder exist for poor network conditions, and capping a small player down to them looks worse than its size suggests. Name a lower rung to weaken the floor, or `'270p'` to lift it for any real ladder.
+
+### Four things that sound alike
+
+Four separate mechanisms bound which rendition plays, and they’re easy to mistake for each other:
+
+| Option | Side | What it does |
+| --- | --- | --- |
+| `source.playback.maxResolution` | Server | A Mux query param. Trims the manifest, so higher renditions never arrive — not even by hand. |
+| `source.maxAutoResolution` | Client | A ceiling on automatic selection. Everything still arrives and stays selectable by hand. |
+| `source.capRenditionToPlayerSize` | Client | The same kind of ceiling, derived from the element’s rendered size and moving with it. |
+| `source.minAutoResolution` | Client | A bound on the one above. Not a quality minimum, and not related to `playback.minResolution`. |
+
+`playback.maxResolution` and `playback.minResolution` are the server-side pair: they decide what the manifest carries. The other three only bound what adaptive selection picks from whatever does arrive.
+
+## DRM protected sources
+
+Protected content is licensed through `source.drm`, keyed by EME key system id — alongside the URL rather than inside an engine’s namespace, because which engine plays the manifest is decided later and both paths read it:
+
+```tsx
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/protected.m3u8',
+    drm: {
+      'com.apple.fps': {
+        licenseUrl: 'https://license.example.com/fairplay',
+        serverCertificateUrl: 'https://license.example.com/fairplay-cert',
+      },
+      'com.widevine.alpha': { licenseUrl: 'https://license.example.com/widevine' },
+      'com.microsoft.playready': { licenseUrl: 'https://license.example.com/playready' },
+    },
+  }}
+/>
+```
+
+Name every system you hold a license server for — which one gets used is the browser’s choice. `serverCertificateUrl` is the DRM server (application) certificate FairPlay requires; Widevine and PlayReady ignore it.
+
+### What each path can license
+
+The same `drm` reaches both playback paths, and how far it gets is the one thing worth knowing about each:
+
+| Path | Key systems it negotiates | What Video.js does with `drm` |
+| --- | --- | --- |
+| hls.js (MSE) | FairPlay, Widevine, PlayReady | Hands it to hls.js as `drmSystems`, with `emeEnabled` switched on |
+| The browser’s own HLS | FairPlay | Answers the element’s key requests itself: POSTs the CDM’s license request to `licenseUrl` and hands the response back |
+
+So a source naming only Widevine plays through hls.js and cannot play on the native path — [NativeHlsVideo](../reference/components/native-hls-video.md), or any HLS element the browser ends up playing the manifest for. Video.js says so in development, and encrypted media that gets there with no `com.apple.fps` license server fails with a `MEDIA_ERR_ENCRYPTED` error rather than hanging.
+
+For Widevine on hls.js, Video.js asks for a hardware-backed CDM first, falling back to whatever robustness the browser offers, so content restricted to L1 devices plays where it can. Supplying your own `requestMediaKeySystemAccessFunc` replaces that entirely.
+
+### Licensing one engine differently
+
+An engine’s own `drmSystems` **replaces** `source.drm`, for that engine alone. Reach for it when one path licenses differently, or when you need more of [hls.js’s DRM configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#drmsystems) than `drm` covers:
+
+```tsx
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/protected.m3u8',
+    drm: { 'com.apple.fps': { licenseUrl, serverCertificateUrl } },
+    engine: {
+      // hls.js licenses from here instead, and the native path still from `drm`.
+      hlsJs: { drmSystems: { 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } } },
+    },
+  }}
+/>
+```
+
+It replaces rather than merges, so the FairPlay server above is gone as far as hls.js is concerned. `engine.nativeHls.drmSystems` does the same for the native path.
+
+## Mux sources name a playback ID
+
+[MuxVideo](../reference/components/mux-video.md) and [MuxAudio](../reference/components/mux-audio.md) identify a source by `playbackId` rather than a URL, and derive `src` from it. Everything else works the same, engine options included:
+
+```tsx
+<MuxVideo
+  source={{
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    playback: { maxResolution: '1080p' },
+    engine: { hlsJs: { maxBufferLength: 60 } },
+  }}
+  playsInline
+/>
+```
+
+`playback` params ride along in the URL, so `playback.maxResolution` decides which renditions the manifest carries in the first place. `maxAutoResolution` is the other half of that pair: it caps what adaptive selection picks from the renditions that do arrive. Use `playback.maxResolution` when a viewer should never get 4K, and `maxAutoResolution` when they should be able to ask for it.
+
+The same split applies at the bottom of the ladder, and the names are close enough to be worth restating: `playback.minResolution` asks Mux to leave the lowest renditions out of the manifest, while `minAutoResolution` is a client-side bound on the player-size cap. They are unrelated.
+
+Setting a Mux stream URL as `src` works too — the element parses the playback ID and query params back out into `source`. To play something Mux doesn’t host, name it with `src` inside `source`; engine options still apply.
+
+Two more source params describe images rather than playback. `source.storyboard` and `source.poster` carry the modifiers for the storyboard VTT and the poster still — both belong to the source, since a signed token scopes them to one playback ID:
+
+```tsx
+<MuxVideo source={{ playbackId, storyboard: { format: 'jpg' }, poster: { time: 12 } }} playsInline />
+```
+
+`MuxVideo` uses the storyboard itself, adding the thumbnail `<track>` for you so hover previews work without extra markup. Live streams have no storyboard, so the track is dropped once the stream type is known, and signed playback without a matching storyboard token adds none.
+
+### Mux signs DRM with a token
+
+Mux serves FairPlay, Widevine, and PlayReady from URLs derived from a single license token, so `source.drm` takes that token in place of the license servers it would otherwise name. Mux fills the rest in for you, so protected media plays whichever path the browser takes:
+
+```tsx
+<MuxVideo
+  source={{
+    playbackId,
+    playback: { token: playbackToken },
+    drm: { token: drmToken },
+  }}
+  playsInline
+/>
+```
+
+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.
+
+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:
+
+```tsx
+<MuxVideo
+  source={{
+    playbackId,
+    playback: { token: playbackToken },
+    // FairPlay and PlayReady from Mux, Widevine from your own server.
+    drm: { token: drmToken, 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } },
+  }}
+  playsInline
+/>
+```
+
+`source.poster` gets no such treatment — it’s only data, and nothing applies it to the media. Both URLs are readable from `contentData`, keyed by what each one describes:
+
+```ts
+media.contentData;
+// {
+//   poster: 'https://image.mux.com/PLAYBACK_ID/thumbnail.webp?time=12',
+//   storyboard: 'https://image.mux.com/PLAYBACK_ID/storyboard.vtt?format=jpg',
+// }
+```
+
+It’s read-only and derived from `source`, so read it again after `sourcechange`. A key is missing when its URL can’t be built: no playback ID, or signed playback with no matching image token. Changing the URLs means changing the params they’re built from.
+
+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 `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`:
+
+```tsx
+<MuxVideo source={{ playbackId, poster: { width: 320 } }} playsInline />
+```
+
+## Elements without engine options
+
+[HlsVideo](../reference/components/hls-video.md) and [HlsAudio](../reference/components/hls-audio.md) take `src` and the usual media props but expose no `source`. They run on our own playback engine, which does not accept configuration from the element yet.
+
+## See also
+
+- [HlsJsVideo element reference](../reference/components/hlsjs-video.md)
+- [MuxVideo element reference](../reference/components/mux-video.md)
+- [DashVideo element reference](../reference/components/dash-video.md)