Video Streaming Server

This module implements the video stream that streams the music videos. This module provides a thread that takes the videos from a musicdb.mdbapi.videoqueue.VideoQueue to stream them.

So this module consist of the following parts:

Video Streaming Interface

This module maintains a global state! All functions work on the settings in the MusicDBConfig configuration object and the internal state of this module.

There are two functions and one class that are available to manage the Stream:

from mdbapi.videostream import StartVideoStreamingThread, StopVideoStreamingThread, VideoStreamManager

Video Streaming Thread

The Streaming Thread mainly manages updating the queue based on played videos by the stream player (WebUI). This thread is the point where the music managed by MusicDB gets handed over to the users web browser so that the user can watch the video stream.

The VideoStreamManager communicates with the VideoStreamingThread() with a Video Stream Command Queue.

The thread maintains a global dictionary that holds the state of the thread - The Stream State. It can be accessed via musicdb.mdbapi.videostream.VideoStreamManager.GetStreamState(). This will only be updated by the VideoStreamingThread. It contains the following information:

More details are in the VideoStreamingThread() description.

Video Stream Command Queue

The Command Queue is a FIFO buffer of tuple. Each tuple has a command name and an optional argument. For the whole Module, there is only one global Command Queue.

Each instance of the VideoStreamManager class writes into the same queue following the First Come First Serve (FCFS) protocol. The VideoStreamingThread() reads the command from that queue and processes them.

More details are in the VideoStreamingThread() description.

Video Stream Event Management

This module provided a callback interface to react on events triggered by Streaming Thread or by actions done by the VideoStreamManager class.

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

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:

StatusChanged:

Gets triggered when the status of the streaming thread changes. Internal states are excluded.

StreamNextVideo:

Informs the stream player to play the next video in the queue. The video to play is provided by the event as well.

More details are in the VideoStreamingThread() description.

Example

This example shows how to use the callback interface:

def callback(name, arg):
    print("Event "%s" occurred with argument "%s"." % (name, str(arg)))

videostream = VideoStreamManager(mdbconfig, musicdatabase)
videostream.RegisterCallback(callback)

# …

videostream.RemoveCallback(callback)
musicdb.mdbapi.videostream.StartVideoStreamingThread(config, musicdb)[source]

This function starts the Streaming Thread VideoStreamingThread(). You should use this function instead of calling the Streaming Thread function directly.

By calling this function, the global state of this module gets reset. This included removing all commands from the Command Queue.

Parameters
Returns

True on Success, otherwise False

Raises

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

musicdb.mdbapi.videostream.StopVideoStreamingThread()[source]

This function stops the Streaming Thread. The function is blocking and waits until the thread is closed.

Returns

True on success, otherwise False

musicdb.mdbapi.videostream.VideoStreamingThread()[source]

This thread manages the streaming of the videos from the Video Queue.

The thread tracks the played video using the Song Tracker module. It does not track randomly added videos. Only completely played videos will be considered. Skipped videos will be ignored. It also maintains the lastplayed statistic.

The thread triggers the following events:

  • StatusChanged: When the stream state changed

  • StreamNextVideo: When the player shall stream the next video. MDBVideo, streamstate and queue entry is included as rawdata argument.

States

  • isstreaming: This thread manages the queue and provides new videos when a video is considered being watched.

  • isplaying: Stream is in a state where clients could play the current video. This is an assumption of the clients possible state. This does not represent the true clients state, and it is not meant to be used by the clients in any way.

  • currententry: The queue entry ID of the current playing video.

Commands:

  • VideoEnded: When a client send the VideoEnded information to the server (VideoEnded() this thread manages the call. In case the provided entry ID is the same as the currententy ID the next video gets popped from the video queue. Otherwise the command gets ignored.

  • PlayNextVideo: Skip the current video and start playing the next.

  • SetStreamState: Sets the stream state to streaming or not streaming.

When streaming gets deactivated, or activated, it also generates an event (StatusChanged). It is expected that all clients stop playing the current video if isstreaming is set to Flase. In case it is set to True, all clients that were used to play the videos continue playing the current video.

Video Stream Manager Class

class musicdb.mdbapi.videostream.VideoStreamManager(config, database)[source]

This class provides an interface to the Streaming Thread (VideoStreamingThread()) and the Video Queue that will be streamed.

The communication is implemented with a command queue. More details about those commands can be found in the VideoStreamingThread() description. Anyway, the details of the command queue are not important to know. They get hide by this class. Only important thing to know is, that when multiple instances of this class are used, the actions follow the First Come First Server protocol.

Note

Important for developer:

Never call the musicdb.mdbapi.videoqueue.VideoQueue.NextVideo() method directly from this class! Send the "PlayNextVideo" command to the VideoStreamingThread() instead. The thread handles the skip to the next video and starts streaming the new file.

Parameters
Raises

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

GetStreamState()[source]

This method returns the current state of the Streaming Thread as a dictionary.

Returns

A copy of the Stream state. See the top of the documentation for details of the Stream State.

Play(play=True)[source]

Set the play-state.

  • If play is True (default value), the Streaming Thread streams data.

  • If play is False, the audio stream gets paused.

This function is forcing the state. It does not care about the current playing state.

When the command got successful executed, the VideoStreamingThread() will trigger the StatusChanged event.

Parameters

play (bool) – Playstate the Streaming Thread shall get

Returns

True on success. When play is not a Boolean, False gets returned.

PlayNextVideo()[source]

This function triggers the Streaming Thread to play the next video in the queue.

Returns

True on success, otherwise False

PushCommand(command, argument=None)[source]

Class internal interface to the Video Stream Command Queue used to communicate with the VideoStreamingThread(). You should not access the queue directly, because the Streaming Thread expects valid data inside the queue. This is guaranteed by the methods that use this method.

Parameters

  • command (str) – A command to the Streaming Thread. Valid commands are listed in the VideoStreamingThread() section of the documentation.

  • argument – An argument to the command.

Returns

True on success, False when the Streaming Thread is not running.

RegisterCallback(function)[source]

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

VideoEnded(queueentryid)[source]

This method informs the Streaming Thread the video was completely streams. It sets the lastplayed statistics of the video and triggers the Streaming Thread to play the next video in the queue.

This method can be called multiple times for the same queue entry.

Parameters

queueentryid (int) – The ID of the queue entry that got finished streaming

Returns

True on success, otherwise False