Composer provides WebAPIs:s for integration with backend systems such as game logic engines, automation systems, or web servers. API:s are secured via HTTP(S) and private API keys. The WebAPI of Composer allows external applications or systems to control Composer in many different ways. The built-in concept of Connectors makes it possible to create API triggers that execute a series of customizable actions. More on Connectors can be found in the Connectors chapter.

Use cases

• Use the APIs for dynamic setups that interact with your game or external data. 

• Build API-triggered events (connectors)

• Enable camera switching

• Use effects and animation playback

• Delay execution

• Animate layer properties (ease in/out)

• Enable cue point (metadata) injection into Vindral Live CDN

Activating the WebAPI

Composer WebAPI can be enabled and configured in the settings window:

The API can be reached over HTTP or HTTPS (requires a certificate and a host with an FQDN).
The HTTPS API can be reached on port 443, while the HTTP API can be reached at the configured port.

HTTPS example: 

https://composer.internal/api/settings/get

HTTP example: 

http://192.168.0.100:44433/api/settings/get

Composer Web API can be disabled or enabled in the application settings.
During an auto-restart of the application, the Web API will temporarily be disabled and return:
“The current configuration does not allow API calls when the playback state is not running. API call ignored. Caller IP: [::1]:55569” 

Composer is, by default, set to listen to any HTTP API call on port 44433. You can change the port number in the settings “Web API listening port:”
Ensure the operating system's Firewall has the port open for incoming and outgoing traffic.

ApiKeys.json (optional)

If the API is enabled (via HTTPS or HTTP), defining secret API keys can add an additional level of security. 

API keys are defined in a JSON file, “apikeys.json”, in the application root folder.

Below is an example in which two API keys have been defined:

{
"Keys": [
	"a3583efd-de12-4274-af47-7d8291626ea8",
	"2014c992-63b1-4d41-8881-c6ed63a32cf2"
	]
}

If API keys are defined, any API call must include a valid API key for the API call to be accepted. If no API keys are specified, no API key is required.
Using an invalid API key will return an HTTP RESULT 403 (Forbidden).

Example of an API-call which includes an API key query parameter:

HTTPS  :

https://composer.internal/api/connector/trigger?name="WinningNumber"&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8

HTTP:

http://[yourIp:port]/api/connector/trigger?name="WinningNumber"&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8

Calling a WebAPI

Example of an API call that includes an API key query parameter:

HTTPS:

https://composer.internal/api/connector/trigger?name=WinningNumber&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8

HTTP:

http://[yourIp:port]/api/connector/trigger?name=WinningNumber&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8

API functions

Connectors - Executing connectors

/api/connector/trigger?name=[NameOfConnector]

or with parameters:
/api/connector/trigger?name=[NameOfConnector]&param1=[variable]

Returns a success or error code.

This API is used for triggering the connector that has been created and defined in the Composer GUI, under the tab "Connectors"

Example:
http://[yourIp:port]/api/connector/trigger?name=MyConnectorName

Parameters:

• name: Name of the connector to trigger/execute (example above = MyconnectorName)

• param1 or [anyname]: A variable value of a parameter can be used to set string properties in a Connectors Api command using the @@paramname. Read more about Parameterized Connectors.

Target - Send metadata (“cue points” or “timed metadata”)

/api/metadata/send?targetid=[Private ID]&message=[message]
(this assumes you have added and configured a “Vindral CDN metadata target”. See chapter Vindral CDN Metadata Target)

Returns a success or error code

Parameters:

• targetid: private id of the Vindral CDN Metadata target

• message: message to send

Another way of sending metadata is via connectors. See chapter Parameterized Connectors: The advantage of using connectors is that you do not need to use the “Vindral CDN Metadata target” targetID in the API call.

Input - CAV media - Jump to Cue Point (.cav media file)

When using CAV video files, it is possible to add cue points in the video, and use the API to jump between the cue points within the videofile. Read more...

api/cavjumptocuepoint?targetname=<nameOfInput>&cuepointid=<nameOfCuePoint>

Returns a success or error code

Parameters:

• targetname: The name of the CAV input in Composer

• cuepointid: The name of the cue point defined in the .cav media file

Input - Scene - Disable Scene render property

By disabling the render property of a scene, the scene and the scene operators and targets will not be rendered. This is used for turning off unused scene render that will increase performance.

http://localhost:44433/api/scene/disablerender?target=<nameOfScene>&value=<true/false>

Parameters:

• target: The name of the Scene in Composer

• value: True/False

Audio - Retrieve the average audio level (last second) for a scene

http://localhost:44433/api/scene/audio/getaudiolevellastsecond?scene=Scene

This api will return the audio level for all 8 channels (level=0-1)
Example response:
[0.5566802, 0.5569817, 0, 0, 0, 0, 0, 0]

Scene layers - Batch

See batch function in Scene layers.

/api/batch/showlayer?batch=FrontCam

/api/batch/hidelayer?batch=FrontCam

/api/batch/showlayersolo?batch=FrontCam

Scene layers - SetSource

Set/change the Input source of a scene layer.

/api/layer/setsource?scene="MySceneName"&layer="MyImageLayerName"&source="MyNewInputName"

scene = The scene name
layer = The scene layer name
source = The Input name of the source (Source must be in the list of Inputs in Composer, urls are not valid)

Get settings

/api/settings/get

Returns the current running settings.xml JSON, or an error code

Get project.xml

/api/project/getxml

Returns the current running project.prj as XML.

Get last error

/api/lasterror/get

This method will return the last 20 errors.

Get system information

(Only supported on the Desktop version)

/api/systeminfo/get

Returns system information as JSON data

Get license information

/api/license/get

Returns license information as JSON data

Get license validation information

/api/license/validate

Returns license information as JSON data

Get Composer statistic

/api/getstatistics

Returns Composer statistic information as JSON data

Sample response:

{"DateTime":"2023-10-16T06:12:12.364008Z","MachineName":"NICLAS-RYZEN-9","ApplicationVersion":"1.7.8689.13892","ApplicationStarted":"2023-10-16T07:43:13.0648293+02:00","LastProjectFile":"C:\\VindralLocalMedia\\Projects\\reallocate-missing-garbage-lut-cleanplate.prj","StartAllInputsOnStart":true,"StartAllTargetsOnStart":false,"VideoFrameRate":"Fps2997","SessionStarted":"2023-10-16T07:43:18.6958653+02:00","SessionUptime":"00:28:53.6677399","PlaybackState":"Running","NumCongestiveFramesSinceStart":4,"NumWorkerQueueFlushesSinceStart":0,"AverageProcessingTime":4.3,"ProcessingQueueSize":0,"FramesProcessed":51965,"NumAuthorizedApiCalls":1,"LastAuthorizedApiCall":"2023-10-16T08:12:12.3637764+02:00","NumErrorsReported":1,"LastErrorReported":"2023-10-16 07:43:18:: Could not locate LUT image: C:\\VindralLocalMedia\\Media\\Videos\\LutRgbToLab2.png ","NumWarningsReported":2,"LastWarningReported":"2023-10-16 07:43:14:: This is a trial version. Application will only run for a random number of hours - in this session 22 hours. ","LastApiTriggerInvoked":""}

Get target statistics

/api/targets/getstatistics

Returns statistics information (Json) on all targets.

Sample response:

{"MachineName":"NICLAS-RYZEN-9","Project":"C:\\Users\\nicla\\Desktop\\ComposerMultibrandingDemo\\ComposerMultibrandingDemo\\Projects\\Multibranding.prj","DateTimeString":"2023-02-16T09:52:04.9411056Z","RtmpTargets":[{"Name":"RtmpTarget Brand A","ConnectionStatus":"Connected","CurrentRTMPEndPoint":"rtmps://rtmp.eu-north.cdn.vindral.com/publish/realsprint_demo_sk_e4dc1483-e3d0-4787-9cd1-ced5a3716ff5","UpTimeSinceStartTimeSpan":"00:00:09.6466745","OutgoingBitRateMbitPerSecond":"4,201691","NumAutoReconnectsperformed":"0","AverageVideoEncoderTimeMs":4.987999999997555,"MaxVideoEncoderTimeMS":11.510000000009313,"AverageNetworkWriteTimeMs":0.08589999999094289,"OutputQueueSize":"0","ErrorCount":"0","LastErrorDateTime":"","LastErrorMessage":"","WarningCount":"0","LastWarningDateTime":"","LastWarningMessage":"","VideoFramesWritten":"290","AudioFramesWritten":"453"},{"Name":"RtmpTarget Brand B","ConnectionStatus":"Disconnected","CurrentRTMPEndPoint":null,"UpTimeSinceStartTimeSpan":"00:00:00","OutgoingBitRateMbitPerSecond":"0","NumAutoReconnectsperformed":"0","AverageVideoEncoderTimeMs":0.0,"MaxVideoEncoderTimeMS":0.0,"AverageNetworkWriteTimeMs":0.0,"OutputQueueSize":"0","ErrorCount":"0","LastErrorDateTime":"","LastErrorMessage":"","WarningCount":"0","LastWarningDateTime":"","LastWarningMessage":"","VideoFramesWritten":"0","AudioFramesWritten":"0"}]}

Get target object properties

/api/objects/getproperties?targetname=<nameOfTarget>

Returns object properties as JSON data
Only works for Target objects.

Get image

/api/image/get?width=[Value]&height=[Value]&quality=[Value]&scene=[scenename]

Returns a jpeg image or an error code
If no "scene" is added as a parameter, the returned image is what Composer thinks is the "main" scene. If there are several scenes, the latest added scene has the highest priority, nested scenes have the lowest priority.

Optional parameters:

• width: image width

• height: image height

• quality: image quality in percentage (0-100)

• scene: The name of the Composer scene (Inputs & scenes). [scenename] is case-sensitive.

Get Face Detector Best Result Image

/api/facedetect/getimage?target=[Private ID]

Returns a jpeg image or an error code

The Private ID is found in the Face Detect Operator, 

Alarms

For more information on Alarms, see the Settings chapter.

/api/alarms/get

Returns Alarm status as JSON data

/api/alarms/clear

Calling this Api will clear any active Alarm.

Controlling Composer state

/api/start

Starts the Composer processing engine.
Returns a success or error code. The start API call can only be made when Composer is stopped.

/api/stop

Stops the Composer processing engine.
Returns a success or error code. Note that the stop API call can only be made when Composer is started.

/api/exit

Exits (quits) the Composer processing engine.
Returns a success or error code. Note that the exit API call can only be made when Composer is stopped.

/api/project/save

Saves the current project file.
Returns a success or error code. If Composer is stopped, the "Disable Web API when the project is not running" must be unset in the application settings. Otherwise, the project file will not be saved.
NOTE! In the Desktop version, removing/adding/rearranging inputs will not be saved using the API, use the File/Save instead. Properties modified for the project will be saved.

Test and debug

/api/tests/setcongestive

Force an auto-flushing (flushes the application worker queue internally, forced by the system being in a congestive state)

/api/debug/fatal

This will simulate an execution of a fatal in Composer.

/api/debug/error

This will simulate an execution of an error in Composer.

/api/debug/warning

This will simulate an execution of a warning in Composer.

Regarding TLS/Certificates

The WebAPI can be accessed via HTTP or HTTPS. HTTPS requires an FQDN and a valid certificate.