Cinegy Multiviewer API Reference

Reading time ~8 minutes

Introduction

Cinegy Multiviewer contains a simple set of REST API webservice methods, which provide the user with external control of hosting Cinegy Multiviewer behavior.

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

http://<multiviewerip>:8000

It is possible 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 Cinegy Multiviewer is a very simple application 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

Returns status of Cinegy Multiviewer

Returns SRT connection statistics

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 Cinegy Multiviewer

Returns the current title of the specified layout

Changes the title of the specified layout

Changes the title of the specified player

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 Cinegy 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 Cinegy 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 Cinegy Multiviewer is operating (false is never reachable).

Example XML Result:

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

GETSRTSTATS

Returns collected SRT statistics and publishes it to the web browser.

URL Template:

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

Example XML Result:

<SrtStats>
<Connections>
<Connection Key="169.255.0.5:62551 <- 9001" MsTimeStamp="2765" PktSent="8484"
PktRecv="0" PktSndLoss="0" PktRcvLoss="0" PktRetrans="0" PktRcvRetrans="0"
PktSentACK="0" PktRecvACK="117" PktSentNAK="0" PktRecvNAK="0" MbpsSendRate="33.377"
MbpsRecvRate="0.000" UsSndDuration="2310400" PktReorderDistance="0"
PktRcvAvgBelatedTime="0.000" PktRcvBelated="0" PktSndDrop="0" PktRcvDrop="0"
PktRcvUndecrypt="0" ByteSent="11538240" ByteRecv="0" ByteRcvLoss="0" ByteRetrans="0"
ByteSndDrop="0" ByteRcvDrop="0" ByteRcvUndecrypt="0" UsPktSndPeriod="159"
PktFlowWindow="8121" PktCongestionWindow="8192" PktFlightSize="4" MsRTT="0.023"
MbpsBandwidth="1429.140" ByteAvailSndBuf="9534000" ByteAvailRcvBuf="12286500"
MbpsMaxBW="68.402" ByteMSS="1500" PktSndBuf="1836" ByteSndBuf="2496960" MsSndBuf="294"
MsSndTsbPdDelay="120" PktRcvBuf="0" ByteRcvBuf="0" MsRcvBuf="0" MsRcvTsbPdDelay="120"
PktReorderTolerance="0" PktSentUnique="8484" PktRecvUnique="0" ByteSentUnique="11538240"
ByteRecvUnique="0"/>
<Connection Key="169.255.0.5:9001 -> 62551" MsTimeStamp="4986" PktSent="0" PktRecv="8489"
PktSndLoss="0" PktRcvLoss="0" PktRetrans="0" PktRcvRetrans="0" PktSentACK="117"
PktRecvACK="0" PktSentNAK="0" PktRecvNAK="0" MbpsSendRate="0.000" MbpsRecvRate="18.522"
UsSndDuration="0" PktReorderDistance="0" PktRcvAvgBelatedTime="0.000" PktRcvBelated="0"
PktSndDrop="0" PktRcvDrop="0" PktRcvUndecrypt="0" ByteSent="0" ByteRecv="11545040"
ByteRcvLoss="0" ByteRetrans="0" ByteSndDrop="0" ByteRcvDrop="0" ByteRcvUndecrypt="0"
UsPktSndPeriod="10" PktFlowWindow="8192" PktCongestionWindow="8192" PktFlightSize="0"
MsRTT="0.023" MbpsBandwidth="1586.784" ByteAvailSndBuf="12288000" ByteAvailRcvBuf="12181500"
MbpsMaxBW="1000.000" ByteMSS="1500" PktSndBuf="0" ByteSndBuf="0" MsSndBuf="0"
MsSndTsbPdDelay="120" PktRcvBuf="70" ByteRcvBuf="92120" MsRcvBuf="96" MsRcvTsbPdDelay="120"
PktReorderTolerance="0" PktSentUnique="0" PktRecvUnique="8489" ByteSentUnique="0"
ByteRecvUnique="11545040"/>
<Connection Key="88.198.225.93:9000 -> 62552" MsTimeStamp="4980" PktSent="0" PktRecv="5053"
PktSndLoss="0" PktRcvLoss="0" PktRetrans="0" PktRcvRetrans="0" PktSentACK="198" PktRecvACK="0"
PktSentNAK="0" PktRecvNAK="0" MbpsSendRate="0.000" MbpsRecvRate="11.038" UsSndDuration="0"
PktReorderDistance="0" PktRcvAvgBelatedTime="0.000" PktRcvBelated="0" PktSndDrop="0"
PktRcvDrop="0" PktRcvUndecrypt="0" ByteSent="0" ByteRecv="6872080" ByteRcvLoss="0"
ByteRetrans="0" ByteSndDrop="0" ByteRcvDrop="0" ByteRcvUndecrypt="0" UsPktSndPeriod="10"
PktFlowWindow="8192" PktCongestionWindow="8192" PktFlightSize="0" MsRTT="40.919"
MbpsBandwidth="2558.376" ByteAvailSndBuf="12288000" ByteAvailRcvBuf="11973000"
MbpsMaxBW="1000.000" ByteMSS="1500" PktSndBuf="0" ByteSndBuf="0" MsSndBuf="0"
MsSndTsbPdDelay="120" PktRcvBuf="209" ByteRcvBuf="275044" MsRcvBuf="203" MsRcvTsbPdDelay="120"
PktReorderTolerance="0" PktSentUnique="0" PktRecvUnique="5053" ByteSentUnique="0"
ByteRecvUnique="6872080"/>
</Connections>
<SrtPlayers>
<Player Name="Player 1" SrtKey="88.198.225.93:9000 ->" Url="srt://srt.cinegy.com:9000"/>
<Player Name="Player 2" SrtKey="169.255.0.5:9001 ->" Url="srt://169.255.0.5:9001"/>
</SrtPlayers>
</SrtStats>

Every present connection has its own Connection element.

Connection Key – identifies connection and data flow direction, consists of remote IP, remote port, local port and data flow indicator (→/←).

The SrtPlayers section defines SRT URLs of the SRT input players configured in Cinegy Multiviewer Configurator with the following attributes:

  • Name – the SRT player name;

  • SrtKey – the SRT key identifier corresponding to the appropriate Connection key.

  • Url – a custom SRT URL name defined by user.

The rest of the parameters are from SRT library statistics.

Note
 We do not use accumulated statistics as we never reset statistics values.

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 Cinegy 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 Cinegy Multiviewer. The index range is 1 to {number of layouts}.

Example XML Result:

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

GETLAYOUTTITLE

Returns the title of a layout of your choice.

URL Template:

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

Parameters:

ID – the ID of a target Cinegy Multiviewer layout.

SETLAYOUTTITLE

Changes the title of the specified layout.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetLayoutTitle?ID={LayoutID}&Title={LayoutTitle}

Parameters:

ID – the ID of a target Cinegy Multiviewer layout.

Title – the desired layout name.

SETPLAYERTITLE

Changes the title of the specified player.

URL Template:

http://<mvservernameorip>:8090/Multiviewer/Rest/SetPlayerTitle?PlayerID={LayoutID}&Title={PlayerName}

Parameters:

PlayerID – the ID of a Cinegy Multiviewer input.

Title – the desired text label to be attached to the player.

GETACTIVELAYOUT

Returns the zero-based index of the active layout (only relevant when multi-layout configurations are loaded from XML generated with the Cinegy 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 relevant when multi-layout configurations are loaded from XML generated with the Cinegy Multiviewer Layout Designer tool).

URL Template:

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

Parameters:

ID – the index of a 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 the lowest) audio channels for the specified player.

URL Template:

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

Parameters:

PlayerID – the index of a 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 a player to change. The index range is 0 to "count - 1" of players. ID - the index of an 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 a 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 Cinegy Multiviewer, reloading settings and layouts. Useful if the settings have been altered or the Cinegy 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 – a service-accessible path to the WAV file to be played. WAV must be a 48Khz 16-bit PCM encoding to play at correct pitch and tempo. It is 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 targeted 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 a 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 a 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 a 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>