Skip to main content

​
Overview

The GuildNodeManager class is responsible for creating and managing guild queue instances. It maintains a cache of active queues and provides methods for queue lifecycle management. It is accessible via player.nodes.

​
Constructor

new GuildNodeManager<Meta = any>(player: Player)
​
player
Player
required
The Discord Player instance that owns this node manager

​
Properties

​
player
Player
The Discord Player instance associated with this manager
​
cache
Collection<string, GuildQueue>
Collection of all active guild queues, keyed by guild ID

​
Methods

​
create()

Creates a new guild queue or returns the existing one. 
create<T = Meta>(guild: GuildResolvable, options?: GuildNodeCreateOptions<T>): GuildQueue<T>
​
guild
GuildResolvable
required
The guild to create the queue for (can be Guild object, guild ID, or any Discord.js guild resolvable)
​
options
GuildNodeCreateOptions<T>
Queue configuration options
​
returns
GuildQueue<T>
The created or existing guild queue instance
Example: 
import { GuildQueue } from 'discord-player';

// Create a basic queue
const queue = player.nodes.create(interaction.guild);

// Create a queue with options
const queue = player.nodes.create(interaction.guild, {
  volume: 50,
  leaveOnEnd: false,
  leaveOnEmpty: true,
  leaveOnEmptyCooldown: 60000,
  metadata: {
    channel: interaction.channel,
    requestedBy: interaction.user
  }
});

// Create with custom metadata type
interface QueueMetadata {
  channel: TextChannel;
  requestedBy: User;
  startTime: Date;
}

const queue = player.nodes.create<QueueMetadata>(interaction.guild, {
  metadata: {
    channel: interaction.channel as TextChannel,
    requestedBy: interaction.user,
    startTime: new Date()
  }
});
Throws:
  • NoGuildError if the guild cannot be resolved

​
get()

Gets an existing queue. 
get<T = Meta>(node: NodeResolvable): GuildQueue<T> | null
​
node
NodeResolvable
required
Queue resolvable (GuildQueue instance, Guild object, or guild ID)
​
returns
GuildQueue<T> | null
The guild queue if found, null otherwise
Example: 
// Get by guild ID
const queue = player.nodes.get(interaction.guildId);

// Get by guild object
const queue = player.nodes.get(interaction.guild);

// Get by queue instance
const sameQueue = player.nodes.get(queue);

if (queue) {
  console.log('Queue found with', queue.tracks.size, 'tracks');
} else {
  console.log('No queue exists for this guild');
}

​
has()

Checks if a queue exists. 
has(node: NodeResolvable): boolean
​
node
NodeResolvable
required
Queue resolvable
​
returns
boolean
true if queue exists, false otherwise
Example: 
if (player.nodes.has(interaction.guildId)) {
  await interaction.reply('Queue already exists!');
} else {
  const queue = player.nodes.create(interaction.guild);
  await interaction.reply('Created new queue!');
}

​
delete()

Deletes a queue and cleans up all resources. 
delete(node: NodeResolvable): boolean
​
node
NodeResolvable
required
Queue resolvable
​
returns
boolean
true if queue was deleted, false otherwise
Example: 
const deleted = player.nodes.delete(interaction.guildId);

if (deleted) {
  await interaction.reply('Queue deleted and bot left voice channel');
} else {
  await interaction.reply('No queue to delete');
}
Throws:
  • NoGuildQueueError if trying to delete a non-existing queue
Note: This method performs cleanup operations including:
  • Stopping playback
  • Disconnecting from voice channel
  • Clearing all tracks and history
  • Removing all event listeners
  • Clearing all timeouts

​
resolve()

Resolves a node resolvable to a GuildQueue instance. 
resolve<T = Meta>(node: NodeResolvable): GuildQueue<T> | undefined
​
node
NodeResolvable
required
Queue resolvable
​
returns
GuildQueue<T> | undefined
The resolved guild queue, or undefined if not found
Example: 
const queue = player.nodes.resolve(interaction.guild);

if (queue) {
  console.log('Resolved queue:', queue.id);
}

​
resolveId()

Resolves a node resolvable to a guild ID. 
resolveId(node: NodeResolvable): string | null
​
node
NodeResolvable
required
Queue resolvable
​
returns
string | null
The guild ID, or null if not found
Example: 
const guildId = player.nodes.resolveId(queue);
console.log('Queue belongs to guild:', guildId);

​
Usage Examples

​
Basic Queue Management

import { Player } from 'discord-player';

const player = new Player(client);

// Create a queue when user joins voice
client.on('interactionCreate', async (interaction) => {
  if (!interaction.isCommand()) return;
  
  if (interaction.commandName === 'play') {
    // Get or create queue
    let queue = player.nodes.get(interaction.guildId);
    
    if (!queue) {
      queue = player.nodes.create(interaction.guild, {
        metadata: {
          channel: interaction.channel,
          requestedBy: interaction.user
        }
      });
    }
    
    // Use queue...
  }
});

​
Queue with Custom Configuration

const queue = player.nodes.create(interaction.guild, {
  // Audio settings
  volume: 50,
  equalizer: [
    { band: 0, gain: 0.2 },
    { band: 1, gain: 0.15 }
  ],
  
  // Behavior settings
  leaveOnEnd: false,
  leaveOnEmpty: true,
  leaveOnEmptyCooldown: 300000, // 5 minutes
  pauseOnEmpty: true,
  
  // Queue limits
  maxSize: 100,
  maxHistorySize: 50,
  
  // Features
  disableHistory: false,
  preferBridgedMetadata: true,
  
  // Metadata
  metadata: {
    channel: interaction.channel,
    requestedBy: interaction.user,
    djRole: interaction.guild.roles.cache.find(r => r.name === 'DJ')
  }
});

​
Queue Lifecycle Management

// Create queue
const queue = player.nodes.create(interaction.guild);

// Check if queue exists
if (player.nodes.has(interaction.guildId)) {
  console.log('Queue already exists');
}

// Get queue
const existingQueue = player.nodes.get(interaction.guildId);

// Delete queue when done
player.nodes.delete(interaction.guildId);

​
Iterate All Queues

// Get all active queues
const allQueues = player.nodes.cache;

console.log(`Active queues: ${allQueues.size}`);

allQueues.forEach((queue, guildId) => {
  console.log(`Guild ${queue.guild.name}: ${queue.tracks.size} tracks`);
});

​
Clean Up Inactive Queues

function cleanupInactiveQueues() {
  player.nodes.cache.forEach((queue, guildId) => {
    // Delete queue if no tracks and not playing
    if (queue.tracks.size === 0 && !queue.node.isPlaying()) {
      player.nodes.delete(guildId);
      console.log(`Cleaned up queue for guild ${guildId}`);
    }
  });
}

// Run cleanup every hour
setInterval(cleanupInactiveQueues, 3600000);

​
Typed Metadata

interface MyQueueMetadata {
  channel: TextChannel;
  requestedBy: User;
  djOnly: boolean;
  language: string;
}

const queue = player.nodes.create<MyQueueMetadata>(interaction.guild, {
  metadata: {
    channel: interaction.channel as TextChannel,
    requestedBy: interaction.user,
    djOnly: false,
    language: 'en'
  }
});

// TypeScript knows the metadata type
const channel = queue.metadata?.channel; // TextChannel
const user = queue.metadata?.requestedBy; // User

​
NodeResolvable

type NodeResolvable = GuildQueue | GuildResolvable
Can be:
  • A GuildQueue instance
  • A Guild object
  • A guild ID string
  • Any Discord.js guild resolvable

​
QueueStrategy

type QueueStrategy = 'FIFO' | 'LIFO'
  • FIFO: First In First Out (default) - tracks play in order added
  • LIFO: Last In First Out - most recently added track plays next

​
Notes

  • Queues are automatically cached when created
  • Creating a queue for a guild that already has one returns the existing queue
  • Deleting a queue performs complete cleanup including disconnecting from voice
  • The cache property is a Discord.js Collection for easy iteration
  • Options not specified in create() use sensible defaults
  • Global hooks (onBeforeCreateStream, etc.) are automatically applied if registered
  • Use typed metadata for better TypeScript support

Build docs developers (and LLMs) love

Get started for freeTalk to us