Queue¶

Queue is a thread-safe audio queue with built-in history tracking, loop modes, shuffle, and async waiting. Each Player has two queues: player.queue (main) and player.auto_queue (AutoPlay recommendations).

Guide

See the Queue Guide for usage patterns, loop modes, and history examples.

Queue ¶

Queue(*, history: bool = True)

The default custom revvlink Queue designed specifically for :class:revvlink.Player.

ℹNote

Player implements this queue by default. You can access it via revvlink.Player.queue.

Supported operations

str(queue)A string representation of this queue.

repr(queue)The official string representation of this queue.

if queueBool check whether this queue has items or not.

queue(track)Put a track in the queue.

len(queue)The amount of tracks in the queue.

queue[1]Peek at an item in the queue. Does not change the queue.

for item in queueIterate over the queue.

if item in queueCheck whether a specific track is in the queue.

queue[1] = trackSet a track in the queue at a specific index.

del queue[1]Delete a track from the queue at a specific index.

reversed(queue)Return a reversed iterator of the queue.

Attributes:

Name	Type	Description
`history`	:class:`revvlink.Queue`	A queue of tracks that have been added to history. Tracks are added to history when they are played.

mode `property` `writable` ¶

mode: QueueMode

The current :class:~revvlink.QueueMode of the queue.

This property can be set with any :class:~revvlink.QueueMode.

Returns:

Type	Description
class:`~revvlink.QueueMode`	The current queue mode.

history `property` ¶

history: Queue | None

The history queue containing previously played tracks.

Returns:

Type	Description
class:`Queue` \| None	The history queue, or `None` if history is disabled.

count `property` ¶

count: int

The queue member count.

Returns:

Type	Description
`int`	The amount of tracks in the queue.

is_empty `property` ¶

is_empty: bool

Whether the queue has no members.

Returns:

Type	Description
`bool`	Whether the queue is empty.

loaded `property` `writable` ¶

loaded: Playable | None

The currently loaded track that will repeat when the queue is set to :attr:revvlink.QueueMode.loop.

This track will be retrieved when using :meth:revvlink.Queue.get if the queue is in loop mode. You can unload the track by setting this property to None or by using :meth:revvlink.Player.skip with force=True.

Setting this property to a new :class:revvlink.Playable will replace the currently loaded track, but will not add it to the queue; or history until the track is played.

Returns:

Type	Description
class:`revvlink.Playable` \| None	The currently loaded track or `None` if there is no track ready to repeat.

Raises:

Type	Description
`TypeError`	The track was not a :class:`revvlink.Playable` or `None`.

get ¶

get() -> Playable

Retrieve a track from the left side of the queue. E.g. the first.

This method does not block.

⚠Warning

Due to the way the queue loop works, this method will return the same track if the queue is in loop mode. You can use revvlink.Player.skip with force=True to skip the current track.

Do NOT use this method to remove tracks from the queue, use either:

del queue[index]
revvlink.Queue.remove
revvlink.Queue.delete

Returns:

Type	Description
class:`revvlink.Playable`	The track retrieved from the queue.

Raises:

Type	Description
`QueueEmpty`	The queue was empty when retrieving a track.

get_at ¶

get_at(index: int) -> Playable

Retrieve a track from the queue at a given index.

⚠Warning

Due to the way the queue loop works, this method will load the retrieved track for looping.

Do NOT use this method to remove tracks from the queue, use either:

del queue[index]
revvlink.Queue.remove
revvlink.Queue.delete

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the track to get.	required

Returns:

Type	Description
class:`revvlink.Playable`	The track retrieved from the queue.

Raises:

Type	Description
`QueueEmpty`	The queue was empty when retrieving a track.
`IndexError`	The index was out of range for the current queue.

put_at ¶

put_at(index: int, value: Playable) -> None

Put a track into the queue at a given index.

ℹNote

This method doesn't replace the track at the index but rather inserts one there, similar to a list.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index to put the track at.	required
`value`	`Playable`	The track to put.	required

Raises:

Type	Description
`TypeError`	The track was not a :class:`revvlink.Playable`.

get_wait `async` ¶

get_wait() -> Playable

This method returns the first :class:revvlink.Playable if one is present or waits indefinitely until one is.

This method is asynchronous.

Returns:

Type	Description
class:`revvlink.Playable`	The track retrieved from the queue.

put ¶

put(
    item: list[Playable] | Playable | Playlist,
    /,
    *,
    atomic: bool = True,
) -> int

Put an item into the end of the queue.

Accepts a :class:revvlink.Playable, :class:revvlink.Playlist or list[:class:revvlink.Playable].

Parameters:

Name	Type	Description	Default
`item`	`list[Playable] \| Playable \| Playlist`	list[:class:`revvlink.Playable`] The item to enter into the queue.	required
`atomic`	`bool`	Whether the items should be inserted atomically. If set to `True` this method won't enter any tracks if it encounters an error. Defaults to `True`.	`True`

Returns:

Type	Description
`int`	The number of tracks added to the queue.

put_wait `async` ¶

put_wait(
    item: list[Playable] | Playable | Playlist,
    /,
    *,
    atomic: bool = True,
) -> int

Put an item or items into the end of the queue asynchronously.

Accepts a :class:revvlink.Playable or :class:revvlink.Playlist or list[:class:revvlink.Playable].

ℹNote

This method implements a lock to preserve insert order.

Parameters:

Name	Type	Description	Default
`item`	`list[Playable] \| Playable \| Playlist`	list[:class:`revvlink.Playable`] The item or items to enter into the queue.	required
`atomic`	`bool`	Whether the items should be inserted atomically. If set to `True` this method won't enter any tracks if it encounters an error. Defaults to `True`.	`True`

Returns:

Type	Description
`int`	The number of tracks added to the queue.

delete ¶

delete(index: int) -> None

Method to delete an item in the queue by index.

Raises:

Type	Description
`IndexError`	No track exists at this index.

Examples:

python3

# Deletes the track at index 1 (The second track).
queue.delete(1)

peek ¶

peek(index: int = 0) -> Playable

Method to peek at an item in the queue by index.

ℹNote

This does not change the queue or remove the item.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index to peek at. Defaults to `0` which is the next item in the queue.	`0`

Returns:

Type	Description
class:`revvlink.Playable`	The track at the given index.

Raises:

Type	Description
`QueueEmpty`	There are no items currently in this queue.
`IndexError`	No track exists at the given index.

swap ¶

swap(first: int, second: int) -> None

Swap two items in the queue by index.

Parameters:

Name	Type	Description	Default
`first`	`int`	The first index to swap with.	required
`second`	`int`	The second index to swap with.	required

Returns:

Type	Description
`None`

Raises:

Type	Description
`IndexError`	No track exists at the given index.

Example

python3

# Swap the first and second tracks in the queue.
queue.swap(0, 1)

index ¶

index(item: Playable) -> int

Return the index of the first occurence of a :class:revvlink.Playable in the queue.

Parameters:

Name	Type	Description	Default
`item`	`Playable`	The item to search the index for.	required

Returns:

Type	Description
`int`	The index of the item in the queue.

Raises:

Type	Description
`ValueError`	The item was not found in the queue.

shuffle ¶

shuffle() -> None

Randomly shuffle all tracks currently in the queue.

This method shuffles the queue in place.

Example

python3

player.queue.shuffle()

clear ¶

clear() -> None

Remove all tracks from the queue.

ℹNote

This does not clear the history queue. To clear history, use queue.history.clear().

Example

python3

player.queue.clear()

copy ¶

copy() -> Queue

Create a shallow copy of this queue.

Returns:

Type	Description
class:`Queue`	The copied queue.

reset ¶

reset() -> None

Reset the queue and history to their default states.

This clears all tracks, history, and cancels any pending waiters.

ℹNote

This will cancel any waiting futures on the queue. E.g. revvlink.Queue.get_wait.

remove ¶

remove(item: Playable, /, count: int | None = 1) -> int

Remove a specific track from the queue up to a given count or all instances.

ℹNote

This method starts from the left hand side of the queue E.g. the beginning.

⚠Warning

Setting count to <= 0 is equivalent to setting it to 1.

Parameters:

Name	Type	Description	Default
`item`	`Playable`	The item to remove from the queue.	required
`count`	`int \| None`	The amount of times to remove the item from the queue. Defaults to `1`. If set to `None` this will remove all instances of the item.	`1`

Returns:

Type	Description
`int`	The amount of times the item was removed from the queue.

Raises:

Type	Description
`ValueError`	The item was not found in the queue.

Queue¶

Queue ¶

mode property writable ¶

history property ¶

count property ¶

is_empty property ¶

loaded property writable ¶

get ¶

get_at ¶

put_at ¶

get_wait async ¶

put ¶

put_wait async ¶

delete ¶

peek ¶

swap ¶

index ¶

shuffle ¶

clear ¶

copy ¶

reset ¶

remove ¶

mode `property` `writable` ¶

history `property` ¶

count `property` ¶

is_empty `property` ¶

loaded `property` `writable` ¶

get_wait `async` ¶

put_wait `async` ¶