MusicDB Websocket API

The following documentation is part of the Python code documentation for developers. So, there may appear some pythonic codes. Most code presented on this page is JavaScript.

The names for the methods and arguments are identical. The returned values of each method are the same as sent back by the server to the client. So when the server method has an argument albumid (like def GetAlbum(self, albumid):), than the JavaScript argument is also albumid. To give the argument 1000 to the GetAlbum function, the arguments-object must look like {albumid: 1000}.

Communication

Packet format

A packet is a JSON string with the following entries:

method:

Different methods to communicate with the server

fncname:

The name of the function that shall be called on the server

fncsig:

A function signature. If there is a response, this signature can be used to tell the client what function to call next. This entry is not used by the server and can be null.

arguments:

These are the arguments to the called function. It is an object or list of objects with each element addressing one argument of the called method on the server. On received packets, this are the returned values.

pass:

A place for pass-through arguments. The server will not touch this entry and returns it as it is. This may be useful to give the receiving client some context.

key:

This entry holds the WebSocket API key. If this key does not match with the key configured for the running server in the MusicDB Configuration ([websocket]->apikey), then the packet gets dropped. Its value gets set by the JavaScript implementation right before the packet gets send to the server.

The following code show an abstract of the implementation:

// method and fncname are mandatory, the other entries are optional
fncsig = fncsig || null;
pass   = pass   || null;
args   = args   || null;

// Create Packet
var packet = {
    method:     method,
    fncname:    fncname,
    fncsig:     fncsig,
    arguments:  args,
    pass:       pass
}

// Make JSON string out of the packet
var buffer;
buffer = JSON.stringify(packet);

// Send string to the server
try
{
   socket.send(buffer);
}
catch(error)
{
   window.console && console.log("[MDB] Error: Sending message to server failed!");
}

Methods

call:

A call of a function on the server. There will be no response from the server.

request:

A request of data from the server. The returned value are stored in the arguments entry. The method entry gets set to response by the server.

reponse:

This marks a direct response from the server to the client who requested data. This method should only be used by the server!

broadcast:

A broadcast is a packet from the server that got send to all connected clients. If the client uses the broadcast method, the response gets send to all clients as broadcast as well.

notification:

An notification is similar to a broadcast with the main difference that there was no client side action before. Notifications can result of internal state changes of the server. This method should only be used by the server!

There is a special broadcast triggered whenever the server gets triggered to update its caches by system signal USR1 (mdbapi.server.UpdateCaches()). This broadcast should be used to update the caches on client side. It has the following signature: {method:"broadcast", fncname:"sys:refresh", fncsig:"UpdateCaches", arguments:null, pass:null}

Client side interface

The MusicDB interface on client side is implemented in the file musicdb.js. This file is documented under Websocket Connection. The connection can be started by calling ConnectToMusicDB(). Then there can be used several functions and callback routines to communicate with the MusicDB Websocket Server.

To establish a connection on startup, just wait for the onload event from the browser:

window.onload = function ()
{
   ConnectToMusicDB();
}

Note

The configuration must be done inside the file musicdb.js. Read the Websocket Connection documentation for setting up the watchdog and the address of the websocket server! See the sections for the watchdog and the communication to the server.

Callback functions

• onMusicDBConnectionOpen()

• onMusicDBConnectionError()

• onMusicDBWatchdogBarks()

• onMusicDBConnectionClosed()

• onMusicDBNotification(fnc, sig, rawdata)

• onMusicDBMessage(fnc, sig, args, pass)

A minimal implementation may look like this:

function onMusicDBConnectionOpen()
{
   window.console && console.log("[MDB] Open");
}
function onMusicDBConnectionError()
{
   window.console && console.log("[MDB] Error");
}
function onMusicDBWatchdogBarks()
{
   window.console && console.log("[MDB] WD Barks");
}
function onMusicDBConnectionClosed()
{
   window.console && console.log("[MDB] Closed");
}
function onMusicDBNotification(fnc, sig, rawdata)
{
   window.console && console.log("[MDB] Notification");
}
function onMusicDBMessage(fnc, sig, args, pass)
{
   window.console && console.log("[MDB] Message");

   if(fnc == "GetAlbum" && sig == "ShowAlbum")
      ShowAlbum(args.artist, args.album, args.cds, args.tags);
}

Send data to the server

The following functions are available to communicate with the server. The arguments args and pass are optional arguments.

function MusicDB_Call(fncname, args)
function MusicDB_Request(fncname, fncsig, args, pass)
function MusicDB_Broadcast(fncname, fncsig, args, pass)

The documentation of these function are linked in the following list:

• MusicDB_Call()

• MusicDB_Request()

• MusicDB_Broadcast()

Example:

// Request an album with ID 1000 and signal the client that the response shall be used to show it.
MusicDB_Request("GetAlbum", "ShowAlbum", {albumid: 1000});

Events

The Streaming Thread generates events that get broadcast to all clients via notifications.

The package has the following information:

• method: notification

• pass: null

• Event triggered by Audio Streaming Server

  • fncname: "MusicDB:AudioStream"

  • fncsig: "onStatusChanged" or "onTimeChanged"

  • argument: The playtime of the current song in seconds, when the fncsig is "onTimeChanged"

• Event triggered by Video Streaming Server

  • fncname: "MusicDB:VideoStream"

  • fncsig: See related documentation

  • argument: See related documentation

• Event triggered by MusicDB Song Queue

  • fncname: "MusicDB:SongQueue"

  • fncsig: "onSongQueueChanged" or "onSongChanged"

  • argument: None

• Event triggered by MusicDB video Queue

  • fncname: "MusicDB:VideoQueue"

  • fncsig: "onVideoQueueChanged" or "onVideoChanged"

  • argument: None

• Event triggered by Task Management Thread

  • fncname: "MusicDB:Task"

  • fncsig: "ChunkRequest", "StateUpdate" or "InternalError"

  • argument: See taskmanagement.taskmanager.TaskManager.NotifyClient()

See the related documentation of the event sources for more details

Server side API

Overview of all WebAPI Methods sorted by category (some methods appear multiple times).

Available Methods

Artists

• GetArtists()

• GetArtistsWithAlbums() (Alternative: GetFilteredArtistsWithAlbums)

• GetFilteredArtistsWithVideos()

• CreateArtistEntry()

• UpdateArtistEntry()

• RemoveArtistEntry()

Albums

• GetAlbums()

• GetHiddenAlbums()

• GetSortedAlbumCDs()

• GetAlbum()

• HideAlbum()

• SetAlbumOrigin()

• SetAlbumImportTime()

• SetAlbumColor()

• AddAlbumToQueue()

• UpdateAlbumEntry()

• RemoveAlbumEntry()

Songs

• GetSong()

• AddSongToQueue()

• AddRandomSongToQueue()

• RemoveSongFromQueue()

• MoveSongInQueue()

• GetSongRelationship()

• UpdateSongStatistic()

• CutSongRelationship()

• PlayNextSong()

• CreateSongEntry()

• UpdateSongEntry()

• RemoveSongEntry()

Videos

• GetVideos()

• GetVideo()

• AddVideoToQueue()

• AddRandomVideoToQueue()

• RemoveVideoFromQueue()

• MoveVideoInQueue()

• UpdateVideoStatistic()

• SetVideoColor()

• SetVideoTimeFrame()

• PlayNextVideo()

• VideoEnded()

• SetVideoThumbnail()

• GetVideoRelationship()

• CutVideoRelationship()

Queue

• GetSongQueue()

• GetVideoQueue()

• AddSongToQueue()

• AddRandomSongToQueue()

• AddVideoToQueue()

• AddAlbumToQueue()

• RemoveSongFromQueue()

• RemoveVideoFromQueue()

• MoveSongInQueue()

• MoveVideoInQueue()

Tag related

• GetTags()

• GetTagsStatistics()

• GetSongTags()

• GetAlbumTags()

• GetVideoTags()

• SetAlbumTag()

• RemoveAlbumTag()

• SetSongTag()

• RemoveSongTag()

• SetVideoTag()

• RemoveVideoTag()

• AddGenre()

• AddSubgenre()

• AddMoodFlag()

• DeleteTag()

• ModifyTag()

Lyrics

• GetSongLyrics()

• SetSongLyrics()

Uploading

• InitiateUpload()

• UploadChunk()

• GetCurrentTasks()

• AnnotateUpload()

• InitiateContentIntegration()

• InitiateMusicImport()

• InitiateArtworkImport()

• RemoveUpload()

File Handling

• SaveWebUIConfiguration()

• LoadWebUIConfiguration()

• FindNewContent()

• FindAlbumSongFiles()

• RenameMusicFile()

• RenameAlbumDirectory()

• RenameArtistDirectory()

• ChangeArtistDirectory()

• InitiateFilesystemScan()

Other

• Find()

• GetAudioStreamState()

• GetVideoStreamState()

• SetAudioStreamState()

• SetVideoStreamState()

• PlayNextSong()

• PlayNextVideo()

• SetMDBState()

• GetMDBState()

• GetTables()

Special Functions

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

Bounce(args)

This is a special method that does nothing but returning the arguments given to it. It can be used to propagate information between different clients or trigger certain events inside a client.

Parameters

args (dict) – A dictionary with any data

Returns

The dictionary given as argument

Example

MusicDB_Broadcast("Bounce", "UpdateValue", {value: 42}); // Tell all clients that value is 42
MusicDB_Request("Bounce", "TriggerEvent");               // Trigger an event inside the client

Artists

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

CreateArtistEntry(name)

This method creates a new Artist with the name name.

If there is no directory with the same name in the music root directory, a new directory will be created. When creating the directory fails, so that there exists no directory with the artist name, None will be returned.

If there is already an artist with the same name existing in the database, its database entry will be returned. If there the artist is unknown, a new entry will be created. The new entry will be returned.

For details see musicdb.mdbapi.music.MusicDBMusic.CreateNewArtist().

Parameters

name (str) – Name of the new artist.

Returns

The artist entry, or None on error.

GetArtists()

Returns a list of artists. This list is sorted by the name of the artist.

A list entry contains the following values:

• id: Artist ID

• name: Artist name

• path: Relative path to the artist directory

Returns

A list of artists

GetArtistsWithAlbums(applyfilter=False)

This method returns a list of artists and their albums. Each entry in this list contains the following two elements:

• artist: An entry like the list entries of GetArtists()

• albums: A list of albums that was returned by GetAlbums() for the related artist.

Artists without albums or albums that got filters out will not appear in the list.

Attention

The JavaScript API uses the following aliases:

• GetArtistsWithAlbums: Without arguments, and so without applying the filter.

• GetFilteredArtistsWithAlbums: With applying the filter option.

So, from JavaScripts point of view this method does not have any parameters.

Parameters

applyfilter (bool) – Default value is False

Returns

A list of artists and their albums

Example

MusicDB_Request("GetFilteredArtistsWithAlbums", "ShowArtists");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetFilteredArtistsWithAlbums" && sig == "ShowArtists")
    {
        for(let artist of args)
        {
            console.log("Artist: " + artist.name);
            for(let albumdata of artist.albums)
                console.log(albumdata.album); // album entry
                console.log(albumdata.tags);  // tags for the album
        }
    }
}

GetFilteredArtistsWithVideos()

This method returns a list of artists and their videos. The genre-filter gets applied to the videos. Each entry in this list contains the following two elements:

• artist: An entry like the list entries of GetArtists()

• videos: A list of videos

Artists without videos or videos that got filters out will not appear in the list.

Returns

A list of artists and their videos

Example

MusicDB_Request("GetFilteredArtistsWithVideos", "ShowArtists");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetFilteredArtistsWithVideos" && sig == "ShowArtists")
    {
        for(let artist of args)
        {
            console.log("Artist: " + artist.name);
            for(let video of artist.videos)
                console.log(" -> " + video.name);
        }
    }
}

RemoveArtistEntry(artistid)

This method removes an artist and all its albums and songs from the database. The related directory and files in the Music Directory remains untouched. All other information related to the songs will be removed from the database as well.

Parameters

artistid (int) – ID of the album to remove

Example

MusicDB_Call("RemoveArtistEntry", {artistid: 42});

UpdateArtistEntry(artistid, newpath)

This method updates the database entry of the artist with the ID artistid. The information for the update come from the directory addressed by newpath. The update is done via musicdb.mdbapi.music.MusicDBMusic.UpdateArtist(). All albums inside the directory get updated via musicdb.mdbapi.music.MusicDBMusic.UpdateAlbum() as well as all their songs via musicdb.mdbapi.music.MusicDBMusic.UpdateSong().

Parameters

• artistid (int) – ID of the artist to update

• newpath (str) – Path to the new artist directory relative to the music directory

Example

MusicDB_Call("UpdateArtisEntry", {artistid: 1337, newpath: "Moved Artist"});

Albums

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AddAlbumToQueue(albumid, position, cd=None)

This method adds all songs of an album at any position of the queue.

If cd is None (or not given), all songs of all CDs are added to the queue. If cd is an integer, it limits the CD that will be added. The CD number starts with 0 for the first CD of an album.

The position can be "next" if the songs shall be placed behind the current playing song. So, all new added songs will be played next. Alternative "last" can be used to place the songs at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the SongQueue. Then the songs get append to that addressed entry.

If a song is flagged as “hated” or disabled, than it gets discarded.

Parameters

• albumid (int) – ID of the album that shall be added

• position (str/int) – "next", "last" or Song-Queue Entry ID - Determines where the songs get added

• cd (None/int) – (Optional) Only this CD of the album should be added to the queue. Starting with 0 for the first CD of an album.

Returns

None

Example

MusicDB_Call("AddAlbumToQueue", {albumid:23});
MusicDB_Call("AddAlbumToQueue", {albumid:42, position:"next"});
MusicDB_Call("AddAlbumToQueue", {albumid:13, position:"last", cd=1});

GetAlbum(albumid)

This method returns an album and its songs, separated by CDs.

GetAlbum returns a dictionary with the following keys:

• artist: database entry of the artist of the album

• album: the database entry of the album itself

• tags: a list of tags as returned by GetAlbumTags()

• cds: a list of CDs that contains a list of songs for each CD. See GetSortedAlbumCDs() for details.

Parameters

albumid (int) – The ID of that album that shall be returned

Returns

A dictionary with information of the requested album, its tags and songs

Example

MusicDB_Request("GetAlbum", "ShowAlbum", {albumid:albumid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetAlbum" && sig == "ShowAlbum")
    {
        console.log("Artist: " + args.artist.name);
        console.log("Album:  " + args.album.name);
        for(let cd of args.cds)
        {
            for(let track of cd)
            {
                let song, songtags
                song     = track.song;
                songtags = track.tags;
                console.log(" -> " + song.name);
            }
        }
    }
}

GetAlbums(artistid, applyfilter=False)

GetAlbums returns a list of albums of an artist. The list is sorted by release date of the album, starting with the earliest one. Each entry in the list has the following two elements:

• album: An album entry from the database.

• tags: The returned tag entry by GetAlbumTags()

The filter gets applied to only the genre tags.

Parameters

• artistid (int) – ID of the artist whose albums shall be returned

• applyfilter (bool) – Default value is False

Returns

A list of albums and their tags

Example

MusicDB_Request("GetAlbums", "ShowAlbums", {artistid:artistid, applyfilter:false});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetAlbums" && sig == "ShowAlbums")
    {
        for(let listentry of args)
        {
            let album, tags;
            album = listentry.album;
            tags  = listentry.tags;

            console.log("Tags of " + album.name + ":");
            console.log(tags);
        }
    }
}

GetHiddenAlbums()

GetHiddenAlbums returns a list of all albums that are flagged as hidden.

The list is sorted by artist and release date of the album, starting with the earliest one. Actually the list is sorted by the albums path. Because of the naming scheme it leads to push alphabetic artists order and release-date order.

Each entry in the list has the following two elements:

• album: An album entry from the database.

• tags: The returned tag entry by GetAlbumTags()

Returns

A list of albums and their tags

Example

MusicDB_Request("GetHiddenAlbums", "ShowAlbums");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetHiddenAlbums" && sig == "ShowAlbums")
    {
        for(let listentry of args)
        {
            let album, tags;
            album = listentry.album;
            tags  = listentry.tags;

            console.log("Tags of " + album.name + ":");
            console.log(tags);
        }
    }
}

GetSortedAlbumCDs(albumid)

This method returns a sorted list of CDs of an album. Each CD entry is a further sorted list of songs. Each song-entry is a dictionary with the following keys:

• song: The database entry of the song

• tags: a list of tags as returned by GetSongTags()

Parameters

albumid (int) – ID of the album that CD and songs shall be returned

Returns

A sorted list of CDs, its songs and their tags

HideAlbum(albumid, hide)

Hides or shows an album depending on the hide state. When hide == True the album gets hidden, when hide == False the hidden state gets reset to make the album visible again.

Parameters

• albumid (int) – ID of the album

• hide (boolean) – Hide or Show the album

Returns

None

Example

MusicDB_Call("HideAlbum", {albumid: 1000, hide: false});

RemoveAlbumEntry(albumid)

This method removes an album and all its songs from the database. The related directory and files in the Music Directory remains untouched. All other information related to the songs will be removed from the database as well.

Parameters

albumid (int) – ID of the album to remove

Example

MusicDB_Call("RemoveAlbumEntry", {albumid: 42});

SetAlbumColor(albumid, colorname, color)

Sets a color scheme for an album. Valid color names are the following and must be given as string to the colorname parameter. The color itself must be in HTML-Format: #RRGGBB.

The following color-names exist:

• "bgcolor" - Background color

• "fgcolor" - Primary foreground color

• "hlcolor" - Secondary foreground color

Parameters

• albumid (int) – ID of the album

• colorname (str) – Name of the color to set ("fgcolor", "hlcolor", "bgcolor")

• color (str) – Color code in HTML notation: #RRGGBB

Returns

None

Example

MusicDB_Call("SetAlbumColor", {albumid:1000, colorname:"bgcolor", color:"#42AB23"});

SetAlbumImportTime(albumid, importtime)

This method updates the import time (“added” entry) of an album. This is the time at which the album has been imported into the MusicDB Database. It is expected that the importtime is a unix time stamp in seconds.

Usually this time gets set by the import routines. Do only change this value if it is obviously wrong.

Parameters

• albumid (int) – ID of the album to update

• importtime (str|int) – Time at which the album has been imported

Returns

None

Example

let jstimestamp   = Date.now();                     // milliseconds
let unixtimestamp = Math.floor(jstimestamp / 1000); // seconds

MusicDB_Call("SetAlbumImportTime", {albumid: 1000, importtime: unixtimestamp});

SetAlbumOrigin(albumid, origin)

This method updates the origin of an album. The origin must be a string like "iTunes", "Amazon", "CD" or "internet". Any string is possible.

The origin describes where the album files come from - where they have be bought. Usually the string stored in origin is the name of the online shop. Avoid URLs.

Parameters

• albumid (int) – ID of the album to update

• origin (str) – Origin of the album

Returns

None

Example

MusicDB_Call("SetAlbumOrigin", {albumid: 1000, origin: "internet"});

UpdateAlbumEntry(albumid, newpath)

This method updates the database entry of the album with the ID albumid. The information for the update come from the directory addressed by newpath. The update is done via musicdb.mdbapi.music.MusicDBMusic.UpdateAlbum(). All songs inside the directory get updated via musicdb.mdbapi.music.MusicDBMusic.UpdateSong() as well.

Parameters

• songid (int) – ID of the album to update

• newpath (str) – Path to the new album directory relative to the music directory

Example

MusicDB_Call("UpdateAlbumEntry", {albumid: 1337, newpath: "Artist/2020 - Updated Album"});

Songs

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AddRandomSongToQueue(position, albumid=None)

Similar to AddSongToQueue(). Instead of a specific song, a random song gets chosen by the random-song manager Randy (See Randomizer). This is done using the mdbapi.randy.Randy.GetSong() method.

If an album ID is given, the new song will be added from that album using musicdb.mdbapi.randy.Randy.GetSongFromAlbum().

Parameters

• position (str) – "next" or "last" - Determines where the song gets added

• albumid (int) – Optional album ID from that the song shall be

Returns

None

Example

MusicDB_Call("AddRandomSongToQueue", {position:"last"});
MusicDB_Call("AddRandomSongToQueue", {albumid:"42", position:"next"});

AddSongToQueue(songid, position)

This method adds a new song to the queue of songs that will be streamed.

The song gets address by its ID. The position can be "next" if the song shall be places behind the current playing song. So, the new added song will be played next. Alternative "last" can be used to place the song at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the SongQueue. Then the song gets append to that entry.

Parameters

• songid (int) – ID of the song that shall be added

• position (str/int) – "next", "last" or Song-Queue Entry ID - Determines where the song gets added

Returns

None

Example

MusicDB_Call("AddSongToQueue", {songid:1000, position:"next"});

CreateSongEntry(newpath)

This method creates a new song entry in the database. The song file is addressed by newpath. This file must fulfill the MusicDB name scheme for song files. The import is done via musicdb.mdbapi.music.MusicDBMusic.AddSong().

It is important that the album already exists in the database. This method does not replace the InitiateMusicImport() which imports new albums or videos. This method is supposed to be used to add a new song to an existing album. The album entry gets updated as well (number of songs).

Parameters

newpath (str) – Path to the new song file relative to the music directory

Example

MusicDB_Call("CreateSongEntry", {newpath: "Artist/2020 - Album/01 Updated Song.flac"});

CutSongRelationship(songid, relatedsongid)

This method removes the relation between two songs.

After executing this method, the MusicDB server broadcasts the result of GetSongRelationship(). (method = "broadcast", fncname = "GetSongRelationship") So each client gets informed about the changes made.

Parameters

• songid (int) – ID of one song

• relatedsongid (int) – ID of the related song

GetSong(songid)

This method returns the information of a song, its album and artist, and its tags.

The returned dictionary has the following keys:

• song: the database entry of the song itself.

• artist: database entry of the artist of the song

• album: the database entry of the album in that the song is listed

• tags: a list of tags as returned by GetSongTags()

Parameters

songid (int) – ID of the song

Returns

A dictionary with information of the song

Example

MusicDB_Request("GetSong", "ShowSong", {songid:songid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSong" && sig == "ShowSong")
    {
        console.log("Artist: " + args.artist.name);
        console.log("Album:  " + args.album.name);
        console.log("Song:   " + args.song.name);
        for(let mood of args.tags.moods)
        {
            console.log("Mood: " + mood.name);
        }
    }
}

GetSongRelationship(songid)

This method returns the relationship of a song. It is a list of songs that were played before or after the song with song ID songid.

The returned dictionary contains the same song ID given as argument to this method, as well as the corresponding song, album and artist entry of that song. Additional the requested list of related songs is given. Each lists entry is a dictionary with the related song, album and artist album from the database. Furthermore the weight is given. The weight indicates how often the two songs were played together. Hated and disabled songs will not appear in the list.

The list of songs gets sorted by the keys in the following list: (sorted by priority)

• Artist Name

• Album Release

• Album Name

• Song CD

• Song Number

The tags of that song will also be returned separated into genre, subgenre and mood. See GetSongTags() for details how they are returned.

Parameters

songid (int) – ID so a song

Returns

A list of related songs

Example

MusicDB_Request("GetSongRelationship", "ShowRelations", {songid:songid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSongRelationship" && sig == "ShowRelations")
    {
        console.log("Songs related to the one with ID " + args.songid);
        console.log(" … from the album " + args.album.name);
        for(let entry of args.songs)
            console.log("Song " + entry.song.name + " with weight " + entry.weight);
            console.log(entry.tags.genres)
    }
}

MoveSongInQueue(entryid, afterid)

This is a direct interface to musicdb.mdbapi.songqueue.SongQueue.MoveSong(). It moves a song from one position in the queue to another one.

It is not allowed to move the current playing song (index 0). When this is tried, nothing happens.

Parameters

• entryid (str) – Position of the song

• afterid (str) – The position the song shall be moved to

Returns

None

Example

Assuming the following queue:

entry ID	song ID
1337	1
7357	2
2323	3
4242	4

Then the two calls will be applied. The first one is invalid, because entry ID "1337" addresses the current playing song at the top of the queue. So that one will be ignored. The next one moves song 2 to the end of the queue.

MusicDB_Call("MoveSongInQueue", {entryid:"1337", afterid:"2323"});
MusicDB_Call("MoveSongInQueue", {entryid:"7357", afterid:"4242"});

So after processing the two calls, the queue looks like this:

entry ID	song ID
1337	1
2323	3
4242	4
7357	2

PlayNextSong()

This method skips the current playing song. If there is no song that can be skipped, the Song Queue or Streaming Thread will handle this properly.

Returns

None

Example

MusicDB_Call("PlayNextSong");

RemoveSongEntry(songid)

This method removes a song from the database. The related file in the Music Directory remains untouched. All other information related to the song entry will be removed from the database as well.

Parameters

songid (int) – ID of the song to remove

Example

MusicDB_Call("RemoveSongEntry", {songid: 23});

RemoveSongFromQueue(entryid)

This method removes a song from song queue. The song gets identified by the entry ID of the queue entry.

If the song is currently streamed, playing the next song gets triggered.

Parameters

entryid (str) –

Returns

None

Example

MusicDB_Call("RemoveSongFromQueue", {entryid:"82390194629402649"});

UpdateSongEntry(songid, newpath)

This method updates the database entry of the song with the ID songid. The information for the update come from the song file addressed by newpath. The update is done via musicdb.mdbapi.music.MusicDBMusic.UpdateSong().

Parameters

• songid (int) – ID of the song to update

• newpath (str) – Path to the new song file relative to the music directory

Example

MusicDB_Call("UpdateSongEntry", {songid: 23, newpath: "Artist/2020 - Album/01 Updated Song.flac"});

UpdateSongStatistic(songid, statistic, modifier)

When this method got called direct via the JavaScript API, the MusicDB server broadcasts the result of GetSong(). (method = "broadcast", fncname = "GetSong") So each client gets informed about the changes made. This is important to update the HUD if the song is currently playing.

This method is a direct interface to musicdb.lib.db.musicdb.MusicDatabase.UpdateSongStatistic(). See the related documentation for more details.

Videos

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AddRandomVideoToQueue(position)

Similar to AddVideoToQueue(). Instead of a specific video, a random video gets chosen by the random music manager Randy (See Randomizer). This is done using the musicdb.mdbapi.randy.Randy.GetVideo() method.

Parameters

position (str) – "next" or "last" - Determines where the song gets added

Returns

None

Example

MusicDB_Call("AddRandomVideoToQueue", {position:"last"});

AddVideoToQueue(videoid, position)

This method adds a new video to the queue of videos that will be played.

The video gets address by its ID. The position can be "next" if the video shall be places behind the current playing video. So, the new added video will be played next. Alternative "last" can be used to place the video at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the VideoQueue. Then the video gets append to that entry.

Parameters

• videoid (int) – ID of the video that shall be added

• position (str/int) – "next", "last" or Video-Queue Entry ID - Determines where the song gets added

Returns

None

Example

MusicDB_Call("AddVideoToQueue", {videoid:1000, position:"last"});

CutVideoRelationship(videoid, relatedvideoid)

This method removes the relation between two videos.

After executing this method, the MusicDB server broadcasts the result of GetVideoRelationship(). (method = "broadcast", fncname = "GetVideoRelationship") So each client gets informed about the changes made.

Parameters

• videoid (int) – ID of one video

• relatedvideoid (int) – ID of the related video

GetVideo(videoid)

This method returns a video entry from the Music Database.

GetVideo returns a dictionary with the following keys:

• artist: A Database entry of the artist of the video

• album: The database entry of the album of the video, if known. Can be None.

• song: The database entry of the song related to the video, if known. Can be None.

• video: The video with the videoid of the request

• tags: A list of tags as returned by GetVideoTags()

Parameters

videoid (int) – The ID of that video that shall be returned

Returns

A dictionary with information of the requested video

Example

MusicDB_Request("GetVideo", "ShowVideo", {videoid:1000});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideo" && sig == "ShowVideo")
    {
        console.log("Artist: " + args.artist.name);
        console.log("Video:  " + args.video.name);
    }
}

GetVideoRelationship(videoid)

This method returns the relationship of a video to other videos. It is a list of videos that were played before or after the video with video ID videoid.

The returned dictionary contains the same video ID given as argument to this method, and list of related videos. Each lists entry is a dictionary with the related video and artist from the database. Furthermore the weight is given. The weight indicates how often the two videos were played together. Hated and disabled videos will not appear in the list.

The list of videos gets sorted by the keys in the following list: (sorted by priority)

• Artist Name

• Video Release

The tags of that videos will also be returned separated into genre, subgenre and mood. See GetVideoTags() for details how they are returned.

Parameters

videoid (int) – ID so a video

Returns

A list of related videos

Example

MusicDB_Request("GetVideoRelationship", "ShowRelations", {videoid:7357});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideoRelationship" && sig == "ShowRelations")
    {
        console.log("Videos related to the one with ID " + args.videoid)
        for(let entry of args.videos)
            console.log("Video " + entry.video.name + " with weight " + entry.weight);
            console.log(entry.tags.genres)
    }
}

GetVideos(artistid, applyfilter=False)

GetVideos returns a list of videos of an artist. The list is sorted by release date of the video, starting with the earliest one. Each entry in the list has the following two elements:

• video: A video entry from the database.

• tags: The returned tag entry by GetVideoTags()

The filter gets applied to only the genre tags.

Parameters

• artistid (int) – ID of the artist whose videos shall be returned

• applyfilter (bool) – Default value is False

Returns

A list of videos and their tags

Example

MusicDB_Request("GetVideos", "ShowVideos", {artistid:artistid, applyfilter:false});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideos" && sig == "ShowVideos")
    {
        for(let listentry of args)
        {
            let video, tags;
            video = listentry.video;
            tags  = listentry.tags;

            console.log("Tags of " + video.name + ":");
            console.log(tags);
        }
    }
}

MoveVideoInQueue(entryid, afterid)

This is a direct interface to musicdb.mdbapi.videoqueue.VideoQueue.MoveVideo(). It moves a video from one position in the queue to another one.

It is not allowed to move the current playing video (index 0). When this is tried, nothing happens.

Parameters

• entryid (str) – Position of the video

• afterid (str) – The position the video shall be moved to

Returns

None

PlayNextVideo()

This method skips the current playing video. If there is no video that can be skipped, the Video Queue or Streaming Thread will handle this properly.

Returns

None

Example

MusicDB_Call("PlayNextVideo");

RemoveVideoFromQueue(entryid)

This method removes a video from the video queue. The video gets identified by the entry ID of the queue entry.

If the video is currently streamed, playing the next video gets triggered.

Parameters

entryid (str) –

Returns

None

Example

MusicDB_Call("RemoveVideoFromQueue", {entryid:"82390194629402649"});

SetVideoColor(videoid, colorname, color)

Sets a color scheme for a video. Valid color names are the following and must be given as string to the colorname parameter. The color itself must be in HTML-Format: #RRGGBB.

The following color-names exist:

• "bgcolor" - Background color

• "fgcolor" - Primary foreground color

• "hlcolor" - Secondary foreground color

Parameters

• videoid (int) – ID of the video

• colorname (str) – Name of the color to set ("fgcolor", "hlcolor", "bgcolor")

• color (str) – Color code in HTML notation: #RRGGBB

Returns

True on success, otherwise false

Example

MusicDB_Call("SetVideoColor", {videoid:1000, colorname:"bgcolor", color:"#42AB23"});

SetVideoThumbnail(videoid, timestamp)

This method sets a new video thumbnail via ChangeThumbnail().

Parameters

• videoid (int) – ID of the video to update

• timestamp (int) – Time stamp of the frame to select (in seconds)

Returns

None

Example

// Use frame at 1:10 as thumbnail
MusicDB_Call("SetVideoThumbnail", {videoid:1000, timestamp:70});

SetVideoTimeFrame(videoid, begin, end)

Set the time frame for a video. This time frame defines where the player should start playing the video and where it should end. Purpose for this is to cut away intros and outros. The values are floating point numbers an represent the second inside the video file.

In case begin or end is None (null in JavaScript), they get reset to the default value. The default for begin is 0.0 and for end is the total play time of the video.

Parameters

• videoid (int) – ID of the video

• begin (int) – Begin of the main content in seconds.

• end (int) – End of the main content in seconds.

Returns

True on success, otherwise false

Example

MusicDB_Call("SetVidoTimeFrame", {videoid:1000, begin:23, end:142});

UpdateVideoStatistic(videoid, statistic, modifier)

This video allows setting some statistics and properties for a video. When this method got called direct via the JavaScript API, the MusicDB server broadcasts the result of GetVideo(). (method = "broadcast", fncname = "GetSong") So each client gets informed about the changes made and can synchronize itself.

This method is a direct interface to lib.db.musicdb.MusicDatabase.UpdateVideoStatistic(). See the related documentation for more details.

VideoEnded(entryid)

Notify the Video Queue that the current played video with a specific entry id ended. In case multiple clients are calling this method, the ~mdbapi.videostream.VideoStreamManager will handle the conflict.

Parameters

entryid (str) – UUID of the video entry in the song queue

Returns

None

Example

MusicDB_Call("VideoEnded", {entryid:'168493523207840521806064336792025247758'});

Queue

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AddAlbumToQueue(albumid, position, cd=None)

This method adds all songs of an album at any position of the queue.

If cd is None (or not given), all songs of all CDs are added to the queue. If cd is an integer, it limits the CD that will be added. The CD number starts with 0 for the first CD of an album.

The position can be "next" if the songs shall be placed behind the current playing song. So, all new added songs will be played next. Alternative "last" can be used to place the songs at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the SongQueue. Then the songs get append to that addressed entry.

If a song is flagged as “hated” or disabled, than it gets discarded.

Parameters

• albumid (int) – ID of the album that shall be added

• position (str/int) – "next", "last" or Song-Queue Entry ID - Determines where the songs get added

• cd (None/int) – (Optional) Only this CD of the album should be added to the queue. Starting with 0 for the first CD of an album.

Returns

None

Example

MusicDB_Call("AddAlbumToQueue", {albumid:23});
MusicDB_Call("AddAlbumToQueue", {albumid:42, position:"next"});
MusicDB_Call("AddAlbumToQueue", {albumid:13, position:"last", cd=1});

AddRandomSongToQueue(position, albumid=None)

Similar to AddSongToQueue(). Instead of a specific song, a random song gets chosen by the random-song manager Randy (See Randomizer). This is done using the mdbapi.randy.Randy.GetSong() method.

If an album ID is given, the new song will be added from that album using musicdb.mdbapi.randy.Randy.GetSongFromAlbum().

Parameters

• position (str) – "next" or "last" - Determines where the song gets added

• albumid (int) – Optional album ID from that the song shall be

Returns

None

Example

MusicDB_Call("AddRandomSongToQueue", {position:"last"});
MusicDB_Call("AddRandomSongToQueue", {albumid:"42", position:"next"});

AddSongToQueue(songid, position)

This method adds a new song to the queue of songs that will be streamed.

The song gets address by its ID. The position can be "next" if the song shall be places behind the current playing song. So, the new added song will be played next. Alternative "last" can be used to place the song at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the SongQueue. Then the song gets append to that entry.

Parameters

• songid (int) – ID of the song that shall be added

• position (str/int) – "next", "last" or Song-Queue Entry ID - Determines where the song gets added

Returns

None

Example

MusicDB_Call("AddSongToQueue", {songid:1000, position:"next"});

AddVideoToQueue(videoid, position)

This method adds a new video to the queue of videos that will be played.

The video gets address by its ID. The position can be "next" if the video shall be places behind the current playing video. So, the new added video will be played next. Alternative "last" can be used to place the video at the end of the queue. In case position is an integer, it is interpreted as an entry ID of the VideoQueue. Then the video gets append to that entry.

Parameters

• videoid (int) – ID of the video that shall be added

• position (str/int) – "next", "last" or Video-Queue Entry ID - Determines where the song gets added

Returns

None

Example

MusicDB_Call("AddVideoToQueue", {videoid:1000, position:"last"});

GetSongQueue()

This method returns a list of songs, albums and artists for each song in the song queue. If there are no songs in the queue, an empty list gets returned.

Each entry of the list contains the following information:

• entryid: A unique ID to identify the entry in the queue (as string because it is a 128 integer that blows JavaScripts mind)

• israndom: A boolean value set to true when the song got added randomly and not explicitly by the user

• song: The song entry from the database

• album: The related album entry from the database

• artist: The related artist entry from the database

Returns

A list of song, album and artist information for each song in the song queue

Example

MusicDB_Request("GetSongQueue", "ShowSongQueue");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSongQueue" && sig == "ShowSongQueue")
    {
        for(let entry of args)
        {
            console.log(entry.song.name + " by " + entry.artist.name);
        }
    }
}

GetVideoQueue()

This method returns a list of videos, albums and artists for each video in the video queue. If there are no videos in the queue, an empty list gets returned. The album or artist can be null if there is no associated to the video.

Each entry of the list contains the following information:

• entryid: A unique ID to identify the entry in the queue (as string because it is a 128 integer that blows JavaScripts mind)

• israndom: A boolean value set to true when the video got added randomly and not explicitly by the user

• video: The video entry from the database

• album: The related album entry from the database or null.

• artist: The related artist entry from the database or null.

Returns

A list of video, album and artist information for each video in the video queue

Example

MusicDB_Request("GetVideoQueue", "ShowVideoQueue");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideoQueue" && sig == "ShowVideoQueue")
    {
        for(let entry of args)
        {
            console.log(entry.video.name + " by " + entry.artist.name);
        }
    }
}

MoveSongInQueue(entryid, afterid)

This is a direct interface to musicdb.mdbapi.songqueue.SongQueue.MoveSong(). It moves a song from one position in the queue to another one.

It is not allowed to move the current playing song (index 0). When this is tried, nothing happens.

Parameters

• entryid (str) – Position of the song

• afterid (str) – The position the song shall be moved to

Returns

None

Example

Assuming the following queue:

entry ID	song ID
1337	1
7357	2
2323	3
4242	4

Then the two calls will be applied. The first one is invalid, because entry ID "1337" addresses the current playing song at the top of the queue. So that one will be ignored. The next one moves song 2 to the end of the queue.

MusicDB_Call("MoveSongInQueue", {entryid:"1337", afterid:"2323"});
MusicDB_Call("MoveSongInQueue", {entryid:"7357", afterid:"4242"});

So after processing the two calls, the queue looks like this:

entry ID	song ID
1337	1
2323	3
4242	4
7357	2

MoveVideoInQueue(entryid, afterid)

This is a direct interface to musicdb.mdbapi.videoqueue.VideoQueue.MoveVideo(). It moves a video from one position in the queue to another one.

It is not allowed to move the current playing video (index 0). When this is tried, nothing happens.

Parameters

• entryid (str) – Position of the video

• afterid (str) – The position the video shall be moved to

Returns

None

RemoveSongFromQueue(entryid)

This method removes a song from song queue. The song gets identified by the entry ID of the queue entry.

If the song is currently streamed, playing the next song gets triggered.

Parameters

entryid (str) –

Returns

None

Example

MusicDB_Call("RemoveSongFromQueue", {entryid:"82390194629402649"});

RemoveVideoFromQueue(entryid)

This method removes a video from the video queue. The video gets identified by the entry ID of the queue entry.

If the video is currently streamed, playing the next video gets triggered.

Parameters

entryid (str) –

Returns

None

Example

MusicDB_Call("RemoveVideoFromQueue", {entryid:"82390194629402649"});

Tag related

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AddGenre(name)

This method creates a new genre. If the tag already exists, nothing happens.

After executing this command, GetTags() gets executed. Its return value gets send via broadcast.

If tagging is disabled nothing will be changed. The broadcast gets send anyway.

Parameters

name (str) – Name of the new genre

AddMoodFlag(name, icon, color, posx, posy)

This method creates a new Mood Flag. If the tag already exists, nothing happens.

See musicdb for details about the attributes!

If color is null, no color is used for the flag. This should be the default case, because the mood flags should adopt to the WebUI color scheme. Otherwise the color must be given in 7-character HTML notation: #RRGGBB.

The icon type gets derived from the content of the icon parameter via musicdb.mdbapi.tags.MusicDBTags.AnalyseIcon()

After executing this command, GetTags() gets executed. Its return value gets send via broadcast.

If tagging is disabled nothing will be changed. The broadcast gets send anyway.

Parameters

• name (str) – Name of the new subgenre

• icon (str) – Icon for that flag

• color (str) – (optional) HTML Color

• posx (int) – X-Position in the moods-grid

• posy (int) – X-Position in the moods-grid

AddSubgenre(name, parentname)

This method creates a new subgenre. If the tag already exists, nothing happens.

After executing this command, GetTags() gets executed. Its return value gets send via broadcast.

If tagging is disabled nothing will be changed. The broadcast gets send anyway.

Parameters

• name (str) – Name of the new subgenre

• parentname (str) – Name of the main genre

DeleteTag(tagid)

This method deletes a tag addressed by its tag ID.

Warning

If the tag is a Genre, its sub-genres will be deleted as well!

Before deleting the tag, this tag as well as its child-tags (sub-genre tag) will be removed from all songs, albums and videos.

After executing this command, GetTags() gets executed. Its return value gets send via broadcast.

If tagging is disabled nothing will be changed. The broadcast gets send anyway.

Parameters

• name (str) – Name of the new subgenre

• parentname (str) – Name of the main genre

GetAlbumTags(albumid)

Similar to GetSongTags(). This method returns the tags for an Album.

GetSongTags(songid)

Returns a dictionary with the following keys:

• songid: The same ID as given as argument

• genres: A list of tags of class Genre

• subgenres: A list of tags of class Subgenre

• moods: A list of tags of class Mood

Each entry of the dict is a list with tags. Each tag is a dictionary as returned by musicdb.lib.db.musicdb.MusicDatabase.GetTargetTags().

Parameters

songid (int) – ID of the song for which the tags are requested

Returns

A dict of tags sorted by classes

Example

MusicDB_Request("GetSongTags", "ShowSongTags");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSongTags" && sig == "ShowSongTags")
    {
        let genres, subgenres, moods;
        genres    = args.genres;
        subgenres = args.subgenres;
        moods     = args.moods;

        console.log("Tags of the song with the ID " + args.songid);
        for(let tag of genres)
            console.log(tag.name);
        for(let tag of subgenres)
            console.log(tag.name);
        for(let tag of moods)
            console.log(tag.name);
    }
}

GetTags()

This method returns all tags that are available, separated by the tag classes.

Returns

A dictionary of all classes with lists of all available tags

Example

MusicDB_Request("GetTags", "ShowTags");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetTags" && sig == "ShowTags")
    {
        let genres, subgenres, moods;
        genres    = args.genres;
        subgenres = args.subgenres;
        moods     = args.moods;

        for(let tag of genres)
            console.log(tag.name);
        for(let tag of subgenres)
            console.log(tag.name);
        for(let tag of moods)
            console.log(tag.name);
    }
}

GetTagsStatistics()

This method returns the usage statistics as a dictionary with an entry for each tag. The key is the tag ID. The value is another dictionary with the following keys:

• tag: The whole tag entry for the corresponding ID

• songs: The amount of songs tagged with this tag as integer

• albums: The amount of albums tagged with this tag as integer

• videos: The amount of videos tagged with this tag as integer

• children: Number of child tags as integer

The level of confidence or if the tag was approved for the song/video/album is not considered. All set tags are counted.

Returns

A dictionary with usage-statistics of all tags

Example

MusicDB_Request("GetTagsStatictics", "ShowTags");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetTagsStatistics" && sig == "ShowTags")
    {
        for(let entry of args)
            console.log(`The tag ${entry.tag.name} is assigned to ${entry.songs} songs.`);
    }
}

GetVideoTags(videoid)

Similar to GetSongTags(). This method returns the tags for a Video.

ModifyTag(tagid, attribute, value)

This method allows to modify most of the attributes of a tag. The tagid addresses the tag, attribute the attribute. value is the new attribute set for the tag.

The following attributes are allowed: "name" "icon" "icontype" "color" "posx" "posy". See musicdb for details about the attributes!

In case the icon gets modified, the icon-type will be updated automatically via musicdb.mdbapi.tags.MusicDBTags.AnalyseIcon()

After executing this command, GetTags() gets executed. Its return value gets send via broadcast.

If tagging is disabled nothing will be changed. The broadcast gets send anyway.

Parameters

• tagid (int) – ID of the tag to modify

• attribute (str) – The name of the attribute that shall be modified

• newvalue – The new value. Read the introduction at the top of the document to see what values are possible for a specific attribute

RemoveAlbumTag(albumid, tagid)

Removes a tag from an album

If tagging is disabled nothing will be done.

Parameters

• albumid (int) – ID of the album

• tagid (int) – ID of the tag

Returns

None

Example

MusicDB_Call("RemoveAlbumTag", {albumid:albumid, tagid:tagid});

RemoveSongTag(songid, tagid)

Removes a tag from a song

If tagging is disabled nothing will be done.

After executing this method, the MusicDB server broadcasts the result of GetSong(). (method = "broadcast", fncname = "GetSong") So each client gets informed about the changes made. This is important to update the HUD if the song is currently playing.

After setting the new tag for the song, the album tags get updated using musicdb.mdbapi.tags.MusicDBTags.DeriveAlbumTags(). So when changing a genre or sub genre, then they get suggested as album genre or sub genre

Parameters

• songid (int) – ID of the song

• tagid (int) – ID of the tag

Returns

None

Example

MusicDB_Call("RemoveSongTag", {songid:songid, tagid:tagid});

RemoveVideoTag(videoid, tagid)

Removes a tag from a video.

If tagging is disabled nothing will be done.

After executing this method, the MusicDB server broadcasts the result of GetVideo(). (method = "broadcast", fncname = "GetVideo") So each client gets informed about the changes made. This is important to update the HUD if the video is currently playing.

Parameters

• videoid (int) – ID of the video

• tagid (int) – ID of the tag

Returns

None

Example

MusicDB_Call("RemoveVideoTag", {videoid:videoid, tagid:tagid});

SetAlbumTag(albumid, tagid)

Sets a tag for an album. This method sets the approval-level to 1 (Set by User) and confidence to 1.0 for this tag. So, this method can also be used to approve an AI set tag.

If tagging is disabled nothing will be done.

Parameters

• albumid (int) – ID of the album

• tagid (int) – ID of the tag

Returns

None

Example

MusicDB_Call("SetAlbumTag", {albumid:albumid, tagid:tagid});

SetSongTag(songid, tagid, approval=1, confidence=None)

Sets a tag for a song. This method sets the approval-level to 1 (Set by User) and confidence to 1.0 for this tag by default. So, this method can also be used to approve an AI set tag.

It is also possible to set a “guesses” tag by setting approval to 0 and confidence to a value less that 1.0.

If tagging is disabled nothing will be done.

After executing this method, the MusicDB server broadcasts the result of GetSong(). (method = "broadcast", fncname = "GetSong") So each client gets informed about the changes made. This is important to update the HUD if the song is currently playing.

After setting the new tag for the song, the album tags get updated using musicdb.mdbapi.tags.MusicDBTags.DeriveAlbumTags(). So when changing a genre or sub genre, then they get suggested as album genre or sub genre

Parameters

• songid (int) – ID of the song

• tagid (int) – ID of the tag

• apprival (int) – (optional) 0: for “just a guess”, not approved. 1: Approved by the user.

• confidence (float) – (optional) A value between 0.0 and 1.0 representing the confidence that an none-approved tag is valid.

Returns

None

Examples

MusicDB_Call("SetSongTag", {songid:songid, tagid:tagid});

MusicDB_Call("SetSongTag", {songid:songid, tagid:tagid, approval:0, confidence:0.5});

MusicDB_Request("SetSongTag", "UpdateTagInput", {songid:songid, tagid:tagid}, {taginputid:taginputid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSong" && sig == "UpdateTagInput")
    {
        console.log("Updating " + pass.taginputid + " for song " + args.song.name);
        Taginput_Update(pass.taginputid, args.tags);
    }
}

SetVideoTag(videoid, tagid)

Sets a tag for a video. This method sets the approval-level to 1 (Set by User) and confidence to 1.0 for this tag. So, this method can also be used to approve an AI set tag.

If tagging is disabled nothing will be done.

After executing this method, the MusicDB server broadcasts the result of GetVideo(). (method = "broadcast", fncname = "GetVideo") So each client gets informed about the changes made. This is important to update the HUD if the video is currently playing.

Parameters

• videoid (int) – ID of the video

• tagid (int) – ID of the tag

Returns

None

Examples

MusicDB_Call("SetVideoTag", {videoid:videoid, tagid:tagid});

MusicDB_Request("SetVideoTag", "UpdateTagInput", {videoid:videoid, tagid:tagid}, {taginputid:taginputid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideo" && sig == "UpdateTagInput")
    {
        console.log("Updating " + pass.taginputid + " for video " + args.video.name);
        Taginput_Update(pass.taginputid, args.tags);
    }
}

Lyrics

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

GetSongLyrics(songid)

This method returns the lyrics of a song.

The returned dictionary contains the same song ID given as argument to this method, as well as the corresponding song, album and artist entry of that song. Additional the requested lyrics and the lyricsstate explicitly. The specification how lyrics are formatted and which states are available can be found in the musicdb documentation.

Parameters

songid (int) – ID so a song

Returns

The lyrics of the song and additional information

Example

MusicDB_Request("GetSongLyrics", "ShowLyrics", {songid:songid});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetSongLyrics" && sig == "ShowLyrics")
    {
        console.log("Song lyrics to the one with ID " + args.songid);
        console.log(" … from the album " + args.album.name);
        console.log(args.lyrics);
        console.log("The lyrics state is " + args.lyricsstate);
    }
}

SetSongLyrics(songid, lyrics, state)

This method is a direct interface to SetLyrics(). The specification how lyrics are formatted and which states are available can be found in the musicdb documentation.

Parameters

• songid (int) – ID of the song the lyrics belong to

• lyrics (str) – The lyrics to store

• lyricsstate (int) – The new state of the lyrics

Returns

None

Uploading

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

AnnotateUpload(taskid, annotations)

Adds some information to an uploaded file that can help during the import process. For example a video or album name can be annotated so that after the upload was complete, the file already has the correct name for importing.

Annotation is an object that can have multiple keys.

Parameters

• taskid (str) – Unique ID to identify the upload task

• annotations (dict) – A dictionary with elements to annotate to an upload

Returns

Nothing

GetCurrentTasks()

This method gets all tasks from the taskmanager. This list then gets split into three lists:

• videos: A list of all video related tasks

• albumfiles: A song or any other album content processed as part of an album upload

• artworks: Artwork uploads and import

• any: Can be anything. Depends on the task.

Returns

a list with information about all yet unprocessed uploads

Example

MusicDB_Request("GetCurrentTasks", "ShowTasks");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    console.log(args.albumfiles);
    console.log(args.albums);
    console.log(args.videos);
    console.log(args.artworks);
    console.log(args["any"]);
}

InitiateArtworkImport(sourcepath, targetpath)

Similar to InitiateMusicImport(), but uses musicdb.mdbapi.artworkmanager.ArtworkManager.InitiateImport() to prepare and start an import task.

The sourcepath must address an existing image file in the upload directory or a song file or video file in the music directory. The targetpath must address a video file or album directory inside the music directory. The target path must address music that is also registered in the database.

Parameters

• sourcepath (str) – Path to an image, song or video file

• targetpath (str) – Path to an album directory or video file

Returns

The task ID as string

InitiateContentIntegration(taskid, musicpath)

This method integrates uploaded content into the Music Directory. The task with the ID taskid must be in state "readyforintegration".

When the content type is "artwork", then the artwork will directly be imported. Then the musicpath determines the target of the artwork import. Because artwork cannot only be integrated but must be imported, the import process will directly be triggered.

Otherwise the musicpath defines the target file or directory inside the Music Directory to that the uploaded content will be moved to.

Parameters

• taskid (str) – ID to identify the upload

• musicpath (str) – Path to the destination directory or of the target for artwork import.

Returns

The task ID as string

InitiateMusicImport(contenttype, contentpath)

This method uses musicdb.mdbapi.importmanager.ImportManager.InitiateImport() to prepare and start an import task.

The contentpath addresses the content that shall be imported. This path must be relative to the music directory.

Parameters

• contenttype (str) – Type of the content: ("video", "album", "artwork")

• contentpath (str) – Path to the content that shall be imported. For example to an Album.

Returns

The task ID as string

Example

MusicDB_Request("InitiateMusicImport", "NewTaskID",
    {contenttype: "album", contentpath: "artist/2021 - new album"});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(sig != NewTaskID)
        return;

    if(args == null)
        console.error("Initiate Import failed!");
    else
        console.log(`New Task ID: ${args}`);
}
function onMuiscDBNotification(fnc, sig, rawdata)
{
    if(fnc == "MusicDB:Task" && sig == "StateUpdate")
        console.log(`State Update: ${rawdata["state"]}`);
}

InitiateUpload(taskid, mimetype, contenttype, filesize, checksum, filename)

This method uses musicdb.mdbapi.uploadmanager.UploadManager.InitiateUpload().

Parameters

• taskid (str) – Unique ID to identify the upload task

• mimetype (str) – MIME-Type of the file (example: "image/png")

• contenttype (str) – Type of the content: ("video", "album", "artwork")

• filesize (int) – Size of the complete file in bytes

• checksum (str) – SHA-1 check sum of the source file

• sourcefilename (str) – File name (example: "test.png")

Returns

The task ID taskid

Example

// TODO

RemoveUpload(taskid)

This method triggers removing a specific upload. This includes the uploaded file as well as the upload task information and annotations.

The upload task can be in any state. When the remove-operation is triggered, its state gets changed to "remove".

See musicdb.mdbapi.uploadmanager.UploadManager.RequestRemoveUpload() for details.

Parameters

taskid (str) – ID to identify the upload

UploadChunk(taskid, chunkdata)

Parameters

• taskid (str) – Unique ID to identify the upload task

• chunkdata (str) – Hex-string of the chunk

File Handling

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

ChangeArtistDirectory(oldalbumpath, newartistdirectory)

This method changes the artist directory of an album. If the new artist directory is not existing it will be created. If it exists, the album directory will just be moved into the existing artist directory. The old artist directory will not be touched, even if it becomes an empty directory.

To rename an artist directory see RenameArtistDirectory().

If the album exists in the Music Database, its entry will be updated (including its songs). In this case, a possibly new artist will be imported into the database as well.

If the album does not exists in the database, only the Music Directory will be updated.

The complete album path, relative to the Music Directory must be given.

If the old path does not address a directory, False gets returned. No files will be overwritten.

In case the album addressed by oldalbumpath exists in the database, the function musicdb.mdbapi.music.MusicDBMusic.ChangeAlbumArtist() is used to keep the database updated.

Parameters

• oldalbumpath (str) – Path to the album directory inside the old artists directory

• newartistdirectory (str) – Name of the new artist directory in that the addressed album will be moved in.

Returns

True on success, otherwise False

Example

// Will succeed
MusicDB_Call("ChangeArtistDirectory", {
        oldalbumpath:       "Old Artist/2021 - Album Name",
        newartistdirectory: "Already Existing Artist"
        });

// Will succeed
MusicDB_Call("ChangeArtistDirectory", {
        oldalbumpath:       "Old Artist/2021 - Album Name",
        newartistdirectory: "New Artist"
        });

// Will succeed if album is known by the database
MusicDB_Call("ChangeArtistDirectory", {
        oldalbumpath:       "Old Artist/2021 - Album Name", // That album has already been moved by the user
        newartistdirectory: "New Artist"
        });


// Will fail because new artist directory contains a sub directory
MusicDB_Request("ChangeArtistDirectory", "ConfirmRename", {
        oldalbumpath:       "Old Artist/2021 - Album Name",
        newartistdirectory: "New Artist/subdirectory"
        });

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "ChangeArtistDirectory" && sig == "ConfirmRename")
    {
        if(args === true)
            console.log(`Renaming ${pass.oldfile} succeeded.`);
    }
}

FindAlbumSongFiles(albumpath)

This method returns a list of song files and information from the given album path.

Warning

Because this method is supposed to be used before the album has been imported into MusicDB, it is not checked and guaranteed that the returned paths are fulfilling the MusicDB naming scheme (See Music Naming Scheme).

The album path can address an album that has not been imported into the MusicDB yet. The whole method only works on file system level and does not interact with the database.

Beside the paths to the song files (relative to the music directory), some additional meta data is provided. These data can be used to validate the naming of the paths because they are not necessarily fulfilling the MusicDB music naming scheme. These additional data may also be wrong.

Note

Before importing a song, a user has to validate the data returned by this method.

If the album path is not a valid directory inside the music directory, an empty list gets returned.

Each list entry is a dictionary with the following information:

• path (string): relative path to the music file

• frommeta (dict): Song information collected from the files meta data

  • songname (string)

  • albumname (string)

  • artistname (string)

  • releaseyear (integer)

  • origin (string): Where the files comes from. Where it has been bought.

  • cdnumber (integer)

  • songnumber (integer)

  • haslyrics (boolean): True when there are lyrics attached to the song file

  • hasartwork (boolean): True when there is an album cover attached to the song file

• frompath (dict): Song information collected from the file path (keep in mind that this path is not yet verified by the user to be correct).

  • songname (string)

  • albumname (string)

  • artistname (string)

  • releaseyear (integer)

  • cdnumber (integer)

  • songnumber (integer)

The information inside the "frompath" dictionary is collected via musicdb.mdbapi.musicdirectory.MusicDirectory.AnalysePath(). When this method fails, None is stored under that key.

Parameters

albumpath (str) – path to an album that may have new/unknown songs. The path must be relative to the music directory.

Returns

A list of song file information of an album directory

FindNewContent()

This method uses musicdb.mdbapi.music.MusicDBMusic.FindNewPaths() to get all new albums and videos.

The lists of albums and videos contain objects with the following keys:

• For Videos:

  • "path": Path to the new video

  • "artistname":

  • "videoname":

  • "release":

  • "extension":

• For Albums:

  • "path": Path to the new album

  • "artistname":

  • "albumname":

  • "release":

Returns

"albums" and "videos". Each list entry is another object with the key listed in the description.

Return type

A dict with two listst

Example

MusicDB_Request("FindNewContent", "ListContent");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "FindNewContent" && sig == "ListContent")
    {
        console.log(args.albums);
        console.log(args.videos);
    }
}

InitiateFilesystemScan()

This method can be used to scan the file system and find lost paths inside the database. It does the following steps:

1. Check all database entries if the associated files and directories can be found via musicdb.mdbapi.music.MusicDBMusic.FindLostPaths()

2. If not, collect their database entry

3. Find all new files and directories via musicdb.mdbapi.music.MusicDBMusic.FindNewPaths()

4. Collect their path and check sum (this may take some time)

The returned information has the following structure

• "newpaths"

  • "artists", "albums", "songs", "filteredsongs", "videos"

    • Each entry is a list of paths as string

• "lostpaths"

  • "artists", "albums", "songs", "videos"

    • Each entry is a list of database entries as dictionary

The found information are annotated to the task

Returns

The task ID as string

Example

MusicDB_Call("InitiateFilesystemScan");

// …

function onMuiscDBNotification(fnc, sig, task)
{
    if(fnc == "MusicDB:Task" && sig == "StateUpdate")
    {
        if(task["state"] == "fsscancomplete")
            console.log(task["annotations"]);
    }
}

LoadWebUIConfiguration()

This method loads the configuration for the WebUI from the MusicDB data directory.

The configurations are described at webui

Example

MusicDB_Request("LoadWebUIConfiguration", "ShowConfig");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "LoadWebUIConfiguration" && sig == "ShowConfig")
    {
        console.log("Video mode is " + args.WebUI.videomode); // "enabled" or "disabled"
        console.log("Lyrics are " + args.WebUI.lyrics);       // "enabled" or "disabled"
    }
}

Returns

A dictionary with all configurations

RenameAlbumDirectory(oldpath, newpath)

Renames an album directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme).

If the album has an entry in the Music Database, its entry is updated as well. In this case the new path must fulfill the Music Naming Scheme. The update triggers musicdb.mdbapi.music.MusicDBMusic.UpdateAlbum(). This leads to updating the path, name, release and origin of an album.

The position of the album should be plausible anyway. So it must be placed inside an artist directory.

The complete path, relative to the Music Directory must be given. Anyway, the artist directories must not be different. Only the album directory name can be different.

If the old path does not address a directory, the Method returns False. If the new path does address an already existing file or directory, the method returns False as well. No files will be overwritten.

Parameters

• oldpath (str) – Path to the directory that shall be renamed

• newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

// Will succeed
MusicDB_Call("RenameAlbumDirectory", {
        oldpath:"Artist/2021 - Old Album Name",
        newpath:"Artist/2021 - New Album Name"
        });

// Will succeed, if the album has no entry in the database.
// Otherwise it fails because the file names violate the naming scheme.
MusicDB_Call("RenameAlbumDirectory", {
        oldpath:"Artist/Old Album Name",
        newpath:"Artist/New Album Name"
        });

// Will fail because artist name changed as well.
MusicDB_Request("RenameAlbumDirectory", "ConfirmRename", {
        oldpath:"Artist/Old Album Name",
        newpath:"New Artist/2021 - New Album Name"
        },
        {
        oldfile:"Old Album Name, Old Song Name.flac"
        });

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "RenameAlbumDirectory" && sig == "ConfirmRename")
    {
        if(args === true)
            console.log(`Renaming ${pass.oldfile} succeeded.`);
    }
}

RenameArtistDirectory(oldpath, newpath)

Renames an artist directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme).

If the artist has an entry in the Music Database, its entry is updated as well. In this case the new path must fulfill the Music Naming Scheme. The update triggers musicdb.mdbapi.music.MusicDBMusic.UpdateArtist(). This leads to updating the path, name, release and origin of all albums inside the artist directory.

The position of the artist should be plausible anyway. So it must be placed inside the music directory and not being a sub directory.

If the old path does not address a directory, the Method returns False. If the new path does address an already existing file or directory, False gets returned. No files will be overwritten.

To change the artist directory of an album see RenameArtistDirectory().

Parameters

• oldpath (str) – Path to the directory that shall be renamed

• newpath (str) – New name of the artist directory

Returns

True on success, otherwise False

Example

// Will succeed
MusicDB_Request("RenameArtistDirectory", "ConfirmRename", {
        oldpath:"Old Artist",
        newpath:"New Artist"
        });

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "RenameArtistDirectory" && sig == "ConfirmRename")
    {
        if(args === true)
            console.log(`Renaming ${pass.oldfile} succeeded.`);
    }
}

RenameMusicFile(oldpath, newpath)

Renames a song or video file. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme).

If the song has an entry in the Music Database, its entry is updated as well. In this case the new path must fulfill the Music Naming Scheme.

The position of the file should be plausible anyway. So a song file should be inside a artist/album/-directory, a video file inside an artist directory.

The complete path, relative to the Music Directory must be given. Anyway, the artist and album directories must not be different. Only the file name can be different.

If the old path does not address a file, the Method returns False. If the new path does address an already existing file, the method returns False as well. No files will be overwritten.

Parameters

• oldpath (str) – Path to the file that shall be renamed

• newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

// Will succeed
MusicDB_Call("RenameMusicFile", {
        oldpath:"Artist/2021 - Album Name/01 old file name.mp3",
        newpath:"Artist/2021 - Album Name/01 new file name.mp3"
        });

// Will succeed, if the song has no entry in the database.
// Otherwise it fails because the file names violate the naming scheme.
MusicDB_Call("RenameMusicFile", {
        oldpath:"Artist/2021 - Album Name/old file name.mp3",
        newpath:"Artist/2021 - Album Name/new file name.mp3"
        });

// Will fail if because album name changed as well
MusicDB_Request("RenameMusicFile", "ConfirmRename", {
        oldpath:"Artist/Old Album Name, Old Song Name.flac",
        newpath:"Artist/2021 - New Album Name/01 New Song Name.flac"
        },
        {
        oldfile:"Old Album Name, Old Song Name.flac"
        });

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "RenameMusicFile" && sig == "ConfirmRename")
    {
        if(args === true)
            console.log(`Renaming ${pass.oldfile} succeeded.`);
    }
}

SaveWebUIConfiguration(config)

This method saves the whole configuration back into the MusicDB data directory. The argument to this method must be a dict with the whole configuration as returned by LoadWebUIConfiguration()

The configurations are described at webui

This function should be called using the MusicDB_Broadcast method to allow propagating the changes to other connected clients. When using the request method the new configuration gets returned similar to LoadWebUIConfiguration().

Example

webuiconfig.WebUI.videomode = "enabled";
MusicDB_Broadcast("SaveWebUIConfiguration", "UpdateConfig", {config: webuiconfig});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "SaveWebUIConfiguration" && sig == "UpdateConfig")
    {
        console.log("Someone changed the configuration:");
        console.log("Video mode is " + args.WebUI.videomode); // "enabled" or "disabled"
        console.log("Lyrics are " + args.WebUI.lyrics);       // "enabled" or "disabled"
    }
}

Returns

A dictionary with all configurations

Other

class musicdb.lib.ws.mdbwsi.MusicDBWebSocketInterface

Find(searchstring, limit)

This method starts a search for searchstring on songnames, albumnames and artistnames. The returned value is a dictionary with the following entries:

• songs: A list of songs, each entry is a dictionary with the following information:

  • song: The song entry from the database

  • album: The related album entry from the database

  • artist: The related artist entry from the database

• albums: A list of albums, each entry is a dictionary with the following information:

  • album: The related album entry from the database

  • artist: The related artist entry from the database

• artists: A list of artists, each entry is a dictionary with the following information:

  • artist: The related artist entry from the database

  • albums: A list of all albums by this artist, ordered by release year

The search does not look for exact matching. It looks for most likeliness. So, typos or all lowercase input are no problem.

The list of songs will not contain any hated or disabled songs.

Parameters

• searchstring (str) – The string to search for

• limit (int) – max number entries that will be returned for each category

Returns

A dictionary with the search-results

Example

MusicDB_Request("Find", "ShowResults", {searchstring:"cake", limit:5});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "Find" && sig == "ShowResults")
    {
        for(let entry of args.songs)
            console.log(entry.name);
        for(let entry of args.albums)
            console.log(entry.name);
        for(let entry of args.artists)
            console.log(entry.name);
    }
}

GetAudioStreamState()

This method returns the state of the Streaming Thread. (See Audio Streaming Server)

The state is a dictionary that has always the following information:

• isconnected: True if MusicDB is connected to Icecast, otherwise False

• isplaying: True if the Streaming Thread is in playing-mode, otherwise False

• hasqueue: True when there is at least one song in the queue. When False, the following song information are not included!

In case there is a at least one song in the queue, this current streamed song gets returned with the following information:

• song: The song entry from the database for the song that is currently playing

• album: The related album entry from the database

• artist: The related artist entry from the database

• songtags: a list of tags as returned by GetSongTags()

• albumtags: a list of tags as returned by GetAlbumTags()

Returns

The current state of the streaming thread

Example

MusicDB_Request("GetAudioStreamState", "ShowStreamState");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetAudioStreamState" && sig == "ShowStreamtate")
    {
        if(args.isconnected == true)
        {
            console.log("Connection to Icecast established");
        }
        if(args.hasqueue == true)
        {
            console.log("Current playing song: " + args.song.name);
        }
    }
}

GetMDBState()

This method returns the current global state of the MusicDB WebUIs

Currently, the only state existing is the list of selected genres.

The state is a dictionary with the following information:

• albumfilter: a list of tag-names of class Genre

• MusicDB:

  • uimode: Defines if UI is in "audio" or "video" mode

• audiostream

  • isconnected: True if MusicDB is connected to Icecast, otherwise False

  • isplaying: True if the Streaming Thread is in playing-mode, otherwise False

  • currentsong: The song entry from the database for the song that is currently playing or None

• videostream

  • isstreaming: True if MusicDB manages the video stream

  • isplaying: True if the Streaming Thread is in playing-mode, otherwise False

  • currentvideo: The video entry from the database for the video that is currently playing or None

Returns

Current global MusicDB WebUI state

Example

MusicDB_Request("GetMDBState", "ShowMDBState");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetMDBState" && sig == "ShowMDBState")
    {
        console.log(args.MusicDB.uimode);

        let activetags;
        activetags = args.albumfilter;
        for(let genrename of activetags)
            console.log(genrename);
    }
}

GetTables(tablenames)

Returns a dictionary that contains for each requested table a key. Behind this key is a list of dictionaries representing the rows of the requested table.

If tablenames is None, the result is an empty dictionary.

The following list shows all valid names and links to the database calls that returned lists will be returned by this method.:

• "songs": musicdb.lib.db.musicdb.MusicDatabase.GetAllSongs()

• "albums": musicdb.lib.db.musicdb.MusicDatabase.GetAllAlbums()

• "artists": musicdb.lib.db.musicdb.MusicDatabase.GetAllArtists()

• "tags": musicdb.lib.db.musicdb.MusicDatabase.GetAllTags()

Parameters

tablenames (list of strings) – A list of table names.

Returns

A dict of lists of database entries

Example

MusicDB_Request("GetTables", "ShowTables", {position:["songs", "albums"]});

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetTables" && sig == "ShowTables")
    {
        console.log("Tags of the song with the ID " + args.songid);
        for(let song of args.songs)
            console.log(song.name);
        for(let album of args.albumss)
            console.log(album.name);
    }
}

GetVideoStreamState()

This method returns the state of the Video Streaming Thread. (See Video Streaming Server)

The state is a dictionary that has always the following information:

• isstreaming: True if MusicDB manages the video stream

• isplaying: True if the Streaming Thread is in playing-mode, otherwise False

• hasqueue: True when there is at least one song in the queue. When False, the following song information are not included!

• currententry: (string) UUID of the current entry in the queue - the video that gets streamed, or null.

In case there is a at least one song in the queue, this current streamed song gets returned with the following information:

• video: The video entry from the database for the video that is currently playing

• artist: The artist entry from the database related to the video

• videotags: a list of tags as returned by GetVideoTags()

Returns

The current state of the streaming thread

Example

MusicDB_Request("GetVideoStreamState", "ShowStreamState");

// …

function onMusicDBMessage(fnc, sig, args, pass)
{
    if(fnc == "GetVideoStreamState" && sig == "ShowStreamtate")
    {
        if(args.hasqueue == true)
        {
            console.log("Current playing video: " + args.video.name);
        }
    }
}

PlayNextSong()

This method skips the current playing song. If there is no song that can be skipped, the Song Queue or Streaming Thread will handle this properly.

Returns

None

Example

MusicDB_Call("PlayNextSong");

PlayNextVideo()

This method skips the current playing video. If there is no video that can be skipped, the Video Queue or Streaming Thread will handle this properly.

Returns

None

Example

MusicDB_Call("PlayNextVideo");

SetAudioStreamState(state)

This method can be used to set the playing-state of the audio stream (see Audio Streaming Server)

The following arguments are possible:

• "play": Set state to playing. If there are songs in the queue, MusicDB starts streaming.

• "pause": Set state to pause.

• "playpause": Toggle between playing and pause

Parameters

state (str) – New playing-state for the audio streaming thread. state must be one of the following strings: "playpause", "play" or "pause".

Returns

None

Example

MusicDB_Call("SetAudioStreamState", {state:"playpause"});

SetMDBState(category, name, value)

This method sets the global state of MDB clients

If the state is not available in the global state settings, it will be created.

When the category is "albumfilter", then name must be a Genre-Name and value is True or False. If a genre gets set to true, all albums for that genre are included in the list of returned albums by methods that use the filter.

After executing this method, the MusicDB server broadcasts the result of GetMDBState(). (method = "broadcast", fncname = "GetMDBState") So each client gets informed about the new state.

The category must be "albumfilter" or "MusicDB" with name "uimode"! To set the album filter, Set() is used. For setting the UI mode, SetUIMode() is called. Details of valid modes are listed there as well.

Parameters

• category (str) – Category of the state

• name (str) – Name of the sate

• value – Value of the state

Returns

None

Example

MusicDB_Call("SetMDBState", {category:"albumfilter", name:"Metal", value:true});

SetVideoStreamState(state)

This method can be used to set the streaming-state of the video stream (see Video Streaming Server)

The following arguments are possible:

• "play": Set state to playing. If there are songs in the queue, MusicDB starts streaming.

• "pause": Set state to pause.

• "playpause": Toggle between playing and pause

Parameters

state (str) – New streaming-state for the video streaming thread. state must be one of the following strings: "playpause", "play" or "pause".

Returns

None

Example

MusicDB_Call("SetVideoStreamState", {state:"playpause"});