Skip to main content
The GuildQueue class represents a music queue for a specific guild. It manages tracks, playback, voice connections, and audio processing.

​
Getting a Queue

import { useQueue } from 'discord-player';

const queue = useQueue(guild.id);
// or
const queue = player.nodes.get(guild.id);

​
Properties

​
id
string
The unique identifier of this queue (Snowflake)
​
guild
Guild
The guild this queue belongs to
​
player
Player
The player instance
​
tracks
Queue<Track>
The track queue
​
history
GuildQueueHistory
The queue history manager
​
connection
VoiceConnection | null
The voice connection
​
channel
VoiceBasedChannel | null
The voice channel
​
dispatcher
StreamDispatcher | null
The audio stream dispatcher
​
filters
GuildQueueAudioFilters
Audio filters manager
​
node
GuildQueuePlayerNode
The player node (playback control)
​
metadata
T
Custom metadata attached to this queue
​
repeatMode
QueueRepeatMode
Current repeat mode (OFF, TRACK, QUEUE, AUTOPLAY)
​
isPlaying
boolean
Whether audio is currently playing
​
isEmpty
boolean
Whether the queue is empty
​
currentTrack
Track | null
The currently playing track
​
size
number
Number of tracks in the queue

​
Playback Control Methods

​
play()

Start playing a track: 
await queue.play(track);
​
track
Track | null
required
The track to play, or null to play next in queue
​
options
PlayOptions
Play options (seek, immediate, filtersUpdate, encoderArgs)

​
pause()

Pause playback: 
queue.node.pause();
​
returns
boolean
True if paused successfully

​
resume()

Resume playback: 
queue.node.resume();
​
returns
boolean
True if resumed successfully

​
skip()

Skip the current track: 
const skipped = await queue.node.skip();
​
returns
Promise<boolean>
True if skipped successfully

​
stop()

Stop playback and clear queue: 
queue.node.stop();

​
seek()

Seek to a position: 
await queue.node.seek(60000); // Seek to 1 minute
​
position
number
required
Position in milliseconds
​
returns
Promise<boolean>
True if seek was successful

​
Track Management Methods

​
addTrack()

Add a track to the queue: 
queue.addTrack(track);
​
track
Track | Track[]
required
Track or array of tracks to add

​
insertTrack()

Insert a track at a specific position: 
queue.insertTrack(track, 0); // Insert at front
​
track
Track | Track[]
required
Track or array of tracks to insert
​
index
number
default:"0"
Position to insert at

​
removeTrack()

Remove a track: 
const removed = queue.removeTrack(2); // Remove track at index 2
// or
const removed = queue.removeTrack(track); // Remove specific track
​
track
TrackResolvable
required
Track, track ID, or index
​
returns
Track | null
The removed track

​
clear()

Clear all tracks from queue: 
queue.tracks.clear();

​
shuffle()

Shuffle the queue: 
queue.tracks.shuffle();
​
returns
Track[]
The shuffled tracks

​
Queue State Methods

​
setRepeatMode()

Set repeat mode: 
import { QueueRepeatMode } from 'discord-player';

queue.setRepeatMode(QueueRepeatMode.TRACK);
​
mode
QueueRepeatMode
required
The repeat mode: OFF (0), TRACK (1), QUEUE (2), AUTOPLAY (3)

​
setVolume()

Set playback volume: 
queue.node.setVolume(50); // 50%
​
volume
number
required
Volume level (0-200)
​
returns
boolean
True if volume was set

​
enableDynamicShuffle()

Enable dynamic shuffle mode: 
queue.enableDynamicShuffle();

​
disableDynamicShuffle()

Disable dynamic shuffle mode: 
queue.disableDynamicShuffle();

​
Voice Connection Methods

​
connect()

Connect to a voice channel: 
await queue.connect(voiceChannel);
​
channel
GuildVoiceChannelResolvable
required
The voice channel to connect to
​
returns
Promise<GuildQueue>
The queue instance

​
disconnect()

Disconnect from voice channel: 
queue.disconnect();

​
delete()

Delete this queue: 
queue.delete();

​
Utility Methods

​
getTimestamp()

Get current playback timestamp: 
const timestamp = queue.node.getTimestamp();
console.log(`${timestamp.current.label} / ${timestamp.total.label}`);
​
returns
TrackTimestamp
Object with current and total time info

​
createProgressBar()

Create a progress bar: 
const bar = queue.node.createProgressBar();
console.log(bar); // ▬▬▬▬▬▬▬🔘▬▬▬▬▬▬▬▬▬▬
​
options
ProgressBarOptions
Progress bar customization options
​
returns
string
The formatted progress bar

​
isEmpty()

Check if queue is empty: 
if (queue.isEmpty()) {
  console.log('Queue is empty');
}
​
returns
boolean
True if queue has no tracks

​
tasksQueue

Access the async task queue: 
await queue.tasksQueue.acquire();
try {
  // Critical section
} finally {
  queue.tasksQueue.release();
}

​
Example

Complete queue management example: 
import { useQueue } from 'discord-player';

// Get the queue
const queue = useQueue(interaction.guildId);

if (!queue) {
  return interaction.reply('No music is being played!');
}

// Current track info
const track = queue.currentTrack;
console.log(`Now playing: ${track.cleanTitle}`);
console.log(`Duration: ${track.duration}`);

// Playback control
queue.node.pause();
queue.node.resume();
await queue.node.skip();
await queue.node.seek(30000);
queue.node.setVolume(75);

// Queue management
queue.addTrack(newTrack);
queue.insertTrack(track, 0);
queue.removeTrack(2);
queue.tracks.shuffle();
queue.tracks.clear();

// Repeat modes
queue.setRepeatMode(QueueRepeatMode.QUEUE);

// History
const prev = queue.history.previousTrack;
await queue.history.back();

// Filters
await queue.filters.ffmpeg.toggle('bassboost');
queue.filters.equalizer.setEQ([
  { band: 0, gain: 0.25 },
  { band: 1, gain: 0.25 }
]);

// Connection
const timestamp = queue.node.getTimestamp();
const bar = queue.node.createProgressBar();

console.log(`${timestamp.current.label} ${bar} ${timestamp.total.label}`);

Build docs developers (and LLMs) love

Get started for freeTalk to us