The Queue class manages a player's track queue, allowing you to add, remove, and manipulate tracks. The queue is persistent and synchronized with the internal database.
Queue is an essential component for managing multiple tracks in a music bot. It provides methods for adding, removing, and manipulating track order, with automatic persistence.
Properties
| Property | Type | Description | Default |
|---|---|---|---|
database | Database | Database instance for persistence | Required |
guildId | string | Guild ID associated with the queue | Required |
player | Player | The player instance this queue belongs to | Required |
tracks | Track[] | Array containing all tracks in queue | [] |
size | number | Number of tracks in queue | 0 |
duration | number | Total duration of all tracks in the queue (milliseconds) | 0 |
isEmpty | boolean | Whether the queue is empty | true |
first | Track | The first track in the queue | null |
last | Track | The last track in the queue | null |
all | Track[] | All tracks currently in the queue | [] |
position | number | The current position of the playing track in the queue (0-based index) | 0 |
previous | Track[] | All tracks before the current playing track in the queue | [] |
Methods
add
Add Track
Adds a track or an array of tracks to the queue and persists it in the database. Filters out blacklisted tracks. Emits queueAdd event.
Parameters
Returns & Example
Returns
• boolean — Whether the track was added successfully
queue.add(track);
get
Get Track
Gets a track at a specific position in the queue.
Parameters
Returns & Example
Returns
• Track — The track at the specified position
const track = queue.get(0); // Get first track
has
Has Track
Checks if a specific track is in the queue.
Parameters
Returns & Example
Returns
• boolean — Whether the track exists in queue
if (queue.has(track)) {
console.log('Track is in queue');
}
remove
Remove Track
Removes a track at a specific position and updates the database. Emits queueRemove event.
Parameters
Returns & Example
Returns
• boolean — Whether the track was removed successfully
queue.remove(0); // Remove first track
shift
Shift Track
Removes and returns the first track in the queue. Emits queueRemove event.
Returns & Example
Returns
• Track — The first track in queue
const nextTrack = queue.shift();
unshift
Unshift Track
Adds a track to the beginning of the queue. Emits queueAdd event.
Parameters
Returns & Example
Returns
• boolean — Whether the track was added successfully
queue.unshift(track);
pop
Pop Track
Removes and returns the last track in the queue. Emits queueRemove event.
Returns & Example
Returns
• Track — The last track in queue
const lastTrack = queue.pop();
clear
Clear Queue
Clears all tracks from the queue and removes from database. Emits queueRemove event.
Returns & Example
Returns
• boolean — Whether the queue was cleared successfully
queue.clear();
shuffle
Shuffle Queue
Randomly shuffles tracks in the queue using Math.random().
Returns & Example
Returns
• boolean — Whether the queue was shuffled successfully
queue.shuffle();
removeDuplicates
Remove Duplicates
Removes duplicate tracks from the queue based on their encoded string. Returns true if duplicates were removed, false otherwise.
Returns & Example
Returns
• boolean — Whether duplicates were removed.
const removed = queue.removeDuplicates();
if (removed) {
console.log('Duplicates removed from queue.');
}
removeBlacklistedTracks
Remove Blacklisted Tracks
Removes tracks from the queue whose source is in the manager's blacklistedSources list. Emits trackBlacklisted event for each removed track.
Returns & Example
Returns
• boolean — true if any blacklisted tracks were removed, false otherwise.
const removed = queue.removeBlacklistedTracks();
if (removed) {
console.log('Blacklisted tracks removed from queue.');
}
sortByTitle
Sort by Title
Sorts the queue alphabetically by track title.
Returns & Example
Returns
• boolean — true if the queue was sorted, false if there were fewer than 2 tracks.
queue.sortByTitle();
sortByAuthor
Sort by Author
Sorts the queue alphabetically by track author.
Returns & Example
Returns
• boolean — true if the queue was sorted, false if there were fewer than 2 tracks.
queue.sortByAuthor();
sortByDuration
Sort by Duration
Sorts the queue by track duration in ascending order.
Returns & Example
Returns
• boolean — true if the queue was sorted, false if there were fewer than 2 tracks.
queue.sortByDuration();
find
Find Track
Finds a track in the queue by its identifier or by a partial match in its title.
Parameters
Returns & Example
Returns
• Track | undefined — The found track or undefined if not found.
const foundTrack = queue.find('my-track-id');
if (!foundTrack) {
const anotherTrack = queue.find('song title');
}
move
Move Track
Moves a track from one position to another within the queue.
Parameters
Returns & Example
Returns
• boolean — true if the track was moved successfully, false otherwise.
queue.move(0, 2); // Moves the first track to the third position
moveRange
Move Range
Moves a contiguous range of tracks from one position to another within the queue. Emits queueMoveRange event.
Parameters
Returns & Example
Returns
• boolean — true if the tracks were moved successfully, false otherwise.
// Move 2 tracks starting from index 0 to index 3
queue.moveRange(0, 3, 2);
removeRange
Remove Range
Removes a range of tracks from the queue. Emits queueRemoveRange event.
Parameters
Returns & Example
Returns
• boolean — true if the tracks were removed successfully, false otherwise.
// Remove tracks from index 1 to 3 (inclusive)
queue.removeRange(1, 3);
duplicate
Duplicate Track
Duplicates a track in the queue a specified number of times. The duplicated tracks are inserted immediately after the original track. Emits queueDuplicate event.
Parameters
1Returns & Example
Returns
• boolean — true if the track was duplicated successfully, false otherwise.
// Duplicate the first track once
queue.duplicate(0);
// Duplicate the second track 3 times
queue.duplicate(1, 3);
jump
Jump to Track
Removes all tracks before the specified index, effectively making the track at the given index the new first track in the queue.
Parameters
Returns & Example
Returns
• boolean — true if the jump was successful, false otherwise.
// Make the track at index 5 the new first track
queue.jump(5);
slice
Slice Queue
Returns a shallow copy of a portion of the queue into a new array object selected from start to end (end not included).
Parameters
slice extracts up to (but not including) end. Returns & Example
Returns
• Track[] — A new array containing the extracted elements.
const firstTwoTracks = queue.slice(0, 2);
filter
Filter Queue
Creates a new array with all elements that pass the test implemented by the provided function.
Parameters
true to keep the element, false otherwise. Returns & Example
Returns
• Track[] — A new array with the elements that pass the test.
const longTracks = queue.filter(track => track.duration > 300000); // Tracks longer than 5 minutes
reverse
Reverse Queue
Reverses the order of the elements in the queue in place.
Returns & Example
Returns
• boolean — true if the queue was reversed successfully, false otherwise.
queue.reverse();