New in v1.9 — first-class NodeLink, mixed pools, plugin filters

YuKumo

A modern, lightweight, production-ready Lavalink v4 client engineered for TypeScript and JavaScript. Minimal dependencies (only ws), full strict type safety, and a framework-agnostic architecture.

Get Started API Reference GitHub

$npm install yukumo

const yukumo = new YuKumo({
  nodes: [{ host: "localhost", port: 2333, password: "..." }],
  resuming: { enabled: true },   // audio survives bot restarts
  queueOptions: { persist: true },
});

const player = await yukumo.createPlayer({ guildId, voiceChannelId });
const { tracks } = await yukumo.search("never gonna give you up");
await player.play(tracks[0], { volume: 80 });

npm v1.9.060 KB minzipMIT LicenseTypeScript StrictMinimal Deps (ws only)

Works with your favorite Discord library

discord.jsSeyfertErisOceanic.jsDiscordeno

Built for scale, designed for speed

Every subsystem in YuKumo is engineered to be fast, type-safe, and lightweight out of the box.

Restart-Proof Sessions

Session resuming + player snapshots: redeploy your bot and the music keeps playing. Live players are adopted silently with zero audio gap.

High Performance Engine

Player creation in ~1.8ms. Queue operations at ~9.3M ops/sec. Event dispatch at ~663k ops/sec.

Source-Aware Autoplay

Per-source recommendations — YouTube RD mixes, Spotify sprec, Deezer, Yandex, SoundCloud — with played-track dedupe to prevent loops.

Queue Persistence

Queues auto-save to Memory/Redis storage on every change and restore after a restart — playlists survive redeploys.

SponsorBlock & Live Lyrics

Server-side sponsor skipping and timestamped live lyric lines via the SponsorBlock and LavaLyrics node plugins.

Self-Healing Connections

WS heartbeats detect half-open dead nodes, error-rate guards destroy runaway players, and every destroy carries a reason.

First-Class NodeLink

Lavalink & NodeLink in one mixed pool. Auto-detected node types, a capability system that routes features to a capable node, extra DSP filters, voice receive, chapters, and built-in lyrics.

100% Strict Type Safety

Full TypeScript support with strict typings across nodes, players, search, filters, and events.

Minimal Dependencies

Only one runtime dependency (ws). Lightweight footprint with native Bun WebSocket support.

Framework Agnostic

Native support for discord.js, Seyfert, Eris, Oceanic.js, and Discordeno.

Built-in Queue Manager

Repeat modes, Fisher-Yates shuffle, history navigation, sortBy, removeTrack, unique, lock, and range manipulation.

Modular Plugin Lifecycle

Hook into search queries, voice connections, track playback, player destruction, and node selection.

NodeLink · first-class

Lavalink and NodeLink, one API

Mix Lavalink v4 and NodeLink nodes in a single pool. YuKumo detects each node's type on connect, exposes what it can do, and routes feature requests — lyrics, chapters, voice receive, extra DSP filters — to a node that supports them. Ask for a feature a node can't serve and you get a typed error, never a silent failure.

Auto-detected node.type / capabilities / supports()
Capability-aware selection + graceful cross-family failover
10 extra DSP filters, built-in lyrics, chapters, mixer & voice receive

Read the NodeLink guide

import { YuKumo, createLavalinkNode, createNodeLinkNode } from "yukumo";

const kumo = new YuKumo({
  nodes: [
    createLavalinkNode({ host: "ll", port: 2333, password: "..." }),
    createNodeLinkNode({ host: "nl", port: 2333, password: "..." }),
  ],
});

node.type;                     // "lavalink" | "nodelink"
node.supports("voiceReceive"); // true on NodeLink

// routed to a lyrics-capable node in the mixed pool
const lyrics = await kumo.getLyrics(track.encoded);
await player.setEcho({ delay: 200, feedback: 0.4 });

1.8ms

Player creation

9.3M

Queue ops / sec

663k

Events / sec

60KB

Bundle size

Runtime dep (ws)

Everything you need to ship

Guides, references, and release notes — kept in lockstep with every version.