Integration Guide

Choosing the Right Tool for External Control

Composer provides four complementary systems for external integration. This guide helps you understand what each feature does and when to use it.

Quick Reference

1. WebAPI

The WebAPI is Composer's HTTP interface that allows external systems to communicate with your project. It's the foundation layer that enables all external control.

See the full WebAPI documentation.

When to Use WebAPI

• You need to perform a single, specific action (start/stop playback, get system info)
• You're building integrations with external systems that send HTTP requests
• You want to query Composer's state (settings, statistics, errors)
• You need to trigger Connectors from external applications
• You need to execute JavaScript functions from the Script Engine

Example Endpoints

2. Connectors

Connectors let you trigger actions in Composer from external systems—anything from a single command to advanced multi-step sequences. They're configured entirely through the GUI, so no coding or programming is required.

See the full Connectors Documentation.

When to Use Connectors

• You want to configure workflows visually in the GUI without writing code
• You need to control any Composer component (Inputs, Layers, Operators, Targets)
• You want to trigger a single action or a sequence of multiple actions
• You want timed sequences with delays between actions
• You need animated property transitions (opacity, position, rotation)
• You want to create reusable workflows that can be triggered by anyone
• You need parameterized actions (e.g., display different player names using @@param)
• You need advanced configurations but prefer visual setup over scripting

Key Features

Example API Calls

# Trigger by name
http://[IP:PORT]/api/connector/trigger?name=WinAnimation

# Trigger by value
http://[IP:PORT]/api/connector/trigger?value=win32

# With parameter
http://[IP:PORT]/api/connector/trigger?name=ShowPlayer&PlayerName=Alex

# Multiple connectors
http://[IP:PORT]/api/connector/trigger?name=BigWin%2BWinAnimation32

3. Batches

Batches let you control multiple layers across scenes using shared tags (batch names). Instead of showing/hiding layers individually, tag them with a common name and control them all at once via the API.

Key concept: If multiple layers share the same batch name, a single batch command affects all of them simultaneously. This makes it easy to synchronize layers across multiple scenes or outputs with one API call.

Simplest setup: Just add a batch name to a layer's Batch field and call the API directly—no additional configuration needed.

Batch Processor Input: If you want to trigger batch commands from a Connector, you'll need to add a Batch Processor Input to your project. It acts as a bridge between Connectors and the Batch system. This is only needed for Connectors—the WebAPI and Script Engine can call batch commands directly.
See the full Batch Processor Documentation.

When to Use Batches

• You want the quickest setup with no additional configuration
• You need to switch between camera angles or overlay groups instantly
• You want to show/hide multiple related layers with one command
• You're building a live production with multiple visual states (e.g., "Scoreboard", "Replay", "Interview")
• You need "solo" functionality—show one group while hiding everything else

Commands

Comparison Types

Example API Calls

# Show all layers with batch containing "Cam"
http://[IP:PORT]/api/batch/showlayer?batch=Cam&comparison=contains

# Solo front camera in specific scene
http://[IP:PORT]/api/batch/showlayersolo?batch=FrontCam&scene=MainScene&comparison=equal

# Hide all overlays
http://[IP:PORT]/api/batch/hidelayer?batch=Overlay&comparison=endswith

4. Script Engine

The Script Engine gives you total control over Composer through JavaScript. Like Connectors, it can access all Composer components and use parameters. The key difference is that scripts can include conditional logic (if/else), loops, calculations, and your own custom functions. It requires programming knowledge.

See the full Script Engine Documentation.

When to Use Script Engine

• You need conditional logic (if/else based on game state, time, or external data)
• You want to create custom functions for reusable logic
• You want to react to every rendered frame (OnRenderFrame event)
• You need to parse and process complex data from external systems
• You want to build custom animations or property calculations
• You need to read object properties and make decisions based on them
• You need loops or other programming constructs
• You're comfortable with JavaScript programming

Key Events

These are built-in events that Composer calls automatically:

Custom Functions

Beyond the built-in events, you can create your own functions and programming logic. This lets you build customized workflows tailored to your specific needs:

// Your own custom functions
function switchToCamera(cameraName) {
    Project.CallBatchCommand('SHOWLAYERSOLO', cameraName);
    Logger.Debug('Switched to: ' + cameraName);
}

function showOverlayWithFade(layerName, duration) {
    Project.SetLayerOpacityByName('Main', layerName, 0);
    Project.ShowLayerByName('Main', layerName);
    Project.AddPropertyAnimator(layerName, 'Opacity', 0, 100, duration, Enums.AnimationEasing.EaseInOut);
}

// Use your functions from events or other functions
function OnConnectorStartGame(parameters) {
    switchToCamera('MainCam');
    showOverlayWithFade('GameOverlay', 500);
}

Custom functions can be called from the WebAPI, from built-in events, from Connector triggers, or from other custom functions—giving you complete flexibility to structure your code however you prefer.

What Scripts Can Control

Like Connectors, the Script Engine can access all components in Composer. Both can use parameters for dynamic values. The difference is that scripts allow conditional logic—if/else statements, loops, and calculations based on runtime data.

Object properties, enums, commands, and more

For more information on available object properties, enums, and commands accessible using the Script Engine, read the Script Engine Property Reference Documentation.

API Access

You can call script functions directly via the WebAPI:

http://[IP:PORT]/api/scriptengine/execute?function=MyFunction&parameter=Hello

// This function can be called from the API
function MyFunction(message) {
    Logger.Debug("Received: " + message);
    // Do something with the parameter...
}

Implementation Patterns

This section covers common scenarios and helps you choose the right approach based on your requirements.

Single Output vs. Multi-Output

Single Output (Simple)

For a single output stream with camera switching, Batches are the simplest solution—just tag your layers and call the API:

/api/batch/showlayersolo?batch=Cam1

Multiple Outputs (Branding)

For multiple output streams (e.g., different brandings), you have several options depending on your needs:

Pattern 1: Batches Only

The quickest way to get started—no Connectors or scripts needed. Just add a batch name to your layers and call the API.

Create camera layers across multiple output scenes that share the same batch name. When you trigger a batch command, all layers with that batch name are affected simultaneously.

Setup:

1. Add a batch name (e.g., CAM1) to a layer's Batch field
2. Call the API

Example: If Cam1 layers in both Output1 and Output2 scenes share the batch name CAM1, a single call switches both:

# Switches to Cam1 on ALL outputs that have a layer tagged "CAM1"
/api/batch/showlayersolo?batch=CAM1

If you need different cameras per output, use unique batch names per output:

# Switch cameras independently per output
/api/batch/showlayersolo?batch=OUT1_CAM1&scene=Output1
/api/batch/showlayersolo?batch=OUT2_CAM3&scene=Output2

Pros: Simple to set up; one call can control multiple outputs if they share batch names.
Cons: Multiple HTTP calls required when outputs need different cameras.

Pattern 2: Connectors for Combined Actions

Use Connectors to bundle multiple batch commands into a single trigger. You can trigger multiple Connectors in one API call:

# Trigger camera switches for all outputs in one call
/api/connector/trigger?name=OUT1_Cam1%2BOUT2_Cam3

You can also create Connectors for entire workflows (e.g., game phases) with timed sequences:

# Trigger a full "betting phase" sequence for all outputs
/api/connector/trigger?name=Betting_OUT1%2BBetting_OUT2

Pros: Single HTTP call, supports animations and delays, parameters via @@paramname for dynamic values, can also trigger script functions for added logic.
Cons: Adding new sequences or changing structure requires editing the project.

Pattern 3: Script Engine for Conditional Logic

When you need conditional logic (if/else) that Connectors can't provide, use the Script Engine. Parameters passed via the API can drive different code paths:

# Example: Pass parameters to drive script logic
/api/connector/trigger?name=PhaseRunner&phase=betting&vip=true

Your script receives the parameters and executes the appropriate actions:

function OnConnectorPhaseRunner(parameters) {
    // parameters contains the query string, e.g., "?name=PhaseRunner&phase=betting&vip=true"
    Logger.Debug("Received: " + parameters);
    
    // Check if this is the betting phase
    if (parameters.indexOf("phase=betting") >= 0) {
        Project.TriggerConnectorByName('BettingPhaseAnimation');
    }
    
    // Check if VIP treatment is needed
    if (parameters.indexOf("vip=true") >= 0) {
        Project.TriggerConnectorByName('VIPOverlay');
    }
}

Pros: Full flexibility, runtime-configurable, single HTTP call.
Cons: Requires JavaScript knowledge, more complex to maintain.

Pattern 4: Hybrid (Connectors + Script Engine)

Combine the GUI simplicity of Connectors with Script Engine logic. The Connector handles visual actions (animations, layer changes), while the script adds conditional logic:

# Trigger Connector - it runs its commands AND calls OnConnectorPhaseRunner()
/api/connector/trigger?name=PhaseRunner&phase=betting

function OnConnectorPhaseRunner(parameters) {
    // Connector already handled the standard animations
    // Script adds conditional logic on top
    
    if (parameters.indexOf("phase=betting") >= 0) {
        // Additional logic for betting phase
        Logger.Debug("Betting phase started");
    }
}

Pros: Best of both worlds—Connector actions can be edited in the GUI, while scripts handle the conditional logic.
Cons: Logic is split between two places.

Choosing the Right Pattern

Where Should Logic Live?

Hybrid Approach: Many implementations use a backend for decision-making (which camera, which phase) and Composer for execution (how to show it, with what animations). The backend sends simple triggers; Composer handles the visual complexity.

Multiple Ways to Achieve the Same Result

Most tasks in Composer can be accomplished in several ways. Here's an example showing different approaches to switch to Camera 1:

All of these achieve the same visual result. Choose based on:

• How quickly do you need to get started? Fastest → Batches. More setup → Connectors or Scripts.
• Who will maintain it? Prefer visual tools → Connectors or Batches. Comfortable with code → Script Engine.
• Do you need to pass dynamic values? Yes → Connectors (with @@paramname) or Script Engine.
• Is it part of a larger sequence? Yes → Connectors or Script Engine. No → Direct Batch API.
• Do you need conditional logic (if/else)? Yes → Script Engine. No → Any approach works.

Decision Guide: Which Tool Should I Use?

The table below offers recommendations, but remember—these aren't strict rules. If a different approach feels more natural for your team or workflow, it will likely work just as well.

For detailed documentation on each feature, refer to the individual feature pages in the Composer Document Center.