Script Engine

The Script Engine is a powerful feature that allows you to create more complex scenes controlled by code (JavaScript). Almost all features and functions in Composer can be used via the Script Engine, and you can access all inputs, scenes, targets, and connectors.

Using the Script Engine, you can create logic that controls your content based on internal and external information, game events, date/time, and much more. Below are a few examples:

• Start/stop playback of media
• Hide/show layers
• Animate layer opacity, position, or rotation
• Read object properties
• Take action based on date, time, frame count, or external data
• Start/stop targets
• Trigger a connector
• Call a batch command
• Execute a target command
• Switch layer source

The Script Engine is designed to alter the project assets/setup, execute commands, and trigger connectors. It is not intended for building projects or replacing the desktop UI.

Use the Script Engine with caution. RealSprint does not provide support for user-created scripts.

Getting started

Using the Script Engine requires knowledge of JavaScript and an understanding of how Composer works. It should be seen as an advanced feature and is only recommended if you are familiar with JavaScript, have knowledge of software development, and have a deep understanding of Composer.

To start, follow these steps:

1. Enable the Scripting Engine in Settings
2. Save your project (if not yet saved)
3. Add a script to your project using the Script Engine/Create Script menu item.
4. Save and reload your project.
5. Use the Script Engine/Edit Script menu item to edit the script. This menu will use the system's default editor for JavaScript files (.js). If you don’t have an editor, we recommend using Microsoft Visual Code.

Working with numbers
Be aware that floating-point numbers may display more decimal places than expected due to how computers store decimal values (IEEE 754). See the FAQ section for solutions.

Events

The Scripting Engine has three main functions where you add your code:

• OnProjectInit()
  This method is called when the project is loaded and initialized. This is where you initialize your variables and setup your init state.
• OnRenderFrame()
  This method is called on every frame rendered by Composer.
• OnProjectStop()
  This method is called when the project stops (unloads)

Global variables can be declared and shared across different functions. A complete code sample is further down this page.

Object properties, enums, and more

For more information on available object properties and commands, see the Script Engine Property Reference Documentation.

Getting Started

Activating the Script Engine

By default, the Script Engine is disabled, but you can easily activate it in Settings:

• Enable Script Engine - enables or disables the engine
• Enable calling script functions from API: if enabled, script functions can be called from the HTTP API.
• Enable auto-reload of script - if this option is enabled, Composer will reload the script if the script is modified on disk.
• The script file must be located in the same folder as the project file and use the .js extension.

Create a new script

1. From the menu, select Script Engine -> Create Script
   
2. Save and reload the project

Open and Edit the Script

1. From the menu, select Script Engine -> Edit Script
   
2. The script will open in your default text editor.

Script Debug Window

The Script Debug Window provides real-time insight into your script's execution. Since the Script Engine does not support breakpoints or code inspectors, this window serves as your primary debugging tool.

Open the Script Debug Window from the Script Engine -> Open Script Debug Window menu option.

Use the Script Debug Window to:

• Monitor performance – Track execution time to ensure your script runs efficiently within the 400ms limit
• View log output – See messages from Logger.Debug(), Logger.Info(), and other logging functions in your code
• Track errors – Identify runtime errors and exceptions that may cause your script to stop
• Control execution – Start, stop, and reload your script without leaving the interface

The log panel displays timestamped messages from both your script and the Composer engine, color-coded by severity. This makes it easy to trace the flow of your code and pinpoint where issues occur. 

Status Panel

Controls

Log Filters

Use the checkboxes to filter which message types appear in the log:

• Show Fatal errors – Critical errors that stop execution
• Show Errors – Runtime errors
• Show Warnings – Potential issues
• Show Info events – Informational messages (Logger.Info)
• Show Debug events – Debug output (Logger.Debug)
• Show Trace events – Detailed trace-level messages

Your first script

Below is an example of a very simple script:

//Import namespaces
var VindralEngine = importNamespace('VindralEngine');
var Scene = importNamespace('VindralEngine.Compositing.Scene');
var VindralLogLibrary = importNamespace('VindralLogLibrary');

//Declarations that make it smoother to write code
var Project = VindralEngine.Project.RunningInstance;
var Animator = VindralEngine.Animator;
var Logger = VindralLogLibrary.Logger;

//End of required section---------------------------------------

//Declare global variables
let frameCount = 0;

//The OnProjectInit function will be executed at the project start
function OnProjectInit()
{
    Logger.Debug('This is a debug message from the ScriptEngine of Composer, and the OnProjectInit() function');
}

//The OnRenderFrame function will be executed at every frame
function OnRenderFrame()
{   
    //Do some stuff every frame
    frameCount=frameCount+1;

    //On every 300:th frame, log the current frame number
    if (frameCount % 300==0)
        Logger.Debug('FramesProcessed: ' + frameCount);
}

//The OnProjectStop function will be executed then the project stops.
function OnProjectStop()
{
    Logger.Debug('OnProjectStop called by ScriptEngine');
}

Debugging

Debugging your scripts is currently limited to using the logger feature, which can output debug information and track runtime errors. There is currently no support for breakpoints or inspectors.

Security

By default, the scripting engine is disabled, and scripts can only be executed from the same folder as the project file.

Performance

Script performance is presented in the lower right corner of the UI:

Fetching large Composer objects, such as a Scene, may be very costly. Carefully study the Execution time and avoid code that renders a long execution time.

Accessing scripts from the API

Executing JS functions from the HTTP API is disabled by default, but you can enable execution using Settings. When enabled, you can execute the JS function using the /api/scriptengine/execute function.

Example:
http://localhost:44433/api/scriptengine/execute?function=EnableAudioPreview

function EnableAudioPreview()
{
    Project.EnableAudioPreview();
    return ‘Audio preview enabled’;
}

You can also pass parameters to a JS function.

Example - Single parameter:
http://localhost:44433/api/scriptengine/execute?function=MyFunction&parameter=Hello

function MyFunction(message)
{
    return ‘You called MyFunction with the parameter’+message;
}

Example - Multiple parameters in a JSON object:

{
  "playerId": "u123",
  "score": 21
}

Send a request with the JSON package example above:
http://localhost:44433/api/scriptengine/execute?function=MyFunction&parameter={"playerId":"u123","score":21}

function MyFunction(message) {

    // Parse the JSON message
    var data = JSON.parse(message);

    // Extract playerId and score
    var playerId = data.playerId;
    var score = data.score;

    Logger.Info("Player ID: " + playerId + ", Score: " + score);
}

Accessing connectors from scripts

Connectors defined in Composer can be triggered from the Script Engine.

Example:

triggered=Project.TriggerConnectorByName('MyTrigger');

Limitations

By default, scripts have the following limitations:

• Max memory allocation: 4Mb
• Max number of lines executed: 10.000
• Max execution time: 400ms

If any of these limitations are overrun, the Script Engine will render an error and stop.

Code Examples

The Script Demo project in the tutorials menu can be a good starting point.

Script Engine Property Reference List

The Script Engine Property Reference List gives you a detailed overview of all available properties for Inputs, Operators, and Targets, helping you build powerful, customized workflows with the Script Engine.

View the list of available properties here.

Script support functions

Composer has several functions designed as support functions for the Script Engine. These functions provide fast and easy access to commonly used tasks.

For a list of all properties for the inputs, targets, operators, as well as enums, see the Script Engine Property Reference Documentation.

Input

Target

Operator

Connector

Scene

Layer

Batch

HTTP / WebSocket

Project.AddApiCommandToQueue("/api/connector/trigger?name=MyConnector)

Object

Execution Time

Animation

Misc

Animator class

The Animator class supports animating layertransform properties, including position, anchor point, scale, opacity, and rotation.

Layertransform properties exist on all scene layers within Composer.

The cData parameter is currently not used/implemented.
 The AnimateEasing and AnimateOptions parameters are optional.

The example below will animate the layer ‘Scene PGM’ found in the scene ‘Scene PGM with replay’. It will animate the opacity over a period of 1000ms, starting at a value of 30 and ending at 100. The animation will be smoothed using the AnimateEasing option EasiInEaseOut. No additional options are provided.

Project.Animator.AddLayerTransformationItem('Scene PGM with replay', 'Scene PGM', Animator.AnimateTransform.Opacity, 1000, 30, 100, 'Stuff with Opacity', Animator.AnimateEasing.EaseInEaseOut, Animator.AnimateOptions.None);

The example below will animate the x position of the layer ‘Logo’ found in the scene ‘Output scene’. In this case, the initial x position is the same as the current position. The end position is 200. The animation duration is 100 ms.:

Project.Animator.AddLayerTransformationItem('Output scene', 'Logo', Animator.AnimateTransform.PositionX, 100, 0, 200, '', Animator.AnimateEasing.EaseInEaseOut, Animator.AnimateOptions.UseCurrentValueAsInitialValue);

The AddLayerTransformationItem uses the following three enum parameters:

AnimateTransform enum

public enum AnimateTransform
{
    PositionX,
    PositionY,
    ScaleX,
    ScaleY,
    AnchorPointX,
    AnchorPointY,
    Rotation,
    Opacity
}

AnimateEasing enum

For AddLayerTransformationItem.

public enum AnimateEasing
{
    Linear,
    EaseInEaseOut
}

AnimationEasing enum

For AddPropertyAnimator.

public enum AnimateEasing
{
    None,
    EaseInOut
}

AnimationOptions enum

public enum AnimateOptions
{
    None,
    UseCurrentValueAsInitialValue
}

RunningAnimationBehavior enum

public enum RunningAnimationBehavior
{
    // If other animations are running (on the same object and property), do not add the new animation"
    CancelNewAnimation = 0,

    // Cancels all running animations on the same object and property"
    AbortRunningAnimations = 1,

    // Ignore if there are existing animations running on the same object and property. NOT RECOMMENDED."
    AllowMultipleAnimations = 2
}

Internals

The Scripting Engine is based on https://github.com/sebastienros/jint

FAQ

How do I start the playback of a video clip?

Example:

//Get a reference to the input LogoAnimation.mov
var mediaInput=Project.GetMovieInputByName("LogoAnimation.mov");

if ((mediaInput!=null) && (mediaInput.PlayCommand.CanExecute))
  mediaInput.PlayCommand.Execute();

How do I get the current frame from a video clip?

Example:

//Get a reference to the input LogoAnimation.mov
var mediaInput=Project.GetMovieInputByName("LogoAnimation.mov");

//Get the current playback frame
var currentFrame=mediaInput.VideoFrameIndex;

How do I trigger a connector that I have defined in Composer?

Example:

//If the trigger is found, the return value will be true
triggered=Project.TriggerConnectorByName('MyTrigger');

How do I load an image into an existing input?
Example:

myUri=System.Uri('C:\\Program Files\\RealSprint AB\\Vindral Composer\\Media\\Images\\fishingplace.jpeg', System.UriKind.Absolute);
myInput=Project.GetInputByName('My still image');
myInput.SourceUrl=myUri;

Can I start or stop targets in Composer?

Example:

//Start recording
target=Project.GetTargetByName('Scene','FileTarget #1');
if ((target!=null) && (target.StartCommand.CanExecute))
{
    target.StartCommand.Execute();
    Logger.Debug('Starting recording');
}

How do I retrieve the name and file path to the current running project?

Example:

Logger.Debug('Current project: '+Project.RunningProjectFileName);

How do I retrieve the number of errors and warnings?

Example:

Logger.Debug('Number of errors: '+Project.NumErrorsReported+', Warnings: '+Project.NumWarningsReported);

How can I change the settings for an operator?

Example:

histogramOperator = Project.GetLayerOperatorByName('Scene Tracker', 'My video clip', 'Histogram Operator');
if (histogramOperator != null) {
        //Get the value TemporalQualified (boolean)
        valueBool = Project.GetObjectProperty(histogramOperator, 'TemporalQualified');
        //Do something with the value
}

How can I get a reference to a scene layer and set a property on that layer?

Example:

layer = Project.GetLayerByName('Scene PGM', 'TextBallInPocket')
if (layer != null)
    layer.IsVisible = false;

Can I fetch a property from an operator? For example, the Histogram Operator?

Example:

histogramOperator = Project.GetLayerOperatorByName('Scene Tracker', 'Scene Masks', 'Histogram Operator');
if (histogramOperator != null) {
    value = Project.GetObjectProperty(histogramOperator, 'TemporalQualified');
    //Do something based on value
}

When is the OnRenderFrame() method executed?

At the beginning of each frame, before Composer renders the content.

Can I write a text file to disk? I need to store some values on disk.

Yes, you can. Below is an example:

var file = new System.IO.StreamWriter('my-data-file.txt');
file.WriteLine('Hello World !');
file.Dispose();

How can I execute JavaScript with Interactive Buttons?

Add an Interactive Button and, under its Options section, do the following:

1. Activate "Enable interaction".
2. In the "Script function name" field, enter the name of the JavaScript function you want to call.

   Example: OnMyInteractiveButtonClick

3. Optional - Add a value to the "Script function parameter" to be sent to your function when the button is clicked.

   Example: Hello World

In your JavaScript:

function OnMyInteractiveButtonClick(myParameter) {
    Logger.Debug("From my Interactive Button: " + myParameter);
}

Finally, add the interactive button to a Scene.

How can I send HTTP requests?

To send HTTP requests, you can use HttpGetRequestAsync(string endpoint, string messageId).

// Define the endpoint and a messageId for identifying the response.
let endpoint = 'https://your.endpoint';
let messageId ='myMessageId123';

// Send request asynchronously.
Project.HttpGetRequestAsync(httpRequest, myMessageId);

// Each response triggers the OnComposerMessage(json) callback with a JSON object containing the response data.
function OnComposerMessage(json) {

    // The JSON object contains the following properties:
    // MessageId - The ID you specified when sending the request
    // ResponseCode - The HTTP response code (e.g., 200, 404)
    // ResponseText - The content of the response
    Logger.Info("OnComposerMessage: " + json);

    // let response = JSON.parse(json);
    // if (response.MessageId === messageId) {
    //     Logger.Info("This is the response for myMessageId123: " + response.ResponseText);
    // }
}

How can I animate a property using AddPropertyAnimator?

You can use the AddPropertyAnimator function to smoothly animate any property of an input or a scene layer.

Here are a few examples:

// Animate audio volume on an input from silence (-80) to 0 dB over 3 seconds
Project.AddPropertyAnimator("MyInput", "StereoGainDb", -80, 0, 3000, Enums.AnimationEasing.None);

// Animate audio volume on an input from current volume (null) to 0 dB over 3 seconds
Project.AddPropertyAnimator("MyInput", "StereoGainDb", null, 0, 3000, Enums.AnimationEasing.None);

// Animate layer opacity from 0-100 over 1 second using an ease-in-out effect.
Project.AddPropertyAnimator("layer MyInput", "Opacity", 0 100, 1000, Enums.AnimationEasing.EaseInOut);

// Stop new animation if there is already an ongoing animation on the same object and property
Project.AddPropertyAnimator("layer MyInput", "Opacity", 50 100, 2000, Enums.AnimationEasing.None, Enums.RunningAnimationBehavior.CancelNewAnimation);

// Animate layer rotation from the current property value (null) to 90 over 1200 milliseconds
Project.AddPropertyAnimator("layer  MyInput", "Rotate", null, 90, 1200, Enums.AnimationEasing.None);

Example: Trigger a function from an API request that sends a JSON package to higher/lower the volume on a selected input:

function GainControl(json) {

    // Parse the JSON input
    const data = JSON.parse(json);

    // Extract parameters
    const input_name = data.input_name;
    const from_level = data.from_level;
    const to_level = data.to_level;
    const duration = data.duration;
    
    // Add the StereoGainDb property animator to the specified input
    Project.AddPropertyAnimator(input_name, "StereoGainDb", from_level, to_level, duration, Enums.AnimationEasing.EaseInOut);
    
}

Trigger the above example like this:

http://[IP:PORT]/api/scriptengine/execute?function=GainControl&parameter={"input_name":"[NAME_OF_INPUT]","from_level":-0,"to_level":-80,"duration":3000}

Can I access bitmap data (pixels) using the scripting engine?

No. JavaScript is too slow for processing bitmap data in real-time. And, there is currently no way of fetching a bitmap from Composer in JavaScript.

Can I use the Script Engine to create a web page shown in Composer?

No. The Script Engine can only interact with Composer properties, methods, and your project content.

Can I write my operators using the scripting engine?

No. Extending Composer requires access to the Composer SDK.

What happens if a project uses a script, but the script does not exist?

There will be an error during load, but the project will start anyway.

What happens if there is an error in the script?

There will be an error, and the script engine will stop.

What happens if the script takes too long to execute?

There will be an error, and the script engine will stop.

Why do my float/double values have extra decimal places in JavaScript?

JavaScript stores numbers using floating-point representation (IEEE 754). Because of this, some decimal values (such as 0.1 or 21.6) cannot be stored exactly and may appear with extra decimal places.

For example, a value you expect to be 21.6 might be shown as 21.600000381469727. This is normal behavior and not an error.

Examples: how to round or format numbers

// Round to 1 decimal place (returns a number for further calculations)
let rounded = Math.round(myValue * 10) / 10; // 21.5678 → 21.6

// Round to 1 decimal place (returns a string for display purposes)
let display = myValue.toFixed(1); // 21.5678 → "21.6"

Do you provide technical support for JavaScript-related questions?

No.

Does the Script Engine work in the runtime version, including Linux?

Yes.

Can I use the Script Engine to use JavaScript code found on external web pages?

No.

Is the Script Engine running on multiple threads?

No, it is a single-threaded engine running on the same thread as the main Render thread in Composer.