Controlling Mirage Audio System

Introduction

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.

Connecting

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.

Setting Additional Options

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:

Events

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

Metadata Events

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

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.

Playback Events

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

Flags

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.

Multistate Flags

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.

Control

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.

Browsing

Basics

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.

Other list item attributes

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

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

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.

Online Content

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.

Choosing Default Online Accounts

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.

Retrieving Available Accounts

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

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.

Valid Browse Commands

BrowseAlbums

BrowseArtists

BrowseComposers

BrowseFavorites

BrowseGenres

BrowseNowPlaying

BrowsePicklist

BrowsePlaylists

BrowseRadioSources

BrowseTitles

BrowseTopMenu

Browse Top Menu

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>.

Initiating playback with Content

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

Directly Addressable Content

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

• Genres

• Playlists

• Presets

• Scenes

• Titles

Modifying the Queue

Initiating playback with an existing queue can be done in several ways that allow for queue construction or replacement. The available options and each option’s protocol verb are:

• Play Next (Next)

  • Insert the addressed content after the currently playing track

• Play Now (Now)

  • Insert the addressed content after the currently playing track and perform a skip

• Replace Queue (Replace)

  • Replace the entire queue with the addressed content

• Add To Queue (AddToQueue)

  • Append the addressed content to the end of the queue

• Add To Playlist (AddToPlaylist)

  • Append the addressed content to the end of a playlist as selected from the subsequently provided menu

While all of these options are always available, the options are condensed to those unique actions and presented to the connected client in a number of ways. In other words, when the queue is empty, the only presented option is Now because there is nothing to modify. Sending Replace in such a scenario would perform the same exact action as Now. The list of options is communicated to the connected client via the LocalQueueOptions status event or as a menu when indicating playback via the ClarifyTitleIntent command. To ensure MMS knows the client supports this functionality, be sure to indicate as such by sending SetOption supports_playnow=true during the preamble. See the Setting Additional Options section above for more details.

The intended option is communicated to the server by appending it to the end of the Play<Container> command after the container’s GUID. For example, PlayAlbum c8507e3c-a5c0-4503-bd87-0b711580987e Replace. For items where a listAction is provided and that listAction is ClarifyTitleIntent, append the verb to the end of that command. For example, ClarifyTitleIntent 1609d2f0-b7c8-4996-9a48-4f434ad436e0 Next. Leaving the verb off will result in a menu for the user to select from unless there is only one action available, in which case MMS will perform that action.

Presets

To store a Preset, use the StorePreset command. This command takes an optional double-quoted name argument. If the name argument is specified, the MMS will store the Preset with that name. If no name is specified, the MMS will prompt for a name using an InputBox. InputBoxes are natively supported by all our control system drivers. As with all protocol commands, each command should be terminated with a carriage return and a line feed (\r\n).

Examples:

StorePreset - This will be responded to with an InputBox from the server.

StorePreset "Party Time" - This will save a Preset called Party Time

To recall a Preset, use the RecallPreset command. This command takes either the double-quoted name of the Preset or the unique ID of the Preset. To get either of these, please see the BrowseFavorites command, described below. Recalling a Preset will replace the state of the selected Instance with the state stored in the Preset. As with all protocol commands, each command should be terminated with a carriage return and a line feed (\r\n).

Examples:

RecallPreset "Party Time" - This recalls the Preset by name

RecallPreset 9f9c8919-f939-d67a-dce2-cb049a4ead99 - This recalls the Preset by unique ID

Edit a preset with EditPreset nameOrId

Rename a preset with RenamePreset nameOrId newName

Delete a preset with DeletePreset nameOrId

To browse available Presets, use the BrowseFavorites or BrowsePresets commands. This Browse command adheres to the same pattern as all other Browse commands.

This feature was once called Snapshot.

Relevant Events

There are some events that indicate changes to favorites to the control client.

FavoritesChanged will be sent whenever any change is made to any preset. It will always be true. Simply receiving it is sufficient to rebrowse presets.

FavoritesCount will be sent whenever the number of presets changes.

FavoritesCount differs from FavoritesChanged in that it will only be sent when a preset is added or deleted while FavoritesChanged includes name changes.

Scenes

To store a Scene, use the StoreScene command. This command takes an optional double-quoted name argument. If the name argument is specified, the MMS will store the Scene with that name. If no name is specified, the MMS will prompt for a name using an InputBox. InputBoxes are natively supported by all our control system drivers. The scene will save with the currently playing content for the selected instance in the currently playing Zones alternatively current instance at the current volume levels. As with all protocol commands, each command should be terminated with a carriage return and a line feed (\r\n).

Examples:

StoreScene - This will be responded to with an InputBox from the server.

StoreScene "Party Time" - This will save a Scene called Party Time

To recall a Scene, use the RecallScene command. This command takes either the double-quoted name of the Scene or the unique ID of the Scene. To get either of these, please see the BrowseScenes command, described below. Recalling a Scene will turn on and set the volume in the Zones/Instance contained in the Scene and replace the state of the instance with the state stored in the Scene. Note that when using Autonomic amps, the instance for playback might be different from the currently selected instance. As with all protocol commands, each command should be terminated with a carriage return and a line feed (\r\n).

Examples:

RecallScene "DinnerTime" - This recalls the Scene by name

RecallScene 9f9c8919-f939-d67a-dce2-cb049a4ead99 - This recalls the Scene by unique ID

Delete a Scene with DeleteScene nameOrId

Relevant Events

There are some events that indicate changes to scenes to the control client.

ScenesChanged will be sent whenever any change is made to any scene. It will always be true. Simply receiving it is sufficient to rebrowse scenes.

ScenesCount will be sent whenever the number of scenes changes.

Playlists

Playlists are browsed with BrowsePlaylists. This command adheres to the same pattern as all Browse commands.

Rename a playlist with RenamePlaylist oldName newName

Delete a playlist with DeletePlaylist nameOrId

Reorder tracks within a playlist with ReorderPlaylist playlistId srceTrackId destTrackId

A playlist can be directly played with PlayPlaylist nameOrId

Relevant Events

There are some events that indicate changes to favorites to the control client.

PlaylistsChanged will be sent whenever any change is made to any playlist. It will always be true. Simply receiving it is sufficient to rebrowse playlists.

PlaylistCount will be sent whenever the number of playlists changes.

PlaylistCount differs from PlaylistsChanged in that it will only be sent when a playlist is added or deleted while PlaylistsChanged includes name changes.

Now Playing

The now playing queue can be browsed with BrowseNowPlaying. Only browse the queue if the BrowseNowPlayingAvailable event is true.

All now playing indexes are 1 based.

Change songs by using JumpToNowPlayingitem <indexOfItem>.

Reorder the queue with ReorderNowPlaying <indexOfTrackToMove> <indexToMoveTo>.

Remove a song with RemoveNowPlayingItem <indexOfTrackToRemove>.

Clear the queue with ClearNowPlaying. Passing False as an argument will clear the queue and stop playback of any station based content. Passing True or no argument will clear the queue and stop any queue based content from playing back but will not disrupt playback for station based content.

Triggers

Some servers are equipped with Input and Output Triggers. Input triggers are activated by adding a voltage to the input pin (5 -24V AC or DC). Output triggers will supply a voltage on the output pin (12VDC 100mA max).

Relevant Commands

Turn on/off an output trigger with SetOutputTrigger <indexOfTrigger> <true/false> , where <indexOfTrigger> is in trigger order independent of the trigger label. IE. Trigger Out A would have <indexOfTrigger> of 1.

Example:

Turn on Trigger Out A: SetOutputTrigger 1 true

Turn off Trigger Out C: SetOutputTrigger 3 false

Relevant Events

There are some events for Input Triggers. Each Input Trigger does have one event, TriggerIn1 through TriggerIn<x>, where the event is true when voltage is applied to the input pin.

Album Art

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

The specific handler on the MMS is called getart so an example of a base for retrieving art would be http://192.168.0.59:5005/getart?.... Always include the ID of the item. If constructing the URL manually rather than using the value of BaseWebUrl, it is acceptable to leave the port off the request. For example http://192.168.0.59/getart?.... Requests for /getart on port 80 are processed the same as requests on port 5005.

To construct the full URL to get art, use the above values along with the below options.

JSON HTTP API

General Information

The root endpoint for all HTTP API communication is http://ipOrNameOfServer/api/. A GET request to this endpoint will receive a JSON response containing three arrays: events, browse, and messages.

Response

events contains name,value pairs where the event names are the same as the previously described IP protocol and values carry the same meaning per event.

browse contains the response to any browse commands made on separate GET requests to this same endpoint. This will discussed more later.

messages contains generic messages.

Sending commands

To send commands, simply replace any spaces in the command as it would be used in the IP protocol with a /. For example, if the IP command is SubscribeEvents True, a GET to http://ipOrNameOfServer/api/SubscribeEvents/True would execute that command. Be sure to URL encode any parameters to ensure no invalid characters

It's important to remember that there is a fundamental difference between the HTTP JSON API and the IP protocol in that HTTP communications are NOT guaranteed to be processed in the order the control client sends them as they are all transmitted on different sockets. The server may receive them out of order. To handle this and to force sets of commands to be processed in order, make use of the Script command. This command allows several commands to executed in a specific order by transmitting them all at once. When using the Script command, be sure to URL encode each (sub)command entirely as it is a parameter rather than a command. For example, if we wanted to set the target instance and subscribe to events in that order, we would do http://ipOrNameOfServer/api/Script/SetInstance%20Player_A/SubscribeEvents%20True.

Regardless of the command sent, the response will be received in the next request to the bare endpoint http://ipOrNameOfServer/api/. To ensure communicates between clients and the server are properly routed, be sure to include a query string containing clientId=<some UUID>. For example: clientId=0a5926cc-e68f-4f82-92c4-ba148dfab6c9. This ensures that multiple clients can send and receive without interfering with each other. Leaving the clientId out of command requests and/or polling requests will cause inter-client cross talk.

Browsing

Browsing through HTTP works nearly identically as through a regular socket. Send browse commands in the fashion described in Sending Commands.

In these examples, we’re sending BrowsePresets 1 10.

If sending a single command, separate the command and arguments with /:

If sending as part of a script, URL encode the entire command and pass it as an argument to Script:

Expect the next poll to /api to contain data like this: