Queues

A GuildQueue belongs to one guild and decides which track plays next. Remedia plays the audio. The queue keeps the current track, the upcoming tracks, and the history.

Create or get a queueCopy Anchor Link

import { QueueRepeatMode } from 'discord-player';

const queue = await player.createQueue(guildId, {
  maxSize: 100,
  maxHistorySize: 50,
  repeatMode: QueueRepeatMode.OFF,
  metadata: { textChannelId },
});

const existing = player.getQueue(guildId); // null when there is no queue

Options apply only when the queue is created. player.play() creates a queue for you, so you usually only call getQueue().

maxSize limits upcoming tracks. The current track does not count toward it.

Add and play tracksCopy Anchor Link

The usual route is player.play(), which searches, queues, and starts playback:

const { queue, track } = await player.play({ guildId, channelId }, query);

If you already have Track objects, use the queue directly:

await queue.play(track, { channelId }); // Queue it and start if idle
queue.addTrack(track); // Upcoming only
queue.addTracks(moreTracks);

channelId can be left out when the queue is already connected.

Read queue stateCopy Anchor Link

Repeat modesCopy Anchor Link

import { QueueRepeatMode } from 'discord-player';

queue.repeatMode = QueueRepeatMode.TRACK;

AutoplayCopy Anchor Link

With AUTOPLAY, the queue calls the source's track.related operation after the last track finishes. If the source returns nothing, playback ends.

To pick the related track yourself, listen for willAutoPlay and call done with the track, or null to stop:

player.events.on('willAutoPlay', (queue, tracks, done) => {
  done(tracks[0] ?? null);
});

Without a listener, the queue prefers a track that has not played yet. Skipping, stopping, or changing the queue cancels a pending selection.

ShuffleCopy Anchor Link

queue.enableShuffle(); // Picks the next track at random each time
queue.disableShuffle();
queue.toggleShuffle();

Shuffle picks the next upcoming track at random. It does not reorder the queue and does not change history. Turning it off does not restore an earlier order.

Change the orderCopy Anchor Link

All of these work on upcoming tracks only:

A track can be a Track, a track ID, or an index.

Delete a queueCopy Anchor Link

await queue.destroy(); // or player.deleteQueue(guildId)

This stops playback, leaves voice, and clears the queue. A later player.play() creates a new queue.