WebSockets

Composer ships an embedded WebSocket server that pushes real-time events to subscribed clients and accepts a small set of command messages. This page covers the connection model, the message envelope, the catalogue of message types, and the subscription channels.

Note — not available on Core licences

The WebSocket server is disabled at startup under a Vindral Composer Core (free) licence, regardless of the EnableWebSockets setting. No listener is opened on the configured port and clients will fail to connect. See Activating a license for licence-tier details.

Connection

The server is off by default. Enable it via the EnableWebSockets setting (see the WebSockets section of the settings.xml reference). Restart Composer for the change to take effect — the WebSocket server is started during application startup.

On a successful handshake the server immediately sends a Welcome message containing the connection's assigned Guid. Clients should keep that GUID and quote it back in subsequent commands so the server can route replies.

Authentication

The WebSocket server does not perform API-key authentication itself. Treat its port as trusted: bind to localhost for local-only access, or restrict the listening interface to a private network and front it with a TLS-terminating proxy (nginx, Caddy, etc.) that handles auth.

Use the HTTP API's WebSocket management endpoints to enumerate or disconnect connected clients on demand — those are protected by the same apikey mechanism as the rest of the HTTP API.

Message envelope

Every frame sent in either direction is a JSON object with this shape:

{
  "Type":     "PropertyChanged",
  "Content":  "<payload — usually a JSON string or human-readable string>",
  "Guid":     "<connection / receiver guid>",
  "ObjectId": "<related object guid, or all-zero if not applicable>",
  "DateTime": "2026-04-29T13:42:18.0000000Z"
}

Type is one of the values in the table below (case-sensitive). Content is the actual payload — a plain string for system messages, a JSON-encoded inner document for PropertyChanged / MultiplePropertiesChanged / ComponentLogUpdate, etc. Guid is the connection's identity (server-assigned in the Welcome message) and ObjectId references a Composer object when relevant.

Message types

Defined in WebSocketServer.Enums.SocketMessageType.

Subscription channels

Send a Subscribe message with Content set to one of these values to start receiving the matching push type. Channel names are case-insensitive on subscribe; Unsubscribe accepts the same names plus the wildcard All.

An Unsubscribe message with Content: "All" cancels every subscription on the connection.

Lifecycle events

The Runtime API broadcasts coarse lifecycle events (project start/stop/reload, runtime exit, etc.) to all WebSocket clients via the RuntimeEvent message type. The full event list lives on the Runtime API WebSocket Events page.

Configuration

All WebSocket-related settings live under the WebSockets section of settings.xml:

• EnableWebSockets — master on/off switch.
• WebSocketsHostName and WebSocketsPort — listening interface and port.
• WebSocketsMaxConnectedSubscribers — connection cap (default 1).
• WebSocketsMaxIncomingMessageQueueLength / WebSocketsMaxOutgoingMessageQueueLength — back-pressure tuning.
• WebSocketThrottledPropertiesFrequency — how often coalesced pushes (audio mixer, property changes) emit.
• WebSocketMsgAudioDecimals / WebSocketMsgAudioRmsDecimals — precision of audio level values to keep payloads small.

Quick start (browser JavaScript)

const ws = new WebSocket('ws://localhost:8081/');

ws.addEventListener('open', () => {
  // Subscribe to system info pushes.
  ws.send(JSON.stringify({ Type: 'Subscribe', Content: 'SystemInformation' }));
});

ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.Type) {
    case 'Welcome':
      console.log('Connected as', msg.Guid);
      break;
    case 'SystemInformationUpdate':
      console.log('System info:', JSON.parse(msg.Content));
      break;
    case 'Error':
      console.warn('Server error:', msg.Content);
      break;
  }
});

Related documentation

• HTTP API › WebSocket Management — list and disconnect connected clients via HTTP.
• Runtime API › WebSocket Events — full catalogue of RuntimeEvent broadcasts.
• Script Engine › WebSockets — sending WebSocket messages from a project script.
• Settings — the Web API tab covers WebSocket-related options through the UI; the settings.xml reference lists every WebSocket-section property.