Building Shiesuta: Scaling a Discord Music Bot with Lavalink

When building Discord bots that handle music playback, developers quickly hit a wall if they attempt to decode audio directly in Node.js. Node’s single-threaded event loop simply wasn’t designed to decode Opus frames, resample high-bitrate PCM buffers, and stream UDP voice packets concurrently across dozens of servers.

That’s where Lavalink enters the picture, and why I built Shiesuta and Hakari on top of it.

The Problem with In-Process Audio

In standard Discord bot libraries (discord.js, eris), playing audio usually involves:

1. Spawning ffmpeg or ytdl-core as a subprocess.
2. Piping standard output through an Opus encoder.
3. Writing UDP packets directly through the voice socket connection.

While this works for one or two personal servers, CPU usage spikes drastically with 10+ concurrent voice connections. When garbage collection pauses happen, the audio stutters, and event loop latency degrades general bot command responses.

Offloading Audio to Standalone Nodes

Lavalink acts as an audio routing middleware written in Java. It connects directly to Discord’s Voice Gateway via WebSockets and UDP, handling:

• Audio track resolution (YouTube, Spotify, SoundCloud, Bandcamp, raw HTTP).
• Native decoding via Lavaplayer.
• Volume adjustments, equalization filters, and audio pitch modulation.
• UDP voice packet transmission directly to Discord’s media relays.

[Discord Gateway] <--- WebSocket ---> [Bot (Node.js)]
                                            |
                                      REST / WebSocket
                                            v
[Discord Voice Server] <--- UDP Stream --- [Lavalink Node]

The Node.js bot client only needs to send lightweight JSON payloads instructing the node to play track identifiers or adjust filters.

Failover & Multi-Node Architecture

In Shiesuta and Hakari, one of our primary goals was zero-interruption playback even during server maintenance. We structured multi-node balancing:

import { MoonlinkManager } from 'moonlink.js';

const manager = new MoonlinkManager(
  [
    {
      host: process.env.LAVALINK_HOST,
      port: 2333,
      secure: false,
      password: process.env.LAVALINK_PASS,
    }
  ],
  {
    clientName: 'Shiesuta/1.0.0',
    autoResume: true,
    resumeTimeout: 60,
  },
  (guildId, payload) => {
    const guild = client.guilds.cache.get(guildId);
    if (guild) guild.shard.send(payload);
  }
);

Key Takeaways:

• Auto-Resume: By assigning a session identifier and enabling autoResume, if the bot process restarts, the Lavalink node keeps streaming audio in voice channels for up to 60 seconds without disconnecting.
• Queue State Isolation: Storing queue items in memory with fallback snapshots in Redis ensures playback queues survive ephemeral server restarts.

Lavalink turns what used to be a fragile, resource-hungry nightmare into a clean, decoupled distributed system — keeping my favorite metal, pop playlists, and My Chemical Romance albums streaming without dropping a single frame.