NodeLink Search

Shared and Native Enums

SearchPlatform remains the shared enum. Use NodeLinkSearchPlatform for the native prefix catalog, NodeLinkRecommendationPlatform for recommendations, and NodeLinkSearchType for type modifiers. Values do not include the trailing colon.

import {
  NodeLinkSearchPlatform,
  NodeLinkSearchType,
} from "magmastream";

const result = await manager.search({
  source: NodeLinkSearchPlatform.Unified,
  query: "daft punk",
}, requester);

const albums = await manager.search({
  source: NodeLinkSearchPlatform.YouTubeMusic,
  searchType: NodeLinkSearchType.Album,
  query: "daft punk",
}, requester);

The second call sends ytmsearch:album:daft punk and requires NodeLink.

Prefix Catalog

These are the exported alpha.10 enum members, including direct prefixes and aliases. Inclusion in the enum is not a promise that a source is enabled on your server or that it supports every modifier.

Enum member	Wire prefix
Unified	search:
YouTube	ytsearch:
YouTubeMusic	ytmsearch:
SoundCloud	scsearch:
Spotify	spsearch:
AppleMusic	amsearch:
Deezer	dzsearch:
Tidal	tdsearch:
Bandcamp	bcsearch:
AmazonMusic	amazonmusic:
AmazonMusicSearch	azsearch:
Anghami	agsearch:
Audiomack	audiomack:
AudiomackSearch	admsearch:
Audius	ausearch:
Bilibili	bilibili:
BilibiliSearch	bilisearch:
Bluesky	bksearch:
EternalBoxDirect	eternalbox:
EternalBox	ebox:
EternalBoxJukebox	jukebox:
Flowery	flowery:
FloweryTTS	ftts:
Gaana	gaanasearch:
GaanaSearch	gnsearch:
GoogleDrive	gdsearch:
GoogleTTS	gtts:
GoogleTTSSpeak	speak:
IHeartRadio	iheartradio:
IHeartRadioSearch	ihsearch:
Jiosaavn	jssearch:
LastFM	lfsearch:
LazyTTS	lazypytts:
LazyTTSAlt	lazytts:
LetrasMus	lmsearch:
Mixcloud	mixcloud:
MixcloudSearch	mcsearch:
Netease	ntsearch:
NicoVideo	nicovideo:
NicoVideoSearch	ncsearch:
Pandora	pdsearch:
PiperTTS	pipertts:
Qobuz	qbsearch:
Shazam	shsearch:
ShazamAlt	szsearch:
SongLink	slsearch:
VKMusic	vksearch:
Yandex	ymsearch:

Metadata sources may mirror playback to another enabled source. Source configuration and upstream authentication are server concerns.

Routing Rules

Input	Eligible backend
Shared search prefix, ordinary URL	Any usable node
NodeLink-only prefix such as search: or pipertts:	NodeLink
Explicit searchType or recognized raw type modifier	NodeLink
Explicit NodeLinkRecommendationPlatform source	NodeLink
Raw sprec:mix:...	Lavalink
Other raw sprec:...	NodeLink
Raw ytrec:, jsrec:, lmrec:	NodeLink
Other overlapping raw recommendation prefixes	Not inherently NodeLink-only

Selection honors the manager's priority/load strategy among eligible connected, non-backup nodes. A known prefixed identifier is passed through unchanged, without adding another search prefix. Unknown prefixes are not promised the same treatment.

Enum identity cannot distinguish identical string values: NodeLinkSearchPlatform.YouTube and SearchPlatform.YouTube both mean ytsearch. Use a type modifier or a genuinely native prefix when the search must run on NodeLink. A player's node identifier does not pin manager searches.

Search Type Modifiers

The format is <prefix>:<type>:<query>. Common types are track, playlist, album, artist, and channel. SoundCloud also accepts source-specific aliases such as user. The full client enum additionally exposes plural and alternate names; their meaning and support depend on the source.

const playlists = await manager.search({
  source: NodeLinkSearchPlatform.SoundCloud,
  searchType: NodeLinkSearchType.Playlist,
  query: "lofi beats",
});

// Already-prefixed queries also work.
const users = await manager.search("scsearch:user:trap nation");

Custom searchType strings must be alphanumeric and are normalized to lowercase.

Resolve Collection Results

Playlist/channel/artist search entries can be non-playable metadata results. Load their URI before adding the resulting tracks to a queue:

const collection = playlists.tracks.find((track) => track.uri);
if (collection?.uri) {
  const loaded = await manager.search({
    // A native source keeps this URL request on NodeLink.
    source: NodeLinkSearchPlatform.Unified,
    query: collection.uri,
  }, requester);
  await player.queue.add(loaded.tracks);
}

Do not treat a placeholder encoded result as a playable song.

Recommendations

Enum member	Wire prefix
Spotify	sprec:
Deezer	dzrec:
Tidal	tdrec:
VKMusic	vkrec:
Qobuz	qbrec:
Yandex	ymrec:
YouTube	ytrec:
Jiosaavn	jsrec:
LetrasMus	lmrec:

For NodeLink Spotify, use its seed syntax:

import { NodeLinkRecommendationPlatform } from "magmastream";

const recommendations = await manager.search({
  source: NodeLinkRecommendationPlatform.Spotify,
  query: "seed_tracks=1xKMSHgGIQ26RhDDxmIjan",
}, requester);

This builds sprec:seed_tracks=.... It is not the Lavalink/LavaSrc sprec:mix:track:... workaround. That raw mix identifier deliberately routes to Lavalink in a mixed pool. Do not combine it with a NodeLink recommendation source to attempt native recommendations.

player.getRecommendedTracks(track) uses the library's recommendation selection and fallback logic. It is separate from manually choosing a recommendation prefix and does not guarantee selection of the player's own node.

Result Handling

The manager supports NodeLink album, artist, episode, station, podcast, show, and short load types in addition to the standard track/search/playlist types. Collection loads include playlist; track-like loads expose a track array.

if (result.loadType === "empty" || result.loadType === "error") {
  console.log("No playable results returned.");
} else {
  console.log(result.tracks.length);
}

if ("playlist" in result) {
  console.log(result.playlist.playlistInfo.name);
  console.log(result.playlist.pluginInfo);
}

Empty/backend-error results expose tracks: []. Request failures and timeouts can still throw. Respect upstream rate limits; increasing the client timeout does not fix a server waiting on a long Spotify retry.