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>