ReferenceMedia

SpotifyAudio

Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed

The Spotify embed 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

pnpm add @videojs/spotify-audio

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.

<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’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

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>
  );
}

.spotify-audio {
  width: 100%;
  height: 152px;
}

API Reference

Props

Accepts these Video.js-specific props:

Prop	Type	Default
`autoplay`	`boolean`	`false`
`controls`	`boolean`	`false`
`loop`	`boolean`	`false`
`playsInline`	`boolean`	`true`
`poster`	`string`	`''`
`preload`	`MediaPreloadType`	`'metadata'`
`source`	`object`	`null`
Description Spotify URL or URI in `src`, plus embed options under `engine.spotify`. Replacing it re-derives `src`. Type `{ src?: string; engine?: SpotifySourceEngineConfig } \| null`
`src`	`string`	`''`

Engine options

`source.engine.spotify`

Pass Spotify embed options under source.engine.spotify, spelled exactly as Spotify spells them, plus anything Spotify adds next. Media Sources covers how engine options fit into a structured source.

<SpotifyAudio
  source={{
    src: 'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5',
    engine: { spotify: { t: 90, theme: 0 } },
  }}
/>

Option	Type	Details
`preferVideo`	`boolean \| undefined`
Description 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`
Description `referrerpolicy` for the embed iframe. Not a Spotify embed parameter.
`t`	`number \| undefined`
Description Start position in seconds.
`theme`	`0 \| undefined`
Description `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.

Refs

`ref`

Forwards to the rendered <iframe>, an HTMLIFrameElement. The iframe cannot play or seek; use mediaRef for playback.

const ref = useRef<HTMLIFrameElement>(null);

<SpotifyAudio ref={ref} />

`mediaRef`

Receives the SpotifyAdapter that drives the embed, which exposes media methods and properties such as play() and currentTime. It is set once the adapter has attached to the iframe, so its target is already that iframe, and it is cleared when the iframe unmounts.

import type { SpotifyAdapter } from '@videojs/spotify-audio';

const mediaRef = useRef<SpotifyAdapter>(null);

<SpotifyAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();

Events

Handle standard media events with React event props such as onPlay and onTimeUpdate. The adapter dispatches them, not the iframe. For events without a React prop, call addEventListener on the adapter from mediaRef.