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

package/docs/guides/keyboard-shortcuts.md

@@ -10,7 +10,7 @@ Add keyboard shortcuts and pointer gestures to the player declaratively, with on
 
 ## Recommended approach
 
-Declare shortcuts with `<media-hotkey>` and gestures with `<media-gesture>` inside the player container. Each maps an input to a player action; the prebuilt skins ship a full set.
+Declare shortcuts with `<media-hotkey>` and gestures with `<media-gesture>` inside the player container. Each maps an input to a player action. The packaged skins include bindings suited to their player preset.
 
 ```html
 <video-player>
@@ -31,39 +31,51 @@ Declare shortcuts with `<media-hotkey>` and gestures with `<media-gesture>` insi
 </video-player>
 <script type="module">
   import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
   import '@videojs/html/ui/hotkey';
-  import { GestureElement } from '@videojs/html';
-
-  // Gesture has no standalone define entry; register the element directly.
-  customElements.define(GestureElement.tagName, GestureElement);
+  import '@videojs/html/ui/gesture';
 </script>
 ```
 
 ## How it works
 
-- `<media-hotkey>` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. Step actions have shared defaults and accept a custom `value`. The actions call the same feature state actions your components use.
-- `<media-gesture>` binds pointer input — `tap` and `doubletap` — to the same actions, minus `seekToPercent` and plus `toggleControls`. Bindings are scoped by `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`) — regions split the container’s width, not the rendered video’s — so double-tap-left rewinds while double-tap-right skips forward.
-- `<media-status-announcer>` announces action results to screen readers, and the input indicator components render transient on-screen feedback (volume level, captions on/off) the way native players do. The prebuilt skins wire these up.
+- `<media-hotkey>` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. `seekStep` and `volumeStep` use a default step unless you pass a custom `value`. These input actions call the feature actions your components use; for example, `toggleFullscreen` chooses `requestFullscreen` or `exitFullscreen` based on `isFullscreen`.
+- `<media-gesture>` binds `tap` and `doubletap` to the same actions. Gestures also support `toggleControls`; `seekToPercent` is available only to hotkeys. Scope each binding with `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`). For example, a double tap on the left can rewind while a double tap on the right skips forward.
+- `<media-status-announcer>` announces action results to screen readers. The input indicator components show brief on-screen feedback, such as volume level or captions on and off, the way native players do. The packaged skins include both.
+
+The on-demand video skins bind these keys:
+
+- Space and `k`: play and pause
+- `m`: mute
+- `f`: fullscreen
+- `c`: captions
+- `i`: picture-in-picture
+- Left and Right arrows, `j` and `l`: seek 10 seconds
+- Up and Down arrows: volume
+- `0`–`9`: jump to a percentage
+- `<` and `>`: speed
+
+Live video skins keep the playback, mute, volume, fullscreen, captions, and picture-in-picture shortcuts. They omit seeking and speed shortcuts.
 
-The prebuilt skins bind the conventional set: Space and `k` toggle playback, `m` mutes, `f` fullscreens, `c` toggles captions, `i` toggles picture-in-picture, arrows seek and change volume, `j`/`l` seek in larger steps, `0`–`9` jump to a percentage, and `<`/`>` change speed.
+How the container splits into regions depends on which regions you bind for the same gesture type and pointer type. Left and right bindings divide the container into halves. Adding a center binding divides it into thirds. A center-only binding covers the whole container; a left-only or right-only binding covers that half. These regions use the container’s width, not the rendered video’s width.
 
 ## Availability and constraints
 
 - Hotkeys listen on the player container by default, so multiple players on a page don’t fight over keys. Pass `target="document"` on a hotkey to make it page-wide — appropriate only when one player owns the page.
 - Typing is protected: while focus is in an editable field, single-key bindings are skipped automatically. Modifier combinations (for example `Ctrl+Shift+f`) still fire.
 - Repeatable actions (seeking, volume) fire on held keys; toggle actions don’t repeat.
-- Touch tap-to-toggle-controls and tap-to-pause are mutually exclusive per pointer type — the skins pause on mouse tap and toggle controls on touch tap, matching platform conventions.
-- Gestures and the built-in touch handling coordinate through one recognizer; register gestures declaratively instead of adding raw pointer listeners next to them.
+- Use only one of `toggleControls` and `togglePaused` for tap bindings with the same pointer type. The packaged skins pause on a mouse tap and toggle controls on a touch tap, matching platform conventions.
+- Declared gestures and the built-in touch handling share one recognizer. Use the gesture components to add bindings. Extra raw pointer listeners can toggle controls twice.
 
 ## Common variations
 
 ### Customize a shortcut
 
-Render your own `<media-hotkey>` set instead of a skin’s: every binding is just an element, so add, remove, or re-key them freely.
+For a packaged skin, [add the skin source to your project](./customize-skins.md#style-skin-source) and edit its `<media-hotkey>` declarations. Adding another binding alongside the packaged skin does not replace its bindings. For a custom UI, edit your own `<media-hotkey>` set directly.
 
 ### Seek step size
 
-`seekStep` takes its step from `value` — match your content: 5 seconds for short clips, 15 or 30 for long-form.
+Set the `seekStep` distance with `value`. Match it to your content: 5 seconds for short clips, 15 or 30 seconds for long-form video.
 
 ## Troubleshooting
 
@@ -73,11 +85,11 @@ Focus is outside the player container. Click the player first, or move focus int
 
 ### Double-tap seek also toggles pause
 
-Regions overlap: keep single-tap `togglePaused` on `center` only, and double-tap seek on `left` and `right`, as in the skin defaults.
+The built-in recognizer delays a matching single tap and cancels it when a double tap occurs. Check that your tap and double-tap bindings use compatible `pointer` filters. Remove separate click handlers that also toggle playback, and avoid native video controls on the same gesture surface.
 
 ### No visual feedback on keyboard actions
 
-The input indicator components render that feedback; use a prebuilt skin or add `<media-status-announcer>` and the indicator components from the skin source to a custom UI.
+The input indicator components render that feedback; use a packaged skin or add `<media-status-announcer>` and the indicator components from the skin source to a custom UI.
 
 ## Related pages
 

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.3. 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 } };
@@ -308,7 +311,11 @@ It survives a `src` change, so swapping the source keeps the frame you asked for
 
 ## Elements without engine options
 
-[`<hls-video>`](../reference/components/hls-video.md) and [`<hls-audio>`](../reference/components/hls-audio.md) take `src` and the usual media attributes but expose no `source`. They run on our own playback engine, which does not accept configuration from the element yet.
+[`<hls-video>`](../reference/components/hls-video.md) and [`<hls-audio>`](../reference/components/hls-audio.md) take `src` or `source`, and the usual media attributes.
+
+Their `source` carries only `src`, `type`, and `drm`, with no `engine`, `preferPlayback`, or rendition caps. They run on our own playback engine, which does not accept configuration from the element yet.
+
+On `<hls-video>`, `drm` licenses FairPlay, Widevine, and PlayReady, taking the same license servers as [DRM protected sources](#drm-protected-sources). `<hls-audio>` accepts `drm` but ignores it, so one source object serves both.
 
 ## See also