Skip to main content
The application.yml file is the primary configuration file for Lavalink. It should be placed in the same directory where you start your Lavalink server.

​
Complete Example

application.yml
server: # REST and WS server
  port: 2333
  address: 0.0.0.0
  http2:
    enabled: false # Whether to enable HTTP/2 support

plugins:
#  name: # Name of the plugin
#    some_key: some_value # Some key-value pair for the plugin
#    another_key: another_value

lavalink:
  plugins:
#    - dependency: "com.github.example:example-plugin:1.0.0" # required
#      repository: "https://maven.example.com/releases" # optional
#      snapshot: false # optional, defaults to false
#  pluginsDir: "./plugins" # optional, defaults to "./plugins"
#  defaultPluginRepository: "https://maven.lavalink.dev/releases" # optional
#  defaultPluginSnapshotRepository: "https://maven.lavalink.dev/snapshots" # optional
  
  server:
    password: "youshallnotpass"
    sources:
      # The default Youtube source is deprecated and won't receive further updates
      # Please use https://github.com/lavalink-devs/youtube-source#plugin instead
      youtube: false
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      nico: true
      http: true # warning: keeping HTTP enabled without proxy could expose IP
      local: false
    
    filters: # All filters are enabled by default
      volume: true
      equalizer: true
      karaoke: true
      timescale: true
      tremolo: true
      vibrato: true
      distortion: true
      rotation: true
      channelMix: true
      lowPass: true
    
    nonAllocatingFrameBuffer: false
    bufferDurationMs: 400 # NAS buffer duration (minimum 40ms)
    frameBufferDurationMs: 5000 # Audio buffer in milliseconds
    opusEncodingQuality: 10 # Range: 0-10 (10 is best quality)
    resamplingQuality: LOW # Options: LOW, MEDIUM, HIGH
    trackStuckThresholdMs: 10000 # Track stuck threshold
    useSeekGhosting: true # Read buffer during seek
    youtubePlaylistLoadLimit: 6 # Pages at 100 each
    playerUpdateInterval: 5 # Update frequency in seconds
    youtubeSearchEnabled: true
    soundcloudSearchEnabled: true
    soundcloudFilterOutPreviewTracks: false
    gc-warnings: true
    
    #ratelimit:
    #  ipBlocks: ["1.0.0.0/8", "..."] # IP blocks for rotation
    #  excludedIps: ["...", "..."] # IPs to exclude from rotation
    #  strategy: "RotateOnBan" # RotateOnBan | LoadBalance | NanoSwitch | RotatingNanoSwitch
    #  searchTriggersFail: true # Whether search 429 triggers IP fail
    #  retryLimit: -1 # -1 = default | 0 = infinity | >0 = retry count
    
    #youtubeConfig: # Required for avoiding age restrictions
    #  email: "" # Google account email
    #  password: "" # Google account password
    
    #httpConfig: # Proxy configuration to protect your IP
    #  proxyHost: "localhost" # Proxy hostname (IP or domain)
    #  proxyPort: 3128 # Proxy port (3128 is default for Squid)
    #  proxyUser: "" # Optional proxy username
    #  proxyPassword: "" # Optional proxy password
    
    timeouts:
      connectTimeoutMs: 3000
      connectionRequestTimeoutMs: 3000
      socketTimeoutMs: 3000

metrics:
  prometheus:
    enabled: false
    endpoint: /metrics

sentry:
  dsn: ""
  environment: ""
#  tags:
#    some_key: some_value
#    another_key: another_value

logging:
  file:
    path: ./logs/

  level:
    root: INFO
    lavalink: INFO

  request:
    enabled: true
    includeClientInfo: true
    includeHeaders: false
    includeQueryString: true
    includePayload: true
    maxPayloadLength: 10000
    beforeRequest: false

  logback:
    rollingpolicy:
      max-file-size: 1GB
      max-history: 30

​
Server Configuration

​
server.port
integer
default:"2333"
The port where Lavalink will listen for connections.
​
server.address
string
default:"0.0.0.0"
The address to bind to. Use 0.0.0.0 to listen on all interfaces or 127.0.0.1 for localhost only.
​
server.http2.enabled
boolean
default:"false"
Whether to enable HTTP/2 support for the REST API.

​
Plugin Configuration

​
lavalink.plugins
array
List of plugins to load on startup.
​
lavalink.pluginsDir
string
default:"./plugins"
Directory where plugins are stored.
​
lavalink.defaultPluginRepository
string
default:"https://maven.lavalink.dev/releases"
Default Maven repository for plugin downloads.
​
lavalink.defaultPluginSnapshotRepository
string
default:"https://maven.lavalink.dev/snapshots"
Default Maven repository for snapshot plugin downloads.

​
Authentication

​
lavalink.server.password
string
required
Password for authenticating client connections to Lavalink.
Use a strong, unique password. This password is sent in plain text over the connection, so always use TLS/SSL in production.

​
Audio Sources

​
lavalink.server.sources
object
Enable or disable specific audio sources.
The default YouTube source is deprecated. Use the youtube-source plugin instead.
​
lavalink.server.sources.youtube
boolean
default:"false"
Enable YouTube source (deprecated).
​
lavalink.server.sources.bandcamp
boolean
default:"true"
Enable Bandcamp source.
​
lavalink.server.sources.soundcloud
boolean
default:"true"
Enable SoundCloud source.
​
lavalink.server.sources.twitch
boolean
default:"true"
Enable Twitch source.
​
lavalink.server.sources.vimeo
boolean
default:"true"
Enable Vimeo source.
​
lavalink.server.sources.nico
boolean
default:"true"
Enable Niconico source.
​
lavalink.server.sources.http
boolean
default:"true"
Enable HTTP source for direct URLs.
Keeping HTTP enabled without a proxy configured could expose your server’s IP address.
​
lavalink.server.sources.local
boolean
default:"false"
Enable local file playback.

​
Audio Filters

All filters are enabled by default. Set to false to disable specific filters.
​
lavalink.server.filters.volume
boolean
default:"true"
Enable volume filter.
​
lavalink.server.filters.equalizer
boolean
default:"true"
Enable equalizer filter.
​
lavalink.server.filters.karaoke
boolean
default:"true"
Enable karaoke filter.
​
lavalink.server.filters.timescale
boolean
default:"true"
Enable timescale filter (speed/pitch adjustment).
​
lavalink.server.filters.tremolo
boolean
default:"true"
Enable tremolo filter.
​
lavalink.server.filters.vibrato
boolean
default:"true"
Enable vibrato filter.
​
lavalink.server.filters.distortion
boolean
default:"true"
Enable distortion filter.
​
lavalink.server.filters.rotation
boolean
default:"true"
Enable rotation filter (8D audio effect).
​
lavalink.server.filters.channelMix
boolean
default:"true"
Enable channel mix filter.
​
lavalink.server.filters.lowPass
boolean
default:"true"
Enable low pass filter.

​
Performance Settings

​
lavalink.server.nonAllocatingFrameBuffer
boolean
default:"false"
Reduces allocations per player at the expense of non-instantaneous changes (e.g., volume).
​
lavalink.server.bufferDurationMs
integer
default:"400"
Duration of the NAS buffer in milliseconds. Higher values handle GC pauses better.
  • Set to <= 0 to disable JDA-NAS
  • Minimum value: 40ms
  • Lower values may introduce audio pauses
​
lavalink.server.frameBufferDurationMs
integer
default:"5000"
How many milliseconds of audio to keep buffered.
​
lavalink.server.opusEncodingQuality
integer
default:"10"
Opus encoder quality level.
  • Range: 0 to 10
  • 10 is best quality but most CPU-intensive
  • Lower values reduce CPU usage
​
lavalink.server.resamplingQuality
string
default:"LOW"
Quality of resampling operations.Options:
  • LOW - Fastest, lowest quality
  • MEDIUM - Balanced
  • HIGH - Best quality, most CPU-intensive
​
lavalink.server.trackStuckThresholdMs
integer
default:"10000"
Threshold in milliseconds for detecting stuck tracks. A track is considered stuck if it doesn’t return audio data within this time.
​
lavalink.server.useSeekGhosting
boolean
default:"true"
When seeking, continue reading from the audio buffer until empty or seek is ready.

​
Playlist and Search Settings

​
lavalink.server.youtubePlaylistLoadLimit
integer
default:"6"
Number of pages to load from YouTube playlists (100 tracks per page).
  • Default 6 = 600 tracks maximum
​
lavalink.server.playerUpdateInterval
integer
default:"5"
How frequently to send player updates to clients, in seconds.
​
lavalink.server.youtubeSearchEnabled
boolean
default:"true"
Enable YouTube search functionality.
​
lavalink.server.soundcloudSearchEnabled
boolean
default:"true"
Enable SoundCloud search functionality.
​
lavalink.server.soundcloudFilterOutPreviewTracks
boolean
default:"false"
Filter out 30-second preview tracks from SoundCloud results.
​
lavalink.server.gc-warnings
boolean
default:"true"
Enable garbage collection warnings in logs.

​
Rate Limiting

See the Route Planner documentation for detailed information.
​
lavalink.server.ratelimit.ipBlocks
array
List of IP blocks in CIDR notation for IP rotation.Example: ["1.0.0.0/8", "2001:db8::/32"]
​
lavalink.server.ratelimit.excludedIps
array
IPs to explicitly exclude from rotation.
​
lavalink.server.ratelimit.strategy
string
IP rotation strategy.Options:
  • RotateOnBan - Switch IP when banned
  • LoadBalance - Random IP selection
  • NanoSwitch - Nanosecond-based switching
  • RotatingNanoSwitch - Rotating nanosecond-based switching
​
lavalink.server.ratelimit.searchTriggersFail
boolean
default:"true"
Whether a search 429 (rate limit) response should trigger marking the IP as failing.
​
lavalink.server.ratelimit.retryLimit
integer
default:"-1"
Number of retries for failed requests.
  • -1 = use default lavaplayer value
  • 0 = infinity
  • >0 = specific retry count

​
YouTube Configuration

​
lavalink.server.youtubeConfig.email
string
Google account email for avoiding age restrictions.
Some restricted videos can be played without authentication.
​
lavalink.server.youtubeConfig.password
string
Google account password.

​
HTTP Proxy Configuration

​
lavalink.server.httpConfig.proxyHost
string
Proxy hostname (IP address or domain).
Useful for protecting your music node from IP-grabbing attacks. Only the proxy IP will be exposed.
​
lavalink.server.httpConfig.proxyPort
integer
default:"3128"
Proxy port (3128 is the default for Squid proxy).
​
lavalink.server.httpConfig.proxyUser
string
Optional username for proxy basic authentication.
​
lavalink.server.httpConfig.proxyPassword
string
Optional password for proxy basic authentication.

​
Timeouts

​
lavalink.server.timeouts.connectTimeoutMs
integer
default:"3000"
Connection timeout in milliseconds.
​
lavalink.server.timeouts.connectionRequestTimeoutMs
integer
default:"3000"
Connection request timeout in milliseconds.
​
lavalink.server.timeouts.socketTimeoutMs
integer
default:"3000"
Socket timeout in milliseconds.

​
Metrics Configuration

​
metrics.prometheus.enabled
boolean
default:"false"
Enable Prometheus metrics endpoint.
​
metrics.prometheus.endpoint
string
default:"/metrics"
Path for the Prometheus metrics endpoint.

​
Sentry Configuration

​
sentry.dsn
string
Sentry DSN for error tracking.
​
sentry.environment
string
Environment name for Sentry (e.g., “production”, “staging”).
​
sentry.tags
object
Custom tags to attach to Sentry events.

​
Logging Configuration

​
logging.file.path
string
default:"./logs/"
Directory where log files will be stored.
​
logging.level.root
string
default:"INFO"
Root logging level.Options: TRACE, DEBUG, INFO, WARN, ERROR
​
logging.level.lavalink
string
default:"INFO"
Lavalink-specific logging level.

​
Request Logging

​
logging.request.enabled
boolean
default:"true"
Enable HTTP request logging.
​
logging.request.includeClientInfo
boolean
default:"true"
Include client information in request logs.
​
logging.request.includeHeaders
boolean
default:"false"
Include HTTP headers in request logs.
​
logging.request.includeQueryString
boolean
default:"true"
Include query strings in request logs.
​
logging.request.includePayload
boolean
default:"true"
Include request payload in logs.
​
logging.request.maxPayloadLength
integer
default:"10000"
Maximum length of payload to include in logs.
​
logging.request.beforeRequest
boolean
default:"false"
Log requests before they are processed (instead of after).

​
Log Rotation

​
logging.logback.rollingpolicy.max-file-size
string
default:"1GB"
Maximum size of a single log file before rotation.
​
logging.logback.rollingpolicy.max-history
integer
default:"30"
Number of days to keep log files.

Environment Variables

Configure using environment variables instead

Route Planner

Configure IP rotation strategies

IPv6 Setup

Setup IPv6 for better rate limit handling

Config Server

Manage multiple instances centrally

Build docs developers (and LLMs) love

Get started for freeTalk to us