- 19 Mar 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
WebAPI
- Updated on 19 Mar 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
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.
Important!
On the Windows platform, the application needs to be launched with elevated user permissions (Administrator). Otherwise, the Web APIs:s will be inactive.
If changes are made to the WebAPI settings, the application needs to be restarted.
ApiKeys.json
If the API is enabled (via HTTPS or HTTP), there is an option to add an additional level of security by defining secret API keys.
API keys are defined in a JSON file, “apikeys.json”, found 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 defined, 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?value="WinningNumber"&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8
HTTP:
http://[yourIp:port]/api/connector/trigger?value="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?value="WinningNumber"&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8
HTTP:
http://[yourIp:port]/api/connector/trigger?value="WinningNumber"&Param1="32"&apikey=494df910-9c09-4c7d-b240-37ba8b358de8
API functions
Connectors - Executing connectors
/api/connector/trigger?value=[Value_name]
or with parameters:
/api/connector/trigger?value=[Value_name]¶m1=[variable]
Returns a success or error code.
This API is used for triggering the connector that have been created and defined in the Composer GUI, under the tab "Connectors"
Parameters:
value: Name of the connector to trigger/execute (example above = connectorName)
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
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. Same function as the application menu File/Save.
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 is not 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.