Vonage Video API - Client Observability: Setup, Stats, and Known Limitations Vonage Video API - Client Observability: Setup, Stats, and Known Limitations

Vonage Video API - Client Observability: Setup, Stats, and Known Limitations

Vonage API Support

Objective

Enable and troubleshoot the Client Observability feature in the Vonage Video API to monitor real-time call quality for publishers and subscribers.

Applies To

  • Vonage Video API 

  • Platforms: JavaScript, iOS, Android, Windows, Linux, React Native

  • Network Stats

Procedure

Set these two flags at initialisation to unlock the full feature set. You can see all of them in action in the Client Observability Demo on GitHub.

// Publisher
OT.initPublisher('publisher', {
  publishSenderStats: true,    // must be on the publisher — no effect on subscriber
  audioFallbackEnabled: true,  // improves networkCondition score accuracy
});

// Subscriber
session.subscribe(stream, 'sub', {
  audioFallbackEnabled: true,
});

Stats API Code Reference

Publisher stats — publisher.getStats():

publisher.getStats((err, arr) => {
  const stats = arr[0].stats;
  const t = stats.mediaLink.transport;

  // ── Audio ──────────────────────────────────────────
  stats.audio.packetsSent
  stats.audio.packetsLost
  stats.audio.bytesSent

  // ── Video (per-layer for simulcast) ────────────────
  stats.video.packetsSent
  stats.video.packetsLost
  stats.video.bytesSent
  stats.video.videoLayers[0].encoderOutputFrameRate
  stats.video.videoLayers[0].qualityLimitationReason  // 'none'|'bandwidth'|'cpu'|'other'

  // ── Uplink transport (SDK 2.33+) ───────────────────
  t.connectionEstimatedBandwidth  // bps — uplink capacity
});

Subscriber stats — subscriber.getStats():

subscriber.getStats((err, stats) => {
  const v  = stats.video;
  const ml = stats.mediaLink;
  const lt = ml.transport;
  const rt = ml.remotePublisherTransport;

  // ── Received video (SDK 2.33+) ─────────────────────
  v.width                    // NOT decodedWidth — returns undefined
  v.height                   // NOT decodedHeight — returns undefined
  v.decodedFrameRate
  v.freezeCount
  v.totalFreezesDuration     // NOT totalFreezesDurationMs
  v.pauseCount
  v.totalPausesDuration      // NOT totalPausesDurationMs

  // ── Local downlink transport (SDK 2.34+) ───────────
  lt.connectionEstimatedBandwidth  // bps — downlink capacity
  lt.networkCondition
  lt.networkConditionReason
  ml.networkDegradationSource      // 'none'|'local'|'remote'|'both_or_unclear'

  // ── Sender-side stats ──────────────────────────────
  rt.connectionEstimatedBandwidth  // subscriber's available capacity
  rt.networkCondition              // publisher's uplink health
  rt.networkConditionReason
  // ⚠ stats.senderStats is DEPRECATED — use rt above
});

Network Condition events — networkConditionChanged (SDK 2.34+):

// Publisher
publisher.on('networkConditionChanged', ({ reason, statsContainer }) => {
  const t = statsContainer?.mediaLink?.transport;
  // ⚠ NOT statsContainer.stats.mediaLink
  t?.networkCondition       // 'excellent'|'good'|'fair'|'warning'|'critical'|'unknown'
  t?.networkConditionReason // 'none'|'bandwidth'|'packetLoss'
  reason
});

// Subscriber
subscriber.on('networkConditionChanged', ({ reason, statsContainer }) => {
  const ml = statsContainer?.mediaLink;
  // ⚠ NOT statsContainer.stats.mediaLink
  ml?.transport?.networkCondition
  ml?.remotePublisherTransport?.networkCondition
  ml?.networkDegradationSource  // 'none'|'local'|'remote'|'both_or_unclear'
});

Troubleshooting — Stats Not Appearing

  1. Confirm SDK version is 2.33 or later.

  2. Confirm publishSenderStats: true is on the publisher, not the subscriber.

  3. Wait a few seconds — the RTCP feedback loop needs time to stabilise.

  4. If networkCondition returns Unknown, confirm audioFallbackEnabled: true is set on both sides.

Known Limitations

  • iOS: connectionEstimatedBandwidth and connectionMaxAllocatedBitrate frequently return nil on iOS — this is a platform-level WebRTC constraint, not a Vonage bug. Use subscriber-side metrics (packetsLost, bytesReceived, freeze/pause counts) as the primary signal on iOS instead.

  • Firefox: Sender-side stats may be unavailable when the publisher is on Firefox — browser-level WebRTC limitation.

  • CPU performance state (cpuPerformanceChanged on the session object) is Web only — Chrome 125+, Edge 125+, Opera 111+. Not available on Firefox or Safari.

Additional Information