WebApi

Overview

Composer provides WebAPIs for integration with backend systems such as game logic engines, automation systems, or web servers. The WebAPI allows external applications to control Composer through HTTP(S) requests secured with private API keys.

The built-in Connectors system enables you to create API triggers that execute customizable action sequences. For more information, see the Connectors chapter.

Use cases

Create dynamic setups that interact with your game or external data
Build API-triggered events using Connectors
Enable camera switching and scene layer control
Trigger effects and animation playback
Animate layer properties with ease in/out transitions
Inject cue points (timed metadata) into Vindral Live CDN

💡Your title goes here
Composer offers several ways to integrate with external systems — WebAPI, Connectors, Batches, and Script Engine. Read the Integration Guide to learn what each does and when to use them.

Prerequisites

Important

On Windows, the application must be launched with Administrator permissions. Otherwise, the WebAPIs will be inactive.

Before using the WebAPI, ensure:

The WebAPI is enabled in Composer settings
Your firewall allows incoming and outgoing traffic on the configured port
For HTTPS: A valid certificate and FQDN are configured

Activating the WebAPI

Enable and configure the WebAPI in the settings window:

Connection settings

The API can be reached over HTTP or HTTPS:

HTTPS: Port 443 (requires a certificate and FQDN)
HTTP: Configurable port (default: 44433)

HTTPS example:

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

HTTP example:

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

API availability

During an auto-restart of the application, the WebAPI is temporarily disabled and returns:

"The current configuration does not allow API calls when the playback state is not running. API call ignored. Caller IP: [::1]:55569"

If changes are made to the WebAPI settings, restart the application for them to take effect.

Authentication (API keys)

API keys add an additional layer of security to your WebAPI. Keys are defined in a JSON file named apikeys.json located in the application root folder.

Example configuration with two API keys:

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

Behavior:

If API keys are defined, all API calls must include a valid key
If no keys are specified, no key is required
Invalid API keys return HTTP 403 (Forbidden)

Making API calls

Include the API key as a query parameter when authentication is enabled:

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 reference

Connectors

Trigger a connector

/api/connector/trigger?name=[NameOfConnector]
        /api/connector/trigger?name=[NameOfConnector]&param1=[variable]

Executes a connector defined in the Composer GUI under the Connectors tab. Returns a success or error code.

Parameters:

name (required): Name of the connector to trigger
param1 or [anyname] (optional): Variable value used to set string properties via @@paramname. See Parameterized Connectors.

Example:

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

Media and inputs

Send metadata (cue points)

/api/metadata/send?targetid=[Private ID]&message=[message]

Sends timed metadata to a Vindral CDN Metadata target. Returns a success or error code.

Parameters:

targetid: Private ID of the Vindral CDN Metadata target
message: Message content to send

You can also send metadata via Connectors, which eliminates the need to include the target ID in the API call. See Parameterized Connectors.

Jump to CAV cue point

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

Jumps to a specific cue point within a CAV video file. Read more about CAV files.

Parameters:

targetname: Name of the CAV input in Composer
cuepointid: Name of the cue point in the .cav file

Play a video file

/api/media/videofileinput/play?videofileinput=[video_input_name]&sourceuri=[absolute_or_relative_path_to_video_file]

Loads and plays a new video file in the specified video input. The path can be absolute or relative. Playback starts automatically once the file is parsed.

Get audio level

/api/scene/audio/getaudiolevellastsecond?scene=Scene

Returns the average audio level (last second) for all 8 channels. Values range from 0 to 1. Only works when the project is set to use 8 audio channels.

Example response:

[0.5566802, 0.5569817, 0, 0, 0, 0, 0, 0]

Get a list of SRT Inputs

/api/inputs/get/srt

Returns a JSON list containing all SRT inputs:

Sample response:

[
  {
    "Id": "92442724-ace6-4b2b-b344-673026004c8f",
    "Name": "SRT input",
    "ListenerAddress": "srt://@@LocalIP():9000?mode=listener&latency=200000",
    "RunningListenerAddress": "srt://192.168.0.2:9000?mode=listener&latency=200000",
    "SrtInputStreamState": "ReceivingData",
    "ListenerStatus": "Started",
    "RunningIndicatorState": "Running",
    "StreamTime": "0:00:19:24f",
    "Width": 1920,
    "Height": 1080
  },
  {
    "Id": "611e5753-264b-44d4-b5ff-6efb79f98867",
    "Name": "SRT input #2",
    "ListenerAddress": "srt://0.0.0.0:[port]?mode=listener&latency=200000",
    "RunningListenerAddress": "",
    "SrtInputStreamState": "NotStarted",
    "ListenerStatus": "NotStarted",
    "RunningIndicatorState": "None",
    "StreamTime": "0:00:00:00f",
    "Width": 0,
    "Height": 0
  }
]

Get a list of SRT Targets

api/targets/get/srt

Returns a JSON list containing all SRT targets.

Sample response:

[
  {
    "Id": "49baa16b-a9ee-49d6-bc7f-ba204f90e494",
    "Name": "SRT Target #1",
    "SrtConnectionString": "srt://@@localip():9001?pkt_size=1316&latency=200000&mode=listener",
    "CurrentSrtEndPoint": "srt://192.168.0.2:9001?pkt_size=1316&latency=200000&mode=listener",
    "ConnectionStatus": "Connected",
    "RunningIndicatorState": "Running",
    "UpTimeSinceStart": "18 seconds"
  },
  {
    "Id": "0821b089-cb61-4af7-936f-90694afeb516",
    "Name": "SRT Target #2",
    "SrtConnectionString": "srt://[ipadress]:[port]?pkt_size=1316&latency=200000&mode=caller",
    "CurrentSrtEndPoint": "",
    "ConnectionStatus": "Disconnected",
    "RunningIndicatorState": "None",
    "UpTimeSinceStart": ""
  }
]

Get a list of RTMP Targets

api/targets/get/rtmp

Returns a JSON list containing all RTMP targets.

Sample response:

[
  {
    "Id": "6a425de4-a82e-4aa5-9afc-b2ab46af58b3",
    "Name": "RTMP Target",
    "RunningServerAddress": "rtmp://[ipadress]:[port]?...",
    "CurrentRTMPEndPoint": "rtmp://[ipadress]:[port]?...",
    "ConnectionStatus": "Connected",
    "RunningIndicatorState": "Running"
  }
]

Scenes and layers

Disable scene rendering

/api/scene/disablerender?target=<nameOfScene>&value=<true/false>

Disables or enables scene rendering. Disabling unused scenes improves performance.

Parameters:

target: Scene name in Composer
value: true (disable) or false (enable)

Batch layer operations

Control multiple layers using batch names. See Scene layers for details.

/api/batch/showlayer?batch=FrontCam
        /api/batch/hidelayer?batch=FrontCam
        /api/batch/showlayersolo?batch=FrontCam

Set layer source

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

Changes the input source of a scene layer. The source must exist in the Inputs list (URLs are not valid).

Parameters:

scene: Scene name
layer: Layer name
source: New input name

Images

Get scene image

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

Returns a JPEG image of the specified scene. If no scene is specified, returns the "main" scene (the latest added scene has highest priority; nested scenes have lowest priority).

Optional parameters:

width: Image width in pixels
height: Image height in pixels
quality: JPEG quality (0-100)
scene: Scene name (case-sensitive)

Get the face detector image

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

Returns a JPEG image of the best face detection result. The Private ID is found in the Face Detect Operator settings.

System information

Get settings

/api/settings/get

Returns the current settings.xml as JSON.

Get project XML

/api/project/getxml

Returns the current project.prj as XML.

Get last errors

/api/lasterror/get

Returns the last 20 errors.

Get system information

/api/systeminfo/get

Returns system information as JSON. (Desktop version only)

Get license information

/api/license/get

Returns license information as JSON.

Validate license

/api/license/validate

Returns license validation information as JSON.

Get the performance report

/api/reports/getperformancereport

Returns performance information as HTML.

Get Composer statistics

/api/getstatistics

Returns Composer statistics as JSON.

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 for all targets as JSON.

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.xxx.cdn.vindral.com/publish/xxx_demo_xx_e4dc1483-xxxx-xxxx-xxxx-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 target object properties as JSON. Only works for Target objects.

Alarms

For more information on Alarms, see the Settings chapter.

Get alarm status

/api/alarms/get

Returns alarm status as JSON.

Clear alarms

/api/alarms/clear

Clears all active alarms.

Application control

These APIs control the Composer application state. (Windows Desktop only)

Start Composer

/api/start

Starts the Composer processing engine. Can only be called when Composer is stopped (but not quit).

Stop Composer

/api/stop

Stops the Composer processing engine. Can only be called when Composer is running.

Exit Composer

/api/exit

Exits (quits) the Composer application. Can only be called when Composer is stopped and the setting “Disable Web Api when project not running” is disabled in Settings/Web API.

Save project

/api/project/save

Saves the current project file. If Composer is stopped, "Disable Web API when the project is not running" must be disabled in settings.

Note

In the Desktop version, adding, removing, or rearranging inputs will not be saved via the API. Use File > Save instead. Only property modifications are saved via API.

Testing and debugging

Force a congestive state

/api/tests/setcongestive

Forces an auto-flush of the application worker queue by simulating a congestive state.

Simulate a fatal error

/api/debug/fatal

Simulates a fatal error in Composer.

Simulate error

/api/debug/error

Simulates an error in Composer.

Simulate warning

/api/debug/warning

Simulates a warning in Composer.

TLS/HTTPS configuration

The WebAPI supports both HTTP and HTTPS connections. To use HTTPS, you must configure a fully qualified domain name (FQDN) and install a valid TLS certificate on the host machine.