PLUGINS.md

Lavalink Plugins

Warning: The plugin system is still in beta. Breaking changes may still be made to the plugin API if deemed necessary.

Lavalink supports third-party plugins to add additional functionality such as custom audio sources, custom filters, WebSocket handling, REST endpoints, and much more.

List of plugins:

• Google Cloud TTS plugin A text to speech plugin using the google cloud tts api
• SponsorBlock plugin for skipping sponsor segments in YouTube videos
• LavaSrc plugin adds Spotify, Apple Music & Deezer(native play) support
• LavaSearch plugin adds advanced search functionality including playlists, albums, artists, tracks & terms
• DuncteBot plugin adds additional source managers that are not widely used
• Extra Filter plugin adds additional audio filters to lavalink
• XM plugin adds support for various music tracker module formats

Lavalink loads all .jar files placed in the plugins directory, which you may need to create yourself. Lavalink can also download plugin .jar files automatically by editing the configuration file. See the respective plugin repository for instructions.

You can add your own plugin by submitting a pull-request to this file.

Distributing your plugin

The official plugin repository is hosted on https://maven.lavalink.dev. If you want to publish your plugin there, please reach out to us via Discord for credentials. The Lavalink team has release (https://maven.lavalink.dev/releases) and snapshot (https://maven.lavalink.dev/snapshots) repositories which you can use to publish your plugin. By default, Lavalink will look for the plugin in the Lavalink repository, but you can also specify a custom repository for each plugin in your application.yml file.

lavalink:
  plugins:
    - dependency: "com.github.example:example-plugin:1.0.0" # required, the dependency to your plugin
      repository: "https://maven.example.com/releases" # optional, defaults to https://maven.lavalink.dev/releases for releases
      snapshot: false # optional, defaults to false, used to tell Lavalink to use the snapshot repository instead of the release repository

The default repositories can also be overridden in your application.yml file.

lavalink:
  defaultPluginRepository: "https://maven.example.com/releases" # optional, defaults to https://maven.lavalink.dev/releases
  defaultPluginSnapshotRepository: "https://maven.example.com/snapshots" # optional, defaults to https://maven.lavalink.dev/snapshots

Additionally, you can override the default plugin path where Lavalink saves and loads the downloaded plugins.

lavalink:
  pluginsDir: "./lavalink-plugins" # optional, defaults to "./plugins"

Developing your own plugin

Note:
If your plugin is developed in Kotlin make sure you are using Kotlin v1.8.22

Follow these steps to setup a new Lavalink plugin

Now you can start writing your plugin. You can test your plugin against Lavalink by running Gradle with the :runLavalink Gradle task. The Gradle plugin documentation might be helpful.

Lavalink has a plugin API which you can integrate with. The API is provided as an artifact and is used by the template. It is also possible to integrate with internal parts og Lavalink, but this is not recommended. Instead, open an issue or pull-request to change the API.

Lavalink is configured by plugins using the Spring Boot framework using Spring annotations.

You can define custom REST endpoints and configuration file properties. See the Spring Boot documentation for Spring Web MVC and type-safe configuration.

If you simply want to add a Lavaplayer AudioSourceManager to Lavalink it is sufficient to simply provide it as a bean. For example:

import org.springframework.stereotype.Service;

@Service
class MyAudioSourceManager implements AudioSourceManager {
    // ...
} 

Likewise, you can also add new MediaContainerProbe this way, to be used with the HTTP and local sources:

import org.springframework.stereotype.Service;

@Service
class MyMediaContainerProbe implements MediaContainerProbe {
    // ...
} 

To intercept and modify existing REST endpoints, you can implement the RestInterceptor interface:

import org.springframework.stereotype.Service;
import dev.arbjerg.lavalink.api.RestInterceptor;

@Service
class TestRequestInterceptor implements RestInterceptor {
    // ...
}

To add custom info to track and playlist JSON, you can implement the AudioPluginInfoModifier interface:

import org.springframework.stereotype.Service;
import dev.arbjerg.lavalink.api.AudioPluginInfoModifier;

@Service
class TestAudioPluginInfoModifier implements AudioPluginInfoModifier {
	// ...
}