Introduction

Cinegy Multiviewer contains a simple set of REST API webservice methods, which allow external control of the behaviour of the hosting Multiviewer.

These APIs are used by the Cinegy Multiviewer Remote Control HTML pages, so for a demonstration of these APIs in use, just browse to the remote control page:

http://<multiviewerip>:8000

It is possble to see these web service methods as generated and consumed by the remote control by pressing buttons in your browser with the browser development tools open (often available by hitting F12).

Since Multiviewer is a very simple app with no persistent data, we made the decision to implement all operations as GET commands and pass arguments within the query string of that GET URL - so all methods documented below are always HTTP GET calls.

Overview of Available Methods

Below is a summary table of the available methods, and a brief description of the purpose of the method.

MethodDescription

Returns status of Multiviewer

Returns the number of players loaded into the current layout

Returns the zero-based index of the active / selected player

Changes the currently active / selected player

Returns the number of layouts loaded into the Multiviewer

Returns the zero-based index of the active layout

Changes the currently active layout

Returns the number of audio channels for the specified player

Sets the selected / active audio channel in the specified player

Returns the selected / active audio channel in the specified player

Causes a soft-restart of the Multiviewer, reloading settings and layouts

Allows a user-specified WAV file to be played via the alarm audio channel

Specifies a colored border to be rendered around the specified player

Returns the current border color for the specified player

Returns the current title of the specified player

Details of Available Methods

GETSTATUS

Returns status of Multiviewer.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetStatus

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true, if Multiviewer is operating (false is never reachable).

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

GETPLAYERSNUMBER

Returns the number of players loaded into the current layout.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetPlayersNumber

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the number of players available in the current layout. The index range is 1 to {number of players}.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">16</int>

GETACTIVEPLAYER

Returns the zero-based index of the active / selected player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetActivePlayer

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the index of an active player. The index range is 0 to "count - 1" of players.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">2</int>

SETACTIVEPLAYER

Changes the currently active / selected player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetActivePlayer?ID={ID}

Parameters:

ID – the index of player, which we want to activate. The index range is 0 to "count - 1" of players.

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true/false depending on success of selection.

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

GETLAYOUTSNUMBER

Returns the number of layouts loaded into the Multiviewer.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetLayoutsNumber

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the number of layouts available on the Mutliviewer. The index range is 1 to {number of layouts}.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">2</int>

GETACTIVELAYOUT

Returns the zero-based index of the active layout (only meaningful when multi-layout configurations are loaded from XML generated with the Multiviewer Layout Designer tool).

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetActiveLayout

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the index of the active layout. The index range is 0 to "count - 1" of layouts.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">3</int>

SETACTIVELAYOUT

Changes the currently active layout (only meaningful when multi-layout configurations are loaded from XML generated with the Multiviewer Layout Designer tool).

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetActiveLayout?ID={ID}

Parameters:

ID – the index of layout, which we want to activate. The index range is 0 to "count - 1" of layouts.

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true/false depending on success of selection.

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

GETAUDIOCHANNELSNUMBER

Returns the number of detected or configured (whichever is lowest) audio channels for the specified player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetAudioChannelsNumber?PlayerID={PlayerID}

Parameters:

PlayerID – the index of player to query. The index range is 0 to "count - 1" of players.

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the number of audio channels. The index range is 0 to 8.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">2</int>

SETACTIVEAUDIOCHANNEL

Sets the selected / active audio channel in the specified player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetActiveAudioChannel?PlayerID={PlayerID}&ID={ID}

Parameters:

PlayerID – the index of player to change. The index range is 0 to "count - 1" of players. ID - the index of the audio channel to select

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true / false depending on success of selection.

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

GETACTIVEAUDIOCHANNEL

Returns the selected / active audio channel in the specified player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetActiveAudioChannel?PlayerID={PlayerID}

Parameters:

PlayerID – the index of player to query. The index range is 0 to "count - 1" of players.

Response (XML):

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</int>
{Result} - the index of the active audio channel. The index range is -1 to 8, with -1 indicating an error reading the specified player and 0 that there is no selected audio channel.

Example XML Result:

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">0</int>

RESTART

Causes a soft-restart of the Multiviewer, reloading settings and layouts. Useful if the settings have been altered or the multiviewer display has become corrupted.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/Restart

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true / false depending on success of reset.

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

PLAYALERT

Allows a user-specified WAV file to be played via the alarm audio channel. Useful when creating custom alarm scripts to control triggering of different alarm values.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/PlayAlarm?FileName={FileName}

Parameters:

FileName – service-accessible path to a WAV file to be played. WAV must be a 48Khz 16-bit PCM encoding to play at correct pitch and tempo. Not recommended to use network locations.

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true / false depending on success of playback.

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

SETPLAYERBORDERCOLOR

Allows a user to reset the color of the border of the specified player to a value provided. Using this border color control, various tally or highlighting workflows can be integrated. The border width of the targetted player must be greater than zero to have an effect.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetPlayerBorderColor?PlayerID={PlayerID}&Color={Color}

Parameters:

PlayerID – the index of player to query. The index range is 0 to "count - 1" of players.

Color – the required color to use when rendering the border - ARGB hex format (e.g. Color=FF0000FF for bright blue). Do not use a # symbol prefix.

Response (XML):

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</boolean>
{Result} - true / false depending on success of border setting

Example XML Result:

<boolean xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</boolean>

GETPLAYERBORDERCOLOR

Returns the currently assigned border color value as ARGB hexadecimal string of the indicated player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetPlayerBorderColor?PlayerID={PlayerID}

Parameters:

PlayerID – the index of player to query. The index range is 0 to "count - 1" of players.

Response (XML):

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</string>
{Result} - ARGB string (prefixed with hash symbol) indicating the current border color.

Example XML Result:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">#FF0000FF</string>

GETPLAYERTITLE

Returns the current string value of the title for the indicated player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/GetPlayerTitle?PlayerID={PlayerID}

Parameters:

PlayerID – the index of player to query. The index range is 0 to "count - 1" of players.

Response (XML):

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">{Result}</string>
{Result} - Title string indicating the current player border title.

Example XML Result:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">3sat HD</string>