pomice/docs/hdi/queue.md

Use the Queue class

Pomice has an optional queue system that works seamlessly with the library. This queue system introduce quality-of-life features that every music application should ideally have like queue shuffling, queue jumping, and looping.

To use the queue system with Pomice, you must first subclass the Player class within your application like so:

from pomice import Player

class CustomPlayer(Player):
    ...

After you have initialized your subclass, you can add a queue variable to your class so you can access your queue when you initialize your player:

from pomice import Player, Queue

class CustomPlayer(Player):
    ...
    self.queue = Queue() 

Adding a song to the queue

To add a song to the queue, we must use Queue.put()

Queue.put()

After you have initialized your function, we need to include the item parameter, which is a Track:

Queue.put(item=<your Track here>)

After running the function, your track should be in the queue.

Getting a track from the queue

To get a track from the queue, we need to do a few things.

To get a track using its position within the queue, you first need to get the position as a number, also known as its index. If you dont have the index and instead want to search for its index using keywords, you have to implement a fuzzy searching algorithm to find said track using a search query as an input and have it compare that query against the titles of the tracks in the queue. After that, you can get the Track object by getting it with its index

Getting index of track

If you have the Track object and want to get its index within the queue, we can use Queue.find_position()

Queue.find_position()

After you have initialized your function, we need to include the item parameter, which is a Track:

Queue.find_position(item=<your Track here>)

After running the function, it should return the position of the track as an integer.

Getting track with its index

If you have the index of the track and want to get the Track object, you first need to get the raw queue list:

queue = Queue.get_queue()

After you have your queue, you can use basic list splicing to get the track object:

track = queue[<index>]

Getting the next track in the queue

To get the next track in the queue, we need to use Queue.get()

Queue.get()

After running this function, it'll return the first track from the queue and remove it.

:::{note}

If you have a queue loop mode set, this behavior will be overridden since the queue is not allowed to remove tracks from the queue if its looping.

:::

Removing a track from the queue

To remove a track from the queue, we must use Queue.remove()

Queue.remove()

After you have initialized your function, we need to include the item parameter, which is a Track:

Queue.remove(item=<your Track here>)

:::{important}

Your Track object must be in the queue if you want to remove it. Make sure you follow before running this function.

:::

After running this function, your track should be removed from the queue.

Shuffling the queue

To shuffle the queue, we must use Queue.shuffle()

Queue.shuffle()

After running this function, your queue should be in a different order than it was originally.

:::{tip}

This function works best if theres atleast 3 tracks in the queue. The more tracks, the more variation the shuffle has.

:::

Looping the queue

To loop the queue, we must use Queue.set_loop_mode()

Queue.set_loop_mode(...)

After you have initialized your function, we need to include the mode parameter, which is a LoopMode enum:

Queue.set_loop_mode(mode=LoopMode.<mode>)

The two types of LoopMode enums are LoopMode.QUEUE and LoopMode.TRACK. QUEUE loops the entire queue and TRACK loops the current track.

After running the function, your queue will now loop using the mode you specify.

Resetting the loop mode

To reset the loop mode, we must use Queue.disable_loop()

Queue.disable_loop()

:::{important}

You must have a loop mode set before using this function. It will not work if you do not a loop mode set

:::

After running the function, your queue should return to its normal functionality.

Jumping to a track in the queue

To jump to a track in the queue, we must use Queue.jump()

Queue.jump(...)

After you have initialized your function, we need to include the item parameter, which is a Track:

Queue.jump(item=<your Track here>)

:::{important}

Your Track object must be in the queue if you want to jump to it. Make sure you follow before running this function.

:::

After running this function, any items before the specified item will be removed, effectively "jumping" to the specified item in the queue. The next item obtained using Queue.get() will be your specified track.