ryuko

A full-featured Lavalink v4 music framework for Node.js.
Built-in queue, autoplay, recommendations, filter presets, and a plugin system — all with zero unnecessary dependencies and clear, readable errors.

Features

• Full Lavalink v4 support (WebSocket + REST)
• Built-in queue with loop modes, shuffle, and history
• Built-in autoplay and track recommendations
• Filter presets — bassboost, nightcore, vaporwave, 8D, and more
• Smart track resolver — URLs, search queries, and playlists in one call
• Multi-node cluster support with automatic load balancing
• Plugin system — extend the library without forking it
• Structured logging with optional debug mode
• Clear, readable errors — every error tells you what went wrong and how to fix it
• Zero unnecessary dependencies — only ws and undici
• CommonJS — works everywhere

Installation

npm install ryuko 

Requirements:

• Node.js 18 or higher
• A running Lavalink v4 server

Quick Start

const { Ryuko } = require("ryuko");

// 1. Create the client
const client = new Ryuko({
  nodes: [
    {
      id:       "main",
      host:     "localhost",
      port:     2333,
      password: "youshallnotpass",
    },
  ],
  sendGatewayPayload: (guildId, payload) => {
    // Send the payload to Discord using your gateway library
    // e.g. gateway.send(guildId, payload);
  },
  debug: false, // Set to true to enable verbose logging
});

// 2. Connect when your bot is ready
client.connect(botUserId);

// 3. Forward Discord voice events
gateway.on("VOICE_STATE_UPDATE",  data => client.handleVoiceUpdate(data));
gateway.on("VOICE_SERVER_UPDATE", data => client.handleVoiceUpdate(data));

// 4. Play music
const player = client.createPlayer(guildId);
player.connect(voiceChannelId, { deafened: true });

const { result } = await client.play(guildId, "never gonna give you up");
console.log(`Now playing: ${result.tracks[0].title}`);

Table of Contents

• Client Setup
• Player
• Queue
• Filters
• Resolver
• Autoplay
• Multi-Node Cluster
• Plugin System
• Events
• Error Handling
• Debug Logging

Client Setup

new Ryuko(options)

| Option | Type | Required | Description | |---|---|---|---| | nodes | NodeConfig[] | ✅ | Array of Lavalink node configs | | sendGatewayPayload | Function | ✅ | Function to send payloads to Discord gateway | | user | string \| object | ❌ | Bot user or ID (can also be passed to connect()) | | debug | boolean | ❌ | Enable verbose debug logging (default: false) | | plugins | Plugin[] | ❌ | Plugins to load on startup | | resolver | object | ❌ | TrackResolver options (see Resolver) |

Player

Create and control music players per guild.

// Create a player
const player = client.createPlayer(guildId);

// Connect to a voice channel
player.connect(channelId, { deafened: true });

// Play a track directly
const track = await client.resolver.resolveFirst("lofi beats");
await player.play(track);

// Or add to queue (auto-starts if idle)
await player.addToQueue(track);

Filters

Apply audio effects using built-in presets or custom filter objects.

const { Filters } = require("ryuko");

// Use a preset
await player.setFilters(Filters.bassboost());

Resolver

The built-in resolver handles URLs, search queries, and playlists automatically.

const { SearchSource } = require("ryuko");

// Auto-detects URLs vs search queries
const result = await client.resolver.resolve("[https://youtu.be/dQw4w9WgXcQ](https://youtu.be/dQw4w9WgXcQ)");

Autoplay

Enable autoplay on a player and Ryuko will automatically fetch and play a related track when the queue runs out.

Multi-Node Cluster

Ryuko extends Cluster and supports multiple Lavalink nodes out of the box.

const client = new Ryuko({
  nodes: [
    { id: "us-east",  host: "node1.example.com", port: 2333, password: "pass" },
  ],
  sendGatewayPayload: (guildId, payload) => gateway.send(guildId, payload),
});

License

MIT