Events

A Server-Sent Events (SSE) stream that pushes Composer state changes to long-lived subscribers, so dashboards and integrations can react without polling. One persistent HTTP connection carries every event the subscriber cares about; the browser's native EventSource object handles reconnect with exponential backoff automatically, and the same apikey mechanism the rest of /api/* uses gates the stream.

Why SSE and not polling

A live UI or dashboard needs to know when state changes (a project loaded, an error logged, a thumbnail refreshed) — not just what the state is. Polling for that with a fast loop wastes bandwidth and adds latency proportional to the poll interval; long-polling closes and reopens a connection per event, costing a TCP/TLS handshake per cycle. SSE keeps one connection open, pushes events when they happen, and falls back to the same text/event-stream wire format MJPEG already uses through the Gateway — proven to proxy cleanly with existing infrastructure.

GET /api/events/subscribe

Opens a long-lived text/event-stream connection. Each event arrives as a pair of lines — an event: line naming the event kind and a data: line carrying a single-line JSON payload — separated by a blank line. The server emits a : keepalive comment every 15 s so dead connections are detected within ~30 s on both ends, and intermediate proxies / NAT mappings stay open on otherwise-quiet streams.

Parameters:

Response: 200 OK — text/event-stream; charset=utf-8, Cache-Control: no-cache, no-store, must-revalidate, chunked transfer encoding. The response never ends voluntarily; the server keeps writing until the client disconnects or Composer is shutting down.

Topics overview

A topic is a coarse category subscribers filter by; each event within a topic has a finer-grained event name that becomes the SSE event: field. Topics let a subscriber opt into only the streams it cares about — a UI that only needs project-status doesn't have to ignore the log firehose, and the server skips JSON-serialize-and-fan-out entirely for topics with zero subscribers.

Pass multiple topics by comma-separating them: ?topics=project,log. Each event is delivered to the connection at most once, regardless of how many of its topics were requested.

Events emitted today

Event timing notes:

• project.load fires after the project file is fully loaded but before playback starts. When DisableWebApiWhenNotRunning is enabled in settings, the rest of /api/* is still closed at this point — wait for project.start before issuing follow-up REST calls.
• project.start always fires once playback transitions to Running. UIs that depend on the HTTP API being available should treat project.start as the "ready" signal rather than project.load.
• project.stop fires for both user-initiated stops and internal recovery cycles (congestive-state restarts). The autoRestart boolean distinguishes them: true means another project.start should follow shortly.
• log.entry events are filtered to Information and above at the source — Debug / Verbose entries never reach the bus, which keeps volume manageable (Composer can emit hundreds of Debug lines per second under load). timestamp is UTC ISO-8601. eventId is the same numeric ID used by Composer's structured logging (see LogEventIdentifiers).
• performance.snapshot is published on a fixed 1 Hz timer that runs only while playback is Running: the first snapshot lands ~1 s after project.start, the last just before project.stop. While the project is Stopped no snapshots are sent — consumers should freeze the last values and treat the absence as "stale" rather than expecting a zeroed snapshot. Numeric units: cpuLoad / gpu*Utilization / averageProcessingTimePercentage are percentages, *Ms are milliseconds, *Gb are gigabytes, framesProcessed / numCongestiveFramesSinceStart / skippedFramesDueToHighComputeTime are cumulative since the last project.start. processingQueueSize > 0 (and isCongestive = true) indicates the render pipeline is falling behind. averageProcessingTimeMs / averageProcessingTimePercentage are the short (50-frame) rolling window; averageProcessingTime10kFramesMs / averageProcessingTime10kFramesPercentage are the long (10 000-frame) window — smoother, better for "is this healthy over time" than the twitchy short window. Both percentages are time / frame-budget × 100. applicationUptimeSeconds is whole seconds since the Composer process started (survives project reloads); sessionUptimeSeconds is whole seconds since the current project started playing (resets to 0 on every project.start).
• source.modified fires only for the three HTTP paths that mutate a source: /api/setproperty on a SourceUrl property, /api/source/reload, and /api/source/clear. It does not fire for source changes made directly in Composer Desktop or from a script. Match targetId (or targetName) to decide whether a preview you're showing for that component must re-fetch — a OneShot preview URL is otherwise parameter-stable and would keep showing the old frame.

Wire format

The SSE wire format is intentionally line-oriented and trivial to parse:

event: project.load
data: {"projectFileName":"C:\\Projects\\Show.prj","topMostSceneId":"3f1c…","activeSceneId":"3f1c…"}

event: project.start
data: {"projectFileName":"C:\\Projects\\Show.prj","topMostSceneId":"3f1c…","activeSceneId":"3f1c…","startedAt":"2026-05-14T19:30:12.5Z"}

event: log.entry
data: {"level":"Warning","message":"Audio preview device is using 44100Hz","loggerName":"","eventId":3000,"timestamp":"2026-05-14T19:30:13.1Z"}

event: performance.snapshot
data: {"playbackState":"Running","isCongestive":false,"cpuLoad":42.0,"systemRamUsageGb":3.21,"gpuUtilization":67.0,"gpuMemoryUsedGb":4.12,"gpuMemoryTotalGb":24.0,"gpuEncoderUtilization":12.0,"gpuDecoderUtilization":0.0,"averageProcessingTimeMs":6.4,"maxProcessingTimeMs":14.1,"averageProcessingTimePercentage":38.0,"averageProcessingTime10kFramesMs":6.1,"averageProcessingTime10kFramesPercentage":36.6,"processingQueueSize":0,"numCongestiveFramesSinceStart":0,"framesProcessed":18432,"skippedFramesDueToHighComputeTime":0,"numErrorsReported":0,"numWarningsReported":1,"numFatalsReported":0,"applicationUptimeSeconds":7384,"sessionUptimeSeconds":612}

event: source.modified
data: {"targetId":"3f1c…","targetName":"Logo image","sourceUrl":"file:///C:/Media/logo.png"}

: keepalive

event: project.stop
data: {"projectFileName":"C:\\Projects\\Show.prj","autoRestart":false}

A complete event is event: + data: + blank line. Lines beginning with : are comments — used here for the 15 s keepalive — and must be ignored by clients. The server never emits the optional id: or retry: SSE fields (see "Replay on reconnect" below).

Connection lifecycle

1. Open — client GETs /api/events/subscribe?topics=... with the usual apikey header or query parameter; the server replies 200 OK and immediately starts emitting events. Any events that fired before the subscription opened are gone — there is no replay window.
2. Steady state — the server writes events as they fire and a : keepalive comment every 15 s. Clients should treat the stream as one-way; no further request body is sent.
3. Heartbeat detection — if more than ~30 s pass without any traffic (events or keepalives), assume the connection is dead and reconnect. Browsers' EventSource does this automatically; native clients should set their read timeout to ~30 s and reconnect on timeout.
4. Close — to unsubscribe cleanly, close the TCP connection (EventSource.close() in browsers, Dispose the response stream / HttpClient request in .NET). The server's loop catches the resulting write failure and tears down the subscription within one keepalive interval.

Authentication

Same apikey mechanism as the rest of /api/*: pass apikey: <key> as a header or ?apikey=<key> in the query string. Browsers don't allow custom headers on EventSource requests, so use the query parameter form from the browser or rely on the Composer Cloud Gateway's cookie auth (which proxies /api/events/subscribe like any other endpoint).

Multiple subscribers and connection limits

Each GET /api/events/subscribe opens one subscription on the server. Multiple clients (or multiple tabs of the same client) can subscribe concurrently; the bus fans out each event to every active subscription that requested its topic. The server has no hard cap on subscriber count, but each subscription keeps one HTTP connection and one bounded in-memory queue alive — practically a few hundred is fine, a few thousand starts to compete with everything else HttpListener is doing.

Browsers apply a per-origin connection limit (~6 in Chrome). A single SSE subscription holds one of those slots for as long as the tab is open, so it's best to consolidate: open one EventSource per page subscribed to all the topics you need, and dispatch internally, rather than one per UI component.

Backpressure and lost events

Each subscription is backed by a bounded queue of 1024 events with a drop-oldest eviction policy. A slow client (background tab, slow uplink) can therefore never back-pressure the publisher — the bus runs at full speed, and stale events are silently dropped from the head of the queue. Clients that absolutely must not miss events should:

1. Listen for the SSE open / reconnect event,
2. Refetch any state they care about via the relevant REST endpoint (/api/project/tree, /api/getstatistics, etc.),
3. Resume processing.

This works because state is always recoverable from the REST API; the SSE stream is best-effort notification, not the source of truth.

Replay on reconnect

The server does not retain a replay buffer of past events, and does not emit SSE id: fields. When a connection drops and reconnects (the browser's EventSource does this transparently with exponential backoff), any events that fired during the gap are lost. Treat reconnect as "refetch what I care about from REST and resume" — the same recipe as for backpressure above.

Error responses

A 200 OK response that later closes mid-stream is not an error — it just means the server saw the client disconnect (or Composer is shutting down).

Examples

Browser (JavaScript / EventSource):

const es = new EventSource('/api/events/subscribe?topics=project,log');

es.addEventListener('project.start', e => {
    const p = JSON.parse(e.data);
    console.log(`project started: ${p.projectFileName}`);
});
es.addEventListener('project.stop', e => {
    const p = JSON.parse(e.data);
    console.log(`project stopped (autoRestart=${p.autoRestart})`);
});
es.addEventListener('log.entry', e => {
    const entry = JSON.parse(e.data);
    if (entry.level !== 'Information') console.log(`[${entry.level}] ${entry.message}`);
});

es.onopen  = () => console.log('SSE connected');
es.onerror = () => console.log('SSE connection blip — EventSource will auto-reconnect');

// To unsubscribe:
// es.close();

.NET (HttpClient + manual parser):

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", apiKey);

var url = "http://composer-host:44433/api/events/subscribe?topics=project";
using var req = new HttpRequestMessage(HttpMethod.Get, url);
using var resp = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
resp.EnsureSuccessStatusCode();

using var stream = await resp.Content.ReadAsStreamAsync();
using var reader = new StreamReader(stream);

string eventName = null, data = null;
while (await reader.ReadLineAsync() is string line)
{
    if (line.Length == 0)
    {
        if (eventName is not null && data is not null)
            Console.WriteLine($"{eventName}: {data}");
        eventName = data = null;
        continue;
    }
    if (line.StartsWith(':')) continue;       // keepalive comment
    var colon = line.IndexOf(':');
    if (colon < 0) continue;
    var field = line[..colon];
    var value = (colon + 1 < line.Length && line[colon + 1] == ' ') ? line[(colon + 2)..] : line[(colon + 1)..];
    if (field == "event") eventName = value;
    else if (field == "data") data = value;
}

The Composer Test SDK ships a typed wrapper around this loop — see ComposerClient.SubscribeEventsAsync in the SDK manual.

curl (smoke test):

curl -N -H "apikey: ${COMPOSER_APIKEY}" \
     "http://localhost:44433/api/events/subscribe?topics=project,log"

-N disables curl's output buffering so events appear as they arrive.

When to use SSE vs polling

For Composer's typical surfaces — project state, log tail, target health — SSE is the better fit; for a one-time "what's the current target status" check, the corresponding REST endpoint is simpler.

Roadmap

Planned topics that aren't shipped yet:

• thumbnail — thumbnail.changed events when a scene's or input's RenderedCudaBgraImage updates, so dashboards can refresh static-image previews without polling MJPEG.

When new topics ship, they appear here and the events topic-name list in the parameter table; existing subscribers keep working unchanged.