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

package/docs/reference/components/shaka-video.md

@@ -0,0 +1,108 @@
+# ShakaVideo
+
+Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+
+> **Caution: Unstable API**
+>
+> This API works today, but its shape is still settling and may change in a minor release. The implementation underneath is production quality; what is not final is how you configure it from Video.js. Pin your version and check the changelog when you upgrade.
+
+Choose [Shaka Player](https://github.com/shaka-project/shaka-player) when one media component needs to play DASH, HLS, and progressive files, or when playback requires DRM.
+
+## Import
+
+```bash
+pnpm add @videojs/shaka-video
+```
+
+```tsx
+import { ShakaVideo } from '@videojs/react/media/shaka-video';
+```
+
+## Load a source
+
+`src` takes a manifest URL. DASH, HLS, and progressive files all go through the same property, and Shaka picks the parser from the URL.
+
+```tsx
+<ShakaVideo src="https://example.com/manifest.mpd" />
+```
+
+When the URL carries no extension to go on, name the type with `source.type`. That’s what makes an extensionless manifest playable.
+
+```tsx
+<ShakaVideo source={{ src: 'https://example.com/manifest', type: 'application/dash+xml' }} />
+```
+
+## Protected content
+
+`source.drm` names your license servers, keyed by [EME key system id](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.
+
+```tsx
+<ShakaVideo
+  source={{
+    src: 'https://example.com/manifest.mpd',
+    drm: {
+      'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
+      'com.apple.fps': {
+        licenseUrl: 'https://example.com/fairplay',
+        serverCertificateUrl: 'https://example.com/fairplay.cer',
+      },
+    },
+  }}
+/>
+```
+
+FairPlay needs a `serverCertificateUrl` unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. `source.drm` takes the same shape as hls.js’s own `drmSystems`, so one object describes DRM for either engine.
+
+For the parts of Shaka’s DRM configuration this doesn’t cover, configure Shaka directly. A `drm.servers` under `source.engine.shaka` replaces `source.drm` rather than merging with it.
+
+## Behavior
+
+- Adaptation stays within renditions no larger than the element rendering them, through Shaka’s `abr.restrictToElementSize`. Override it under `source.engine.shaka`.
+- `preload="none"` defers the load until playback is asked for; `autoplay` or a `play()` counts as asking.
+- `preload="metadata"` loads, then holds Shaka’s buffering goals down to a second until `preload` rises to `auto`.
+- `streamType` is detected from the manifest, so a player skin renders live and on-demand content correctly without being told which it is.
+- Changing `source.engine.shaka` reconfigures the running player in place instead of recreating it.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { ShakaVideo } from '@videojs/react/media/shaka-video';
+
+export default function BasicUsage() {
+  return <ShakaVideo className="shaka-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoPlay muted playsInline loop />;
+}
+```
+
+**App.css**
+
+```css
+.shaka-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `'metadata'` | How much to fetch before playback is asked for, mirroring the media element's own `preload`. Shaka has no split between "know the source" and "buffer it", so this maps onto when and how `engine.load()` runs:<br>- `'auto'` — load immediately with the configured buffering goals.<br>- `'metadata'` — load immediately, holding buffering to about a segment; the configured goals come back on the first play intent.<br>- `'none'` / `''` — hold the load entirely until the first play intent. A play intent is a `play` event, a target that is already playing, or `autoplay` — which the spec lets override `preload` for good reason: with nothing fetched there is nothing whose readiness could ever fire it. Widening (`none` → `auto`) takes effect immediately; narrowing after a load began cannot un-fetch and leaves it alone. |
+| `source` | `{ src?: string; type?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: ShakaEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`drm`, `engine.shaka`). Replacing it re-derives `src`. Shaka takes configuration on a live player, so changing `engine.shaka` re-applies it in place instead of recreating the engine. |
+| `src` | `string` | `''` | |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | |
+
+### Ref
+
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
+
+### Events
+
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

package/docs/reference/components/slider.md

@@ -0,0 +1,466 @@
+# Slider
+
+A composable slider component with track, fill, thumb, preview, and value parts
+
+## Import
+
+```tsx
+import { Slider } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<Slider.Root>
+  <Slider.Track>
+    <Slider.Fill />
+  </Slider.Track>
+  <Slider.Thumb />
+  <Slider.Preview>
+    <Slider.Thumbnail.Root>
+      <Slider.Thumbnail.Image />
+    </Slider.Thumbnail.Root>
+    <Slider.Value type="pointer" />
+  </Slider.Preview>
+</Slider.Root>
+```
+
+## Behavior
+
+The base slider provides a generic range input. It manages value, pointer tracking, and drag interactions. The [time slider](./time-slider.md) and [volume slider](./volume-slider.md) add media-specific bindings. The time slider also provides parts for rendering chapter ranges and the chapter at the current interaction position.
+
+`Slider.Thumbnail.Root` supplies the pointer value to the thumbnail. Render `Slider.Thumbnail.Image` inside it for the controlled image; other children can provide loading indicators or overlays.
+
+The slider supports vertical orientation via the `orientation` prop (defaults to `"horizontal"`).
+
+## Styling
+
+Use [CSS custom properties](#css-custom-properties) to position fill, thumb, and preview elements:
+
+React renders standard DOM elements. Add a `className` to style them:
+
+```css
+.slider-fill {
+  width: var(--media-slider-fill);
+}
+
+.slider-thumb {
+  left: var(--media-slider-fill);
+}
+```
+
+Style based on [interaction state](#data-attributes):
+
+```css
+.slider[data-interactive] .slider-track {
+  height: 6px;
+}
+.slider[data-pointing] .slider-preview {
+  opacity: 1;
+}
+```
+
+## Accessibility
+
+Renders with `role="slider"` and automatic ARIA attributes (`aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`). Override the label with the `label` prop. Keyboard controls:
+
+- Arrow Left / Arrow Right: step by `step` increment
+- Page Up / Page Down: step by `largeStep` increment
+- Home: jump to minimum
+- End: jump to maximum
+
+## Examples
+
+### Basic
+
+A slider with track, fill, and thumb.
+
+**App.tsx**
+
+```tsx
+import { Slider } from '@videojs/react';
+import { useState } from 'react';
+
+export default function BasicUsage() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <div className="demo">
+      <Slider.Root className="media-slider" value={value} onValueChange={setValue}>
+        <Slider.Track className="media-slider-track">
+          <Slider.Fill className="media-slider-fill" />
+        </Slider.Track>
+        <Slider.Thumb className="media-slider-thumb" />
+      </Slider.Root>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  padding: 24px;
+  background: #1a1a1a;
+}
+
+.media-slider {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+.media-slider-thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 14px;
+  height: 14px;
+  background: white;
+  border-radius: 50%;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+  transform: translateX(-50%) scale(0);
+  transition: transform 150ms ease;
+}
+
+.media-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-slider[data-dragging] .media-slider-thumb {
+  transform: translateX(-50%) scale(1.1);
+}
+```
+
+### With Preview
+
+A slider with a pointer-tracking preview that displays the value at the current pointer position.
+
+**App.tsx**
+
+```tsx
+import { Slider } from '@videojs/react';
+import { useState } from 'react';
+
+export default function WithPreview() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <div className="demo">
+      <Slider.Root className="media-slider" value={value} onValueChange={setValue}>
+        <Slider.Track className="media-slider-track">
+          <Slider.Fill className="media-slider-fill" />
+        </Slider.Track>
+        <Slider.Thumb className="media-slider-thumb" />
+        <Slider.Preview className="preview">
+          <Slider.Value type="pointer" className="media-slider-value" />
+        </Slider.Preview>
+      </Slider.Root>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  padding: 40px 24px;
+  background: #1a1a1a;
+}
+
+.media-slider {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+.media-slider-thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 14px;
+  height: 14px;
+  background: white;
+  border-radius: 50%;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+  transform: translateX(-50%) scale(0);
+  transition: transform 150ms ease;
+}
+
+.media-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-slider[data-dragging] .media-slider-thumb {
+  transform: translateX(-50%) scale(1.1);
+}
+
+.preview {
+  position: absolute;
+  bottom: 100%;
+  margin-bottom: 6px;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.media-slider[data-pointing] .preview {
+  opacity: 1;
+}
+
+.media-slider-value {
+  padding: 2px 6px;
+  font-size: 12px;
+  color: white;
+  white-space: nowrap;
+  background: rgba(0, 0, 0, 0.8);
+  border-radius: 4px;
+}
+```
+
+## API Reference
+
+### Root
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether the slider is non-interactive. |
+| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
+| `largeStep` | `number` | `10` | Large step increment (Page Up/Down keys). |
+| `max` | `number` | `100` | Maximum value of the slider range. |
+| `min` | `number` | `0` | Minimum value of the slider range. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of slider movement. |
+| `step` | `number` | `1` | Step increment for value changes (arrow keys). |
+| `thumbAlignment` | `'center' \| 'edge'` | `'center'` | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
+| `value` | `number` | `0` | Current slider value. |
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Current slider value in the min–max range. |
+| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
+| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
+| `dragging` | `boolean` | Whether the user is actively dragging. |
+| `pointing` | `boolean` | Whether the pointer is over the slider. |
+| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
+| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
+| `disabled` | `boolean` | Whether the slider is non-interactive. |
+| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-slider-fill` | Fill level percentage (0–100). |
+| `--media-slider-pointer` | Pointer position percentage (0–100). |
+| `--media-slider-buffer` | Buffer level percentage (0–100). |
+
+### Buffer
+
+Displays the buffered range on the slider track.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Fill
+
+Displays the filled portion from start to the current value.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Preview
+
+Positioning container for preview content that tracks the pointer along the slider.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
+
+### Thumb
+
+Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
+
+### Track
+
+Contains the slider's visual track and interactive hit zone.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Value
+
+Displays a formatted text representation of the slider value. Renders an `<output>` element.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `format` | `((value: number) => string)` | — | Custom formatter for the displayed value. Overrides the root's `formatValue`. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
+
+### Thumbnail.Root
+
+Resolves, sizes, and clips the thumbnail at the slider pointer.
+
+Render `Slider.Thumbnail.Image` inside it for the controlled image. Other children can provide loading indicators, overlays, or temporary presentation layers.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+| `thumbnails` | `ThumbnailImage[]` | — | Pre-parsed thumbnail images — bypasses the automatic `<track>` detection. |
+
+### Thumbnail.Image
+
+Displays the image selected and measured by `Thumbnail.Root`.
+
+Renders an `img`, so native image attributes and the `render` escape hatch remain available without replacing the root that owns thumbnail state.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `crossOrigin` | `ThumbnailCrossOrigin` | — | CORS setting for the selected image. Leave unset to follow the media element, or pass `null` to opt out. |
+| `fetchPriority` | `ThumbnailFetchPriority` | — | Image fetch priority hint. |
+| `loading` | `ThumbnailLoading` | — | Image loading strategy. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

package/docs/reference/components/spotify-audio.md

@@ -0,0 +1,109 @@
+# SpotifyAudio
+
+Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed
+
+The [Spotify embed](https://developer.spotify.com/documentation/embeds) accepts tracks, episodes, albums, playlists, shows, and artists. Podcast episodes play in full for signed-out listeners; music plays as a preview until the listener logs in to Spotify.
+
+## Import
+
+```bash
+pnpm add @videojs/spotify-audio
+```
+
+```tsx
+import { SpotifyAudio } from '@videojs/react/media/spotify-audio';
+```
+
+## Load a source
+
+`src` takes an `open.spotify.com` URL for any embeddable entity, including the localized (`/intl-de/`) and already-embedded (`/embed/`) forms, or a `spotify:<type>:<id>` URI. A `t` parameter sets the start position in seconds.
+
+```tsx
+<SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
+```
+
+## Controls
+
+Spotify’s own chrome is the only UI the embed offers, so `controls` decides whether the element is visible at all. With `controls`, it shows Spotify’s player. Without it, the element hides itself and plays as an invisible transport: a hidden iframe still loads and plays, so a [player skin](../../guides/skins.md)’s buttons drive playback while the embed takes no room on the page.
+
+## Behavior
+
+The Spotify embed exposes less than a native `<audio>` element:
+
+- No volume and no mute: the embed takes neither command and reports neither value, so a player skin shows no volume controls at all.
+- No playback rate and no text tracks.
+- `loop` replays the entity from the top when it ends; without it, the embed continues into whatever Spotify queues next.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { SpotifyAudio } from '@videojs/react/media/spotify-audio';
+
+export default function BasicUsage() {
+  return (
+    <div className="spotify-audio">
+      <SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.spotify-audio {
+  width: 100%;
+  height: 152px;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | |
+| `controls` | `boolean` | `false` | |
+| `loop` | `boolean` | `false` | |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `source` | `{ src?: string; engine?: SpotifySourceEngineConfig } \| null` | `null` | Spotify URL or URI in `src`, plus embed options under `engine.spotify`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+
+### Engine options
+
+#### `source.engine.spotify`
+
+Pass [Spotify embed options](https://developer.spotify.com/documentation/embeds) under `source.engine.spotify`, spelled exactly as Spotify spells them, plus anything Spotify adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+```tsx
+<SpotifyAudio
+  source={{
+    src: 'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5',
+    engine: { spotify: { t: 90, theme: 0 } },
+  }}
+/>
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `preferVideo` | `boolean \| undefined` | Embed the video variant of an episode when it has one. Not a URL parameter: the video embed lives at its own path. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Spotify embed parameter. |
+| `t` | `number \| undefined` | Start position in seconds. |
+| `theme` | `0 \| undefined` | `0` renders the embed in its dark theme. Defaults to the light theme. Spotify documents no other value, and the embed goes by whether the parameter is there, so leaving it out is the only way to ask for the default. |
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.
+
+### Events
+
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.