Skip to main content
Version: v2.10.3

Changes in 2.10.3

2.10.3 is the stable release of the Lavalink v4 corrections and NodeLink integration developed throughout the 2.10.3 alpha and dev cycle. This page covers the complete feature and compatibility changes since 2.10.2.

Previous stable release notes are preserved with the 2.10.2 documentation. The comparison touches 20 library/package files. No runtime dependency upgrade is part of this release.

warning

There are public type and result-shape corrections. Read the migration guide before upgrading. Native NodeLink features are not portable to ordinary Lavalink nodes.

Install This Release​

npm install [email protected]

Or use pnpm add [email protected] / yarn add [email protected]. Unqualified installation follows npm's stable latest tag. No alpha or dev tag is needed for this release.

Lavalink remains the primary backend. NodeLink uses the existing Node, Player, and Rest classes with explicit/backend-detected feature handling.

Backend Detection and Mixed Pools​

  • Recognize isNodeLink configuration, upgrade headers iamnodelink / isnodelink, and /v4/info.isNodelink; synchronize the REST flag.
  • Separate shared SearchPlatform from NodeLinkSearchPlatform, NodeLinkRecommendationPlatform, and NodeLinkSearchType.
  • Route native searches to eligible connected, non-backup NodeLink nodes. Reject when no eligible node exists instead of sending native requests to Lavalink.
  • Preserve known prefixed identifiers without adding another prefix.
  • Keep Lavalink's raw sprec:mix:... recommendation workaround on Lavalink. NodeLink Spotify uses sprec:seed_tracks=....
  • Guard native player extras, native filter keys, and native helper operations against ordinary Lavalink nodes.
  • Account for cpu.nodelinkLoad in load-based selection and stats normalization.

Shared enum values such as ytsearch remain usable on either backend. Selecting a NodeLink enum member with an identical shared value does not, by itself, force NodeLink routing.

Search and Load Results​

The native catalog includes unified search, additional providers, recommendation prefixes, TTS prefixes, and aliases. The enum reference lists all exported values.

Type modifiers use <prefix>:<type>:<query>, for example ytmsearch:album:daft punk or scsearch:user:trap nation. Explicit searchType accepts the enum or an alphanumeric custom string.

Album, artist, episode, station, podcast, show, and short load types are handled alongside track/search/playlist. Non-playable collection search entries must be loaded by URI before queueing their contents.

See NodeLink Search.

Playback and Audio Mixer​

  • Add audioTrackId, legacy language, and loudnessNormalizer play options.
  • Add preloadNextTrack() for setting/clearing a gapless next track.
  • Handle TrackEndReasonTypes.Gapless without issuing a duplicate play request.
  • Add setNodeLinkFading() and setNodeLinkLoudnessNormalizer().
  • Add/list/update/remove mixer layers through Node and Player.
  • Offer explicit *NodeLinkMix method aliases alongside the short mixer names.

Mixer volume is 0-1, separate from main player volume 0-1000. Preloading does not add a local queue entry; applications must keep the queue and preload aligned.

See NodeLink Playback.

Filters​

Shared setters now include channel mix, low pass, and configurable tremolo. NodeLink serialization accounts for its lowercase lowpass spelling.

Native effects include high pass, echo, reverb, chorus, compressor, flanger, phaser, phonograph, spatial audio, and tape. Explicit setNodeLink* aliases make their backend requirement visible. Option types expose NodeLink transition and animation fields where supported.

syncFromNode() hydrates local filter state from native filter-change payloads without sending an echo request.

Nonempty setPluginFilters() calls verify the advertised plugin names, defaulting to LavaDSPX-Plugin aliases, case-insensitively. Clearing filters does not require the plugin. Native effects are not nested inside pluginFilters.

See NodeLink Filters.

Lyrics, Chapters, and SponsorBlock​

  • Support NodeLink's native loadlyrics shape and language query, while retaining legacy result variants in the public union.
  • Use native player-scoped lyric subscribe/unsubscribe routes.
  • Add chapter loading through Node and Player, with explicit NodeLink aliases.
  • Add meaning/background helpers with an optional language.
  • Adapt category-based SponsorBlock helpers to native NodeLink settings.
  • Add native SponsorBlock state, settings, and full segment replacement helpers.

Lavalink continues to use supported plugins for lyrics and SponsorBlock. See metadata examples.

Voice Receive and Gateway Events​

  • Parse native binary voice start/audio/stop frames; keep legacy JSON handling.
  • Emit typed live voiceReceiverData frames with speaker, guild, Buffer, format, SSRC, and timestamp.
  • Buffer per-speaker audio until stop and clear receiver resources on cleanup.
  • Expose native mix, diagnostic, worker, playback, lifecycle, Eternal Box, and stream-metadata callbacks.
  • Synchronize local state for native volume/filter/seek/pause/lifecycle changes.
  • Forward unknown/native events through nodeLinkEvent instead of reporting every unfamiliar NodeLink event as an error.
  • Emit playerUpdate for both backends; support applicable global native events without requiring a guild ID.

See voice and event examples.

Additional Native REST Helpers​

Add typed connection diagnostics, single/batch encoding, meaning lookup, direct-stream metadata resolution, and raw PCM streaming. The PCM helper returns an Undici Response whose body the caller consumes or cancels.

See the endpoint map and Rest.

Public Types and Metadata​

  • Model track URI, artwork URL, and ISRC as nullable protocol fields. Modern tracks commonly have a URI, but the API does not guarantee one.
  • Preserve required source names while permitting additional source-name strings.
  • Map raw track userData to built-track customData.
  • Correct playlist.playlistInfo to the core { name, selectedTrack } object. Expose plugin metadata separately as playlist.pluginInfo.
  • Replace broad/incorrect load-response typing with discriminated unions.
  • Separate ready, stats, player-update, track/plugin, and NodeLink gateway payloads.
  • Permit idle-player track: null, nullable frame stats, optional backend-specific info, and optional event track fields.
  • Type route-planner responses and extensible plugin metadata.
  • Make lyrics, chapter, and SponsorBlock manager callbacks tolerate a null track.

REST Behavior​

  • Add session-scoped bulk getPlayers(), including server-response normalization and an HTTP-400 fallback for locally known players.
  • Add typed single/bulk decoding, info, stats, and route-planner helpers.
  • Send bulk decode bodies as JSON arrays, without double encoding.
  • Accept the NodeLink wrapped bulk-decode response.
  • Allow an omitted POST body for endpoints that do not require one.
  • Avoid session-scoped requests when the active session is unavailable.

The bulk-player fallback only discovers players already known to this manager; it is not a server-wide inventory.

Reliability and Persistence​

  • Reset reconnect attempts after a successful connection and fix retry-limit handling.
  • Clear stale node and REST session IDs after disconnection; clear reconnect state and guard player destruction/moves while a node has no usable session.
  • Ignore unusable/null track event data instead of crashing track handling.
  • Normalize empty/backend-error search results to tracks: [].
  • Persist and restore autoplay mode, retry count, and requester state.
  • Restore portable autoplay users through the wrapper's user-resolution hooks. The Discord.js, Eris, Oceanic, Discordeno, Cloudstorm, and Seyfert wrappers retain those callbacks.

Queue-storage changes also include internal variable renames; they do not introduce a new storage backend or configuration migration.

Development History​

This table groups changes by their first relevant tagged checkpoint. Version-only tags are not separate feature releases.

CheckpointDateMain changes since the preceding checkpoint
2.10.3-dev.0April 30, 2026Reconnect cleanup, guarded destruction/node switching, null-track handling
2.10.3-alpha.0May 6, 2026Stale-session request guards
2.10.3-alpha.1 / alpha.2May 7, 2026Session clearing after WebSocket close; formatting/version checkpoints
2.10.3-alpha.3May 7, 2026Reconnect-attempt reset and retry-boundary fix
2.10.3-alpha.4May 10, 2026Empty/error search track arrays; voice-receiver timeout typing
2.10.3-dev.1 / dev.2May 20, 2026Autoplay state preservation and complete restore
2.10.3-alpha.5May 20, 2026Lavalink v4 protocol/type alignment
2.10.3-alpha.6May 21, 2026Plugin-filter guards, bulk-player fallback, NodeLink endpoint adaptation
2.10.3-alpha.7May 22, 2026Mixer, chapters, extra filters, backend-routed searches
2.10.3-alpha.8May 22, 2026Missing native search prefixes
2.10.3-alpha.9May 22, 2026Further prefix aliases, shared search, and search-type modifiers
2.10.3-alpha.10August 31, 2026NodeLink v3 client surface, playback extras, REST helpers, binary voice, expanded events and guards

Migration and Validation​

Read the migration guide for result-shape changes and nullable fields. Follow the validation checklist for both backends and a mixed node pool.

Implementation caveats are documented in the feature guides: getCurrentLyrics() does not normalize NodeLink's result; disconnected REST calls can return null despite non-null signatures; filter update requests can log rather than propagate server errors. Server-side sources, API limits, voice permissions, and enabled features still need live testing.