Lavalink Performance Optimization Guide

A well-optimized Lavalink server delivers smooth audio with minimal resource usage. This guide covers proven optimization techniques to get the best performance from your Lavalink setup.

JVM Optimization

Memory Settings

Configure heap size based on your usage:

bashCopy
# For 50-100 players
java -Xms256M -Xmx512M -jar Lavalink.jar

# For 100-300 players
java -Xms512M -Xmx1G -jar Lavalink.jar

# For 300+ players
java -Xms1G -Xmx2G -jar Lavalink.jar

Key settings:

• -Xms - Initial heap (set to 50% of max)
• -Xmx - Maximum heap (based on available RAM)

Garbage Collection

Use G1GC for balanced performance:

bashCopy
java -XX:+UseG1GC \
     -XX:G1HeapRegionSize=4M \
     -XX:+ParallelRefProcEnabled \
     -XX:+AlwaysPreTouch \
     -jar Lavalink.jar

For low-latency requirements:

bashCopy
java -XX:+UseZGC \
     -XX:+ZGenerational \
     -jar Lavalink.jar

Complete Optimized Startup

bashCopy
java -Xms512M -Xmx1G \
     -XX:+UseG1GC \
     -XX:G1HeapRegionSize=4M \
     -XX:+ParallelRefProcEnabled \
     -XX:+AlwaysPreTouch \
     -XX:MaxGCPauseMillis=50 \
     -XX:+DisableExplicitGC \
     -Djava.net.preferIPv4Stack=true \
     -jar Lavalink.jar

Configuration Optimization

application.yml Tuning

yamlCopy
lavalink:
  server:
    password: "your_secure_password"
    sources:
      youtube: true
      soundcloud: true
      bandcamp: true
      twitch: true
      http: true
      local: false
    bufferDurationMs: 400
    frameBufferDurationMs: 5000
    youtubePlaylistLoadLimit: 6
    playerUpdateInterval: 5
    youtubeSearchEnabled: true
    soundcloudSearchEnabled: true
    gc-warnings: true

server:
  port: 2333
  address: 0.0.0.0

Buffer Settings

bufferDurationMs - Audio buffer before playback starts

• Lower = faster start, more risk of stuttering
• Higher = slower start, smoother playback
• Recommended: 400-600ms

frameBufferDurationMs - Frame buffer size

• Higher values use more memory but handle network hiccups better
• Recommended: 5000ms

Player Update Interval

Controls how often player state updates are sent:

yamlCopy
playerUpdateInterval: 5  # seconds

Lower values = more accurate progress but more network traffic.

Network Optimization

Server Location

Choose a server location close to:

1. Discord voice servers (for audio delivery)
2. Your users (for lower latency)

Discord Voice Server Regions:

• US East: Ashburn, Virginia
• US West: Los Angeles
• Europe: Amsterdam, Frankfurt
• Asia: Singapore, Japan

DNS Configuration

Use fast DNS resolvers:

bashCopy
# In /etc/resolv.conf
nameserver 1.1.1.1
nameserver 8.8.8.8

Connection Limits

Increase system limits for many connections:

bashCopy
# In /etc/sysctl.conf
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.core.netdev_max_backlog = 65535

Source-Specific Optimization

YouTube

YouTube is the most common source. Optimize with:

yamlCopy
lavalink:
  server:
    youtubePlaylistLoadLimit: 6  # Limit playlist loading
    youtubeSearchEnabled: true

Consider using youtube-source plugin for better reliability:

yamlCopy
plugins:
  - dependency: "dev.lavalink.youtube:youtube-plugin:1.0.0"
    repository: "https://maven.lavalink.dev/releases"

Spotify

Spotify requires a plugin since it does not provide direct audio:

yamlCopy
plugins:
  - dependency: "com.github.topi314.lavasrc:lavasrc-plugin:4.0.0"
    repository: "https://maven.topi.wtf/releases"

lavasrc:
  spotify:
    clientId: "your_client_id"
    clientSecret: "your_client_secret"

Monitoring and Profiling

Enable Metrics

yamlCopy
metrics:
  prometheus:
    enabled: true
    endpoint: /metrics

Key Metrics to Watch

• players_active - Current active players
• jvm_memory_used - Memory usage
• jvm_gc_pause - GC pause times
• http_request_duration - API latency

Logging Configuration

Reduce log verbosity in production:

yamlCopy
logging:
  level:
    root: INFO
    lavalink: INFO
  request:
    enabled: false
    includeClientInfo: false
    includeHeaders: false
    includeQueryString: false
    includePayload: false

Resource Management

Player Cleanup

Implement automatic cleanup for inactive players:

javascriptCopy
// In your bot code
setInterval(() => {
  for (const player of manager.players.values()) {
    if (!player.playing && !player.paused) {
      player.destroy();
    }
  }
}, 300000); // Every 5 minutes

Queue Limits

Prevent memory issues from large queues:

javascriptCopy
const MAX_QUEUE_SIZE = 500;

if (player.queue.length >= MAX_QUEUE_SIZE) {
  return message.reply('Queue is full!');
}

Docker Optimization

Optimized Dockerfile

dockerfileCopy
FROM eclipse-temurin:21-jre-alpine

ENV JAVA_OPTS="-Xms512M -Xmx1G -XX:+UseG1GC"

WORKDIR /app
COPY Lavalink.jar .
COPY application.yml .

EXPOSE 2333

CMD java $JAVA_OPTS -jar Lavalink.jar

Docker Compose

yamlCopy
version: '3.8'
services:
  lavalink:
    build: .
    ports:
      - "2333:2333"
    environment:
      - JAVA_OPTS=-Xms512M -Xmx1G -XX:+UseG1GC
    deploy:
      resources:
        limits:
          memory: 1.5G
        reservations:
          memory: 512M
    restart: unless-stopped

Common Performance Issues

High Memory Usage

Causes:

• Too many active players
• Large queues
• Memory leaks in plugins

Solutions:

• Implement player cleanup
• Limit queue sizes
• Update to latest Lavalink version

Audio Stuttering

Causes:

• Insufficient CPU
• Network latency
• Small buffers

Solutions:

• Upgrade server resources
• Choose closer server location
• Increase buffer settings

Slow Track Loading

Causes:

• Source rate limiting
• DNS issues
• Network congestion

Solutions:

• Use source plugins
• Configure fast DNS
• Implement caching

Benchmarking

Test Your Setup

bashCopy
# Check response time
curl -w "%{time_total}\n" -o /dev/null -s http://localhost:2333/version

# Monitor during load
watch -n 1 'curl -s http://localhost:2333/metrics | grep players'

Expected Performance

Conclusion

Lavalink optimization involves JVM tuning, configuration adjustments, and proper resource management. Start with the recommended settings and adjust based on your monitoring data.

HeavenCloud provides pre-optimized Lavalink hosting with all these optimizations applied, so you can focus on building your music bot instead of server tuning.