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

package/docs/{concepts → guides}/media-sources.md

@@ -4,9 +4,7 @@ Set what a media element plays and how its engine plays it with the structured s
 
 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:
 
-ts
-
-```
+```ts
 const video = document.querySelector('hlsjs-video');
 
 video.source = {
@@ -20,57 +18,27 @@ video.source = {
 
 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/google-cast.md)
+| Tier | Home | Example |
+| --- | --- | --- |
+| Which source to play | `source.src`, or an element’s own identity fields | `src`, `<mux-video>`’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 attributes and properties | [Mux Data](./mux-data.md), [`<google-cast>`](../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:
 
-ts
-
-```
+```ts
 video.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**:
 
-ts
-
-```
+```ts
 video.source = { src: 'https://example.com/a.m3u8', preferPlayback: 'native' };
 
 video.src = 'https://example.com/b.m3u8';
@@ -85,9 +53,7 @@ A `sourcechange` event fires whenever `source` changes, from either direction.
 
 `source` is not merged. A new object is a fresh start, and keys you leave out are dropped:
 
-ts
-
-```
+```ts
 video.source = { src, type: 'video/mp4', preferPlayback: 'native' };
 
 // type and preferPlayback are gone, because the new object omits them
@@ -98,90 +64,38 @@ video.source = { src };
 
 Sources are compared **structurally**, not by reference. Reassigning an object with the same values is a no-op — no reload, and no engine teardown:
 
-ts
-
-```
+```ts
 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.
 
-Note
-
-`source` holds an object, so it’s a property, not an attribute — there is no `source=""` in HTML. `src` remains the attribute, and it’s the one to reach for when your markup only names a URL.
+> **Note**
+>
+> `source` holds an object, so it’s a property, not an attribute — there is no `source=""` in HTML. `src` remains the attribute, and it’s the one to reach for when your markup only names a URL.
 
 ## 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/hlsjs-video.md), [MuxVideo](../reference/mux-video.md), [MuxAudio](../reference/mux-audio.md)
-
-an [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning)
+| Key | Elements that read it | It holds |
+| --- | --- | --- |
+| `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.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/) |
+| `engine.spotify` | [`<spotify-audio>`](../reference/components/spotify-audio.md) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
+| `engine.tiktok` | [`<tiktok-video>`](../reference/components/tiktok-video.md) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
+| `engine.twitch` | [`<twitch-video>`](../reference/components/twitch-video.md) | [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) |
 
-`engine.nativeHls`
-
-[NativeHlsVideo](../reference/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/dash-video.md)
-
-[dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html)
-
-`engine.vimeo`
-
-[VimeoVideo](../reference/vimeo-video.md)
-
-[Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed)
-
-`engine.youtube`
-
-[YouTubeVideo](../reference/youtube-video.md)
-
-[YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters)
-
-`engine.cloudflare`
-
-[CloudflareVideo](../reference/cloudflare-video.md)
-
-[Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/)
-
-`engine.spotify`
-
-[SpotifyAudio](../reference/spotify-audio.md)
-
-[Spotify embed options](https://developer.spotify.com/documentation/embeds)
-
-`engine.tiktok`
-
-[TikTokVideo](../reference/tiktok-video.md)
-
-[TikTok player parameters](https://developers.tiktok.com/doc/embed-player)
-
-`engine.twitch`
-
-[TwitchVideo](../reference/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.
+Naming the engine rather than using one generic key matters where an element has more than one to choose from. `<hlsjs-video>` 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:
 
-ts
-
-```
+```ts
 video.source = {
   src: 'https://example.com/stream.m3u8',
   engine: { hlsJs: { maxBufferLength: 60, enableWorker: false } },
@@ -190,9 +104,7 @@ video.source = {
 
 dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
 
-ts
-
-```
+```ts
 const video = document.querySelector('dash-video');
 
 video.source = {
@@ -209,19 +121,15 @@ Where an option means the same thing across engines, it sits on `source` itself
 
 `preferPlayback` picks between [hls.js](https://github.com/video-dev/hls.js/) and the browser’s own HLS support:
 
-ts
-
-```
+```ts
 video.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.
+It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `<hlsjs-video>`, `<mux-video>`, and `<mux-audio>` accept it; DASH and Vimeo have no second playback path.
 
 `maxAutoResolution` caps the highest rendition adaptive bitrate selection reaches for on its own:
 
-ts
-
-```
+```ts
 video.source = { src: 'https://example.com/stream.m3u8', maxAutoResolution: '720p' };
 ```
 
@@ -235,9 +143,7 @@ Changing the cap applies to the running engine, so playback continues uninterrup
 
 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:
 
-ts
-
-```
+```ts
 video.source = { src: 'https://example.com/stream.m3u8', capRenditionToPlayerSize: false };
 ```
 
@@ -245,9 +151,7 @@ The element is measured in device pixels, so a `2` device pixel ratio asks for t
 
 `minAutoResolution` bounds how far down that cap can reach, and defaults to `'720p'`:
 
-ts
-
-```
+```ts
 video.source = { src: 'https://example.com/stream.m3u8', minAutoResolution: '480p' };
 ```
 
@@ -259,35 +163,12 @@ The default is there because the low rungs of a ladder exist for poor network co
 
 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`.
+| 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.
 
@@ -295,9 +176,7 @@ A bound on the one above. Not a quality minimum, and not related to `playback.mi
 
 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:
 
-ts
-
-```
+```ts
 video.source = {
   src: 'https://example.com/protected.m3u8',
   drm: {
@@ -317,25 +196,12 @@ Name every system you hold a license server for — which one gets used is the b
 
 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
+| 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 |
 
-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/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.
+So a source naming only Widevine plays through hls.js and cannot play on the native path — [`<native-hls-video>`](../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.
 
@@ -343,9 +209,7 @@ For Widevine on hls.js, Video.js asks for a hardware-backed CDM first, falling b
 
 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:
 
-ts
-
-```
+```ts
 video.source = {
   src: 'https://example.com/protected.m3u8',
   drm: { 'com.apple.fps': { licenseUrl, serverCertificateUrl } },
@@ -360,11 +224,9 @@ It replaces rather than merges, so the FairPlay server above is gone as far as h
 
 ## Mux sources name a playback ID
 
-[MuxVideo](../reference/mux-video.md) and [MuxAudio](../reference/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:
-
-ts
+[`<mux-video>`](../reference/components/mux-video.md) and [`<mux-audio>`](../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:
 
-```
+```ts
 const video = document.querySelector('mux-video');
 
 video.source = {
@@ -382,21 +244,17 @@ Setting a Mux stream URL as `src` works too — the element parses the playback
 
 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:
 
-ts
-
-```
+```ts
 video.source = { playbackId, storyboard: { format: 'jpg' }, poster: { time: 12 } };
 ```
 
-`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-video>` 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:
 
-ts
-
-```
+```ts
 video.source = {
   playbackId,
   playback: { token: playbackToken },
@@ -408,9 +266,7 @@ DRM playback is always signed, so a `playback.token` belongs alongside it — an
 
 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:
 
-ts
-
-```
+```ts
 video.source = {
   playbackId,
   playback: { token: playbackToken },
@@ -421,9 +277,7 @@ video.source = {
 
 `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
-
-```
+```ts
 video.contentData;
 // {
 //   poster: 'https://image.mux.com/PLAYBACK_ID/thumbnail.webp?time=12',
@@ -436,19 +290,17 @@ video.poster = video.contentData.poster ?? '';
 
 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.
 
-`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`:
+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.
 
-ts
+`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`:
 
-```
+```ts
 video.source = { ...video.source, poster: { width: 320 } };
 ```
 
 Because `source` has no attribute, the poster frame has one of its own. `poster-time` reflects to `source.poster.time`, letting you set it from markup:
 
-html
-
-```
+```html
 <mux-video src="https://stream.mux.com/PLAYBACK_ID.m3u8" poster-time="12"></mux-video>
 ```
 
@@ -456,60 +308,14 @@ It survives a `src` change, so swapping the source keeps the frame you asked for
 
 ## Elements without engine options
 
-[HlsVideo](../reference/hls-video.md) and [HlsAudio](../reference/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.
-
-## Migrate from `config`
-
-Media elements used to take a `config` object: one untyped bag holding engine options, source overrides, and component settings at once. It’s gone, and each of its keys now has a specific home:
-
-Before
-
-After
-
-`config.preferPlayback`
-
-`source.preferPlayback`
-
-`config.contentType`
+[`<hls-video>`](../reference/components/hls-video.md) and [`<hls-audio>`](../reference/components/hls-audio.md) take `src` or `source`, and the usual media attributes.
 
-`source.type`
-
-`config.hlsJs`
-
-`source.engine.hlsJs`
-
-`config.dashJs`
-
-`source.engine.dashJs`
-
-`config.muxData`
-
-the [Mux Data](./mux-data.md) extension’s own props
-
-`config.googleCast`
-
-the [GoogleCast](../reference/google-cast.md) extension’s own props
-
-`config` on VimeoVideo
-
-`source.engine.vimeo`
-
-The engine keys keep their names, so their contents move across unchanged — what moves is the object they sit in.
-
-ts
-
-```
-// Before
-video.config = { preferPlayback: 'native', hlsJs: { maxBufferLength: 60 } };
-
-// After
-video.source = { src, preferPlayback: 'native', engine: { hlsJs: { maxBufferLength: 60 } } };
-```
+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.
 
-`<hls-video>` and `<hls-audio>` accepted a `config` that nothing read. Remove it — those elements never applied it.
+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
 
-- [HlsJsVideo element reference](../reference/hlsjs-video.md)
-- [MuxVideo element reference](../reference/mux-video.md)
-- [DashVideo element reference](../reference/dash-video.md)
+- [hlsjs-video element reference](../reference/components/hlsjs-video.md)
+- [mux-video element reference](../reference/components/mux-video.md)
+- [dash-video element reference](../reference/components/dash-video.md)