Node

Represents an audio node (server instance) used for managing guild player connections, handling track operations, node migration, and more.

Properties

• riffy
• name
• host
• port
• password
• restVersion
• secure
• sessionId
• rest
• wsUrl
• restUrl
• regions
• info
• stats
• connected
• resumeKey
• resumeTimeout
• autoResume
• reconnectTimeout
• reconnectTries
• lastStats

Lyrics Plugin Support

Node provides built-in lyrics plugin utilities accessible through its .lyrics property. Below are the available methods and their signatures:

.lyrics.checkAvailable(eitherOne = true, …plugins)

Checks if required lyrics plugins are present on the Lavalink node.

• Parameters:
  • eitherOne (boolean, default = true): If true, returns true if at least one plugin is present.
  • ...plugins (string[]): Plugin names to look for. Defaults to ["lavalyrics-plugin", "java-lyrics-plugin", "lyrics"].
• Returns: Promise<boolean>
• Throws: RangeError if plugins are missing.

Example:

const hasLyrics = await Node.lyrics.checkAvailable(true, "lavalyrics-plugin");

.lyrics.get(trackOrEncodedTrackStr, skipTrackSource = false)

Fetches lyrics for a given track or encoded track string.

• Parameters:
  • trackOrEncodedTrackStr (Track | string): The track object or encoded track string.
  • skipTrackSource (boolean, default = false): Whether to skip the track source and fetch from the highest priority source (as configured on the Lavalink server).
• Returns: Promise<Object | null> — the lyrics data, null if plugin unavailable or no lyrics found.
• Throws: TypeError if argument is not Track or string.

Example:

const lyrics = await Node.lyrics.get(track, false);

.lyrics.getCurrentTrack(guildId, skipTrackSource = false, plugin)

Fetches lyrics for the currently playing track for a specific player.

• Parameters:
  • guildId (string): The Guild Id of the player.
  • skipTrackSource (boolean, default = false): skip the actual track source & fetch from the highest priority source (Lavalink server configuration).
  • plugin (string, optional): The plugin to use. Only required if there are multiple known plugins. Defaults to one available.
• Returns: Promise<Object | null> — lyrics data or null if not found.

Example:

const lyrics = await Node.lyrics.getCurrentTrack("123456789012345678", false);

• Plugin Examples: "lavalyrics-plugin", "java-lyrics-plugin", "lyrics"

Methods

.connect()

Initiates connection to the Lavalink node (audio server). Handles WebSocket URLs, authorization, and version checks. Returns: Promise<void>

.error(event)

Handles error events, emits debug/error and optionally initiates player migration.

.message(msg)

Handles incoming messages from the node. Dispatches payloads to the relevant players.

.close(event, reason)

Handles node closure and emits disconnect and debug events. Optionally, can trigger automatic player migration. Returns: Promise<void>

.reconnect()

Attempts to reconnect to the node after a disconnection or error.

.destroy(clean=false)

Destroys the node connection. If clean is true, removes all listeners and only cleans up this node; if false, disconnects all associated players before destruction.

.disconnect()

Disconnects but does not fully destroy; optionally tries to move associated players to a different (best) node.

.penalties (getter)

Calculates penalty score based on active players, CPU/system load, frame stats, etc. Used for intelligent load balancing.

.fetchInfo(options)

Fetches Lavalink Node’s version and information. Throws if not supported. Returns: Promise<NodeInfo>

Node Migration

Nodes support migration to ensure seamless playback and high availability:

• Automatic Migration:

  • If a node experiences an error or disconnect (see .error(event) / .close(event, reason)), and configuration such as riffy.options.migrateOnDisconnect or riffy.options.migrateOnFailure is enabled, the node will attempt to auto-migrate all associated players to another available/best node.
  • This process internally uses Player’s .moveTo(newNode) method—see the Player migration docs for method details.

• Relevant Events:

  • Emits nodeDisconnect, nodeError, and nodeDestroy during/after migration attempts.
  • Emits nodeMigrated when players are successfully moved to a new node.
    • TypeScript type:

      // nodeMigrated(newNode: Node, migratedPlayers: Player[]);
      type nodeMigrated = (newNode: Node, migratedPlayers: Player[]) => void;
      • newNode: The Node instance that players have been migrated to.
      • migratedPlayers: Array of Player instances that were migrated.
  • Emits nodeMigrationFailed if player migration fails due to an error or lack of available nodes.
    • TypeScript type:

      // nodeMigrationFailed(oldNode: Node, error: Error, affectedPlayers: Player[]);
      type nodeMigrationFailed = (oldNode: Node, error: Error, affectedPlayers: Player[]) => void;
      • oldNode: The Node migration was attempted from.
      • error: The Error instance representing the migration failure.
      • affectedPlayers: Array of Player instances that failed to migrate.
  • Players are rerouted to the new node or destroyed if migration fails and no spare nodes are available.

• Configuration:

  • migrateOnDisconnect: If true, triggers auto-migration on disconnect.
  • migrateOnFailure: If true, triggers auto-migration on node errors.

Migration Pseudocode Example:

// Inside node error/close handler
if (riffy.options.migrateOnDisconnect) {
  await riffy.migrate(failedNode);
  // Players re-join on new node, playback resumes with minimal disruption
}