Action Router

Skylark SL Neo software services can exchange tasks for execution of certain actions.

The main part of the mechanism for exchanging actions is the Action router module that registrates all other system modules sending or receiving actions. Interaction of modules with Action router is implemented by XML-RPC protocols.

The picture shows launch of playback of the program channel by pressing the keyboard button.

• The operator presses a button on the keyboard
• Event trigger set for this button is activated.
• The GPI Board service generates the Play action for the corresponding program channel.
• Action Router receives the Play action, defines the receiver, converts the action and its parameters to the Skylark API XML-RPC command and sends the command to the receiver.
• The program channel receives the command, analyzes it and launches the playlist for playback.

The functionis active when recording materials to the server database|

More details on configuring the database service.

More details on configuring the program channel service.

Action	Parameters	Description
Play DTMF	DTMF String The number of audio-channel starting from 1 (-1 for all) (optional) The loudness level by the dBFS scale (optional) Tone duration in ms (optional) Pause duration in ms (optional)	Used for one-time playback of a DTMF signal sample at the program channel output. May be used by a central station for playout of a signal about an ad insert for regional partners.
Set background video	Parameters: the source type (FILE/LIVE), filename, or a Live-clip name are set in the window for configuring the rule or are read off a playlist column	setting and change of a file or Live-source for a Background layer.
Set format conversion	Input of the value (scale, crop, box, letter) is implemented in the window for configuring the rule, or the parameter is read off a playlist column.	Setting the conversion mode for a video in case of a mismatch of aspect ratio of original content and program channel settings.
Set format	Input of the value (4:3 or 16:9) is implemented in the window for configuring the rule, or the parameter is read off a playlist column.	Specifying aspect ratio for the output signal of the program channel (4:3 or 16:9).
Set Output AFD	Param 1 – the AFD value: FF, 4x3B, 16x9B, 14×9, 4x3SP14x9, 16x9SP14x9, 16x9SP4x3, NONE or an empty value – Auto)	Redefines the AFD value.
Toggle layer	Input of the layer number (1 is the main full screen layer, 2…9 – graphic layers LAY1…LAY8 respectively) is implemented in the window for configuring the rule (Param1 field), or read from a playlist column; turning on/off displaying the layer does not affect execution of graphic playlists.	Switching displaying a selected layer with a graphic playlist to the opposite: one command turns on/off displaying.
Show layer	The value (number of the graphic layer 1…8) input is implemented in the window for configuring the rule (Param1 field) or is read from a playlist column; turning on/off displaying the layer does not affect execution of graphic playlists.	Turning on displaying the graphic layer with a playlist.
Hide layer	The value (number of the graphic layer 1…8) input is implemented in the window for configuring the rule (Param1 field) or is read from a playlist column; turning on/off displaying the layer does not affect execution of graphic playlists.	Turning off displaying the graphic layer with a playlist.
Toggle graphics	Input of the layer number (1 is the main full screen layer, 2…9 – graphic layers LAY1…LAY8 respectively) is implemented in the window for configuring the rule (Param1 field), or read from a playlist column.	Switching displaying a selected layer with a graphic composition to the opposite: one command turns on/off displaying.
Show graphics	Input of the value (the number of graphic layer 1…8) is implemented in the window for configuring the rule (Param1 field) or is read from the playlist column.	Turning on displaying the layer with a graphic composition.
Hide graphics	Input of the value (the number of graphic layer 1…8) is implemented in the window for configuring the rule (Param1 field) or is read from the playlist column.	Turning off displaying the layer with a graphic composition.
Set graphics	Parameters: the layer number 1…8, the source type (FILE or URL) and the source name are specified in the window for configuring the rule or are read from the playlist column.	Setting and changing a file source for the layer with a graphic composition.
Graphics action	The command input is implemented in the window for configuring the rule (Param1 field) or is read from the playlist column.	Executing the command from SL NEO Graphics SDK.
Set graphics time slot	Input of values (the number of graphic layer 1…8 and time of displaying in ms) is implemented in the window for configuring the rule or is read from the playlist column.	Specifying the time of displaying the layer with a graphic composition.
Toggle logo	The command does not have additional parameters.	Switch of displaying the selected layer with a graphic composition to the opposite: one command may turn on/off displaying.
Show logo	Input of the value (on/off) is implemented in the window for configuring the rule or is read from a playlist column.	Turning on displaying the graphic layer with a logo.
Hide logo	Input of the value (on/off) is implemented in the window for configuring the rule or is read from a playlist column.	Turning off displaying the graphic layer with a logo.
Set logo	Parameters: the source type (FILE or URL) and the source name are specified in the window for configuring the rule or are read from a playlist column.	Setting and changing a file source for the logo layer.
Restart	The command is applied for one layer; the layer number value (1 is the main full screen layer, 2…8 – layers with graphic playlists) is entered in the window for configuring the rule.	Stops executing the playlist, resets statuses of all lines.
Clear	Takes one parameter: the number of the stopped layer (1 is the main full screen layer, 2…8 – layers with graphic playlists).	The action stops the playlist and clears it. Added in 2.2.38
Play	Takes the parameters: Layer number – the layer number value (1 is the main full screen layer, 2…8 – layers with graphic playlists) Startup delay – the start delay set in seconds or “-1” = none. Added in 2.4.64 version.	Launches playback of the first line in the selected playlist or the next line after the last executed one.
Stop	The command is applied for one layer; the layer number value (1 is the main full screen layer, 2…8 – layers with graphic playlists) is entered in the window for configuring the rule.	Stops executing the current playlist event.
Stop if	Takes three parameters: The number of the layer to be stopped. The name of a playlist column to be searched for a value for an additional condition. For example: uri, player, title, comment, group, type, tape, name, gpi1_mode-gpi8_mode, gpi1_val-gpi8_val, item_id, start_type. The value that must be in the playlist so the Stop command would be executed. For gpi1_mode-gpi8_mode – none, on, off, for start_type – manual, hard_start, auto.	The command allows stopping playback, but only in case if the current clip satisfies a certain condition. This allows the user to stop an insert by a closing SCTE-104/35 command, when event identifiers are used in sendings.
Stop Graphics	The command is applied synchronously to all graphic layers	Stops playback of current events in all graphic playlists.
Skip	Takes two parameters: The number of the layer, in which the command will be applied (1 is the main full screen layer, 2…8 – layers with graphic playlists). Line ID (optional). If this parameter is active, the line with the set ID will be skipped instead of the current one.	Quick transition to executing the next or set playlist line. Using the Line ID parameter allows configuring automatic skipping NoMedia lines by using the Media Offline Clip action, the Delay value equal, for example, 2000ms, and calling “Skip $(item_idx)”.
Pause	The command is applied for one layer; the layer number value (1 is the main full screen layer, 2…8 – layers with graphic playlists) is entered in the window for configuring the rule.	Pauses executing the current playlist event.
Unpause	The command is applied for one layer; the layer number value (1 is the main full screen layer, 2…8 – layers with graphic playback) is entered in the window for configuring the rule.	Unpauses executing the current playlist event after the Pause command.
Emergency	The command is applied for the main full screen layer.	Insert of an alarm clip to the current playlist position and quick transition to its execution.
Hold	The command is applied for one layer; the layer number value (1 is the main full screen layer, 2…9 – layers with graphic playlists) is entered in the window for configuring the rule.	Holds the Live-event in the playlist.
Select next clip	The command is applied to one layer; the layer number and PRETAKE or PLAY command are entered in the window for configuring the rule.	Preparation or transition to playback of the next clip in the playlist.
Select clip by number	The command is applied to one layer; the layer number and PRETAKE or PLAY command are entered in the window for configuring the rule.	Preparation or start of playback of the clip in the playlist line with the specified number.
Select clip by current time	The layer number. Numeration starts with 1 (the main playlist, CASTx), 2 (the first graphic layer, CASTx_LAY1), etc. The maximum difference of start time in seconds. Action to execute: PRETAKE or PLAY Action, if not found: NONE, STOP or SKIP Runing Margin (seconds, -1 for none) Start Delay (seconds, -1 for none)	The option is used at regional stations for inserts by DTMF, when automated insert is required only for certain time slots.
Select clip by title	The command is applied to one layer. The layer number, PRETAKE or PLAY command, delay value, clip name (Title column in the playlist) are entered in the window for configuring the rule.	Preparation or start of playback of a clip in the playlist line with the specified name.
Select clip by group	The command is applied to one layer. The layer number, PRETAKE or PLAY command, delay value, group name (Group field in the playlist) are entered in the window for configuring the rule or read off playlist columns.	The Param6 parameter sets a delay of the clip start from the moment of triggering the action. It is similar to Action configuration→Delay, but the difference is in the moment of start of clip preparation. Using Action configuration=Delay leads to the following sequence of actions: a cue-tone came; a delay from Action configuration→Delay; triggering of Select clip by group and start of buferization; start of playback. The option with using Param6 is preferable, as here buferization is implemented beforehand, which helps to avoid brakes while preparing: a cue-tone came; triggering of Select clip by group and start of buferization; a delay from Param6; start of playback. The Param6 value supports fractional values.	Preparation or start of playback of the first clip in the selected playlist group.
Select clip by column	The command is applied to one layer. The PRETAKE or PLAY command, start delay value, column title and its value are entered in the window for configuring the rule or are read off playlist columns.	Preparation or start of playback of a clip in the playlist line, for which the value in a certain column coincides with the specified one.
Play clip	The command is applied for one layer. The parameters are: The layer number (1 is the main full screen layer, 2…9 – layers with graphic playlists). The clip name in the server database. Player name. The IN point. The OUT point. Event duration. The type of conversion (cut, v-mix, x-mix). Transition speed (0 – instantaneous, -1 – fast, -2 – average, -3 – slow). WIPE. Clip parameters. The executable action: APPEND – only add to the end, PRETAKE – add to the end and prepare for playback, PLAY – add to the end and start playback. The delay value in milliseconds. Audio Transparency (0-100, -1 for auto) The clip group. Event ID The sype of start (MANUAL or AUTO).	Placing the clip with the specified name to the playlist end and its playback. An example of using the option for configuring ”Now Playing” and ”Coming Up Next subtitles. The Param10 field value for this action may look like “element@value”: a graphic composition element for inserting and the insertable value, respectively. If a variable value must be sent, recording is implemented in the ProgTitle@$(comment) format. If over one key-parameter value requires to be transferred, they must be separated with @. For example: param1@val1@param2@val2.
Sync Stop	No parameters	Turning off the mode of constant synchronization of the executable playlist of the backup server from the main one.
Sync Start	No parameters	Turning on the mode of constant synchronization of the executable playlist of the backup server from the main one.
Sync Once	No parameters	Turning on one-time synchronization of the executable playlist of the backup server from the main one.
Sync Offline	No parameters	Do offline synchronization to peer program playout service.
Live CC On	Param1 - CC Stream 1 or 2	Turn on live closed captions insertion to the program playout service.
Live CC Off	Param1 - CC Stream 1 or 2	Turn off live closed captions insertion to the program playout service.
Live CC Set Params	Param1-CC stream (1 or 2), Param2-Number of lines (2, 3 or 4), Param3-Base line (1-15), Param4-Identation (0, 4, 8, 12, 16, 20, 24 or 28)	Set live closed captions insertion parameters.
Live CC Append	Param1-CC stream (1 or 2), Param2-Text to append	Send text to the live closed captions stream.
Disable Action handler	Name of the action processor for turning off. An empty value – turning off all processors.	Turns off the selected action processor.
Enable Action handler	Name of the action processor for turning on. An empty value – turning on all processors.	Turns on the selected action processor.
SCTE-104 Splice Request	Parameters are described in the Configuring generation of SCTE-104 Messages article.	Inserts a SCTE-104 Splice Request message.
SCTE-104 Segmentation Descriptor Request	Parameters are described in the Configuring generation of SCTE-104 Messages article.	Inserts a SCTE-104 Segmentation Descriptor Request message.
Gen sGPI Packet	Param1-Param10	Generate and insert an sGPI packet into VANC
Set Time Zone	Param1 – shift in minutes.	Sets a timezone shift relative to UTC in minutes (-9999 – local time).
Next Marker	Param1 – Marker Track (if the value is empty, the General type is used), Param2 – Marker Title (any value, if the field is empty)	Moves to the next key frame of the current clip in the playlist. Parameters were added in the 2.4.14 version.
Prev Marker	Param1 – Marker Track (if the value is empty, the General type is used), Param2 – Marker Title (any value, if the field is empty)	Moves to the previous key frame of the current clip in the playlist. Parameters were added in the 2.4.14 version.
Enable Blur	Param1 – sets a rectangle blurring area in the x,y,w,h format (e.g.: «0.2,0.2,0.5,0.3»).	Activates blurring the top opaque layer in the program channel (graphic layers are transparent). An example of a program channel output with the activated blurring option:
Disable Blur	No parameters.	Turns off blurring the top opaque layer in the program channel. An example of a program channel output with an inactive blurring option:
Enable Beep	Param1 – Loudness of the generated signal in dB (-14 dB by default).	Turns on playback of the tone signal in the audio channel. Added in 2.4.14 version.
Disable Beep	No parameters.	Turns off playback of the tone signal in the audio channel. Added in 2.4.14 version.
Enable Mute	No parameters.	Turns off audio output. Added in 2.4.14 version.
Disable Mute	No parameters.	Turns on audio output. Added in 2.4.14 version.
Set Item Column	The action takes four parameters. Param N: The layer number (enumeration goes from 1, which is the main layer). The sequence number of the playlist element (enumeration goes from 1, which is the first playlist element). The playlist column name. Possible values: key1_mode…key4-mode, gpi1_mode…gpi8_mode, gpi1_val…gpi8_val. The set value. Acceptable values for “xxxx_mode” parameters are: none, on or off; for “xxxx_val” parameters – a string value.	The action allows specifying values in key1_mode-key4-mode, gpi1_mode-gpi8_mode, gpi1_val-gpi8_val fields for the set playlist element.
Clear Last Frame	No parameters.	Reset postroll or invalid frame stills. Added in version 2.2.38.
Set Media Purge Date	The action takes three parameters. Param N: Media URL The number of days less or equal zero = infinite. The parameter is set to ON, YES, TRUE or 1, if the minimum number of days is specified. This means that the deletion time will be updated only in case, if it was set before the number of days.	Set media auto deletion date to a specified amount of days. Added in version 2.2.38.
Dump NoMedia files	No parameters.	Outputs NoMedia clips to the log.
Set OnAir Status	The action takes one parameter. Param 1: The parameter is set to ON, YES, TRUE or 1, if the OnAir status is required to be set.	Sets the OnAir status. The first activation of the parameter outputs a message to the program channel log: LAY_0: Logger on air state: 0 -> 1. If Param1 is empty, the following message is shown: LAY_0: Logger on air state: 1 -> 2.
Emit PlaylistChanged	The action takes one parameter. Param1 – the layer number for calling the event (enumeration starts with 1).	Launches generation of the PLAYLIST_CHANGED event in General Events. Added in 2.3.37.
Merge Output Mixer	Param1 - Mixer spec in a form: [=][ch<=|+>ilay/ich/pct][,ch<=|+>ilay/ich/pct][,....] Input layer 0: background Input layer 1-8: playlist layers Input layer -1: composition of all layers taking layer opacity in account Zero all channels and mix main layer ch1 and ch2 to output 1 and 2: =1=1/1/100,2=1/2/100 Zero all channels and mix background and main layers ch1 to output 1: =1=0/1/100,1+1/1/100	Modify output audio mixer parameters
Enable Output Mixer	Param1 - ON, YES, TRUE or 1 if enabled, OFF, NO, FALSE or 0 is disabld	Set if output audio mixer is applied
Set Open Captions Stream	Param1 - Stream number (0 to turn open captions off)	Set currently displayed open captions stream

The action router service sits at port number 5454 and it accessible through XML-RPC protocol. Every service which needs to react to actions has to register with the action router by calling “add_action” method. Once registered the new handler can be selected in the web console configurator of an action source service. Action parameters are always passed as strings and converted to numerical types if the actual handler method specifies a numeric type. Actual handler method parameter are mapped to actual action parameter according ActionParamInfo specification.

Method name: “add_action” Register a new action handler with the Action Router service This method has the following parameters: Parameter 0 - struct ActionInfo - a structure describing a new action handler Return value - None.

The ActionInfo structure contains the following members:

"name" - string - name of the action used to trigger the action by other services.
"server_type" - string - server type name. It's used for user's reference only.
"server_name" - string - server name used to trigger the action by other services.
"descr" - string - user visible description of the action.
"arg_descr" - array<string> - user visible description of the action parameters.
"reaction_delay" - double - time in seconds needed to execute the action. For example,
                            the playlist actions are usually bound to some particular
                            event in the playlist at some point in time. The playlist
                            action generator will take this reaction delay into account
                            and emit the action "reaction_delay" seconds earlier so that
                            the actual handler completes at the proper time.
"handlers" - array<ActionHandlerInfo> - array of the action handler method descriptions.

The ActionHandlerInfo struct contains the following members:

"host" - string - ip address of the service that handles the action.
"port" - int - port number of the service that handles the action.
"method" - string - XML-RPC method name that handles the action.
"parameters" - array<ActionParamInfo> - array of actual action parameters mapping to the
                                        XML-RPC method's parameters.

The ActionParamInfo struct contains the following members:

"param_type" - string - type name of a parameter. Currently, the following type names
                        are supported:
  "int" - integer number
  "string" - utf8 string
"param_val" - string - value specifier. When a '%X' character sequence is encountered
                       (where X can be in range '1'-'9' or 'A'-'Z') it is substituted 
                       by corresponding actual action parameter. For example, an
                       action may specify just one parameter but the handler method
                       may take two parameters. In this case, one of the parameters
                       can be specified and a fixed value and the other one as "%1"
                       which will use the action's actual parameter.

Important! When reloading the server, re-register your server through the API.

Your services may be registered in Action Router via a special XMP file comgpi.xml, which must be located in the folder C:\Program files (x86)\SL NEO Media Platform\run\. This option is more preferable comparing to registration through the API, as you don’t have to monitor the current registration status of your server. Also, it excludes the possibility of double registration.

<comgpid>
<!-- 
The action tag contains three attributes: 
name – the registered action name. The attribute is used in the Action field.
server_type – the service user name used only for displaying in the interface.
server_name – the service name; is used in the Service field.
-->
  <action name="My Action" server_type="My Server" server_name="My Server_1">
  <!-- Description of the action for output in the interface -->
    <description>
      This is a test Action
    </description>
    <params>
    <!-- Listing parameters with values that will be specified in Param1-Param16 fields -->
      <param>
        <description>
          <!-- Tooltip text for the Param field -->
          Param1 description
        </description>
      </param>
      <param>
        <description>
          Param2 description
        </description>
      </param>
    </params>
    <!-- FIXME -->
    <reaction_delay addr="localhost:12345" method="my_method" value="0.5"/>
    <!-- Description of parameters of the server that will process the XML-RPC request 
    sent after My Action triggers: 
    add – the server port and IP address,
    method – the name of the method called at the server.
    -->
    <handler addr="localhost:12345" method="my_method">
      <!-- 
      Enumeration of parameters sent to my_method.
      Their quantity may differ from the number of parameters sent to the action 
      (in this example, the action takes two parameters and the method takes three). 
      When specifying parameters, it is necessary to define the type in the type field:
      int – an integer,
      double – a floating point value,
      string – a string.
      -->
      <param type="int" value="%1"/>
      <param type="double" value="%2"/>
      <param type="string" value="Custom string with %2 in third param"/>
    </handler>
  </action>
</comgpid>

Triggering this action will send a request to the server:

  <?xml version="1.0"?>
  <methodCall>
    <methodName>my_method</methodName>
  <params>
    <param><value><i4>11</i4></value></param>
    <param><value><double>22.0000000000</double></value></param>
    <param><value>three</value></param>
  </params>
  </methodCall>

An example of a comgpi.xml file for registering an action.

comgpi.xml

<comgpid>
  <action name="send" server_type="Email sender" server_name="Email sender">
    <description>
      This is a test Action
    </description>
    <params>
      <param>
        <description>
          E-mail addr
        </description>
      </param>
      <param>
        <description>
          Theme
        </description>
      </param>
      <param>
        <description>
          Text
        </description>
      </param>
    </params>
    <reaction_delay addr="localhost:8080" method="send_email" value="5"/>
    <handler addr="localhost:8080" method="send_email">
      <param type="string" value="%1"/>
      <param type="string" value="%2"/>
      <param type="string" value="%3"/>
    </handler>
  </action>
</comgpid>

Configuring the action launch.

An example of a nodejs program that “listens” the 8080 port, receives XML-RPC requests from the Skylark server and outputs the request content to the command line.

server.js

var http = require('http');
 
var svr = http.createServer(function(request, response) {
	var body = "";
	    console.log("url: " + request.url);
 
	console.log("method: " + request.method);
    console.log("headers: ");
	console.log(request.headers);
	request.on('data', function (chunk) {
 
		body += chunk;
	});
	request.on('end', function () {
		console.log('body: ' + body);
	})
	}).listen(8080);

The “http” nodejs extension must be installed for this example to work (the “npm install module_name” command). Launching the program is implemented from the command line interface: “nodejs program_file_name.js”.

Content of the XML-RPC request that was received by the program while triggering the “send” action.

Replay Server Management from JavaScript via Instant Replay API

Configuring “Now Playing” Captions

Configuring “Coming up Next” Captions