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.

Method Description
GETSTATUS Returns status of Multiviewer
GETPLAYERSNUMBER Returns the number of players loaded into the current layout
GETACTIVEPLAYER Returns the zero-based index of the active / selected player
SETACTIVEPLAYER Changes the currently active / selected player
GETLAYOUTSNUMBER Returns the number of layouts loaded into the Multiviewer
GETACTIVELAYOUT Returns the zero-based index of the active layout
SETACTIVELAYOUT Changes the currently active layout
GETAUDIOCHANNELSNUMBER Returns the number of audio channels for the specified player
SETACTIVEAUDIOCHANNEL Sets the selected / active audio channel in the specified player
GETACTIVEAUDIOCHANNEL Returns the selected / active audio channel in the specified player
RESTART Causes a soft-restart of the Multiviewer, reloading settings and layouts
PLAYALERT Allows a user-specified WAV file to be played via the alarm audio channel

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>