How to add plugins to Lavalink

Plugins add sources and features to Lavalink: other music sites, lyrics, search types and more. On a PlayNHost node you add one in two ways: put the plugin's .jar file in the plugins folder, or add a dependency line to application.yml and let Lavalink download it. Either way, its settings go under the plugins: section of application.yml, and the node needs a restart.

What is there already

Your node starts with one plugin: the YouTube source, as plugins/youtube-plugin-1.18.2-playnhost1.jar, with its settings under plugins:, youtube:. The plugin list under lavalink: is empty:

lavalink:
  plugins: []
  pluginsDir: "./plugins"

Do not add the YouTube plugin again, either as a file or as a dependency line. A dependency line for it with another version makes Lavalink delete the PlayNHost file at the next start (the console says Deleted ./plugins/youtube-plugin-1.18.2-playnhost1.jar).

Way 1: upload the plugin file

This works even when the plugin's download site is down, because nothing is downloaded at start.

1. Download the plugin's .jar from its own release page, usually on GitHub. Pick a release made for Lavalink 4.
2. In the panel, stop the node.
3. Open Files, open the plugins folder and upload the .jar: How to upload, edit and manage your server files.
4. Add the plugin's settings to application.yml (see below), save, and start the node.

Way 2: a dependency line

1. Copy the plugin's dependency line from its page. It has three parts: group:name:version.
2. Stop the node, open application.yml under Files, and replace plugins: [] under lavalink: with a list:

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

3. Use the exact version from the plugin's page, and the repository it names, if any.
4. Save and start the node. Lavalink downloads the file into plugins on that start and keeps it.

The plugin's settings

Each plugin reads its own block under the top-level plugins: key, next to youtube:. Add yours inside the same plugins: section. A second plugins: line at the top level breaks the file.

plugins:
  youtube:
    enabled: true
    # ... leave the YouTube lines as they are
  lavasrc:
    sources:
      spotify: false

application.yml is YAML: indent with spaces, never tabs, and keep each level two spaces deeper than the one above. A plugin that needs keys (an account, a client ID) may stop the whole node at start if it is switched on without them, so fill in its keys or leave it off.

Check that it loaded

Start the node and read Console. Each plugin that loads prints a Loaded line before the ready line. On a new node the YouTube plugin's looks like this:

Loaded 'youtube-plugin-1.18.2-playnhost1.jar' (17 classes)
Lavalink is ready to accept connections.

A plugin you added gets its own Loaded line with its file name. A plugin from a dependency line is downloaded on the first start, then loaded the same way.

If the node stops instead, the error just above usually names the plugin or the line of application.yml at fault: Lavalink errors and what they mean.

Good to know

• Take a backup before you edit application.yml: How to create, download and restore backups.
• Do not change server.port or plugins.youtube.remoteCipher.url: the panel sets both at every start.
• Only use plugins you trust. A plugin runs inside your node with full access to it, including the password.
• Sites change what they let bots do, so a source plugin can need an update. Check the plugin's release page first when one stops working.
• YouTube has its own guide: How to play YouTube on Lavalink 4.