MusicDB video Queue¶

This module implements the Video Queue. The video queue consists of a global FIFO organized list.

Video 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.

videoid:
A video ID as maintained by the MusicDatabase class.

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

Some features of this queue are:

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

The current playing video is at index 0.

The videos 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 video gets append to the queue.

Video Queue Event Management¶

This module provided a callback interface to react on events triggered on changes in the Video 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:

VideoQueueChanged:
Gets triggered when the video queue changes

VideoChanged:
When the current playing video changes.

Examples

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

queue = VideoQueue(mdbconfig, musicdatabase)
queue.AddVideo(7357)         # 7357 is a video ID
queue.AddVideo(1337)
queue.AddVideo(2342)

print(queue.CurrentVideo()["videoid"])  # 7357
print(queue.CurrentVideo()["videoid"])  # 7357
print(queue.NextVideo()["videoid"])     # 1337
print(queue.CurrentVideo()["videoid"])  # 1337

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

Video Queue Class¶

class musicdb.mdbapi.videoqueue.VideoQueue(config, database)[source]¶

This class implements a queue to manage videos 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.

AddRandomVideo(position='last')[source]¶

This method adds a random video into the queue.

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

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

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

The method musicdb.mdbapi.randy.Randy.GetVideo() will be used to get a random video from the activated genres.

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

Parameters

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

Returns

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

Raises

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

AddVideo(videoid, position='last', israndom=False)[source]¶

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

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

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

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

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

On success, this method triggers the VideoQueueChanged event.

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

The new video gets added to the blacklist via musicdb.mdbapi.blacklist.BlacklistInterface.AddVideo() The method also triggers the VideoQueueChanged event.

Parameters

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

Returns

Nothing

Raises

TypeError – When videoid is not of type int

CurrentVideo()[source]¶

This method returns the current video in the queue.

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

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

Returns: A dictionary as described in the module description

Example

queue = VideoQueue()

# Queue will be empty after creating a VideoQueue object
entry = queue.CurrentVideo()
if entry:
    print("Random VideoID: %s" % (str(entry["videoid"])))
else
    print("Queue is empty! - Adding random video failed!")

# Adds two new video with ID 7357 and 1337.
# Then the current video is the first video added.
queue.AddVideo(7357)
queue.AddVideo(1337)
entry = queue.CurrentVideo()
if entry:
    print("VideoID: %s" % (str(entry["videoid"]))) # 7357
else
    # will not be reached because we explicitly added videos.
    print("Queue is empty! - Adding random videofailed!")

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

Event_VideoQueueChanged()[source]¶

See TriggerEvent() with event name "VideoQueueChanged". 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 = VideoQueue()
uuid  = queue.GenerateID()
print(type(uuid))   # int

GetQueue()[source]¶

This method returns a copy of the video queue.

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

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

Example

queue = videoqueue.GetQueue()

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

GetVideo(entryid)[source]¶

Returns the video ID of the entry addressed by the entry ID

Parameters: entryid (int) – ID of the entry that video ID shall be returned
Returns: The video 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 video queue for the MusicDB State Directory via musicdb.lib.cfg.mdbstate.MDBState.LoadVideoQueue().

Returns: Nothing

MoveVideo(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 video, the method returns with value False

On success, the method triggers the VideoQueueChanged 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

NextVideo()[source]¶

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

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 video and sets the next video on top of the queue.

The stream will not notice this, so that it continues streaming the previous video. (See Video Streaming Server). If you want to stream the next video, call musicdb.mdbapi.videostream.VideoStreamManager.PlayNextVideo().

The musicdb.mdbapi.videostream.VideoStreamManager.PlayNextVideo() then makes the Streaming Thread calling this method.

This method triggers the VideoChanged and VideoQueueChanged event when the queue was not empty. The VideoChanged event gets also triggered when there was no next video.

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

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

Example

queue = VideoQueue()

# Adds two new video with ID 7357 and 1337.
queue.AddVideo(7357)
queue.AddVideo(1337)

entry = queue.CurrentVideo()
print("VideoID: %s" % (str(entry["videoid"]))) # 7357

entry = queue.NextVideo()
print("VideoID: %s" % (str(entry["videoid"]))) # 1337
entry = queue.CurrentVideo()
print("VideoID: %s" % (str(entry["videoid"]))) # 1337

RegisterCallback(function)[source]¶

Register a callback function that reacts on Video 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

RemoveVideo(entryid)[source]¶

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

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

On success, this method triggers the VideoQueueChanged 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.SaveVideoQueue() 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