When to use which

HTTP API

Direct HTTP(S) requests to Composer's WebAPI. Authentication via API keys stored in apikeys.json; without a key, all requests need to come from a host you trust on the network. Best for single actions and system queries against a running project — start playback, change a property, fetch a performance report. The HTTP API talks to the project that's currently loaded; for runtime-process-level control (start / stop / reload / change projects), see the Runtime API below.

The full endpoint catalogue is documented in the HTTP API manual; major categories include:

• Connectors — trigger Connector sequences with optional parameters.
• Media & Inputs — play / stop video and audio inputs, send cue points, retrieve audio levels, manage SRT / RTMP target state.
• Scenes & Layers — control rendering, manage layer visibility, switch layer sources via batches.
• Images — capture scene snapshots and face-detection results.
• System info — settings, project XML, error logs, licence data, performance reports.
• WebSocket — manage client connections.
• Alarms — monitor and clear alarm state.
• Application control — start / stop the processing engine, exit the application, save projects.

Prerequisites

• Run Composer as Administrator on Windows.
• Enable Web API under Settings → Web API.
• Open the configured port (default: 44433) on the firewall.
• For HTTPS on port 443, you need a valid certificate and an FQDN.

Runtime API

The Runtime API is a separate HTTP endpoint exposed by Composer Runtime (the headless application) that controls the runtime process itself — not a project running inside it. Use it to manage the runtime's lifecycle from outside: open a different project, reload the current one after a .prj change, query state, gracefully shut down.

Typical lifecycle calls:

• Open a project on a running runtime — e.g. swap between MorningShow.prj and EveningShow.prj from a scheduler.
• Reload the current project after the .prj file changes on disk — pairs naturally with R1 2026's auto-reload feature.
• Query runtime state (idle / loading / running / stopping) for a deployment dashboard.
• Stop or exit the runtime cleanly from a service supervisor.

The Runtime API is distinct from Composer Desktop, which doesn't expose runtime-lifecycle endpoints (Desktop runs a single project at a time and is driven through its UI). On a host running Composer Runtime, both APIs coexist — the Runtime API on its own port for lifecycle, and the HTTP API on 44433 for whichever project happens to be loaded.

For the full endpoint catalogue (capabilities, errors, lifecycle, project management, Prometheus, status, warnings, WebSocket events), see the Runtime API manual.

Connectors

Connectors are the recommended path for defining sequences of actions visually. Configure them in Composer Desktop's Connectors tab — drop in API Commands, set targets and properties, optionally add delays and animations. Trigger by name or value over a single HTTP endpoint (/api/connector/trigger?name=… or ?value=…).

Connectors are also the natural integration point for Stream Deck and other control surfaces — see Remote control & Stream Deck below.

Batches

Batches tag scene layers so a group of them can be controlled together with a single command. Useful for switching whole camera angles (FrontCam, BackCam), toggling overlay groups, or driving complex scene composition from a single trigger.

Batch operations: showlayer, showlayersolo, hidelayer. Comparison modes: contains (default), equal, startswith, endswith. Drive them from the HTTP API directly, from a Connector, from the Script Engine, or via the Batch Processor input.

Script Engine

The Script Engine is a JavaScript runtime embedded per project. It runs frame-by-frame and exposes Composer's full object graph — every input, scene, layer, operator, target, and connector is reachable from script. Best for conditional logic ("if scene X is live and source Y is silent, switch to backup") and event-driven custom behaviour ("when the score changes, animate the scoreboard").

Connectors triggered by name can call into custom JavaScript functions — see Using Script Engine with Connectors for the naming convention and parameter-passing patterns.

For the canonical scripting reference (lifecycle events, host globals, helper functions), see the Script Engine manual.

WebSockets

The WebSockets endpoint is for real-time, bidirectional communication — live state in a browser UI, server-pushed events instead of polling. Composer's WebSocket protocol covers input state, audio levels, and log entries via subscription channels.

Remote-access note

When connecting to the WebSocket endpoint from a remote host, configure the WebSocket server with the IP address as the hostname (not localhost or a hostname). This is a constraint of the underlying WebSocket library.

Reference clients

RealSprint publishes a sample WebSocket client at github.com/vindral-oss/vindral-composer-ws-client — the easiest way to see connection, subscription, and message-handling patterns end to end.

For secure WebSocket (WSS) in front of Composer, an nginx proxy-pass setup is published at github.com/RealSprint/composer-wss-nginx-proxypass.