The Muse server is a highly concurrent system that allows you to control/play and manipulate your audio tracks, albums and playlists etc. Muse also supports TIDAL or Deezer streaming services for access to online content in addition to your own offline audio files.
The format of the protocol is that of an XML stream using a simple structure making it as easy as possible for systems that don't have native XML support to work with and debug. For example you will not see any XML attributes used so as to facilitate easy parsing. Line delimiters and tabs etc are irrelevant in xml so you can format it for easier reading if you wish. Just bear in mind that formatting means sending more bytes. Don't rely on line delimiters as part of the structure when parsing responses.
It is a requirement to send an XML declaration as the first thing sent to the server so the session can be configured, subsequent declarations can be omitted and if sent will be ignored. Responses of any type will be encoded as per the initial encoding specified. In an attempt to keep overhead down and to simplify parsing for legacy systems, an XML declaration is not supplied as part of any response/event.
When specifying an encoding in the XML declaration, make sure that you are able to encode/decode data in that particular encoding, otherwise you will get unwanted results.
You can connect to the server using port 43000 for unencrypted sessions and port 43443 for encrypted SSL(TLS) ones.
XML Declarations Supported:
<?xml version="1.0" encoding="US-ASCII"?>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-16"?>
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml version="1.0" encoding="UTF-16LE"?>
<?xml version="1.0" encoding="UTF-16BE"?>
Protocol messages are divided up into the following categories as follows:
A request message is the message type that you send to the server, usually with the intention of retrieving data from the server. But also for organizing the data on the server, or controlling playback of audio files. All messages over a single connection to the server are queued. You could for example use one client connection to the server to send and receive all messages, however it is much more efficient to have multiple client connections based upon some kind of logical mapping for example a connection per user. Each connection is handled in its own concurrent thread on the server, with the number the of simultaneous connections only restricted by the available resources of the server, which could be in the hundreds or thousands depending on the server specification and configuration. In large-scale real-world deployments, saturating the maximum number of simultaneous connections shouldn't be a concern.
If you want to send a playback request to the server you would for example send a request that said which player id you wanted to control and what index of the player queue you wish to start playing from. (Each player has a player queue associated with it so that audio playback continues whether you are connected to the server or not.)
When sending requests to the the server, all requests must contain a client id. This is an unique identifier that is not used by the server internally and is for clients to use as they wish for example for debugging and/or mapping responses to requests client-side.
Some requests require a player id. A player id is a numeric entry (starting at 1) identifying which audio player you wish that message to be routed to.
<sireq>
<cid>client1</cid>
<fn>
<play>
<id>255</id>
<ix>32</ix>
</play>
</fn>
</sireq>
A request for albums listings would take the form of (see protocol section for further details):
<sireq>
<cid>client2</cid>
<fn>
<getAlbums>
<ixs>
<i0>0</i0>
<i1>9</i1>
</ixs>
</getAlbums>
</fn>
</sireq>
Streaming service requests require a user id. The user id is necessary to ensure that the correct streaming service user session is used for these requests.
For simple requests you receive back the same data as the request you sent the server, but with the root-tag changed to the response tag as an acknowledgment. For requests that retrieve data, you get back a response that not only contains the info you supplied as part of the request, but also the data that was requested. This is to aid platforms with asynchronous I/O which lack concurrent tools to facilitate safe multi-threading.
<siresp>
<cid>client1</cid>
<fn>
<play>
<id>255</id>
<ix>32</ix>
</play>
</fn>
</siresp>
An example response for a more complex request type would look something like the following (see protocol section for further details):
<siresp>
<cid>client1</cid>
<fn>
<getAlbums>
<ixs>
<i0>0</i0>
<i1>9</i1>
</ixs>
<tn>30</tn>
<n>2</n>
<col>
<al>
<alid>432546325432</alid>
<alnm>Lungs</alnm>
<arnm>Florence and the Machine</arnm>
<arid>432546325432</arid>
<trco>13</trco>
<cv>http://10.5.0.39:8080/art.cgi?id=EF1223232&fm=png</cv>
</al>
<al>
<alid>453454345</alid>
<alnm>All I Ever Wanted</alnm>
<arnm>Kelly Clarkson</arnm>
<arid>432546325432</arid>
<trco>13</trco>
<cv>http://10.5.0.39:8080/art.cgi?id=EF1223234&fm=png</cv>
</al>
</col>
</getAlbums>
</fn>
</siresp>
Event Message
Events need to be registered for. You can use requests to register and unregister for event feedback. Events are asynchronous feedback that send you an update when something happens, for example when a track finishes, or when someone else changes the state of the same audio-player you are interested in. You can register for events for one or many players. When you disconnect from the server you are automatically unregistered from all players you registered events for. You can register and unregister at any time.
<sireq>
<cid>client1</cid>
<fn>
<regForEvents>
<id>234</id>
<id>234</id>
</regForEvents>
</fn>
</sireq>
An example event would look something like the following (see protocol section for further details):
<sievnt>
<playerStatus>
<end>1</end>
<stat>
<pid>2</pid>
<ctm>30</ctm>
<pau>on</pau>
<ply>on</ply>
<shf>off</shf>
<rep>ITEM</rep>
<tr>
<trid>432546325432</trid>
<trnm>Dark days are over</trnm>
<arnm>Florence and the Machine</arnm>
<arid>432546325432</arid>
<alnm>Lungs</alnm>
<alid>432546325432</alid>
<dura>350909</dura>
<cv>http://10.5.0.39:8080/albumart/123456.png</cv>
<grid>343443344344</grid>
<grnm>rock</grnm>
</tr>
</stat>
</playerStatus>
</sievnt>
Error Message
Error messages are sent back to you when things go wrong, for example if you send a malformed request, or maybe you haven't sent an xml declaration. The content of some error messages are mostly for debugging purposes and useful for the Muse developers if a bug is found. All messages respond with their own specific exception so that it makes it easy to identify from what command generated the exception. Exception names are the same name as the request except request is replaced with the word Exception. If you find an unusual bug or behavior then please email the bug and error message to info@tyba.co.uk An example error response may look like the following:
<siresp>
<cid>10.5.0.23:2042</cid>
<fn>
<error>
<nm>AddAllToPlayerException</nm>
<msg>You specified index 23 to play, but there are only 5 tracks in the queue!</msg>
<debug></debug>
</error>
</fn>
</siresp>