This document is intended to extend and eventually replace this document. Please refer to that PDF for an extensive accounting of all commands that existed at the time of its creation.

We categorize control of a Mirage Media Server (MMS) into four categories:

• Connecting and the preamble

• Events

• Control

• Browsing & content selection

• Presets

• Playlists

• Now Playing

• Album Art

For information regarding using the HTTP JSON API endpoints, see the end of this document.

An MMS is controlled via a socket or telnet connection to port 5004 on the device's IP address. Commands sent and responses received are terminated with a carriage return and a line feed. Commands commonly used in a connection preamble will be briefly defined here but will have a more complete definition later.

A typical initialization sequence looks like:

SetClientType DemoClient identifies the control client to the MMS. This command takes a single string argument.

SetClientVersion 1.0.0.0 allows the control client to set a version. We strongly recommend setting a client version. This will allow the server to react to client version changes if necessary. This command takes a version string in the format MAJOR.MINOR.BUILD.REVISION

SetHost 192.168.0.100 tells the server the address the client used to connect to the MMS so the MMS can use that address when generating URLs for cover art in certain protocol responses instead of the MMS' default IP. In this example, the client is connecting to the MMS at 192.168.0.100. It is only necessary to send this command in non-local network configurations or non-flat network configurations where the IP the client is using for the MMS may not be the local IP of the MMS, but is not harmful to use in less complex scenarios. Setting it to an address at which the MMS cannot be found will cause a degradation in performance and behavior. This command takes a single string argument.

SetXmlMode Lists tells the MMS to send any lists as XML instead of text mode. This is recommended if the control client supports XML. This command takes a string argument where that argument is None or Lists.

SetEncoding 65001 tells the MMS to send data as UTF-8. There are other encodings available but 65001 will be the encoding of choice most of the time.

SetInstance Player_A sets which output subsequent browse and control commands are intended for.

SubscribeEvents tells the MMS to send events related to the currently selected instance as they occur. This command takes an optional boolean argument or a comma delimited list of events to limit the subscription to. If missing, the value is assumed to be true, which subscribes the control client to all events. The client will remain subscribed for the duration of its connection. The subscription will follow the client from instance to instance. No resubscription is necessary. Events for the selected or default instance are pushed to the connected client. To get events from another instance, see SetInstance.

GetStatus requests that all events related to the selected instance be sent now.

In some cases, especially when writing a control client not known to MMS, it may be necessary to set some additional options that MMS presumes for known clients. Use the SetOption command during the connection preamble. Here are list of those options:

The MMS communicates data back to its control clients through events. These events carry information about the current state of the server. They can also be used to request input from the user. Some events inform the control client about the availability of various functions while others tell the control client to take some action.

Events follow a simple format:

and will look like:

or

There are four lines of metadata and four metadata labels.

MetaData1 is generally reserved for radio station names or for track count data.

MetaData2 is generally reserved for the artist name.

MetaData3 is generally reserved for the album name.

MetaData4 is generally reserved for the track name.

MetaLabelx events will always provide the label for the corresponding MetaDatax field. MetaLabel1 follows MetaData1, MetaLabel2 follows MetaData2, etc. There are four MetaLabelx events

An example of these events:

Now Playing Art is handled by providing a few separate events.

NowPlayingGuid provides the ID of the now playing item. For example, {20dd901a-b092-3386-dc16-6b56f38a811e}

BaseWebUrl provides the protocol, address, and port portions of the URL to retrieve art from. For example: <http://192.168.0.59:5005.>

For further details, see the Album Art section below.

Track time is provided in seconds. A track duration may be provided, depending on the source of the content.

TrackTime indicates track position in seconds as a non-negative integer.

TrackDuration indicates the total number of seconds in the track as a non-negative integer.

In cases where the content does not have a total time (like a broadcast radio station from TuneIn), TrackDuration will be 0.

In such cases where the MMS has neither a track length nor a current track position, both TrackTime and TrackDuration will be 0.

MediaControl and PlayState both indicate the play state of the output. They have slightly different values but ultimately have the same meaning.

PlayState will be one of the following: Playing, Paused, or Stopped

MediaControl will be one of the following: Play, Pause, or Stop

All these events hold a true|false value and indicate whether a certain functionality is available.

Back defines whether or not there is anything in the navigation stack. If true, use Back <int> to jump back <int> number of pages. The navigation stack begins with 0. 0 is the current page.

BrowseNowPlayingAvailable defines whether a queue is available to browse. This will be true when the queue has more than 0 items even the now playing item is a radio station.

ContextMenu defines whether or not AckButton CONTEXT is a valid command and the TuneBridge™ button should be shown.

Mute defines whether or not the set instance is muted.

PlayPauseAvailable defines whether or not the Play, Pause, and PlayPause are valid and the Play or Pause button should be shown.

RepeatAvailable defines whether or not Repeat is a valid command and the Repeat button should be shown.

Repeat defines whether Repeat is enabled or disabled.

SeekAvailable defines whether or not Seek is a valid command and the scrubbing thumb should be shown on the track progress meter.

ShuffleAvailable defines whether or not Shuffle is a valid command and the Shuffle button should be shown.

Shuffle defines whether or not Shuffle is enabled or disabled.

SkipNextAvailable defines whether or not SkipNext is a valid command and the Skip Next button should be shown.

SkipPrevAvailable defines whether or not SkipPrevious is a valid command and the Skip Previous button should be shown.

Some values have more than two states and therefore cannot be represented as true|false values.

ThumbsUp indicates the state of the Thumbs Up button and whether the ThumbsUp command is available. ThumbsDown is identical to ThumbsUp, replacing Up with Down in all cases. Possible states are -1, 0, and 1 where:

-1 indicates the button is disabled and the command is not available.

0 indicates the button is enabled but not set and the command is available.

1 indicates the button is both enabled and set and the command is available.

At the time of writing, no online service still uses a Stars rating system. However...

Stars indicates the state of the stars and whether the SetStars command is available. States range from -1 to 5 where:

-1 indicates stars are disabled and the command is not available.

0 - 5 indicate stars are enabled and should be showing the number of stars indicated in the value. The command is also available.

Play will tell the MMS to play.

Pause will tell the MMS to pause.

PlayPause will toggle the play state between play and pause.

Seek <int> where <int> is either a non-negative integer between 0 and the value of TrackDuration or a negative integer between -1 and -1 * <valueOfTrackDuration>. When <int> is non-negative, the playback position will be moved relative to the start of the track. When <int> is negative, the playback position will be moved relative to the end of the track.

SkipNext skips to the next track. This command is governed by the SkipNextAvailable event.

SkipPrevious skips to the previous track if the value of TrackTime is less than 5. Otherwise, it restarts the current track if allowed by the given service. This command is governed by the SkipPrevAvailable event.

ThumbsUp toggles the ThumbsUp state between 0 and 1. This command is governed by the ThumbsUp event.

ThumbsDown toggles the ThumbsDown state between 0 and 1. This command is governed by the ThumbsDown event. On some services, setting the ThumbsDown state to 1 will also skip to the next track.

SetVolume sets the volume on the selected output. It takes a single integer argument from 0-50. The selected output must be in variable gain mode, as configured on the System tab of the device’s configuration page.

All browsing on an MMS is done through the same basic format.

Browse<Container> <start> <count>

where <Container> is the target browse type, <start> is the one-based index the returned list should start from, and <count> is the number of items the returned list should contain at most. For example:

BrowseArtists 1 10 will return 10 artists starting at item 1.

BrowseArtists 11 10 will return 10 artists starting at item 11.

Depending on whether SetXMLMode is set, the response may be in either text mode or XML mode. As above, we strongly recommend XML if the control environment supports it as it offers more information.

Every browse item has a default action based on its type. We'll go over these default actions later on. These default actions can be superseded with attributes on each item.

action defines the secondary action to perform if the user presses the the action button for that item.

listAction defines the action to perform if the user presses the list item itself.

browseAction defines the action to perform after doing the default action for that item or doing the listAction if one exists.

artGuid provides the guid to use if displaying art in the browse (See the Album Art section below). If this attribute is missing, use the value of the guid.

button provides an integer value that indicates which secondary action to offer on that item. The value of this attribute is defined by this table

dna provides the name of the attribute containing the value to use for display.

guid provides the item's ID for use in any action.

hasChildren indicates whether that menu item is a branch (1) or a leaf (0).

name provides the name of the item.

Picklists are a way for the server to generically present a list to the control client without the control client needing any additional information about that menu. All online content uses Picklists. Some local menus are Picklists. Given their frequency, we must go over them first.

Picklists are always browsed using the BrowsePicklist command. In some cases, performing an item's action, listAction, or browseAction might result in a Picklist when that item's default action would not. A good example of this is when selecting local content for playback. The list items each have a listAction that results in an intent clarification menu as a picklist that is sent to the client without the need of BrowsePicklist.

Picklist items are selected with the AckPickItem <guid> command if there is no listAction attribute present.

Local content can be browsed in whatever order is desired by the control client. However, most clients follow this pattern:

Albums => Tracks

Artists => Albums => Tracks

Composers => Tracks

Favorites

Genres => Albums => Tracks

Playlists => Tracks

To browse a top level list, simply clear the Music Filter using SetMusicFilter Clear, then send the appropriate Browse command. Valid commands are listed at the bottom of this section.

All online sources are Picklist trees branching from BrowseRadioSources. The response to BrowseRadioSources is a list of RadioSources. To select a specific service, use SetRadioFilter Source=<guidOfService>. Subsequently, use the value of the intended online service. This example assumes SetPickListCount has been set. The example browses Pandora.

To ease access to preferred accounts, we support selecting an account to be preselected in a streaming services' menu. This setting must be reapplied when the control client reconnects as its lifetime is that of the connection. This capability is supported always but only useful if more than one account per service is configured.

To select a specific account, a list of available accounts is required. The BrowseServiceAccounts command works just like all the other commands. Paging is supported but not necessary as it is unlikely that there are more accounts than can be processed in a single chunk.

Setting the preferred account for a given service requires both the service's guid (obtained via the BrowseRadioSources command) and the account's guid (obtained via the BrowseServiceAccounts command). Use both values when using the SetServiceAccount command. Here, we select the pandora@example.com account for the Pandora service.

Subsequently, browsing the top menu for Pandora will be that account.

This command can also be latching per output. This means that it is possible to set a given account as default on a given output of an MMS. Do this by appending False to the end of the above command. For example:

Clearing latched accounts for a service or all services on an output can be done with the following two commands:

where Service is replaced by the name or GUID of the streaming service

or

More details on this command can be found in this article.

BrowseAlbums

BrowseArtists

BrowseComposers

BrowseFavorites

BrowseGenres

BrowseNowPlaying

BrowsePicklist

BrowsePlaylists

BrowseRadioSources

BrowseTitles

BrowseTopMenu

The BrowseTopMenu command supports some non-standard uses. Simply, it can take an additional argument that is neither a start or count value to indicate that the request is actually for the content within a node available as a child to the default response. Subsequently, the picklist response can be handled like any other picklist. This greatly simplifies the handler requirements for a control client.

To specify a different root, use BrowseTopMenu itemGuid=<childGuid>.

The end result of browsing content on MMS is, of course, the initiation of content playback.

Any directly addressable content (local content, presets, playlists, scenes) can be recalled at any time without context or prior browse. Use the Play<Container> <containerGUID> command to do so. For example, to play an Album, use PlayAlbum <albumGUID>. For a Playlist, use PlayPlaylist <playlistGUID>. The full list of directly addressable content is as follows:

• Albums

• Artists

• Composers