Triggers Action

The Triggers action allows you to send a signal to the Player API to activate a specific piece of content for playback on the screen.

When using triggers you must first assign the Slave designation to a loop policy of the frame where the triggered content will play. Once activated by a signal, the Slave frame will then immediately switch to the content that has the assigned trigger category.

The player can accept triggers using any of the following methods:

Creating triggered (Slave) content can be done in three steps:

  1. Add a Trigger category to be used by the frames displaying the triggered content – Create a new category for the trigger with a descriptive name (e.g., “Serial Trigger”). See Add a Category.
  2. Enable the Slave flag on the loop policies of the targeted frames – Edit the respective loop policies of the matching frames and set the Synchronization setting to Slave. The trigger event will activate and playback the content scheduled in the “Slave” loop policy. See Edit Loop Policy Properties – The Settings Section.
  3. Book campaigns targeting the Slave frame that contain bundles with the matching trigger category (e.g. a bundle with category “Serial Trigger”). See Book a Campaign.
Playlist

When the slave campaign finishes playing, the default action is to replay the interrupted slot. However, if you use Trigger Next, Trigger Timeout, or Trigger Skip Control, you have other options. See Use Command-Line Triggers (below).

By default, slave frames will filter out any bundle that has a Category ID, and wait for the trigger before playing triggered content. This results in triggered content only being played when the Master frame plays the appropriate content.

To allow a player to receive signals via a serial port, you must create a triggers.xml file. When bytes are available on the port the player then reads them and performs a lookup in the triggers.xml file to see if it corresponds to a category ID. If a mapping can be found, it uses the synchronization framework to instantly change the player’s content.

A configurable timer will read the triggers.xml file periodically if the modified timestamp changes. This is to allow the Monitor Synchronization service to synchronize the file periodically.

Sample triggers.xml
<triggers version="1.0">
  <device type="serial" enabled="1">
    <param name="name" value="COM3"/>
    <param name="internal_name" value="com_port3"/>
    <param name="bps" value="9600"/>
    <param name="byte_size" value="7"/>
    <param name="parity" value="none"/>
    <param name="read_timeout" value="50"/>
    <param name="write_timeout" value="50"/>
    <param name="flow_control" value="off"/>
    <param name="stop_bits" value="1"/>
  </device>
  <trigger match="01" category_id="2840831" duration="10000"/>
  <trigger match="02" category_id="2840832" duration="10000"/>
  <trigger match="*" category_id="2840833" duration="10000"/>
</triggers>
Parameter Description
param name The fields are used to specify standard RS-232 port communication properties.
trigger match The hexadecimal information sent from an external device to the player. The special “*” match is an optional default value if no other matches are found.
category_id The bundle category of the content that will be triggered.
duration The length of time in milliseconds that the trigger content will be displayed.

Remember, you must send trigger XML commands to the localhost on port 2325 of the player.

When using XML triggers, it is not necessary to create a triggers.xml file.

The trigger match and category information need to be set in the XML message, and then sent to port 2325 as follows:

<rc version="1" id="1" action="trigger" trigger_category_id="1234" duration="1000"/>\r\n\r\n

And the response is:

<rc id="1" version="1" action="trigger" status="1"/>

Each command can be sent with a unique ID so the client application can multiplex requests. The application can use a simple incrementing value for the ID. The following parameters are required:

Parameter Description
version The version is always 1.
id Contains the ACT value.
action The kind of action to be taken, is always “trigger”.
trigger_category_id The bundle category of the content that will be triggered.
duration The length of time in milliseconds that the trigger content will be displayed.

All the frames that are on the display at the time that are set to be Slave frames will immediately play ad copy bundles that have the corresponding trigger category ID set.

We provide a tutorial describing the steps for frame synchronization. See Advanced Tutorials – Frame Synchronization.

It is also possible to trigger playback in a Slave frame of a display unit by playing a trigger content in a Master frame. This is typically used to synchronize content between frames within a single display unit.

To create triggering (Master) and triggered (Slave) content, you must create the following:

    • A trigger category to be used by the synchronizing frames – Create a new category for the trigger with a descriptive name (e.g., “Synch Trigger”).
    • Master and Slave designations on the loop policies of the matching frames – Edit the respective loop policies of the paired frames and set the Synchronization flag to Master or Slave. The trigger content in the frame using the “Master” loop policy will trigger playback of the slave content scheduled in the “Slave” loop policy.
    • Create separate Campaigns targeting the Master and Slave frames that contain Bundles with the matching Trigger Category (e.g., “Synch Trigger”).

When a piece of content in the Master frame is played that has a category that matches the Master/Slave category it will then activate the content in the Slave frame.

As an example, this technique can be used to display movie show times in a side bar when the movie preview appears in the main frame.

When using external triggers it is not necessary to specify a Master frame. This is because the Slave frame will be receiving a signal from either RS-232 or XML connections. The Slave frame, however, must use a Slave-flagged loop policy.

External Triggers for Master Players

External triggers for Master players
It is possible to set  a Master loop policy so that it accepts external triggers.  The setup is done in the remote configuration associated to the Master player where it is possible to select the set of trigger ids that will be issued from an external source.

Behaviour of external triggers

The selected external triggers will be used when a master loop policy generates its playlist. Any playlist items that have a trigger id that matches one of the external triggers will be stripped from the playlist and placed in a bucket of triggerable content.

This means that any content scheduled to the master with a trigger that matches one of the external trigger ids will not play as part of the normal loop: it will only play when triggered via an external application.

Flash content can use triggers for interactive displays by adding buttons or other inputs for users to manipulate by adding an ActionScript to the content. By pushing or clicking a button, the Flash content will trigger content in a slave frame. The content is selected by specifying the associated category id and the content’s playback duration can also be specified in the ActionScript.

When using Flash triggers it is not necessary to specify a Master frame. This is because the Slave frame will receive the trigger from the Flash content. The Slave frame, however, must use a Slave-flagged loop policy.

// Start ActionScript 2.0
var theSocket:XMLSocket = new XMLSocket();
theSocket.onConnect = function(myStatus) {
  if (myStatus) {
    // replace xxxxxx with the appropriate category id
    // replace yyyyyy with the duration for the triggered content
    //duration is in milliseconds
    var myString:String = "<rc version=\"1\" id=\"1\" action=\"trigger\"
      trigger_category_id=\"xxxxxx\" duration=\"yyyyyy\"/>\r\n\r\n"; 
    theSocket.send(myString);
  }
};
theSocket.connect("localhost", 2325);

It is also possible to issue triggers by using the built-in executable trigger. You can find it in the bin/ directory of a Broadsign Player installation.


Usage:
./trigger trigger_category_id [options]

Options:
-?, -h, --help: Displays this help.
-v, --version: Displays version information.
-a, --address <hostName>: Address to connect [localhost or ignored if broadcasting].
-p, --port <port>: Port to connect [2324 or 2325 if broadcasting].
-S, --ssl: Use SSL/TLSv1.
-w, --password <password>: Use provided password (Tcp only).
-d, --duration <duration>: Duration in milliseconds [0 (no duration)] (unused for action_name "condition").			
-b, --broadcast: UDP Broadcast.
-u, --prebuffer <prebuffer>: Instead of playing the trigger right away, pre-buffer it for the next playback. [false]
-n, --play_next <playNext>: Instead of playing the trigger right away, insert it next in the playlist. [false]
-i, --id <playerId>: Player ID broadcasting the trigger (UDP only).
-s, --synchronization_set <sourceName>: Name of the synchronization Set.
-r, --synchronization_role <syncRole>: Synchronization Role (1 - Master, 2 - Backup Master).
-o, --disable_audio <disableAudio>: If supported, disable the audio. The prebuffer setting needs to be true. [false]
-t, --timeout <timeout>: When using play_next, interrupt the current content after the specified timeout in milliseconds. [0 (no timeout)]
-c, --truncate_current <truncateCurrent>: Do not restart the current content after the trigger has finished playing. [false]

Arguments:
trigger_resource_id: Trigger Category ID
Trigger Next and Timeout
    • -n [ --play_next ] arg: Instead of playing the trigger right away, insert it next in the playlist.
    • -t [ --timeout ] arg: When using play_next, interrupt the current content after the specified timeout in milliseconds. [0 (no timeout)]

It is possible to specify a “play next” option on external triggers so that instead of having the triggered content playing right away, it will be inserted as next in the playlist.

In addition to the play_next action, another optional timeout value can be added. This timeout value will ensure that the “Trigger Next” content does not have to wait too long before being displayed. If the currently playing content exceeds the timeout value, it will be interrupted and the trigger next content will then play.

The timeout value is optional. If not specified, the “Trigger Next” will wait until the completion of the current slot before being displayed. The timeout can be specified as a command line option for trigger and also via an XML attribute that can be sent to port 2325.

Trigger Skip Control
    •  -c [ --truncate_current ] arg: Do not restart the current content after the trigger has finished playing.

By default, when issuing a trigger causing an interrupt of the content being played back, the interrupted content restarts once the trigger is over. With the truncate_current option, this behavior will no longer apply and the next spot will be played back.

A custom application can use triggers by sending a JSON message to the WebSocket server of triggers (port 2326). You will need to enable the WebSocket server. For more information, see Configuration Profiles – Players – The Remote Control Tab.

{
  "rc": {
    "synchronization_role": "2",
    "truncate_current": "0",
    "version": "1",
    "pre_buffer": "0",
    "synchronization_set": "0",
    "disable_audio": "0",
    "trigger_category_id": "49114",
    "action": "trigger",
    "id": "1"
  }
}

The player will respond with the following document:

{
  "rc": {
    "id": "1",
    "version": "1",
    "action": "trigger",
    "status": "1"
  }
}
Triggers – JSON Parameters
Parameter Description
id Contains the identifier of the request.
version The version is always 1.
action The kind of action to be taken, in this case trigger.
status A result of “1” indicates that the command succeeded.
synchronization_role The role of the resource in the synchronization setup (1 – Master, 2 – Backup Master).
truncate_current Do not restart the current content after the trigger has finished playing. [false]
prebuffer Instead of playing the trigger right away, pre-buffer it for the next playback. [false]
synchronization_set Name of the synchronization set.
disable_audio If supported, disable the audio. The prebuffer setting needs to be true. [false]
trigger_category_id The ID of the trigger category.