Skip to content

Spotify

@distube/spotify lets members paste Spotify track, album, playlist and artist links and search Spotify. Spotify does not hand out audio, so DisTube finds each track on one of your other plugins, such as YouTube, and plays it from there. The plugin needs no account or API key.

Install it with a plugin that can play, such as YouTube:

npm
npm install @distube/spotify @distube/youtube
Bun
bun add @distube/spotify @distube/youtube

The installation guide covers distube and your adapter.

List Spotify and at least one plugin that can play. This example searches Spotify and plays the first result through YouTube:

import { DiscordJSAdapter } from "@distube/discordjs";
import { SpotifyPlugin } from "@distube/spotify";
import { YouTubePlugin } from "@distube/youtube";
import type { Client, VoiceBasedChannel } from "discord.js";
import { DisTube } from "distube";
declare const client: Client;
declare const voiceChannel: VoiceBasedChannel;
const youtube = new YouTubePlugin();
const spotify = new SpotifyPlugin();
const distube = new DisTube({ adapter: new DiscordJSAdapter(client), plugins: [spotify, youtube] });
const results = await distube.search("artist track", { source: spotify, limit: 5 });
const first = results[0];
if (first) await distube.play(voiceChannel, first);

new DisTube throws INVALID_ARGUMENT when no other plugin can play Spotify’s tracks. SpotifyPlugin takes no options. Short spotify.link links work like the full ones.

When a Spotify track is about to play, DisTube searches its name and artists on your other plugins in plugins order and plays the match nearest the track’s length. A plugin whose top 5 results all have a known length more than 5 seconds away is passed over. To match against YouTube Music songs instead of videos, list YouTubeMusicPlugin before YouTubePlugin.

The queue item stays a Spotify one. queue.item.started carries the match as fallback, so a now-playing message can show what actually played:

import type { DisTube } from "distube";
declare const distube: DisTube<unknown>;
distube.on("queue.item.started", ({ item, fallback }) => {
console.log(fallback ? `${item.song.name}, played from ${fallback.url}` : item.song.name);
});

When no plugin finds the track, the item fails with NO_RESULT.

The Spotify plugin has related, so autoplay after a Spotify track adds another Spotify track. That track plays through the same search fallback as the first.

A failed Spotify lookup reaches your bot as a DisTubeError with error.source set to "spotify" and a code such as NOT_FOUND, UNAVAILABLE or RATE_LIMITED. A failure while a track plays comes from the plugin that played it. The error reference lists every code.

The plugin sends a request up to 3 times when Spotify answers 500, 502, 503, 504 or 408 or the connection breaks, and reports each retry as spotify.request.retried. A failure that lasts through all 3 has error.transient set. A 429 is not retried.