Registry / web-framework / spotify-audio-element

spotify-audio-element

library1.0.4jsnpmunverified

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.

web-framework http-networking

npm install spotify-audio-element

github ↗package ↗

INSTALL

IMPORT

SIG · SPOTIFY-AUDIO-ELEM

spotify-audio-element

web-frameworkjavascriptv1.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

spotify-audio-element

✓ import 'spotify-audio-element';

✗ const SpotifyAudioElement = require('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`).

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

Debug

Known issues

gotchaPlayback 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.

affects: >=0.1.0

gotchaThe 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`).

affects: >=0.1

gotchaCustom 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.

affects: <1.0.0

gotchaAs 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/muxinc/media-elements ↗

packagehttps://www.npmjs.com/package/spotify-audio-element ↗