Lavalink application.yml Explained Line by Line

application.yml controls everything about a Lavalink node: where it listens, who can connect, which sources it plays from, how it buffers and encodes audio, which plugins it loads, and how it logs. Copying a config from a tutorial works until something goes wrong and you don’t know which line to change. This article walks through the settings that matter in Lavalink v4.

The file lives next to Lavalink.jar (or at /opt/Lavalink/application.yml in the official Docker image). YAML is indentation-sensitive: use spaces, never tabs, and keep nested keys aligned.

The server block

server:
  port: 2333
  address: 0.0.0.0
  http2:
    enabled: false

• port — the TCP port for both the REST API and the WebSocket. 2333 is the convention; any free port works. Your bot’s client must use the same one.
• address — the interface to listen on. 0.0.0.0 accepts connections from anywhere (protect it with a firewall and password). 127.0.0.1 accepts only local connections — ideal when the bot runs on the same server.
• http2 — leave disabled unless you have a specific reason.

Authentication

lavalink:
  server:
    password: "a-long-random-string"

Clients send this in the Authorization header. It’s the only thing standing between the internet and your node, so make it long and random, and never use the famous default youshallnotpass on a public server. Generate one with openssl rand -base64 32.

Sources

lavalink:
  server:
    sources:
      youtube: false
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      nico: true
      http: true
      local: false

Each key enables a built-in source manager:

• youtube — the built-in YouTube source is deprecated in v4. Set it to false and use the YouTube plugin instead. Leaving both on causes conflicts.
• http — plays direct links to audio files and streams, including internet radio. Useful, but it lets users make your node fetch arbitrary URLs; disable it if you don’t need it.
• local — plays files from the server’s disk. Keep it false unless you have a reason; it can expose files if paths aren’t controlled.

Plugins such as LavaSrc add more sources (Spotify, Apple Music, Deezer and others) with their own configuration — see LavaSrc explained.

Search

lavalink:
  server:
    soundcloudSearchEnabled: true
    youtubeSearchEnabled: true

These control whether search prefixes like scsearch: work for built-in sources. With the YouTube plugin, YouTube search is controlled by the plugin’s own allowSearch setting instead.

Buffers and playback

lavalink:
  server:
    bufferDurationMs: 400
    frameBufferDurationMs: 5000
    trackStuckThresholdMs: 10000
    useSeekGhosting: true
    playerUpdateInterval: 5
    youtubePlaylistLoadLimit: 6

• bufferDurationMs — the size of the NAS (native audio sender) buffer. Larger values smooth over brief CPU hiccups at the cost of slightly slower reactions to pause and filter changes. 400 ms is a good default; raise it if audio stutters on a busy node.
• frameBufferDurationMs — how many milliseconds of decoded audio frames Lavalink keeps ahead. 5,000 ms (five seconds) absorbs network jitter from sources. Higher values use more memory per player.
• trackStuckThresholdMs — if no audio is produced for this long, Lavalink emits a TrackStuckEvent so your bot can skip. 10 seconds is sensible.
• useSeekGhosting — keeps playing the old position while seeking, so seeks sound seamless. Leave it on.
• playerUpdateInterval — how often (in seconds) Lavalink sends position updates to clients. Five is fine; lower values mean more WebSocket traffic.
• youtubePlaylistLoadLimit — pages of a playlist to load (each page is roughly 100 tracks). Keep it modest to avoid huge playlists consuming memory and time.

Audio quality

lavalink:
  server:
    opusEncodingQuality: 10
    resamplingQuality: LOW

• opusEncodingQuality — 0 to 10, trading CPU for quality when encoding to Opus. 10 is best quality. On a CPU-constrained node with many players, lowering it saves CPU.
• resamplingQuality — LOW, MEDIUM or HIGH. Resampling happens when a source’s sample rate differs from Discord’s 48 kHz. LOW uses little CPU and sounds fine to most listeners; HIGH costs noticeably more CPU per player.

If your node is running out of CPU with many concurrent players, these two settings are the first to adjust.

Garbage collection warnings

lavalink:
  server:
    gc-warnings: true

Logs a warning when garbage collection pauses are long enough to affect audio. Leave it on — frequent warnings mean your heap is too small or your GC needs tuning. See JVM tuning for Lavalink.

Plugins

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

• dependency — the plugin’s Maven coordinates. Lavalink downloads it on startup.
• repository — where to download from, if it isn’t the default.
• snapshot — use the snapshot repository for pre-release builds.
• pluginsDir — where plugin JARs live. You can also drop JARs here manually.

Plugin-specific settings go in a separate top-level plugins: block:

plugins:
  youtube:
    enabled: true
    allowSearch: true
  lavasrc:
    sources:
      spotify: true
    spotify:
      clientId: "..."
      clientSecret: "..."

Note the difference: lavalink.plugins (a list) says which plugins to load; top-level plugins (a map) configures them.

Rate limiting and IP rotation

lavalink:
  server:
    ratelimit:
      ipBlocks: ["2001:db8:1234::/48"]
      strategy: "RotateOnBan"
      searchTriggersFail: true
      retryLimit: -1

Some sources rate-limit or block IPs that make many requests. If you have an IPv6 block routed to your server, Lavalink can rotate requests across addresses. This is an advanced setting; leave it out unless you have a routed IPv6 range and understand the implications. Kerit Cloud’s VPS plans include a /64 IPv6 subnet — see using the IPv6 /64 subnet.

Metrics

metrics:
  prometheus:
    enabled: true
    endpoint: /metrics

Exposes Prometheus metrics — players, memory, CPU, frames — for graphing in Grafana. The endpoint is served on the same port, so restrict who can reach it. See monitoring Lavalink with Prometheus and Grafana.

Logging

logging:
  file:
    path: ./logs/
  level:
    root: INFO
    lavalink: INFO
  logback:
    rollingpolicy:
      max-file-size: 25MB
      max-history: 7

• level — INFO in production. Switch lavalink to DEBUG temporarily when troubleshooting.
• file.path — write logs to files as well as the console. If you do, set a rolling policy so they can’t fill your disk.

A sensible starting point

For a small-to-medium node: port 2333, a strong password, YouTube via the plugin, http only if you need direct links, local: false, bufferDurationMs: 400, frameBufferDurationMs: 5000, opusEncodingQuality: 10, resamplingQuality: LOW, gc-warnings: true, and logging at INFO. Adjust only when you see a specific problem. The full install walkthrough is in setting up Lavalink v4 from scratch.

On Kerit Cloud’s managed Lavalink plans, this file is tuned and maintained for you; on self-managed plans, every line is yours to change.

Summary

application.yml defines where Lavalink listens (server), who can connect (password), what it plays (sources and plugins), how it buffers and encodes (bufferDurationMs, frameBufferDurationMs, opusEncodingQuality, resamplingQuality), and how it reports (metrics, logging). Keep YouTube in the plugin, disable local and unnecessary http, use a strong password, tune encoding settings when CPU runs short, and keep YAML indentation clean.