mediaConnectionFailed

Emitted when the media plane (audio/video) cannot be established or sustained, even though the signaling connection (WebSocket) remains functional. This event lets integrators branch fallback UX — such as HLS playback, dial-in, or a custom retry flow — based on which direction failed and whether a fresh rejoin is likely to help.

The event fires once per failed peer connection for the remainder of that connection's lifetime. Rejoining the room or re-establishing a new peer connection starts a fresh evaluation.

Sample payload

{
  "type": "mediaConnectionFailed",
  "data": {
    "direction": "subscribing",
    "cause": "network_blocked"
  }
}

Parameters

Parameter	Type	Description
direction	'publishing' | 'subscribing'	Which media flow failed. subscribing — the participant cannot receive remote audio/video (silent room). publishing — the participant cannot deliver their own audio/video (others see/hear nothing from them). Both directions can fail independently and each triggers its own event.
cause	'network_blocked' | 'connection_failed'	Why the failure is terminal. network_blocked — the network prevented ICE from gathering any candidates (typically corporate DPI, strict firewall, or port restrictions blocking STUN/TURN). Rejoining the same room on the same network will fail identically. connection_failed — ICE gathered candidates but could not establish or maintain a working path, even after an automatic restart attempt. A fresh peer connection via rejoin may succeed if the underlying issue was transient.

Usage example

sambaFrame.on('mediaConnectionFailed', ({ direction, cause }) => {
  if (cause === 'network_blocked') {
    // Rejoining on the same network will not help.
    // Suggest switching networks, or swap to a fallback transport (e.g. HLS, dial-in).
    showNetworkBlockedFallback({ direction });
  } else {
    // cause === 'connection_failed' — the issue may be transient.
    // Offer a retry, or let the user dismiss and try rejoining.
    showConnectionFailedRetry({ direction });
  }
});

Remarks

The event pairs with the built-in "Media connection failed" modal, which shows direction- and cause-aware copy. Integrators implementing their own fallback UX can dismiss or hide the built-in modal.

• cause: 'network_blocked' corresponds to zero ICE candidates gathered after ICE negotiation. This is a strong signal of network-layer blocking.

• cause: 'connection_failed' fires when an ICE restart attempt fails to re-establish connectivity on a previously-negotiated peer connection.

• Fires independently for publishing and subscribing directions. A single session can emit both if both directions fail.

• Distinct from connectionFailure, which fires for signaling-layer (WebSocket) connection failures, not media-layer failures.