MusicDB Song Queue¶

This module implements the Song Queue. The song queue consists of a global FIFO organized list.

Song Queue Management¶

An entry in this queue is a dictionary having the following keys:

entryid:
An entry ID that is unique for all entries at any time. This UUID is a 128 bit integer.

songid:
A song ID as maintained by the MusicDatabase class.

israndom:
A boolean value that is set to True when the song was added by Randomizer.

Some features of this queue are:

The entry ID is a Version 4 Universally Unique Identifier (UUID) .

The current playing song is at index 0.

The songs remain in the queue until they got completely streamed.

This class is thread safe. So each method of the same instance can be called from different threads.

The queue is persistent. After restarting MusicDB, the queue is not lost.

Furthermore this module cooperates the Randy module (see: Randomizer) When the queue runs empty, a new random song gets append to the queue.

Song Queue Event Management¶

This module provided a callback interface to react on events triggered on changes in the Song Queue.

The following two functions can be used to register or remove a callback function:

RegisterCallback()

RemoveCallback()

Functions that get called must provide two parameters. The first is a string that provides the name of the event as described below. The second parameter contains an event specific argument, or None.

A return value gets not handled.

The following events exist:

SongQueueChanged:
Gets triggered when the Song Queue changes

SongChanged:
When the current playing song changes.

Examples

The following example shows how the NextSong() method works:

queue = SongQueue(mdbconfig, musicdatabase)
queue.AddSong(7357)         # 7357 is a song ID
queue.AddSong(1337)
queue.AddSong(2342)

print(queue.CurrentSong()["songid"])  # 7357
print(queue.CurrentSong()["songid"])  # 7357
print(queue.NextSong()["songid"])     # 1337
print(queue.CurrentSong()["songid"])  # 1337

queueentry = queue.CurrentSong()
if queueentry["israndom"]:
    print("Entry %d is a randomly added song."%(queueentry["entryid"]))

Song Queue Class¶

class musicdb.mdbapi.songqueue.SongQueue(config, database)[source]¶

This class implements a queue to manage songs to play. Whenever the queue changes, its data gets stored in the MusicDB State Directory

When the constructor detects that there is no queue yet (not even an empty one), it tries to load the stored queue. If this fails, a new empty queue gets created.

Parameters

config – MusicDBConfig object holding the MusicDB Configuration
database – A MusicDatabase instance

Raises

TypeError – When the arguments are not of the correct type.

AddRandomSong(position='last', albumid=None)[source]¶

This method adds a random song into the queue.

The position in the queue, where the song gets insert can be changed by setting the position argument:

"last" (default): Appends the song at the end of the queue

"next": Inserts the song right after the current playing song.

When there is an album ID, the randoms song gets selected from that album using musicdb.mdbapi.randy.Randy.GetSongFromAlbum(). If the album ID is None, the method musicdb.mdbapi.randy.Randy.GetSong() will be used to get a random song from the activated genres.

After selecting the random song, the AddSong() method gets used to insert the new song into the queue. If there is no song found by Randy, then nothing gets added to the queue and False will be returned.

Parameters

position (str) – Defines the position where the song gets inserted.
albumid (int/NoneType) – ID of the album from that the song will be selected, or None for selecting a song from the activated genres.

Returns

True when a random song got added to the queue. Otherwise False.

Raises

TypeError – When one of the types of the arguments are not correct

AddSong(songid, position='last', israndom=False)[source]¶

With this method, a new song can be insert into the queue.

The position in the queue, where the song gets insert can be changed by setting the position argument:

"last" (default): Appends the song at the end of the queue

"next": Inserts the song right after the current playing song.

Integer: Entry-ID after that the song shall be inserted.

On success, this method triggers the SongQueueChanged event.

When the song shall be put at the beginning of the queue, then it gets set to index 1 not index 0. So the current playing song (index 0) remains!

The new song gets added to the blacklist via musicdb.mdbapi.blacklist.BlacklistInterface.AddSong() The method also triggers the SongQueueChanged event.

Parameters

songid (int) – The ID of the song that shall be added to the queue
position (str/int) – Defines the position where the song gets inserted
israndom (bool) – Defines whether the song is randomly selected or not

Returns

The new Queue Entry ID as integer

Raises

TypeError – When songid is not of type int

CurrentSong()[source]¶

This method returns the current song in the queue.

The method returns element 0 from the queue which is the current song that can be streamed or gets already streamed. The song shall remain in the queue until it got completely streamed. Then it can be removed by calling NextSong().

When the queue is empty, a new random song gets added. This is the exact same song that then will be returned by this method. If adding a new song fails, None gets returned. This method triggers the SongQueueChanged event when the queue was empty and a new random song got added.

Returns: A dictionary as described in the module description

Example

queue = SongQueue()

# Queue will be empty after creating a SongQueue object
entry = queue.CurrentSong()
if entry:
    print("Random SongID: %s" % (str(entry["songid"])))
else
    print("Queue is empty! - Adding random song failed!")

# Adds two new song with ID 7357 and 1337.
# Then the current song is the first song added.
queue.AddSong(7357)
queue.AddSong(1337)
entry = queue.CurrentSong()
if entry:
    print("SongID: %s" % (str(entry["songid"]))) # 7357
else
    # will not be reached because we explicitly added songs.
    print("Queue is empty! - Adding random song failed!")

Event_SongChanged()[source]¶: See TriggerEvent() with event name "SongChanged" More details in the module description at the top of this document.

Event_SongQueueChanged()[source]¶

See TriggerEvent() with event name "SongQueueChanged". More details in the module description at the top of this document.

This method also tries to save the queue into the MusicDB State Directory.

GenerateID()[source]¶

This method generate a unique ID. In detail, it is a Version 4 Universally Unique Identifier (UUID) . It will be returned as an integer.

This method is build for the internal use in this class.

Returns: A UUID to be used as entry ID

Example

queue = SongQueue()
uuid  = GenerateID()
print(type(uuid))   # int

GetQueue()[source]¶

This method returns a copy of the song queue.

The queue is a list of dictionaries. The content of the dictionary is described in the description of this module.

Returns: The current song queue. [None] if there is no queue yet.

Example

queue = songqueue.GetQueue()

if not queue:
    print("There are no songs in the queue")
else:
    for entry in queue:
        print("Element with ID %i holds the song with ID %i"
                % (entry["entryid"], entry["songid"]))

GetSong(entryid)[source]¶

Returns the song ID of the entry addressed by the entry ID

Parameters: entryid (int) – ID of the entry that song ID shall be returned
Returns: The song ID of the entry, or None if the entry does not exists
Raises: TypeError – When entryid is not of type int

Load()[source]¶

This method loads the last stored song queue for the MusicDB State Directory via musicdb.lib.cfg.mdbstate.MDBState.LoadSongQueue().

Returns: Nothing

MoveSong(entryid, afterid)[source]¶

This method moves an entry, addressed by entryid behind another entry addressed by afterid. If both IDs are the same, the method returns immediately without doing anything. When entryid addresses the current song, the method returns with value False

On success, the method triggers the SongQueueChanged event.

Parameters

entryid (int) –
afterid (int) –

Returns

True when the entry was moved, otherwise False

Raises

TypeError – When entryid or afterid is not of type int

NextSong()[source]¶

This method returns the next song in the queue. This entry will be the next current song.

The method pops the last current element from the queue. Then the new element at position 0, the new current element, will be returned.

If the queue is empty, None gets returned.

Warning

In context of streaming, this method may not be the one you want to call. This Method drops the current song and sets the next song on top of the queue.

The stream will not notice this, so that it continues streaming the previous song. (See Audio Streaming Server). If you want to stream the next song, call musicdb.mdbapi.audiostream.AudioStreamManager.PlayNextSong().

The musicdb.mdbapi.audiostream.AudioStreamManager.PlayNextSong() then makes the Streaming Thread calling this method.

This method triggers the SongChanged and SongQueueChanged event when the queue was not empty. The SongChanged event gets also triggered when there was no next song.

When there is only one entry left in the queue - the current song - then a new one gets add via AddRandomSong()

Returns: The new current song entry in the queue as dictionary described in the module description

Example

queue = SongQueue()

# Adds two new song with ID 7357 and 1337.
queue.AddSong(7357)
queue.AddSong(1337)

entry = queue.CurrentSong()
print("SongID: %s" % (str(entry["songid"]))) # 7357

entry = queue.NextSong()
print("SongID: %s" % (str(entry["songid"]))) # 1337
entry = queue.CurrentSong()
print("SongID: %s" % (str(entry["songid"]))) # 1337

RegisterCallback(function)[source]¶

Register a callback function that reacts on Song Queue related events. For more details see the module description at the top of this document.

Parameters: function – A function that shall be called on an event.
Returns: Nothing

RemoveCallback(function)[source]¶

Removes a function from the list of callback functions.

Parameters: function – A function that shall be called removed.
Returns: Nothing

RemoveSong(entryid)[source]¶

Removes the entry with the ID entryid from the queue. Removing the current song is not allowed! Call NextSong() instead.

When there is only one entry left in the queue - the current song - then a new one gets add via AddRandomSong()

On success, this method triggers the SongQueueChanged event.

Parameters: entryid (int) – Entry to remove
Returns: True on success, otherwise False
Raises: TypeError – When entryid is not of type int

Save()[source]¶

Save the current queue into a csv file in the MusicDB State Directory. Therefor the musicdb.lib.cfg.mdbstate.MDBState.SaveSongQueue() gets used.

Returns: Nothing

TriggerEvent(name, arg=None)[source]¶

This function triggers an event. It iterates through all registered callback functions and calls them.

The arguments to the functions are the name of the even (name) and addition arguments (arg). That argument will be None if there is no argument.

More details about events can be found in the module description at the top of this document.

Parameters

name (str) – Name of the event
arg – Additional arguments to the event, or None

Returns

Nothing