# 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](https://videojs.org/docs/framework/react/guides/skins)’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](https://videojs.org/docs/framework/react/guides/media-sources) 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`.

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt