The Connectors feature is one of Composer's most powerful features. Connectors allow you to define a custom series of commands, that can be triggered via the built-in HTTP API. This allows external systems, such as a game server, a community server, or any other external backend system, to trigger a sequence of commands within Composer. 

Connectors are very flexible and can be used for scene changes, switching cameras, starting animation playback, hiding or showing scene layers, switching audio to a different sound soundtrack, and much more.

The difference between a regular Composer API and a Connector is that a Connector will perform actions you define, while a regular API will perform a predefined command or request.

Connectors can change and animate any property or trigger commands (play, stop, connect, etc) on any object within Composer. This includes all inputs, scenes, layers, operators, and targets. These changes are called API Commands, and a single Connector can contain any number of API Commands.

Calling a Connector from an external application is very easy. There are two different ways to call a connector: by the "Name" of the connector or by the "Value". Below is an example using the Name:

http://YOURIP:PORT/api/connector/trigger?name=MyConnectorName

In the example above, the YOURIP:PORT exposes a Connector called "MyConnectorName". Triggering this connector will trigger the commands defined for the "MyConnectorName" connector.
When using Name to trigger a connector, the "Evaluation" function does not apply. The Evaluation is always "Equals".
The port used is defined in Settings under the tab Web API.

Below is an example using the Value:

http://YOURIP:PORT/api/connector/trigger?value=MyConnectorValue

Working with Connectors

Example: A newly added connector with the name "MyConnectorName", listening to any HTTP connector API-call containing the Name="MyConnectorName" or an API call containing the Value="MyConnectorValue":

To add a new connector, use the Connectors tab and click Add connector.
To collapse all expanded connectors use the button "Collapse all"
The name of a connector can be changed by double-clicking on the title.
To delete a connector, select the connector and press the DELETE key or right-click and select "Delete".
To clone a connector, right-click on the connector and select the Clone popup item.
Re-arrange the order of the connectors by drag and drop.

• Name: The name of the connector ("MyConnectorName)". Dubble-click to rename.
• Evaluation: Contains, ContainsNot, Equals (default), EqualsNot. This only applies when using "Value" calling a connector. When using "Name", the Evaluation is ignored and is threatened as "Equals".
• Value: The key Value to be used when calling a connector by value.
• Invoked # times: Number of times the connector has been invoked.
• Invoke: By clicking the "Test" button, the commands assigned to the connector will be triggered.
• Add Api command: See below.

Adding API commands (actions) to a connector

To add API commands, click on the Add API command button.
To remove an API command, right-click on the API command and select ”Remove API command”.
Re-arrange the order of the commands by drag and drop. Holding down the ALT key will create a COPY of the command when dragging to a different connector.

A connector can consist of several API commands. Each added API command will have the following properties: Target, Property, Value, Delay, Animation time, and Interpolation.

Target - item on which the API command is applied.
Property - the property of the target item on which a new value should be applied
Value - new value
Delay - delay before the API command is executed
Animation time - some properties support animation. This property sets the animation duration.
Interpolation - set the interpolation method for animated properties.

An empty connector containing no API commands (aka “actions”) does not affect Composer.

Connector example

In the example above, using "Name", the connector will listen to API calls with the syntax name=WinAnimation32:

http://YOURIP:PORT/api/connector/trigger?name=WinAnimation32

Using "Value", the connector will listen to API calls with the syntax value=win32 (with the evaluation set to "Equals"):

http://YOURIP:PORT/api/connector/trigger?value=win32

When triggered, four(4) commands will take place:

1.  Set the opacity of the scene layer win_32.mp4 to 0. (Just to be sure it is reset before starting the command sequence)
2.  Start playing the win_32.mp4 media file.
3. Animate the opacity from 0 to 100 during a period of 500ms using Ease in & out
4. After a delay of 2000ms, animate the opacity from 100 to 0 during a period of 500ms using Ease in & out

Parameterized Connectors:

A Connector may also utilize parameters that are useful for some actions. One example is cue points where the Composer should send a cue point containing an eventid (or any other type of metadata). This eventid/metadata can be supplied in any Connector definition and is used by some actions.

Below is an example call using the Name of the Connector:

http://[YOURIP:PORT]/api/connector/trigger?name=VindralMetaDataConnector&Param1="32"

Below is an example call using Value property of the Connector:

http://[YOURIP:PORT]/api/connector/trigger?value=SendCuePoint&Param1="32"

In the examples above, the Param1 value of 32 can be used in an action where a cue point is ingested into the outgoing video stream.

To pass the Param1 value into an API command, use the @@ prefix before the parameter name. Below is an example of how the @@Param1 value is used for forwarding Param1 as a message (cue point) into the Vindral CDN Metadata Target: (See Vindral CDN Metadata Target how to set up and configure the Vindral CDN Metadata Target)

Calling multiple Connectors in a single API-call:

It is possible to call multiple connectors in a single API-call by using the Names of the Connectors. To call multiple connectors, separate each connector with the + character (%2B).

Example:

http://[YOURIP:PORT]/api/connector/trigger?name=BigWinAnimation%2BWinAnimation32

It is also possible to call multiple Connectors when using "Value" in combination with "Evaluation" properties "Contains", ContainsNot" and "EqualsNot".
The below example will trigger both the Connectors with the value "BigWin" and "Win32" because they both contains "Win".
Example:

http://[YOURIP:PORT] /api/connector/trigger?value=Win

Using the Script Engine with Connectors

The built-in Script Engine can execute a script function when a connector is called. To use this feature, ensure you have enabled the Script Engine in Settings and created a script for your project. You also need to create the script function and name it OnConnectorYourConnectorName.

Below is an example of how the connector named TestConnector can trigger a script function and send a parameter to Composer:

http://[YOURIP:PORT]/api/connector/trigger?name=TestConnector&myparameter=123

The script function name is defined as OnConnectorYourConnectorName. In this example, the connector is called TestConnector, and therefore we define the OnConnectorTestConnector function:

function OnConnectorTestConnector(parameters)
{
    Logger.Debug("MyConnector called. Parameters: "+parameters);
}

Composer will only execute script functions when a connector is triggered using the name selector. Using the value selector is not supported.