LavaSrc

LavaSrc

Summary

• Sources
  • Features
  • What is Mirroring?
• Lavalink Usage
  • Configuration
  • Update Settings at Runtime
• Lavaplayer Usage
• Supported URLs and Queries

Sources

Features

• 📁 playlists
• 💿 albums
• 🎵 tracks
• 📻 recommendations
• 🧑 artist top tracks
• 🔍 search results
• 🔬 LavaSearch
• 📜 LavaLyrics

Lavalink Usage

This plugin requires Lavalink v4 or greater

To install this plugin either download the latest release and place it into your plugins folder or add the following into your application.yml

Replace x.y.z with the latest version number

lavalink:
  plugins:
    - dependency: "com.github.topi314.lavasrc:lavasrc-plugin:x.y.z"
      repository: "https://maven.lavalink.dev/releases" # this is optional for lavalink v4.0.0-beta.5 or greater
      snapshot: false # set to true if you want to use snapshot builds (see below)

Snapshot builds are available in https://maven.lavalink.dev/snapshots with the short commit hash as the version

Configuration

For all supported urls and queries see here

To get your Spotify clientId, clientSecret go here & then copy them into your application.yml like the following.

To get your Spotify spDc cookie go here

To get your Apple Music api token go here

To get your Deezer arl cookie go here

To get your Yandex Music access token go here

To get your Vk Music user token go here

To get your Tidal token go here

To get your Qobuz userOauthToken go here

plugins:
  lavasrc:
    providers: # Custom providers for track loading. This is the default
      # - "dzisrc:%ISRC%" # Deezer ISRC provider
      # - "dzsearch:%QUERY%" # Deezer search provider
      - "ytsearch:\"%ISRC%\"" # Will be ignored if track does not have an ISRC. See https://en.wikipedia.org/wiki/International_Standard_Recording_Code
      - "ytsearch:%QUERY%" # Will be used if track has no ISRC or no track could be found for the ISRC
      #  you can add multiple other fallback sources here
    sources:
      spotify: false # Enable Spotify source
      applemusic: false # Enable Apple Music source
      deezer: false # Enable Deezer source
      yandexmusic: false # Enable Yandex Music source
      flowerytts: false # Enable Flowery TTS source
      youtube: false # Enable YouTube search source (https://github.com/topi314/LavaSearch)
      vkmusic: false # Enable Vk Music source
      tidal: false # Enable Tidal source
      qobuz : false # Enabled qobuz source
      ytdlp: false # Enable yt-dlp source
      jiosaavn: false # Enable JioSaavn source
    lyrics-sources:
      spotify: false # Enable Spotify lyrics source
      deezer: false # Enable Deezer lyrics source
      youtube: false # Enable YouTube lyrics source
      yandexmusic: false # Enable Yandex Music lyrics source
      vkmusic: false # Enable Vk Music lyrics source
      lrcLib: false # Enable LRC Library lyrics source (https://lrclib.net)
    spotify:
      # clientId & clientSecret are required for using spsearch
#      clientId: "your client id"
#      clientSecret: "your client secret"
      # spDc: "your sp dc cookie" # the sp dc cookie used for accessing the spotify lyrics api
      countryCode: "US" # the country code you want to use for filtering the artists top tracks. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
      playlistLoadLimit: 6 # The number of pages at 100 tracks each (also used to derive Spotify Partner API playlist track limit)
      albumLoadLimit: 6 # The number of pages at 50 tracks each (also used to derive Spotify Partner API album track limit)
      resolveArtistsInSearch: true # Whether to resolve artists in track search results (can be slow)
      localFiles: false # Enable local files support with Spotify playlists. Please note `uri` & `isrc` will be `null` & `identifier` will be `"local"`
      preferPartnerApi: false # When true, Spotify search uses partner API by default; when false, search uses Spotify v1 API.
      preferV1SearchApi: false # Only used when preferPartnerApi is true. Set true to force Spotify v1 search instead of partner search.
      customTokenEndpoint: "http://localhost:8080/api/token" # Optional custom endpoint for getting the anonymous token. If not set, spotify's default endpoint will be used which might not work. The response must match spotify's anonymous token response format.
    applemusic:
      countryCode: "US" # the country code you want to use for filtering the artists top tracks and language. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
      mediaAPIToken: "your apple music api token" # apple music api token
      # or specify an apple music key
      keyID: "your key id"
      teamID: "your team id"
      musicKitKey: |
        -----BEGIN PRIVATE KEY-----
        your key
        -----END PRIVATE KEY-----      
      playlistLoadLimit: 6 # The number of pages at 300 tracks each
      albumLoadLimit: 6 # The number of pages at 300 tracks each
    deezer:
      masterDecryptionKey: "your master decryption key" # the master key used for decrypting the deezer tracks. (yes this is not here you need to get it from somewhere else)
      arl: "your deezer arl" # the arl cookie used for accessing the deezer api this is not optional anymore
      formats: [ "FLAC", "MP3_320", "MP3_256", "MP3_128", "MP3_64", "AAC_64" ] # the formats you want to use for the deezer tracks. "FLAC", "MP3_320", "MP3_256" & "AAC_64" are only available for premium users and require a valid arl
    yandexmusic:
      accessToken: "your access token" # the token used for accessing the yandex music api. See https://github.com/topi314/LavaSrc#yandex-music
      playlistLoadLimit: 1 # The number of pages at 100 tracks each
      albumLoadLimit: 1 # The number of pages at 50 tracks each
      artistLoadLimit: 1 # The number of pages at 10 tracks each
#      proxy: # If defined, YandexMusic HTTP requests will be proxied through here. YandexMusic uses region blocking
#        url: "https://example.org" # The HTTP proxy to use
#        username: "my-bot" # Optional username to authenticate with the proxy
#        password: "youshallpass" # Optional password to authenticate with the proxy      
    flowerytts:
      voice: "default voice" # (case-sensitive) get default voice from here https://api.flowery.pw/v1/tts/voices
      translate: false # whether to translate the text to the native language of voice
      silence: 0 # the silence parameter is in milliseconds. Range is 0 to 10000.

提示：代码过长已自动截断

Plugin Info

LavaSrc adds the following fields to tracks & playlists in Lavalink

Track

{
  "encoded": "...",
  "info": {
    ...
  },
  "pluginInfo": {
    "albumName": "...",
    "albumArtUrl": "...",
    "artistUrl": "...",
    "artistArtworkUrl": "...",
    "previewUrl": "...",
    "isPreview": false
  },
  "userData": {
    ...
  }
}

Playlist

{
  "info": {
    ...
  },
  "pluginInfo": {
    "type": "playlist",
    "url": "...",
    "artworkUrl": "...",
    "author": "...",
    "totalTracks": 10
  },
  "tracks": [
    ...
  ]
}

Playlist Types

Update Settings at Runtime

Sometimes you may want to update the settings at runtime without restarting Lavalink. This can be done by sending a PATCH request to the /v4/lavasrc/config endpoint. Keep in mind this will NOT update the settings in the application.yml file. If you restart Lavalink the settings will be reset to the ones in the application.yml file.

PATCH /v4/lavasrc/config

LavaSrc Config Object

Spotify Config Object

Apple Music Config Object

Deezer Config Object

Deezer Formats

Yandex Music Config Object

Vk Music Config Object

Qobuz Config Object

Ytdlp Config Object

{
  "spotify": {
    "clientId": "your client id",
    "clientSecret": "your client secret",
    "spDc": "your sp dc cookie", 
    "preferPartnerApi": false,
    "preferV1SearchApi": false,
    "customTokenEndpoint": "http://localhost/api/token"
  },
  "applemusic": {
    "mediaAPIToken": "your apple music api token"
  },
  "deezer": {
    "arl": "your deezer arl",
    "formats": [
      "FLAC",
      "MP3_320",
      "MP3_256",
      "MP3_128",
      "MP3_64",
      "AAC_64"
    ]
  },
  "yandexMusic": {
    "accessToken": "your access token"
  },
  "vkMusic": {
    "userToken": "your user token"
  },
  "qobuz": {
    "userOauthToken": "your user token",
    "appId": "your app ID",
    "appSecret": "your app Secret"
  },
  "ytdlp": {
    "path": "yt-dlp",
    "searchLimit": 10,
    "mixPlaylistLoadLimit": 25,
    "playlistLoadLimit": 1000,
    "customLoadArgs": ["-q", "--no-warnings", "--flat-playlist", "--skip-download", "-J"],
    "customPlaybackArgs": ["-q", "--no-warnings", "-f", "bestaudio", "-J"]
  }
}

Lavaplayer Usage

Replace x.y.z with the latest version number

Snapshot builds are instead available in https://maven.topi.wtf/snapshots with the short commit hash as the version

Using in Gradle:

repositories {
  maven {
    url "https://maven.topi.wtf/releases"
  }
}

dependencies {
  implementation "com.github.topi314.lavasrc:lavasrc:x.y.z"
  implementation "com.github.topi314.lavasrc:lavasrc-protocol:x.y.z"
}

Using in Maven:

<repositories>
  <repository>
    <id>TopiWTF-releases</id>
    <name>Topis Maven Repo</name>
    <url>https://maven.topi.wtf/releases</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.topi314.lavasrc</groupId>
    <artifactId>lavasrc</artifactId>
    <version>x.y.z</version>
  </dependency>
  <dependency>
    <groupId>com.github.topi314.lavasrc</groupId>
    <artifactId>lavasrc-protocol-jvm</artifactId>
    <version>x.y.z</version>
  </dependency>
</dependencies>

Spotify

To get a Spotify clientId & clientSecret you must go here and create a new application.

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new SpotifySourceManager with the default providers, clientId, clientSecret, spDc, countryCode and AudioPlayerManager and register it
// spDc is only needed if you want to use it with LavaLyrics
var spotify = new SpotifySourceManager(clientId, clientSecret, spDc, countryCode, () -> playerManager, DefaultMirroringAudioTrackResolver);
playerManager.registerSourceManager(spotify);

Access Tokens

Getting anonymous & account access tokens is generally optional but required if you want to resolve spotify generated playlists or lyrics.

You can use a service such as Spotify Tokener via the customTokenEndpoint option to support those.

LavaLyrics

// create new lyrics manager
var lyricsManager = new LyricsManager();

// register source
lyricsManager.registerLyricsManager(spotify);

LavaSearch

// create new search manager
var searchManager = new SearchManager();

// register source
searchManager.registerSearchManager(spotify);

Apple Music

Alternatively, you can follow this guide

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new AppleMusicSourceManager with the standard providers, apple music api token, countrycode and AudioPlayerManager and register it
var appleMusic = new AppleMusicSourceManager(null, mediaAPIToken, "us", playerManager);
playerManager.registerSourceManager(appleMusic);

LavaSearch

// create new search manager
var searchManager = new SearchManager();

// register source
searchManager.registerSearchManager(appleMusic);

Deezer

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new DeezerSourceManager with the master decryption key and register it

var deezer = new DeezerSourceManager("the master decryption key", "your arl", formats);
playerManager.registerSourceManager(deezer);

LavaLyrics

// create new lyrics manager
var lyricsManager = new LyricsManager();

// register source
lyricsManager.registerLyricsManager(deezer);

LavaSearch

// create new search manager
var searchManager = new SearchManager();

// register source
searchManager.registerSearchManager(deezer);

Yandex Music

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new YandexMusicSourceManager with the access token and register it
var yandex = new YandexMusicSourceManager("...");

playerManager.registerSourceManager(yandex);

LavaLyrics

// create new lyrics manager
var lyricsManager = new LyricsManager();

// register source
lyricsManager.registerLyricsManager(yandex);

LavaSearch

// create new search manager
var searchManager = new SearchManager();

// register source
searchManager.registerSearchManager(yandex);

Flowery Text-to-Speech

Get list of all voices and languages supported here

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new FloweryTTSSourceManager 
playerManager.registerSourceManager(new FloweryTTSSourceManager());
// create a new FloweryTTSSourceManager with a default voice
playerManager.registerSourceManager(new FloweryTTSSourceManager("..."));

Vk Music

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new VkMusicSourceManager with the user token and register it
var vkMusic = new VkMusicSourceManager("...");

playerManager.registerSourceManager(vkMusic);

LavaLyrics

// create new lyrics manager
var lyricsManager = new LyricsManager();

// register source
lyricsManager.registerLyricsManager(vkMusic);

LavaSearch

// create new search manager
var searchManager = new SearchManager();

// register source
searchManager.registerSearchManager(vkMusic);

Tidal

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new TidalSourceManager with the token and register it
var tidal = new TidalSourceManager(countryCode, () -> playerManager, new DefaultMirroringAudioTrackResolver(providers), "your tidal token");

playerManager.registerSourceManager(tidal);

Qobuz

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new QobuzAudioSourceManager with the userOauthToken and register it
playerManager.registerSourceManager(new QobuzAudioSourceManager("...");

yt-dlp

AudioPlayerManager playerManager = new DefaultAudioPlayerManager();

// create a new YTDLPSourceManager with the path to the yt-dlp executable and register it
playerManager.registerSourceManager(new YTDLPSourceManager("path/to/yt-dlp"));

Supported URLs and Queries

Spotify

• spsearch:animals architects (check out Spotify Search Docs for advanced search queries like isrc & co)
• sprec:seed_artists=3ZztVuWxHzNpl0THurTFCv,4MzJMcHQBl9SIYSjwWn8QW&seed_genres=metalcore&seed_tracks=5ofoB8PFmocBXFBEWVb6Vz,6I5zXzSDByTEmYZ7ePVQeB (only works in Extended quota mode or with anonymous tokens, check out Spotify Recommendations Docs for the full query parameter list)
• sprec:mix:artist:0gxyHStUsqpMadRV0Di1Qt
• sprec:mix:track:4PTG3Z6ehGkBFwjybzWkR8
• sprec:mix:album:7t0YTcJ3HsalOTIE6XzQYo
• sprec:mix:isrc:GBARL9300135
• https://open.spotify.com/track/0eG08cBeKk0mzykKjw4hcQ
• https://open.spotify.com/album/7qemUq4n71awwVPOaX7jw4
• https://open.spotify.com/playlist/7HAO9R9v203gkaPAgknOMp (playlists can include local files if you enabled this via: plugins.lavasrc.spotify.localFiles: true. Please note uri & isrc will be null & identifier will be "local")
• https://open.spotify.com/artist/3ZztVuWxHzNpl0THurTFCv

(including new regional links like https://open.spotify.com/intl-de/track/0eG08cBeKk0mzykKjw4hcQ)

Apple Music

• amsearch:animals architects
• https://music.apple.com/cy/album/animals/1533388849?i=1533388859
• https://music.apple.com/cy/album/for-those-that-wish-to-exist/1533388849
• https://music.apple.com/us/playlist/architects-essentials/pl.40e568c609ae4b1eba58b6e89f4cd6a5
• https://music.apple.com/cy/artist/architects/182821355

Deezer

• dzsearch:animals architects
• dzisrc:USEP42058010
• dzrec:1090538082 (dzrec:{TRACK_ID}, dzrec:track={TRACK_ID} or dzrec:artist={ARTIST_ID})
• https://deezer.page.link/U6BTQ2Q1KpmNt2yh8
• https://www.deezer.com/track/1090538082
• https://www.deezer.com/album/175537082
• https://www.deezer.com/playlist/8164349742
• https://www.deezer.com/artist/159126

Yandex Music

• ymsearch:animals architects
• ymrec:71663565 (ymrec:{TRACK_ID})
• https://music.yandex.ru/album/13886032/track/71663565
• https://music.yandex.ru/album/13886032
• https://music.yandex.ru/track/71663565
• https://music.yandex.ru/users/yamusic-bestsongs/playlists/701626
• https://music.yandex.ru/playlists/e1bb61b5-360d-e3c5-124c-ef58d981ca7d
• https://music.yandex.ru/artist/701626

Flowery TTS

You can read about all the available options here, a list of available voices is here

• ftts://hello%20world
• ftts://hello%20world?audio_format=ogg_opus&translate=False&silence=1000&speed=1.0&voice=09924826-684f-51e9-825b-cf85aed2b2cf

Vk Music

• vksearch:animals architects
• vkrec:-2001015907_104015907 (vkrec:{TRACK_ID})
• https://vk.com/audio-2001015907_104015907
• https://vk.ru/artist/shadxwbxrn
• https://vk.com/audios700949584?q=phonk playlist&z=audio_playlist-219343251_152_389941c481d1375ac0
• https://vk.com/audios700949584?q=phonk playlist&z=audio_playlist-219343251_152
• https://vk.com/music/playlist/-219343251_152_389941c481d1375ac0
• https://vk.ru/music/playlist/-219343251_152
• https://vk.com/music/album/-2000228258_15228258_cafcb9e95f552acbb6?act=album
• https://vk.com/music/album/-2000228258_15228258_cafcb9e95f552acbb6
• https://vk.ru/music/album/-2000228258_15228258?act=album
• https://vk.com/music/album/-2000228258_15228258
• https://vk.com/audios700949584?q=phonk album&z=audio_playlist-2000933493_13933493%2Fbe3494d46d310b0d0d
• https://vk.ru/audios700949584?q=phonk album&z=audio_playlist-2000933493_13933493

Tidal

• tdsearch:animals architects
• tdrec:12345678 (tdrec:{TRACK_ID})
• https://tidal.com/browse/track/12345678
• https://tidal.com/browse/album/12345678
• https://tidal.com/browse/playlist/12345678
• https://tidal.com/browse/artist/12345678

Qobuz

• qbsearch:animals architects
• qbisrc:USEP42058010 (qbisrc:ISRC)
• qbrec:295210968 (qbrec:{TRACK_ID})
• https://open.qobuz.com/track/52151405
• https://play.qobuz.com/album/c9wsrrjh49ftb
• https://play.qobuz.com/playlist/24893079
• https://play.qobuz.com/artist/2070395
• https://www.qobuz.com/us-en/album/kesariya-pritam-arijit-singh-amitabh-bhattacharya/cxtiqss1up8ub

yt-dlp

• ytsearch:animals architects
• ytsearch:"USEP42058010" (ytsearch:"{ISRC}")
• https://www.youtube.com/watch?v=jdWhJcrrjQs
• https://www.youtube.com/watch?v=yEBEg4NGVrw&list=PLcZMZxR9uxC8EGrCPopQT1JjNTV6nnQ1G
• https://youtu.be/jdWhJcrrjQs

JioSaavn

• jssearch:animals architects
• jsrec:identifier
• https://www.jiosaavn.com/song/apna-bana-le/ATIfejZ9bWw
• https://www.jiosaavn.com/album/bhediya/wSM2AOubajk
• https://www.jiosaavn.com/artist/arijit-singh-songs/LlRWpHzy3Hk
• https://www.jiosaavn.com/featured/jai-hanuman/8GIEhrr8clSO0eMLZZxqsA