@videojs/react 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/concepts/media-sources.md

@@ -0,0 +1,483 @@
+# 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/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' }} />
+```
+
+## `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.
+
+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)
+
+`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.
+
+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/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:
+
+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/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:
+
+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:
+
+`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.
+
+`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/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`
+
+`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.
+
+tsx
+
+```
+// Before
+<HlsJsVideo src={src} config={{ preferPlayback: 'native', hlsJs: { maxBufferLength: 60 } }} />
+
+// After
+<HlsJsVideo source={{ src, preferPlayback: 'native', engine: { hlsJs: { maxBufferLength: 60 } } }} />
+```
+
+`<hls-video>` and `<hls-audio>` accepted a `config` that nothing read. Remove it — those elements never applied it.
+
+## See also
+
+- [HlsJsVideo element reference](../reference/hlsjs-video.md)
+- [MuxVideo element reference](../reference/mux-video.md)
+- [DashVideo element reference](../reference/dash-video.md)

package/docs/concepts/mux-data.md

@@ -0,0 +1,85 @@
+# Mux Data
+
+Monitor playback quality and viewer experience by adding the Mux Data extension to a player
+
+[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](./overview.md) to a player and it monitors whichever media that player is playing:
+
+Install the extension alongside the framework façade. The MuxVideo example also installs the Mux playback adapter:
+
+bash
+
+```
+pnpm add @videojs/react @videojs/mux-video @videojs/mux-data
+```
+
+App.tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { MuxData } from '@videojs/react/extensions/mux-data';
+import { MuxVideo } from '@videojs/react/media/mux-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function App() {
+  return (
+    <Player>
+      <Container>
+        <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
+        <MuxData />
+      </Container>
+    </Player>
+  );
+}
+```
+
+That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it inside the player, as a sibling of the media element.
+
+Note
+
+Mux Data is opt-in. No media element monitors playback on its own, Mux ones included, so nothing is measured and no beacons are sent until you add the extension.
+
+## Environment key
+
+Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.
+
+Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
+
+tsx
+
+```
+<HlsJsVideo src="https://example.com/stream.m3u8" />
+<MuxData envKey="YOUR_ENV_KEY" />
+```
+
+An explicit key always wins, so set one to send Mux-hosted views to a specific environment.
+
+## Any media element works
+
+The extension attaches to the media the player is using, not to a specific element type, so it monitors [MuxVideo](../reference/mux-video.md), [HlsJsVideo](../reference/hlsjs-video.md), [DashVideo](../reference/dash-video.md), and the rest alike.
+
+How much it reports depends on the engine playing the stream. Every media gets the playback metrics the media element itself can tell us. On top of that, the component recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media with no JavaScript engine, like native HLS or a plain `<video>`, report the element-level metrics alone.
+
+The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.
+
+## Describe the view
+
+Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:
+
+tsx
+
+```
+<MuxData metadata={{ video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' }} />
+```
+
+## Configuration
+
+The [MuxData reference](../reference/mux-data.md) lists every option: the metadata and software fields above, plus the beacon domain, cookie, debug, and SDK settings. Most options update the current view in place; changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, ending the current view and starting a new one.
+
+## See also
+
+- [MuxData reference](../reference/mux-data.md)
+- [MuxVideo element reference](../reference/mux-video.md)
+- [MuxAudio element reference](../reference/mux-audio.md)
+- [Cast to AirPlay and Chromecast](../how-to/cast-to-airplay-and-chromecast.md): Add Google Cast and AirPlay to a player

package/docs/concepts/overview.md

@@ -0,0 +1,119 @@
+# Overview
+
+How Video.js players are structured — state, UI, media, and extensions
+
+Video.js v10 separates player responsibilities into parts that work independently or together, so you can use as much or as little of Video.js as you need.
+
+For the reasoning behind this design, see [Why Video.js?](./why-videojs.md).
+
+## State management
+
+State is handled by a preset player component, which creates a central state store that all components can access. When you wrap your player in `VideoPlayer`, the components automatically connect to the state.
+
+tsx
+
+```
+{/* All components inside automatically connect to state */}
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+You can access state and actions from anywhere within `VideoPlayer` with the [`usePlayer` hook](../reference/use-player.md).
+
+- [Learn more about state and actions](./features.md)
+
+## User interface
+
+Use a prebuilt **skin** or build your own from the individual **UI components**.
+
+### Skins
+
+Skins are complete, pre-designed player UIs that package components and styles together. They give you a polished starting point, with a small set of CSS custom properties for common visual changes. They don’t try to cover every player with options.
+
+tsx
+
+```
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+- [Learn more about skins](./skins.md)
+
+### UI components
+
+If you want more control than a packaged skin offers, build your own UI from our components. Add, remove, and rearrange them to build the player you need.
+
+tsx
+
+```
+<VideoPlayer>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>
+      <Controls.Content>
+        <PlayButton />
+        {/* ... */}
+      </Controls.Content>
+    </Controls.Root>
+  </Container>
+</VideoPlayer>
+```
+
+The easiest way to get started is to [eject the closest skin](../how-to/customize-skins.md#eject-and-edit-a-skin) and use its styled components as a foundation.
+
+- [Learn more about UI components](./ui-components.md)
+- [Build your own component](../how-to/build-your-own-component.md)
+
+## Media
+
+Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
+
+Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
+
+tsx
+
+```
+<VideoPlayer>
+  <VideoSkin>
+    <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+- [Learn more about media](./media-sources.md)
+
+## Extensions
+
+Extensions add behavior to a player without rendering UI or playing media themselves.
+
+tsx
+
+```
+<VideoPlayer>
+  <VideoSkin>
+    <MuxVideo source={{ playbackId: 'PLAYBACK_ID' }} />
+    <MuxData />
+    <GoogleCast />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+An extension can provide behavior that a UI component controls: GoogleCast supplies the configurable Cast route, and [CastButton](../reference/cast-button.md) renders the control that starts and ends a session.
+
+## Presets
+
+**Presets** preconfigure the state, UI, and media for a specific use case. Extensions stay opt-in, so add them to a preset player when you need them.
+
+The default presets are `@videojs/react/video` and `@videojs/react/audio`, covering the baseline set of controls you’d expect from the HTML `<video>` and `<audio>` tags.
+
+Beyond the defaults, presets target more specific use cases. The `/background` preset combines a media element with autoplay, mute, and loop built in, a skin with no controls, and only the features needed to power it.
+
+You can use it from `@videojs/react/background`.
+
+- [Learn more about presets](./presets.md)