Star ✨ on GitHub

Manager

The Manager is the central hub of Moonlink.js. It coordinates nodes, audio players, and the connection with Discord.

The Manager class coordinates the connection between the Discord client, Lavalink nodes, and the database.

Constructor

new Manager(config)

new Manager(config)#

Creates the central hub for Moonlink.js.

configIManagerConfig required

The main configuration object.

IManagerConfig

nodesINodeOptions[] required

An array of Lavalink nodes to connect to.

optionsIManagerOptionsConfig

Global settings for the manager, players, and system behavior.

send(guildId, payload) => void

Optional. A function to send packets to Discord. Required if you do not use a Connector.

Example
const { Manager } = require('moonlink.js');

const manager = new Manager({
    nodes: [
        { host: 'localhost', port: 2333, password: 'youshallnotpass' }
    ],
    options: {
        clientName: 'MyMusicBot/1.0.0',
        reconnectAttempts: 3
    },
    // Required if not using manager.use()
    send: (id, payload) => client.guilds.cache.get(id)?.shard.send(payload)
});

Properties

Manager Properties

Core components and state accessible via the Manager instance.

Sub-Managers

playersPlayerManager

The interface for managing voice connections (create, destroy, get).

nodesNodeManager

The interface for managing Lavalink node connections and stats.

databaseDatabaseManager

The internal database for queue persistence.

State & Config

optionsIManagerOptionsConfig

The readonly configuration object with defaults applied.

readyNodesMap<string, Node>

A map of nodes that are connected and ready for requests.

initializedboolean

Whether init() has been completed.

clientIdstring

The Bot ID used for this session.

Methods

init(clientId)

init(clientId)#

Initializes the manager, connects to the database, and establishes connections to nodes.

clientIdstring required

The Discord Client ID.

Example
client.on('ready', async () => {
    // Initialize Moonlink when Discord is ready
    await manager.init(client.user.id);
    console.log('Moonlink Manager initialized!');
});

use(connector, client)

use(connector, client)#

Injects a Connector to bridge Moonlink.js with your Discord library.

connectorConnector required

The connector instance.

clientany required

The client instance of your Discord library.

Example
const { Connectors } = require('moonlink.js');

// Using the built-in Discord.js connector
// This automates manager.init() and packet handling!
manager.use(new Connectors.DiscordJs(), client);

search(options)

search(options)#

Searches for tracks, playlists, or albums.

optionsISearchQuery required

The search configuration object.

ISearchQuery

querystring required

The search term or URL.

sourcestring

Force a specific source.

requesterunknown

The requester of the track.

nodestring

Optional node ID.

Example
const res = await manager.search({
    query: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    requester: message.author
});

if (res.loadType === 'track') {
    // Add the first track to the player's queue
    player.queue.add(res.tracks[0]);
}

packetUpdate(packet)

packetUpdate(packet)#

Handles raw voice updates from Discord.

packetany required

The raw data packet.

Example
// Only necessary if NOT using a Connector
client.on('raw', (packet) => {
    manager.packetUpdate(packet);
});

decodeTrack(encoded)

decodeTrack(encoded)#

Decodes a Lavalink base64 track string.

encodedstring required

The base64 string.

Example
const track = manager.decodeTrack("QAA...");
console.log(track.info.title);

encodeTrack(track)

encodeTrack(track)#

Encodes a track object into a Lavalink base64 string.

trackITrackInfo required

The track information object.

Example
const base64 = manager.encodeTrack({
    title: "Rick Roll",
    author: "Rick Astley",
    identifier: "dQw4w9WgXcQ",
    length: 212000,
    isSeekable: true,
    isStream: false,
    uri: "https://youtube.com/watch?v=dQw4w9WgXcQ",
    sourceName: "youtube",
    position: 0
});

Events

Event Usage#

You can listen to any of these events using manager.on(eventName, listener).

Example
manager.on("nodeCreate", (node) => {
    console.log(`Node created: ${node.identifier}`);
});

manager.on("trackStart", (player, track) => {
    console.log(`Now playing: ${track.title} in ${player.guildId}`);
});

manager.on("socketClosed", (player, code, reason) => {
    console.warn(`Voice socket closed: ${code} - ${reason}`);
});

Manager Events

Events emitted by the Manager instance during its lifecycle.

Debug

debug(message: string) => void

Emitted for general debugging logs.

Node Events

nodeCreate(node: Node) => void

Emitted when a node is created.

nodeReady(node: Node, payload: any) => void

Emitted when a node is ready.

nodeConnected(node: Node) => void

Emitted when a node connects.

nodeReconnect(node: Node) => void

Emitted when a node successfully reconnects.

nodeReconnecting(node: Node, attempt: number) => void

Emitted when a node attempts to reconnect.

nodeResume(node: Node) => void

Emitted when a node session is resumed.

nodeDisconnect(node: Node, code: number, reason: string) => void

Emitted when a node disconnects.

nodeError(node: Node, error: Error) => void

Emitted when a node has an error.

nodeDestroy(identifier: string) => void

Emitted when a node is destroyed.

nodeRaw(node: Node, payload: any) => void

Emitted when a raw packet is received from a node.

nodeStateChange(node: Node, oldState: NodeState, newState: NodeState) => void

Emitted when a node's connection state changes.

Player Events

playerCreate(player: Player) => void

Emitted when a player is created.

playerDestroy(player: Player, reason?: string) => void

Emitted when a player is destroyed.

playerUpdate(player: Player, track: Track, payload: any) => void

Emitted when player update data is received.

playerSwitchedNode(player: Player, oldNode: Node, newNode: Node) => void

Emitted when a player is transferred to a different node.

playerConnecting(player: Player) => void

Emitted when a player starts connecting to voice.

playerConnected(player: Player) => void

Emitted when a player successfully connects to voice.

playerReady(player: Player) => void

Emitted when a player is fully ready.

playerResuming(player: Player) => void

Emitted when a player starts resuming.

playerResumed(player: Player) => void

Emitted when a player has successfully resumed.

playerDisconnected(player: Player) => void

Emitted when a player disconnects from voice.

playerReconnect(player: Player, reason?: string) => void

Emitted when a player attempts to reconnect.

playerMoved(player: Player, oldChannel: string, newChannel: string) => void

Emitted when a player moves to a different voice channel.

playerMuteChange(player: Player, selfMute: boolean, serverMute: boolean) => void

Emitted when a player's mute state changes.

playerDeafChange(player: Player, selfDeaf: boolean, serverDeaf: boolean) => void

Emitted when a player's deaf state changes.

playerSuppressChange(player: Player, suppress: boolean) => void

Emitted when a player's suppression state changes.

playerAutoPlaySet(player: Player, autoPlay: boolean) => void

Emitted when autoPlay is toggled.

playerAutoLeaveSet(player: Player, autoLeave: boolean) => void

Emitted when autoLeave is toggled.

playerChangedVolume(player: Player, oldVolume: number, volume: number) => void

Emitted when the volume is changed.

playerChangedLoop(player: Player, oldLoop: PlayerLoop, loop: PlayerLoop) => void

Emitted when the loop mode is changed.

playerTextChannelIdSet(player: Player, oldChannel: string, newChannel: string) => void

Emitted when the text channel is updated.

playerVoiceChannelIdSet(player: Player, oldChannel: string, newChannel: string) => void

Emitted when the voice channel ID is updated manually.

playerNodeSet(player: Player, oldNode: string, newNode: string) => void

Emitted when the player's node identifier is updated.

playerRecoveryStarted(player: Player) => void

Emitted when player recovery begins.

playerRecoverySuccess(player: Player) => void

Emitted when player recovery succeeds.

playerRecoveryFailed(player: Player) => void

Emitted when player recovery fails.

Failover Events

playersMoved(players: Player[], oldNode: Node, newNode: Node) => void

Emitted when multiple players are moved due to node failure.

playersOrphaned(players: Player[], deadNode: Node) => void

Emitted when players cannot be moved and are left without a node.

Player Triggered Events

playerTriggeredPlay(player: Player, track: Track) => void

Emitted when play() is called.

playerTriggeredPause(player: Player) => void

Emitted when pause() is called.

playerTriggeredResume(player: Player) => void

Emitted when resume() is called.

playerTriggeredStop(player: Player) => void

Emitted when stop() is called.

playerTriggeredSkip(player: Player, oldTrack: object, currentTrack: Track) => void

Emitted when skip() is called.

playerTriggeredSeek(player: Player, position: number) => void

Emitted when seek() is called.

playerTriggeredShuffle(player: Player, oldQueue: object, currentQueue: Track[]) => void

Emitted when shuffle() is called.

playerTriggeredBack(player: Player, track: Track) => void

Emitted when back() is called.

Track Events

trackStart(player: Player, track: Track) => void

Emitted when a track starts playing.

trackEnd(player: Player, track: Track, reason: TrackEndReason) => void

Emitted when a track finishes playing.

trackStuck(player: Player, track: Track, threshold: number) => void

Emitted when a track gets stuck.

trackException(player: Player, track: Track, exception: any) => void

Emitted when a track errors.

Queue Events

queueAdd(player: Player, tracks: Track | Track[]) => void

Emitted when tracks are added.

queueRemove(player: Player, tracks: Track | Track[]) => void

Emitted when tracks are removed.

queueMoveRange(player: Player, tracks: Track[], from: number, to: number) => void

Emitted when tracks are moved.

queueRemoveRange(player: Player, tracks: Track[], start: number, end: number) => void

Emitted when a range of tracks is removed.

queueDuplicate(player: Player, tracks: Track[], index: number) => void

Emitted when tracks are duplicated.

queueEnd(player: Player) => void

Emitted when the queue is empty.

Other Events

filtersUpdate(player: Player, filters: Filters) => void

Emitted when filters are updated.

socketClosed(player: Player, code: number, reason: string, remote: boolean) => void

Emitted when the voice connection closes.

voiceSessionChanged(player: Player, oldId: string | boolean, newId: string) => void

Emitted when voice session ID changes.

autoPlayed(player: Player, track: Track, prev: Track) => void

Emitted when a track plays via AutoPlay.

autoLeaved(player: Player, lastTrack?: Track) => void

Emitted when the bot auto-leaves.

Troubleshooting
The fastest way to diagnose the most common Moonlink + voice issues.
Connector
Abstract class for creating custom bridges between Moonlink.js and Discord libraries.