## 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.
Command | Arguments, Effect and Return Values | Version
empty | Returns a simple HTML form for testing the MusicIP Mixer API. |
artists | Returns a list of all the artists. Parameters are:
filter=name | Use 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
showCount | Prefix each artist with the number of songs by that artist
| 1.1.3
albums | Returns a list of all the albums. Parameters are:
artist=name | Only include albums with at least one song by the named artist
bysong | Return key song from each album (useful for other api calls) 1.5
extended | Return album in artist@@name format 1.5
filter=name | Use 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
showCount | Prefix 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:
contents | Only 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
short | Return short-style names (Windows only) 1.1.4
| 1.1.3
filters | Returns a list of all the filters. Parameters are:
showCount | Prefix 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=name | Use the named filter when creating the list (default none) 1.6
showCount | Prefix each genres with the number of songs in that genre
| 1.1.3
getCurrentMixGenre | Returns 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
getCurrentRejectSize | Returns 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
getCurrentRejectType | Returns 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
getCurrentMixSize | Returns 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
getCurrentMixSizeType | Returns 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
getCurrentMixStyle | Returns 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
getCurrentMixVariety | Returns 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
getCurrentTrack | Returns the full path of the currently playing track, if any. Paused tracks still count as current. (Windows only) | 1.8
getLastPlayed | Returns the timestamp the song was last played. Parameters are:
song=fullpath | Choose a song
Returned value is the timestamp, or -1 if the song was not recognized. | 1.1.5
getLyrics | Returns the lyrics of the indicated song. Parameters are:
song=fullpath | Choose a song
Returned value is the lyrics, if present. | 1.1.3
getPlayCount | Returns the play count of the indicated song. Parameters are:
song=fullpath | Choose a song
Returned value is the play count, or -1 if the song was not recognized. | 1.1.5
getPlaylist | Returns 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
short | Return short-style names (Windows only) 1.1.4
index=listindex |
name=listname |
detail | Return the playlist attributes instead of the contents. Returned fields may include name, file, added, modified.1.1.5
| 1.1.3
getRating | Returns the rating of the indicated song. Parameters are:
song=fullpath | Choose 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:
index | Choose a song by index
file | Choose 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
getStatus | Returns a string describing the current mixer status. Current values include `adding`, `analyzing` and `idle`. | 1.1.5.1
incrementPlayCount | Increment the play count of the indicated song by one. Parameters are:
song=fullpath | Choose 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=fullpath | Choose a seed song
artist=name | Choose a seed artist
album=fullpath | Choose a seed album. fullpath is any song from the album
album= artistname@@ albumname | Choose a seed album. (example: "The Beatles@@The White Album")
mixgenre=boolean | Restrict mix to the genre of the seed 1.1.6
mood=name | Make a mood mix based on the given mood 1.5
playlist=name||fullpath | Choose all songs in the playlist as seeds 1.1.5.1
recipe=name | Use 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=name | Use 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
short | Return 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:
detail | Return 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
setLastPlayed | Set the time the indicated song was last played. Parameters are:
force | Set time even if less than currently stored 1.5
song=fullpath | Choose a song
time=timestamp | The 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
setPlayCount | Set the play count of the indicated song. Parameters are:
force | Set count even if less than currently stored 1.5
count=number | The new play count
song=fullpath | Choose a song
Returned value is the number of songs which were changed. | 1.1.5
setRating | Set the rating of the indicated song. Parameters are:
song=fullpath | Choose a song
rating=number | The new rating, 0-5.
Returned value is the number of songs which had ratings changed. | 1.1.3
shutdown | Exit the mixer | 1.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=fullpath | Only include songs from the named album. fullpath is any song from the album
album= artistname@@ albumname | Only include songs from the named album. (example: "Pink Floyd@@Dark Side of the Moon")
artist=name | Only include songs by the named artist
content= (json|m3u|text|xspf) | Set the returned mime type (default text) json|xspf requires 1.5
filter=name | Use 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
extended | Return extended info for each song (as in the getSong command). This ignores the content and short options.1.5
short | Return short-style names (Windows only)
| 1.1.5.1
status | Return the status of the indicated item. Parameters are:
song=fullpath | Choose a song
artist=name | Choose 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. |