MusicIP Mixer Help - HTTP Protocol

The MusicIP Mixer API is a HTTP based protocol for third party applications to interact programmatically with the MusicIP Mixer. The same API works for our Windows, Linux, and Mac products, so you can support all these platforms with one set of code.

In order to use this API, you must have a running copy of the MusicIP Mixer.


To start the MusicIP Mixer API, go to the Services section of the preferences dialog, select MusicIP Mixer API, and press start. If you exit MusicIP Mixer with services running, they will restart automatically when MusicIP Mixer restarts.

This will cause MusicIP Mixer to accept connections on the Server Port as though it were an http server. You can test the API by pointing a web browser to the appropriate port (e.g. http://localhost:10002) where localhost is the machine running MusicIP Mixer, and 10002 is the port passed to mmserver.

The following commands are supported. All urls must be preceeded with "/api/" (for example: http://localhost:10002/api/shutdown). As we get more use out of the API, we expect the number of available commands to increase. If the version listed is higher than the current release version, this means the command is only available in a development or beta build, but will be available in the indicated release.

CommandArguments, Effect and Return ValuesVersion
emptyReturns a simple HTML form for testing the MusicIP Mixer API. 
artists Returns a list of all the artists. Parameters are:
filter=nameUse the named filter when creating the list (default none)
If there is no such filter the name may refer to a genre as an implicit filter. 1.5
showCountPrefix each artist with the number of songs by that artist
1.1.3
albums Returns a list of all the albums. Parameters are:
artist=nameOnly include albums with at least one song by the named artist
bysongReturn key song from each album (useful for other api calls) 1.5
extendedReturn album in artist@@name format 1.5
filter=nameUse the named filter when creating the list (default none)
If there is no such filter the name may refer to a genre as an implicit filter. 1.5
showCountPrefix each album with the number of songs on that album
1.1.5.1
cacheid Returns the timestamp when the cache was last modified. Parameters are:
contentsOnly show when contents were last modified (songs, playlists, analysis info) 1.1.5.1
1.1.3
duplicates Returns a list of all the songs which have duplicates (same as Library/List Duplicates). Parameters are:
content= (json|m3u|text|xspf)Set the returned mime type (default text)
json|xspf requires 1.5
shortReturn short-style names (Windows only) 1.1.4
1.1.3
filters Returns a list of all the filters. Parameters are:
showCountPrefix each filter with the number of songs in that filter
1.1.3
flush Flush any changes made to the current cache. There are no parameters. On success, it returns the number 1 (as text). On failure, it returns the number 0 (as text). 1.7
genres Returns a list of all the genres. Parameters are:
filter=nameUse the named filter when creating the list (default none) 1.6
showCountPrefix each genres with the number of songs in that genre
1.1.3
getCurrentMixGenreReturns the current settings of the "Restrict mix to selected genre" flag, which will be used by the mix command. This is the same as the current user setting in the application. 1.1.6
getCurrentRejectSizeReturns the current size which will be used to limit duplicate artists by the mix command. This is the same as the current user setting in the application. 1.1.6
getCurrentRejectTypeReturns the current type which will be used to limit duplicate artists by the mix command. This is the same as the current user setting in the application. 1.1.6
getCurrentMixSizeReturns the current mix size which will be used by the mix command. This is the same as the current user setting in the application. 1.1.4
getCurrentMixSizeTypeReturns the current mix size type which will be used by the mix command. This is the same as the current user setting in the application. The return value is tracks, min, or mbytes. 1.1.4
getCurrentMixStyleReturns the current mix style which will be used by the mix command. This is the same as the current artist style user setting in the application. 1.1.4
getCurrentMixVarietyReturns the current mix variety which will be used by the mix command. This is the same as the current variety user setting in the application. 1.1.4
getCurrentTrackReturns the full path of the currently playing track, if any. Paused tracks still count as current. (Windows only) 1.8
getLastPlayedReturns the timestamp the song was last played. Parameters are:
song=fullpathChoose a song
Returned value is the timestamp, or -1 if the song was not recognized.
1.1.5
getLyricsReturns the lyrics of the indicated song. Parameters are:
song=fullpathChoose a song
Returned value is the lyrics, if present.
1.1.3
getPlayCountReturns the play count of the indicated song. Parameters are:
song=fullpathChoose a song
Returned value is the play count, or -1 if the song was not recognized.
1.1.5
getPlaylistReturns the list of filenames for all songs in the indicated playlist. Parameters are:
content= (json|m3u|text|xspf)Set the returned mime type (default text) 1.1.4, json|xspf requires 1.5
shortReturn short-style names (Windows only) 1.1.4
index=listindex 
name=listname 
detailReturn the playlist attributes instead of the contents. Returned fields may include name, file, added, modified.1.1.5
1.1.3
getRatingReturns the rating of the indicated song. Parameters are:
song=fullpathChoose a song
Returned value is the rating 0-5, or -1 if the song was not recognized.
1.1.3
getSong Returns information about the indicated song. Parameters are:
indexChoose a song by index
fileChoose a song by file
Returned value is a list of attributes, 1 per line. The first word is the field name, and the rest of the line is the field value. Some fields may not be present if there is no associated value. Current fields are:
name, artist, album, album-id, file, genre, track, active, seconds, bytes, year, bitrate, composer, conductor, orchestra, lyricist, rating, modified, lastplayed, playcount, added
1.1.3
getSongCount Returns the number of songs currently in the cache. 1.1.3
getStatusReturns a string describing the current mixer status. Current values include adding, analyzing and idle. 1.1.5.1
incrementPlayCountIncrement the play count of the indicated song by one. Parameters are:
song=fullpathChoose a song
Returned value is the number of songs affected (0 if the song was not recognized).
1.1.5
mix Return a dynamic playlist. Parameters are:
song=fullpathChoose a seed song
artist=nameChoose a seed artist
album=fullpathChoose a seed album. fullpath is any song from the album
album= artistname@@ albumnameChoose a seed album. (example: "The Beatles@@The White Album")
mixgenre=booleanRestrict mix to the genre of the seed 1.1.6
mood=nameMake a mood mix based on the given mood 1.5
playlist=name||fullpathChoose all songs in the playlist as seeds 1.1.5.1
recipe=nameUse the indicated recipe when making the mix (Windows only) 1.8
rejectsize=#Set the number of items to skip before repeating artists 1.1.6
rejecttype= (tracks|min|mbytes)Set the units for rejectsize (default tracks) 1.1.6
size=#Set the size of the list (default 12)
sizetype= (tracks|min|mbytes)Set the units for size (default tracks)
style=#Set the style slider (default 20, range is 0..200)
variety=#Set the variety slider (default 0, range is 0..9))
filter=nameUse the named filter when creating the playlist (default none)
If there is no such filter, the name may refer to a genre as an implicit filter.
content= (json|m3u|text|xspf)Set the returned mime type (default text)
json|xspf requires 1.5
shortReturn short-style names (Windows only) 1.1.4
You may specify any number of songs, artists or albums as seeds, but you may not mix different types in a single request. If no seeds are set, a random song will be chosen from within the current filter.

As of version 1.1.4, the above default values are replaced with the current application settings from the mix preferences (on some platforms).
1.1.3
moods Returns a list of all the moods. Call this without parameters. This will only return information on platforms supporting the Moods menu. 1.5
playlists Returns a list of all the playlists. Normally you would call this without parameters, but you can pass the following:
detailReturn full attributes for each playlist. Attributes may include: name, file, added, modified. Each playlist will be separated with a blank line in this mode 1.1.5
1.1.3
recipes Returns a list of all the recipes. Call this without parameters. This will only return information on platforms supportings recipes (headless on all platforms, and Windows 1.8 or later). 1.8
setLastPlayedSet the time the indicated song was last played. Parameters are:
forceSet time even if less than currently stored 1.5
song=fullpathChoose a song
time=timestampThe new timestamp, either in seconds from 0 hours, 0 minutes, 0 seconds, January 1, 1970, or as follows: 2005-02-22T23:56:06Z. You may also use the word "now" to set the last played time to the current time.
Returned value is the number of songs which were changed.
1.1.5
setPlayCountSet the play count of the indicated song. Parameters are:
forceSet count even if less than currently stored 1.5
count=numberThe new play count
song=fullpathChoose a song
Returned value is the number of songs which were changed.
1.1.5
setRatingSet the rating of the indicated song. Parameters are:
song=fullpathChoose a song
rating=numberThe new rating, 0-5.
Returned value is the number of songs which had ratings changed.
1.1.3
shutdown Exit the mixer1.1.3
songs Returns a list of all the songs (as a playlist). As of version 1.5, if you pass no artists or albums, all songs are returned. Parameters are:
album=fullpathOnly include songs from the named album. fullpath is any song from the album
album= artistname@@ albumnameOnly include songs from the named album. (example: "Pink Floyd@@Dark Side of the Moon")
artist=nameOnly include songs by the named artist
content= (json|m3u|text|xspf)Set the returned mime type (default text)
json|xspf requires 1.5
filter=nameUse the named filter when creating the playlist (default none)
If there is no such filter the name may refer to a genre as an implicit filter. 1.5
extendedReturn extended info for each song (as in the getSong command). This ignores the content and short options.1.5
shortReturn short-style names (Windows only)
1.1.5.1
statusReturn the status of the indicated item. Parameters are:
song=fullpathChoose a song
artist=nameChoose a artist
Returned value is an integer.
0==> item cannot be used to create mixes
1==> item can be used to create mixes
1.1.3
version Return the version number of the current mixer as text.1.1.3

There are also several methods available for working with custom tags.