Spotify Audio Web Component

Common errors

• Uncaught TypeError: Failed to execute 'define' on 'CustomElementRegistry': the name "spotify-audio" has already been used with this registry

  cause The `spotify-audio-element` script, which registers the `<spotify-audio>` custom element, has been imported or executed multiple times in the same browser context.
  fix Ensure that `import 'spotify-audio-element';` or the CDN script tag is included only once in your application. For example, import it only in your main JavaScript entry file, not in multiple components or HTML partials.

• Spotify player loads but does not play audio, or shows 'Login to Spotify' message.

  cause Spotify's Web Playback SDK requires specific conditions for playback, including a logged-in Spotify Premium user and potentially whitelisted domains for your application. If the user is not logged in or doesn't have Premium, or if the domain is not configured correctly, playback will fail or be limited.
  fix Verify that the user is logged into a Spotify Premium account in their browser. If integrating with a custom application, ensure your application's `redirect_uri` and origin are correctly configured and whitelisted in your Spotify Developer Dashboard. Handle cases where the user does not have a Premium account or is not logged in.

• Failed to load Spotify content when `src` is set to an artist or album URI, instead of a track URI.

  cause The `<spotify-audio>` element, mimicking the `<audio>` API, expects a direct playable media source. While artist or album URIs are valid Spotify resources, they typically represent collections, not a single playable audio track for direct embedded playback.
  fix Ensure the `src` attribute is set to a specific Spotify Track URI (e.g., `spotify:track:YOUR_TRACK_ID`) for direct audio playback. If you intend to play an album or artist's popular tracks, you would first need to use the Spotify Web API to retrieve track URIs. The README example's artist URI might not produce playable audio directly.

Warnings

• gotcha Playback through the Spotify Web Playback SDK (which this element leverages) has significant restrictions. Full playback functionality typically requires a Spotify Premium account, and your application's origin domain may need to be whitelisted in your Spotify Developer Dashboard. Users without Premium or improper configuration might only get 30-second previews or be unable to play at all. Additionally, commercial use of the SDK requires prior written approval from Spotify.
  Fix: Review Spotify's Web Playback SDK documentation and Developer Policy regarding authentication, domain whitelisting, Premium account requirements, and commercial usage. Ensure your application handles user login and token management appropriately for full functionality.
• gotcha The README's CDN quickstart example uses `spotify-audio-element@0.1`. The current stable version on NPM is `1.0.4`. Using the outdated CDN link may result in missing features, bugs, or security vulnerabilities fixed in later releases.
  Fix: Always refer to the official NPM page or project repository for the latest recommended installation instructions and version numbers. For CDN usage, update the version in the URL to the latest stable release (e.g., `spotify-audio-element@1`).
• gotcha Custom Elements (Web Components v1) are well-supported in modern browsers (Chrome, Edge, Firefox, Safari). However, for compatibility with older browser versions, you may need to include polyfills like `@webcomponents/custom-elements`.
  Fix: For wider browser compatibility, consider adding web component polyfills to your project, especially if targeting older browsers or environments that do not fully support Custom Elements v1. `npm install @webcomponents/custom-elements` and import it early in your application's entry point.
• gotcha As of November 2024, Spotify has restricted access to certain Web API endpoints for new applications, including `30-second preview URLs` in multi-get responses. While `spotify-audio-element` primarily uses the Web Playback SDK, these broader API changes indicate a trend towards stricter access and may affect how `src` attributes are resolved or what content is fully playable without explicit user authentication and permissions.
  Fix: Stay informed about Spotify's API and SDK policy changes. Always test your implementation thoroughly with different Spotify account types and ensure your application's API permissions are up-to-date and compliant with Spotify's developer policies.

Install

• npm install spotify-audio-element npm
• yarn add spotify-audio-element yarn
• pnpm add spotify-audio-element pnpm

Imports

• spotify-audio-element
  wrong:

  const SpotifyAudioElement = require('spotify-audio-element');

  correct:

  import 'spotify-audio-element';

  The primary usage is a side-effect import to register the custom element globally. This package is ESM-only.
• SpotifyAudioElement (type)

  import type { SpotifyAudioElement } from 'spotify-audio-element';

  For TypeScript users who need to type references to the custom element, assuming it exports a class for programmatic access and typing. This is a common pattern for web components shipping types.
• <spotify-audio>

  <spotify-audio src="spotify:track:11dFghVXANMlKmJXsNCbNl" controls></spotify-audio>

  Once imported, the custom element can be used directly in HTML. The `src` attribute expects a Spotify URI (e.g., `spotify:track:ID` or `spotify:album:ID`).

Quickstart

Demonstrates how to import and instantiate the `spotify-audio` custom element, set its source, append it to the DOM, and programmatically control playback. It uses an environment variable for a Spotify Track URI to ensure a runnable example.

import 'spotify-audio-element';

const spotifyPlayer = document.createElement('spotify-audio');
spotifyPlayer.setAttribute('controls', '');
// Use a Spotify track URI for direct playback, e.g., 'spotify:track:11dFghVXANMlKmJXsNCbNl' for a public domain track.
// A Spotify artist URI as in the README example ('spotify:artist:246dkjvS1zLTtiykXe5h60') generally only loads the artist page, not playable audio.
// Replace with a valid Spotify track URI or use an environment variable.
spotifyPlayer.setAttribute('src', process.env.SPOTIFY_TRACK_URI ?? 'spotify:track:11dFghVXANMlKmJXsNCbNl');

document.body.appendChild(spotifyPlayer);

// Example of programmatic control after element is added to DOM
spotifyPlayer.addEventListener('loadedmetadata', () => {
  console.log('Spotify player loaded metadata.');
  spotifyPlayer.play();
});

spotifyPlayer.addEventListener('play', () => {
  console.log('Playback started!');
});

spotifyPlayer.addEventListener('error', (e) => {
  console.error('Spotify player error:', e);
});