The event bus

This is the primary API. Subscribe on the Observer instance — it is the single emitter for the entire hierarchy. The ObservedCall / ObservedClient / ObservedPeerConnection objects are EventEmitters too, but those local events are reserved for internal lifecycle wiring; application code uses the observer bus.

Payload shape: ancestry + subject#

Every event delivers exactly one argument: a payload object, always containing the ancestry from the observer down to the entity that raised it, plus the event-specific subject.

type ObserverEventBase           = { observer: Observer, context?: AcceptContext };
type ObservedCallScope           = ObserverEventBase   & { observedCall: ObservedCall };
type ObservedClientScope         = ObservedCallScope   & { observedClient: ObservedClient };
type ObservedPeerConnectionScope = ObservedClientScope & { observedPeerConnection: ObservedPeerConnection };

observer.on('inbound-rtp-added', ({ observer, observedCall, observedClient, observedPeerConnection, observedInboundRtp }) => {
    // all five are present and correctly typed
});

on / off / once / emit are fully typed against the event map — the handler argument is inferred from the event name. You never walk the tree to attach a listener.

Observer level — scope { observer }#

Mediasoup level — scope { observer, observedMediasoupRouter }#

Call level — scope { observer, observedCall }#

Client level — scope { observer, observedCall, observedClient }#

Peer-connection level#

Scope { observer, observedCall, observedClient, observedPeerConnection }.

Local lifecycle events#

These remain on the individual entities rather than the bus, for teardown and coordination. You can listen to them, but prefer the bus equivalents for application logic.

Client issues: the lifecycle on the wire#

From client-monitor-js 4.6.0 a stateful issue arrives as two clientIssues[] entries sharing a key:

raise:      { type: 'stuck-decoder',          key, payload,                                timestamp: raisedAt }
resolution: { type: 'stuck-decoder-resolved', key, payload: { raisedAt, comment, …final }, timestamp: resolvedAt }

The observer opens an entry in observedClient.activeIssues on the raise and closes it on the matching key. Handled for you:

• the -resolved suffix is stripped, so both entries share one logical type;
• a re-raise of a live key refreshes the payload without restarting raisedAt;
• keyless entries are one-shot — reported via client-issue, never tracked;
• issues still open when a client closes are force-resolved (resolvedBy: 'client-closed'), and the registry expires stale entries.

observer.on('client-issue', ({ observedClient, issue }) => { /* opened, or one-shot */ });

observer.on('client-issue-resolved', ({ resolvedIssue }) => {
    resolvedIssue.type;          // 'stuck-decoder' — suffix stripped
    resolvedIssue.durationInMs;  // how long the episode lasted
    resolvedIssue.resolvedBy;    // 'client' | 'timeout' | 'client-closed'
});

observedClient.activeIssues;     // the live per-client mirror, keyed by issue.key

Payload types on the wire#

type ClientEvent    = { type: string; payload?: Record<string, unknown>; timestamp?: number };
type ClientIssue    = { type: string; payload?: Record<string, unknown>; key?: string; timestamp?: number };
type ClientMetaData = { type: string; payload?: Record<string, unknown>; timestamp?: number };
type ExtensionStat  = { type: string; payload?: Record<string, unknown> };

payload fields are objects (schema 3.7.0: free-form JSON, so a payload may nest objects and arrays), and the library reads the ones it understands. Older clients keep working: a payload from a pre-3.5.0 client arrives as a JSON string and is parsed on the way in, so a fleet running a mix of client versions needs no coordination. Values inside a payload are unknown, so narrow before use:

if (typeof issue.payload?.trackId === 'string') { /* … */ }

ClientEventTypes (known event.type values): CLIENT_JOINED, CLIENT_LEFT, PEER_CONNECTION_OPENED / CLOSED / STATE_CHANGED, MEDIA_TRACK_ADDED / REMOVED / MUTED / UNMUTED / RESUMED, ICE_GATHERING_STATE_CHANGED, ICE_CONNECTION_STATE_CHANGED, DATA_CHANNEL_OPEN / CLOSED / ERROR, NEGOTIATION_NEEDED, SIGNALING_STATE_CHANGE, ICE_CANDIDATE, ICE_CANDIDATE_ERROR, and the mediasoup set PRODUCER_* / CONSUMER_* / DATA_PRODUCER_* / DATA_CONSUMER_*.

ClientMetaTypes: MEDIA_CONSTRAINT, MEDIA_DEVICE, MEDIA_DEVICES_SUPPORTED_CONSTRAINTS, USER_MEDIA_ERROR, LOCAL_SDP, OPERATION_SYSTEM, ENGINE, PLATFORM, BROWSER.

A worked sample#

Two consecutive samples from one participant of a mediasoup call show what actually flows through accept(): a rich join snapshot, then lean steady-state ticks.

{
  "timestamp": 1780572332518,
  "callId":   "d3dbf2f5-…",
  "clientId": "c926983c-…",
  "score": 0,                                       // no quality measured yet on the join tick
  "attachments": { "displayName": "Guest", "roomId": "qq0iwfnd" },

  "clientEvents": [                                 // chronological lifecycle
    { "type": "CLIENT_JOINED",                 "timestamp": 1780572324515 },
    { "type": "PEER_CONNECTION_OPENED",        "timestamp": 1780572326790 },
    { "type": "ICE_GATHERING_STATE_CHANGED",   "timestamp": 1780572326811 },
    { "type": "PRODUCER_ADDED",                "timestamp": 1780572326821 },
    { "type": "MEDIA_TRACK_ADDED",             "timestamp": 1780572326821 }
  ],

  "clientMetaItems": [                              // environment & devices, one-off
    { "type": "USER_AGENT_DATA", "payload": { "…": "Chrome 148 / macOS" } },
    { "type": "MEDIA_DEVICE",    "payload": { "label": "BRIO 4K Stream Edition" } }
  ],

  "peerConnections": [
    { "peerConnectionId": "b81c8d9d-…", "outboundRtps": [ /* … */ ], "outboundTracks": [ /* … */ ] },
    { "peerConnectionId": "8635acb7-…", "peerConnectionTransports": [ /* … */ ] }
  ]
}

What accept() does with it, each step emitting on the bus with full ancestry:

1. lazily creates the ObservedCall → call-added;
2. creates the ObservedClient → client-added, then client-joined;
3. creates an ObservedPeerConnection per entry → peer-connection-added (×2 here);
4. creates an ObservedOutboundTrack per track → outbound-track-added, plus the matching outbound-rtp-added;
5. replays the device list as client-metadata and the lifecycle items as client-event, and finally emits client-updated for the whole tick.

attachments.roomId lands on observedClient.attachments — read it on client-updated, not at creation.

The second sample, ~8 s later, carries the same ids, no new clientEvents or clientMetaItems, and just refreshed stats. That is the shape of nearly every sample: the heavy join snapshot happens once.