{"id":16225,"library":"spotify-audio-element","title":"Spotify Audio Web Component","description":"The `spotify-audio-element` package provides a custom web component, `<spotify-audio>`, designed to embed and control Spotify audio playback directly within HTML. It aims to replicate the standard HTML `<audio>` element's API, offering a familiar interface for developers. Currently at version `1.0.4`, this package is part of the `muxinc/media-elements` monorepo, which sees active development across its various media component offerings. While `spotify-audio-element` itself might not have frequent individual version bumps, the monorepo has consistent updates across its related packages. Its primary differentiators include a compliant `HTMLMediaElement` API surface, making it intuitive for those familiar with native audio elements, and seamless integration capabilities with `Media Chrome` for advanced UI customization.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/muxinc/media-elements","tags":["javascript","spotify","audio","player","web component","custom element","typescript"],"install":[{"cmd":"npm install spotify-audio-element","lang":"bash","label":"npm"},{"cmd":"yarn add spotify-audio-element","lang":"bash","label":"yarn"},{"cmd":"pnpm add spotify-audio-element","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary usage is a side-effect import to register the custom element globally. This package is ESM-only.","wrong":"const SpotifyAudioElement = require('spotify-audio-element');","symbol":"spotify-audio-element","correct":"import 'spotify-audio-element';"},{"note":"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.","symbol":"SpotifyAudioElement (type)","correct":"import type { SpotifyAudioElement } from 'spotify-audio-element';"},{"note":"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`).","symbol":"<spotify-audio>","correct":"<spotify-audio src=\"spotify:track:11dFghVXANMlKmJXsNCbNl\" controls></spotify-audio>"}],"quickstart":{"code":"import 'spotify-audio-element';\n\nconst spotifyPlayer = document.createElement('spotify-audio');\nspotifyPlayer.setAttribute('controls', '');\n// Use a Spotify track URI for direct playback, e.g., 'spotify:track:11dFghVXANMlKmJXsNCbNl' for a public domain track.\n// A Spotify artist URI as in the README example ('spotify:artist:246dkjvS1zLTtiykXe5h60') generally only loads the artist page, not playable audio.\n// Replace with a valid Spotify track URI or use an environment variable.\nspotifyPlayer.setAttribute('src', process.env.SPOTIFY_TRACK_URI ?? 'spotify:track:11dFghVXANMlKmJXsNCbNl');\n\ndocument.body.appendChild(spotifyPlayer);\n\n// Example of programmatic control after element is added to DOM\nspotifyPlayer.addEventListener('loadedmetadata', () => {\n  console.log('Spotify player loaded metadata.');\n  spotifyPlayer.play();\n});\n\nspotifyPlayer.addEventListener('play', () => {\n  console.log('Playback started!');\n});\n\nspotifyPlayer.addEventListener('error', (e) => {\n  console.error('Spotify player error:', e);\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=0.1"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Uncaught TypeError: Failed to execute 'define' on 'CustomElementRegistry': the name \"spotify-audio\" has already been used with this registry"},{"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.","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.","error":"Spotify player loads but does not play audio, or shows 'Login to Spotify' message."},{"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.","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.","error":"Failed to load Spotify content when `src` is set to an artist or album URI, instead of a track URI."}],"ecosystem":"npm"}