Version: v2.10.3 (current)

NodeLink Setup

These guides describe the stable 2.10.3 release, compared with 2.10.2. Lavalink v4 remains the primary backend. NodeLink uses the same Node, Rest, and Player classes with backend detection and guarded native features.

warning

Feature availability depends on your server configuration. Implemented client support does not guarantee that every source or plugin will work in your deployment. Follow the release validation checklist.

Install 2.10.3

npm install [email protected]

For pnpm use pnpm add [email protected]; for Yarn use yarn add [email protected]. Pin this version for reproducible installs, or use unqualified installation to follow npm's stable latest tag.

Configure Both Backends

Pass this node list to your existing manager or Discord-library wrapper:

import type { NodeOptions } from "magmastream";

const nodes: NodeOptions[] = [
  {
    identifier: "lavalink",
    host: "127.0.0.1",
    port: 2333,
    password: process.env.LAVALINK_PASSWORD!,
    useSSL: false,
    enableSessionResumeOption: true,
    sessionTimeoutSeconds: 900,
  },
  {
    identifier: "nodelink",
    host: "127.0.0.1",
    port: 2334,
    password: process.env.NODELINK_PASSWORD!,
    useSSL: false,
    isNodeLink: true,
    enableSessionResumeOption: true,
    sessionTimeoutSeconds: 900,
  },
];

Validate the environment variables before constructing the manager. Ports are examples: each server must actually listen on the configured port.

NodeLink is recognized from the explicit isNodeLink option, the WebSocket iamnodelink / isnodelink headers, or /v4/info's isNodelink flag. The detected flag is also applied to node.rest.isNodeLink. Explicit configuration is useful when a proxy strips upgrade headers.

Choose a Node for Native Playback

After your manager is initialized and the node is connected:

const player = manager.create({
  guildId,
  voiceChannelId,
  textChannelId,
  nodeIdentifier: "nodelink",
});

if (!player.node.isNodeLink) {
  throw new Error("This action requires a NodeLink player.");
}

Search routing and playback-node selection are separate. A search can use a different node from the player; player.search() delegates to manager search. Pin a NodeLink player when you need its native playback features.

Feature Boundaries

Feature	Lavalink v4	NodeLink
Search, queue, ordinary playback, volume, pause, seek	Shared API	Shared API
Standard filters	Subject to node support	Shared API
Lyrics	Requires a supported lyrics plugin	Native
SponsorBlock	Requires SponsorBlock plugin	Native
Chapters through `getChapters()`	Not provided by this helper	Native
Extra filters, animations	Not portable core options	Native
Mixer layers, gapless preload, fading, audio-track selection	Native extras rejected	Native
Voice receive	Not supported by this helper	Native
Encoding, meaning, stream resolution, raw PCM loading	NodeLink helpers rejected	Native
Type-modified and NodeLink-only searches	Routed away	Routed here

All helpers whose name contains NodeLink are backend-specific. Shorter aliases such as addMix(), getChapters(), and setEcho() are also NodeLink-only. Aliases do not make a native feature portable.

Mixed-Pool Guards

NodeLink-only searches require a connected, non-backup NodeLink node. Missing eligible nodes reject with MANAGER_NO_NODES. Native player/REST operations on Lavalink reject with NODE_PROTOCOL_ERROR; they are not silently redirected.

Shared prefix values such as ytsearch can use either backend, even when supplied through NodeLinkSearchPlatform.YouTube. See search routing.

Moving a player to another backend does not make native settings portable. Recheck player.node.isNodeLink after moves and use only the destination's supported filters, sources, and extras.

Next Steps

API signatures and payloads are linked from the class and typedef references.

Install 2.10.3​

Configure Both Backends​

Choose a Node for Native Playback​

Feature Boundaries​

Mixed-Pool Guards​

Next Steps​