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
Confirm SDK version is 2.33 or later.
Confirm
publishSenderStats: trueis on the publisher, not the subscriber.Wait a few seconds — the RTCP feedback loop needs time to stabilise.
If
networkConditionreturnsUnknown, confirmaudioFallbackEnabled: trueis set on both sides.
Known Limitations
iOS:
connectionEstimatedBandwidthandconnectionMaxAllocatedBitratefrequently returnnilon 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 (
cpuPerformanceChangedon the session object) is Web only — Chrome 125+, Edge 125+, Opera 111+. Not available on Firefox or Safari.