LavaSrc: Spotify, Apple Music and Deezer Through Lavalink

Users paste Spotify links. It’s the single most common request music bot developers get — and out of the box, Lavalink can’t play them. The LavaSrc plugin fixes that, adding Spotify, Apple Music, Deezer, Yandex Music and other sources. This article explains how it works, how to configure it and what to watch out for.

How LavaSrc handles Spotify: mirroring

It’s important to understand what LavaSrc actually does with a Spotify link, because it explains most of its behaviour.

Spotify doesn’t provide a way for third-party servers to stream its audio. So LavaSrc uses Spotify’s API for metadata — track title, artists, duration, album art and the ISRC (a standard recording identifier) — and then finds the same recording on another source to play. This is called mirroring.

Spotify link → LavaSrc fetches metadata (title, artist, ISRC)
            → searches providers in order, e.g. "ytsearch:"<ISRC>"", then "ytsearch:<artist> <title>"
            → plays the first good match

The result: users paste any Spotify track, album or playlist link and hear the music, with the correct title and artwork shown. Kerit Cloud’s managed Lavalink FAQ describes it the same way — LavaSrc resolves Spotify metadata and streams the audio from another source, which is standard practice in the Lavalink ecosystem.

Apple Music links work the same way. Deezer can be configured to play directly with extra settings, and other sources (such as Yandex Music) have their own options.

Installing LavaSrc

Add the plugin to lavalink.plugins in application.yml:

lavalink:
  plugins:
    - dependency: "com.github.topi314.lavasrc:lavasrc-plugin:VERSION"
      repository: "https://maven.lavalink.dev/releases"

Replace VERSION with the latest release from the LavaSrc GitHub repository (topi314/LavaSrc), and make sure it matches your Lavalink major version (v4). Lavalink downloads it on the next start.

On Kerit Cloud’s managed Lavalink plans, LavaSrc comes pre-installed on every tier, so you can skip this section.

Configuring sources

Plugin settings go in the top-level plugins block:

plugins:
  lavasrc:
    providers:
      - "ytsearch:\"%ISRC%\""
      - "ytsearch:%QUERY%"
    sources:
      spotify: true
      applemusic: false
      deezer: false
      yandexmusic: false
    spotify:
      clientId: "your-spotify-client-id"
      clientSecret: "your-spotify-client-secret"
      countryCode: "US"
      playlistLoadLimit: 6
      albumLoadLimit: 6

providers

The ordered list of searches LavaSrc tries when mirroring. %ISRC% is replaced with the track’s ISRC and %QUERY% with “artist - title”. Searching by ISRC first finds the exact recording more reliably; the title search is the fallback. You can add other sources — for example scsearch:%QUERY% for SoundCloud — as later fallbacks.

Spotify credentials

Create an app in the Spotify for Developers dashboard to get a client ID and secret. They let LavaSrc call Spotify’s API for metadata. Keep them private — they belong in your config, not your bot’s code. countryCode affects regional availability of tracks.

Load limits

playlistLoadLimit and albumLoadLimit cap how many pages of a playlist or album are loaded (each page holds a batch of tracks). Very large playlists take time and memory to resolve; modest limits keep the node responsive.

Other sources

• Apple Music needs a media API token (LavaSrc’s README explains the options) and a country code.
• Deezer can play audio directly with additional configuration; read the README and the platform’s terms before enabling it.
• Yandex Music and others require their own tokens.

Enable only the sources you actually need.

Using it from your bot

Once LavaSrc is installed, your client library passes identifiers straight through to Lavalink:

• Links — https://open.spotify.com/track/..., album and playlist links, Apple Music links — just work with your normal load or search call.
• Search prefixes:

For example, in Shoukaku: node.rest.resolve('spsearch:daft punk get lucky'). In Wavelink: await wavelink.Playable.search("spsearch:daft punk get lucky"). See connecting discord.js with Shoukaku and connecting discord.py with Wavelink.

Spotify search results show Spotify metadata, and the audio is mirrored at play time, so searching Spotify and then playing the result works seamlessly.

Why a track sometimes plays the wrong version

Mirroring depends on finding a match. When a Spotify track plays a live version, a cover or the wrong song, it’s usually because:

• the track has no ISRC match on the provider, so the title search picked a different upload;
• the song title is ambiguous or very common;
• the recording is region-restricted on the provider.

Putting the ISRC provider first improves accuracy a lot. For stubborn cases, users can paste a direct link from the playback source instead.

Troubleshooting

Spotify links return “no matches” or errors — check the client ID and secret, and look at the Lavalink log for authentication errors from Spotify.

Spotify tracks resolve but won’t play — mirroring found a match, but the provider failed to play it. This is usually a problem with the playback source (often the YouTube plugin needs updating), not with LavaSrc. See the YouTube source plugin.

Large playlists are slow — lower playlistLoadLimit, and consider loading the first few tracks immediately while the rest load in the background in your bot.

Plugin fails to load — the LavaSrc version doesn’t match your Lavalink major version. Use a v4-compatible release.

Unknown search source for a prefix — that source isn’t enabled under plugins.lavasrc.sources.

Memory and performance

Each resolved playlist is held in memory while it loads, and mirroring adds searches per track. Busy bots that load many big playlists should budget extra RAM and CPU for the node. How much RAM does Lavalink need? covers sizing.

A note on terms

LavaSrc is a widely used community plugin, and mirroring metadata to other sources is standard in the ecosystem. You’re still responsible for how your bot is used: respect each platform’s terms of service and Discord’s developer policies.

Summary

LavaSrc adds Spotify, Apple Music, Deezer and other sources to Lavalink. For Spotify it fetches metadata through Spotify’s API and mirrors the audio from another source, trying ISRC matches first and title searches second. Install a v4-compatible release, configure providers and the sources you need with their credentials, keep load limits modest, and use spsearch:-style prefixes from your bot. When a mirrored track fails to play, look at the playback source — usually the YouTube plugin — before blaming LavaSrc.