Lavalink Client v4

Production-grade Lavalink v4 client library for Node.js with multi-node support, session resuming, penalty-based load balancing, and circuit breakers.

Features

• REST-first Architecture - Built for Lavalink v4's REST API protocol
• Multi-Node Load Balancing - Penalty-based node selection with configurable weights
• WebSocket Resilience - Exponential backoff with jitter for reconnection
• Session Resuming - Zero-downtime client restarts
• Circuit Breakers - Automatic fault isolation
• Queue Persistence - Redis and in-memory store support
• Auto-skip & Auto-resume - Intelligent playback handling
• Player Migration - Automatic failover on node disconnect
• Full TypeScript - Complete type safety

Installation

npm install lavalink-client

Quick Start

import { Manager, RedisQueueStore } from 'lavalink-client';

const manager = new Manager({
  nodes: [
    {
      id: 'node-1',
      host: 'localhost',
      port: 2333,
      authorization: 'youshallnotpass',
      retries: 10,
      reconnectInterval: 5000,
    },
  ],
  userId: 'YOUR_DISCORD_USER_ID',
  sendGatewayPayload: (guildId, payload) => {
    // Forward to Discord gateway
    guild.shard.send(payload);
  },
  queueStore: new RedisQueueStore({ host: 'localhost', port: 6379 }),
  autoSkip: true,
  autoResume: true,
});

manager.on('nodeConnect', (node) => {
  console.log(`Node ${node.id} connected`);
});

manager.on('trackStart', (player, track) => {
  console.log(`Playing: ${track.info.title}`);
});

manager.connect();

Configuration Options

Node Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | id | string | required | Unique node identifier | | host | string | required | Lavalink server hostname | | port | number | required | Lavalink server port | | authorization | string | required | Lavalink password | | secure | boolean | false | Use WSS/HTTPS | | regions | string[] | [] | Voice regions for routing | | retries | number | 10 | Max reconnection attempts | | reconnectInterval | number | 5000 | Base reconnection delay (ms) | | resumeTimeout | number | 30000 | Session resume timeout (ms) | | moveOnDisconnect | boolean | true | Auto-migrate players on disconnect |

Manager Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | nodes | NodeOptions[] | required | Lavalink node configurations | | userId | string | required | Discord bot user ID | | sendGatewayPayload | function | required | Discord gateway send function | | queueStore | QueueStoreManager | Memory | Queue persistence backend | | autoSkip | boolean | true | Auto-advance on track end/error | | autoResume | boolean | true | Enable session resuming | | destroyAfterMs | number | 30000 | Auto-destroy after queue end (ms) | | maxQueueSize | number | 10000 | Maximum tracks in queue | | maxPreviousTracks | number | 25 | Maximum history entries |

Penalty-Based Load Balancing

The client uses weighted penalty calculation for node selection:

| Component | Weight | Threshold | |-----------|--------|-----------| | Total Players | 1.0x | >100/node | | Playing Players | 2.5x | >50/node | | CPU Load | 3.0x | >70% | | Memory Ratio | 2.0x | >80% | | Frame Deficits | 5.0x | Any non-zero | | Frame Nulls | 3.0x | >10/update |

WebSocket Reconnection

Exponential backoff with jitter:

delay = min(base * 2^attempt + random(0, 0.5 * base * 2^attempt), 60000)

Parameters:

• Base delay: 5s
• Max delay: 60s
• Jitter fraction: 50%

License

MIT License - see LICENSE for details.