DOCSEARCHbyAlgolia
Submit Docs

Lavalink Documentation

repository·master·Indexed 23 days ago

https://github.com/lavalink-devs/lavalink

Lavalink is a standalone audio sending node based on Lavaplayer and Koe, designed to offload audio processing and streaming from main application shards to reduce CPU and memory overhead. It features a REST API for track resolution and player management, support for audio filters (equalizer, timescale, etc.), and a plugin system for extending functionality. Requires Java 17 LTS or newer and officially supports Linux AMD64.

Tokens
23.5K
Snippets
52
Records
124
Agent score
81%

What's inside Lavalink

  1. Overview of Lavalink features

    master

    Lavalink is a standalone audio sending node based on Lavaplayer. It is designed for high performance with a minimal CPU and memory footprint. Key capabilities include:

    • Audio Support: Powered by Lavaplayer, with support for Twitch and YouTube streams.
    • Control & Interaction: Full REST API for player control (including seeking and volume control), and an Event system via WebSockets.
    • Observability: Provides statistics and Prometheus metrics for monitoring.
    • Extensibility: Supports a plugin system.
    • Deployment: Available via Docker images.
    • Security: Supports basic authentication.

  2. Understand RoutePlanner terminology

    master

    When configuring RoutePlanner strategies in Lavalink, understand these two key concepts:

    • Ip block / CIDR block: A collection of IP addresses, typically contiguous and described using CIDR notation.
    • Combined IP Block: Created when you add multiple CIDR blocks to the configuration file. Lavaplayer treats these multiple blocks as a single virtual IP Block.

  3. Required Discord library capabilities for Lavalink integration

    master

    To successfully integrate Lavalink, your Discord library must support the following:

    • Message Sending: The ability to send messages via a shard's gateway connection.
    • Gateway Interception: The ability to intercept voice server and voice state updates from the gateway on your shard connection.

  5. Understand Lavalink WebSocket OP Types

    master

    Lavalink communicates via WebSocket using different Operation (OP) types. These types determine the nature of the payload being sent from the node to your application:

    • ready: Dispatched upon successful connection and authorization.
    • playerUpdate: Dispatched periodically with the latest state of a player.
    • stats: Dispatched once per minute containing node performance metrics.
    • event: Dispatched when specific player or voice events occur (e.g., track starts, ends, or errors).

  6. Configure Voice State for Discord connections

    master

    To connect a player to a Discord voice server, you must provide a Voice State object. This requires four specific values:

    • token: The Discord voice token.
    • endpoint: The Discord voice endpoint.
    • sessionId: The Discord voice session ID.
    • channelId: The Discord voice channel ID (required when updating a player).

    Note: sessionId and channelId are typically obtained from Discord's VoiceStateUpdate event, while endpoint and token are obtained from the VoiceServerUpdate event.

  7. Apply audio filters to a player

    master

    Lavalink supports a wide range of audio filters that can be applied to a player via the filters object. Applying a new filters object in an update request will override all previously applied filters.

    Supported filters include:

    • volume: Adjusts volume from 0.0 to 5.0 (1.0 is 100%).
    • equalizer: Adjusts 15 frequency bands (0-14).
    • karaoke: Targets specific bands to eliminate vocals.
    • timescale: Changes speed, pitch, and rate.
    • tremolo: Oscillates volume.
    • vibrato: Oscillates pitch.
    • rotation: Audio panning (stereo rotation).
    • distortion: Generates unique audio effects using sine/cosine offsets/scales.
    • channelMix: Mixes left and right channels.
    • lowPass: Suppresses higher frequencies.
    • pluginFilters: A map of configurations for custom installed plugins.
    {
  "volume": 1.0,
  "equalizer": [
    {
      "band": 0,
      "gain": 0.2
    }
  ],
  "karaoke": {
    "level": 1.0,
    "monoLevel": 1.0,
    "filterBand": 220.0,
    "filterWidth": 100.0
  },
  "timescale": {
    "speed": 1.0,
    "pitch": 1.0,
    "rate": 1.0
  },
  "tremolo": {
    "frequency": 2.0,
    "depth": 0.5
  },
  "vibrato": {
    "frequency": 2.0,
    "depth": 0.5
  },
  "rotation": {
    "rotationHz": 0
  },
  "distortion": {
    "sinOffset": 0.0,
    "sinScale": 1.0,
    "cosOffset": 0.0,
    "cosScale": 1.0,
    "tanOffset": 0.0,
    "tanScale": 1.0,
    "offset": 0.0,
    "scale": 1.0
  },
  "channelMix": {
    "leftToLeft": 1.0,
    "leftToRight": 0.0,
    "rightToLeft": 0.0,
    "rightToRight": 1.0
  },
  "lowPass": {
    "smoothing": 20.0
  },
  "pluginFilters": {
    "myPlugin": {
      "myPluginKey": "myPluginValue"
    }
  }
}

  10. Use the NanoSwitch strategy

    master

    The NanoSwitch strategy uses the NanoIpRoutePlanner. It switches the IP address on every clock update, using the current nanosecond as the offset within the used block.

    Requirements and constraints:

    • Requires at least a (combined) /64 IPv6 block ($2^{64}$ addresses).
    • If your CIDR is larger than a /64, use the RotatingNanoSwitch strategy instead.

  11. Understand the Player object structure

    master

    The Player object represents the current state of audio playback for a specific guild. It contains information about the currently playing track, volume, pause state, player state (timing/connection), voice connection details, and active audio filters.

    {
  "guildId": "...",
  "track": {
    "encoded": "...",
    "info": {
      "identifier": "dQw4w9WgXcQ",
      "isSeekable": true,
      "author": "RickAstleyVEVO",
      "length": 212000,
      "isStream": false,
      "position": 60000,
      "title": "Rick Astley - Never Gonna Give You Up",
      "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "isrc": null,
      "sourceName": "youtube"
    },
    "pluginInfo": { ... },
    "userData": { ... }
  },
  "volume": 100,
  "paused": false,
  "state": {
    "time": 1500467109,
    "position": 60000,
    "connected": true,
    "ping": 50
  },
  "voice": {
    "token": "...",
    "endpoint": "...",
    "sessionId": "..."
  },
  "filters": { ... }
}

  12. Use the RotatingNanoSwitch strategy

    master

    The RotatingNanoSwitch strategy uses the RotatingNanoIpRoutePlanner. It switches the IP address on every clock update using the current nanosecond as the offset. If a ban occurs, it rotates to the next /64 block as a fallback.

    Requirements and constraints:

    • Requires at least a /64 IPv6 CIDR ($2^{64}$ addresses).
    • To ensure rotation works, you must provide at least two /64 IPv6 CIDRs.
    • You can combine multiple /64s (or larger) without issues, as the strategy rotates across these blocks.
    • Note: It is not recommended to use combined /65s (e.g., two different /65s) for this strategy.