Audio Streaming Server

This module implements the audio stream that streams the songs. This module provides a thread that takes the songs from a musicdb.mdbapi.songqueue.SongQueue to stream them via Icecast. It manages the connection to the Icecast server using the musicdb.lib.stream.icecast module. Further more this module provides some callback interfaces to inform the rest of MusicDB about the state of the stream.

So this module consist of the following parts:

Audio 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.audiostream import StartAudioStreamingThread, StopAudioStreamingThread, AudioStreamManager

Audio Streaming Thread

The Streaming Thread mainly manages sending mp3-file chunks to the Icecast server. This thread is the point where the music managed by MusicDB gets handed over to Icecast so the user can listen to it.

The AudioStreamManager communicates with the AudioStreamingThread() with a Audio Stream Command Queue.

More details are in the AudioStreamingThread() description.

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

  • isconnected (bool): True when connected to Icecast, otherwise False

  • isplaying (bool): True when streaming, otherwise False

Audio 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 AudioStreamManager class writes into the same queue following the First Come First Serve (FCFS) protocol. The AudioStreamingThread() reads the command from that queue and processes them.

The following commands are available:

Play (AudioStreamManager.Play()):

If state is True the current song from the Song Queue gets streamed to Icecast. If state is False the audio stream gets paused.

PlayNextSong (AudioStreamManager.PlayNextSong()):

Stops streaming the current song, and starts with the next song. If streaming is paused, only the next song gets selected as new current song.

Audio Stream Event Management

This module provided a callback interface to react on events triggered by Streaming Thread or by actions done by the AudioStreamManager 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 connection status to Icecast or the play status changed.

TimeChanged:

The time of the current playing position of a song changed. Argument is the current playtime of the song in seconds.

Example

This example shows how to use the callback interface:

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

audiostream = AudioStreamManager(mdbconfig, musicdatabase)
audiostream.RegisterCallback(callback)

# …

audiostream.RemoveCallback(callback)
musicdb.mdbapi.audiostream.AudioStreamingThread()[source]

This thread manages the streaming of the songs from the Song Queue to the Icecast server.

The thread tracks the played song using the Song Tracker module. Randomly added songs will not be tracked, only songs added by the user. Only completely played songs will be considered. Skipped songs will be ignored.

If disableicecast is set in the debug-options, then the stream management loop gets not entered. Everything will be initialized and prepared as if the audio stream would be used anyway. This threads waits and checks every 1s if the thread should be stopped. It also updates the time played (=0). The stream status will be set correctly (isconnected = False, isplaying = False)

The thread triggers the following events:

  • StatusChanged: When the play-state

  • TimeChanged: To update the current streaming progress of a song

The TimeChanged event gets triggered approximately every second.

musicdb.mdbapi.audiostream.StartAudioStreamingThread(config, musicdb)[source]

This function starts the Streaming Thread AudioStreamingThread(). 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.audiostream.StopAudioStreamingThread()[source]

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

Returns

True on success, otherwise False

Audio Stream Manager Class

class musicdb.mdbapi.audiostream.AudioStreamManager(config, database)[source]

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

The communication is implemented with a command queue. More details about those commands can be found in the AudioStreamingThread() 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.songqueue.SongQueue.NextSong() method directly from this class! Send the "PlayNextSong" command to the AudioStreamingThread() instead. The thread handles the skip to the next song 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 audio file data to Icecast.

  • 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 AudioStreamingThread() 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.

PlayNextSong()[source]

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

Returns

True on success, otherwise False

PushCommand(command, argument=None)[source]

Class internal interface to the Audio Stream Command Queue used to communicate with the AudioStreamingThread(). 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 AudioStreamingThread() 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