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
SetClientVersion 1.0.0.0
SetHost 192.168.0.100
SetXmlMode Lists
SetEncoding 65001
SetInstance Player_A
SubscribeEvents
GetStatus

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

...

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
SetClientVersion 1.0.0.0
SetHost 192.168.0.100
SetXmlMode Lists
SetEncoding 65001
SetInstance Player_A
SubscribeEvents
GetStatus

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 which address the control client connected on. This is useful if the control client is connecting through a external connection where the address it used might be a web address. We recommend setting this value always. 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, or All.

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.

...

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

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:

Marker Source Event=Value

and will look like:

StateChanged Player_A TrackTime=121

or

ReportState Player_A TrackTime=121

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:

...

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:

EventReason Source Event=Value

and will look like:

StateChanged Player_A TrackTime=121

or

ReportState Player_A TrackTime=121

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:

ReportState Player_A MetaLabel1=
ReportState Player_A MetaData1=Pandora: Stevie Ray Vaughan Radio
ReportState Player_A MetaLabel2=Artist
ReportState Player_A MetaData2=Stevie Ray Vaughan
ReportState Player_A MetaLabel3=Album
ReportState Player_A MetaData3=Texas Flood (Legacy Edition)
ReportState Player_A MetaLabel4=Track
ReportState Player_A MetaData4=Texas Flood

...

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.

Browsing

Basics

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

Browse<Container> <start> <count>

where <Container> is the 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:

...

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.

...

BrowseTopMenu itemGuid=fbbcedb1-af64-4c3f-bfe5-000000000010

<PickList total="85" start="1" more="true" art="true" alpha="false" displayAs="List" caption="Pandora Internet Radio">
    <PickItem guid="85b427d1-c7d7-818c-b70c-bfa9670d647f" name="Account: pandora@example.com" dna="name" hasChildren="1" button="0" artGuid="fbbcedb1-af64-4c3f-bfe5-000000000010" />
    <PickItem guid="ea03ab84-c1bc-3eb7-c6e8-5e2317c616cb" name="Create a Pandora station..." dna="name" hasChildren="1" button="0" singleInputBox="1" />
    <PickItem guid="126e079c-3c5b-8dad-017a-9bc61ca8e7db" name="Browse Genre Stations" dna="name" hasChildren="1" button="0" />
    <PickItem guid="37313631-3533-3634-3736-353538393632" name="Shuffle" dna="name" hasChildren="0" button="0" artGuid="d2bafcd0-5068-5b5c-21bd-97daf2342342" />
    <PickItem guid="39383033-3534-3633-3830-373834393733" name="Gojira Radio" dna="name" hasChildren="0" button="6" artGuid="082f3d18-2b42-8434-e303-67975034e45f" action="action" />
    <PickItem guid="32323034-3139-3230-3132-303631343034" name="Gunship Radio" dna="name" hasChildren="0" button="6" artGuid="e93114a7-30d9-ea99-98d8-e375c0fecff1" action="action" />
    <PickItem guid="35363833-3235-3137-3335-353638373936" name="Mastodon Radio" dna="name" hasChildren="0" button="6" artGuid="3a729b47-6af2-88b0-7224-d05b87afb7db" action="action" />
    <PickItem guid="37333534-3234-3232-3530-313637393031" name="ODESZA Radio" dna="name" hasChildren="0" button="6" artGuid="0f3611e8-d045-fd68-0c4f-4e167b1233fb" action="action" />
    <PickItem guid="35373136-3731-3433-3132-373238343134" name="Dream Theater Radio" dna="name" hasChildren="0" button="6" artGuid="6156cf0c-999d-cdd7-d588-04539efeba4e" action="action" />
    <PickItem guid="31353534-3037-3831-3935-343430363337" name="Clutch Radio" dna="name" hasChildren="0" button="6" artGuid="0618e948-1022-f4d0-6089-365468554b21" action="action" />
</PickList>"action" />
</PickList>

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

...

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 -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 scenes favorites to the control client.

ScenesChanged PlaylistsChanged will be sent whenever any change is made to any sceneplaylist. 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 ClearNowPlayingplaylists.

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: <httphttp://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 <httphttp://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

...