Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer Portal
OpenTok SDKs provide calls to access real-time network and media statistics in a video session, including sender-side statistics.
Client observability provides detailed stream quality metrics—such as packet loss, data received, and estimated bandwidth— and can be used on any published or subscribed stream.
Statistics can be accessed through two main mechanisms:
This guide includes the following sections:
The Audio and video statistics API provides periodic, fine-grained insight into media performance for both publishers and subscribers. These statistics allow applications to monitor real-time audio and video quality, understand network behavior, detect device-side issues, and respond proactively to bandwidth or performance changes. The API is available across all Video Client SDKs and delivers separate callbacks or events for publisher-side and subscriber-side metrics.
The main types of data and events provided include:
Audio and video statistics – such as frame rates, resolution, bitrate, and packet counts, delivered periodically through callbacks or events.
Media link statistics – provide unified, transport-level metrics that complement the periodic audio and video statistics, including network condition scoring and bandwidth estimation. For subscribers, these metrics additionally expose visibility into the remote publisher's transport performance and network degradation attribution, enabling applications to diagnose connection issues with precision and deliver meaningful, actionable feedback to users.
Video quality change events – triggered whenever the quality of a video stream changes, providing updated metrics along with the reason for any degradation or improvement.
Network condition change events – triggered when a significant change in network condition is detected for a publisher or subscriber. These events report changes in overall network health, and include a complete snapshot of audio and video statistics along with transport-level metrics such as the network condition score, the reason for the condition, and the degradation source. See Network condition for details.
Publisher callbacks provide visibility into the quality of the media being sent to each subscriber (or to the Vonage Video Media Router in routed sessions). These metrics help understand upstream network conditions, observe encoding performance, and diagnose issues such as packet loss or bitrate drops.
Note: In routed sessions, the publisher metrics may not correspond to actual media values because the Vonage Video Media Router may throttle bandwidth to optimize resources. In such cases, do not rely on publisher-side metrics until at least one subscriber is connected. You can ignore quality limitation reasons related to bandwidth for the publisher until a subscriber is present. In relayed sessions, no statistics are reported until at least one subscriber is connected.
Note that when the publisher is in a relayed session, the publisher sends a separate media stream to each subscriber. Because of this, the statistics events may include multiple stats objects—one per subscriber. For each statistics object in a relayed session, two identifying fields are included:
These fields allow you to determine which subscriber each stats object belongs to.
In a routed session (using the Vonage Video Media Router), there is only one outgoing media stream, so the stats array contains a single object, and both connection ID and subscriber ID are undefined.
Publisher transport and network condition metrics are available through the publisher media link statistics. See Media link statistics for details.
Publisher media link statistics include:
These metrics are delivered through:
Subscriber callbacks provide information about the media being received and rendered, helping applications detect playback issues, assess downstream performance, and make adaptive decisions.
Subscriber transport and network condition metrics, including remote publisher transport statistics and network degradation source information, are available through the subscriber media link statistics. See Media link statistics for details.
Subscriber media link statistics include:
Local transport stats: Transport and network statistics for the subscriber's downlink connection, including:
Remote publisher transport stats: Transport and network statistics for the remote publisher's uplink connection, with the same fields as the local transport stats. These stats may be limited if sender-side statistics are not enabled.
Network degradation source: Identifies which side of the connection is primarily responsible for any observed degradation:
Subscriber media link statistics are delivered through:
The SDK provides video quality changed events to give applications detailed insights into the video stream of a publisher or a subscriber. These events complement the periodic networks statistics provided for client observability and allows applications to react to both continuous metrics and significant quality changes.
You can attach a handler to a publisher or a subscriber to access quality changed events. The events provide updated metrics along with the reason for any degradation or improvement. This mechanism allows your application to monitor video performance and adapt UI or behavior accordingly, independent of how the metrics are internally delivered.
The reasons for quality events are triggered according to a defined priority order. For example, a quality limitation caused by bandwidth takes precedence over a resolution change. If you need to track all changes in metrics, inspect the detailed statistics included in each event. Refer to the SDK reference documentation for full details.
For a publisher, the reasons are considered in the following priority order:
For a subscriber, the reasons are considered in the following priority order:
Beyond the core statistics APIs, the OpenTok.js SDK provides additional capabilities for monitoring and responding to call quality changes in real-time. These features help applications optimize performance by adapting to device constraints and network conditions.
Note: Call quality monitoring features, including CPU performance monitoring and Mean Opinion Score (MOS) tracking, are currently available only in the OpenTok.js SDK for web applications.
Key capabilities
CPU Performance Monitoring - Detect changes in device CPU load and adapt your application accordingly. Applications can respond to CPU stress by disabling computationally expensive features or reducing video quality to maintain call stability.
Mean Opinion Score (MOS) - Rate the quality of experience users perceive from your service using the industry-standard MOS scale (1-5). The MOS algorithm accounts for packet loss, bitrate, network latency, and other factors that impact media quality.
Combined Optimization - Build robust applications that respond to both CPU performance and network quality metrics, dynamically adjusting video resolution, frame rates, and other parameters to deliver the best possible user experience under varying conditions.
Pre-call Testing - Use the Vonage Video API Network test library to assess whether a client can support publishing audio and video and estimate MOS scores before users join a session.
For detailed implementation guidance, code examples, and best practices for call quality monitoring in web applications, see the OpenTok.js SDK documentation.
During a call, the publisher transmits a media stream to one or more subscribers. The media may be relayed directly or processed through the Vonage Video Media Router. While subscribers can observe the bitrate of the stream they receive, they typically lack visibility into their total downlink capacity. The Sender-Side Statistics API addresses this limitation by providing metrics that help subscribers assess available bandwidth it has to receive media and optimize stream quality.
A sender can be a Publisher or the Vonage Video Media Router, depending on whether media is flowing point-to-point or through the media router. The API is called Sender-side Statistics because the sender is the source of the reported metrics, delivered to the receiver which is the subscriber.
The API reports two key metrics per bundle (audio-video pair): the maximum bitrate the sender can estimate, and the current bandwidth estimation. The maximum bitrate is a cap on what can be estimated due to platform limitations. The current bandwidth estimation is the estimated downlink bandwidth of the WebRTC peer connection channel capacity that is available for media, independent of the stream's bitrate.
For example, a publisher may send a VGA stream using less than 1 Mbps, while the Vonage Video Media Router, providing the sender-side statistics, may estimate the current bandwidth at 8 Mbps, indicating additional channel capacity. This information can be used by the application to adjust video layouts, or trigger policy-based actions such as Vonage Quality on Demand (QoD).
Note that its interpretation differs when a single peer connection session is created. In a single peer connection session, multiple audio+video bundles share the same connection, so the total bandwidth estimation should be calculated by summing the individual bundle estimations. In other words, the total bandwidth is shared between all subscribers in the single peer connection.
To enable sender-side statistics, use the corresponding method in the client SDK to enable the sender statistics tracks on the publisher. Once activated, the following metrics will be included in the regular subscriber audio and video statistics events:
Optimizing subscriber layouts: Use the Sender API’s estimated bandwidth together with the local end-point RTC statistics to display a high number of subscribers with good video quality.
Adaptive media mode: A subscriber can use the sender statistics determine if the sender’s estimated bandwidth exceeds a defined threshold (for example, 500 kbps) to decide whether to subscribe in video-only or audio-only mode.
Load scaling: Use the sender-side statistics to check if a subscriber can optimally handle an increase in load—such as switching from low-bitrate screen sharing to high-bitrate live video.
Threshold warnings: Use the sender-side statistics to trigger warnings for subscribers if the estimated bandwidth of a sender connection drops below a predefined threshold.
Quality on Demand (QoD) triggers: Use the sender-side statistics to trigger when the estimated network capacity for a subscribed stream falls below a given threshold on mobile network.
In some cases, when the session is relayed—or in certain routed setups with only two participants—and the Publisher uses Firefox, sender-side statistics may not be available due to browser limitations.
The network condition API provides real-time visibility into the health of the network connection for both publishers and subscribers. It exposes a network condition score that reflects the overall quality of the connection, the primary reason driving that score, and—for subscribers—information about which side of the connection is causing any observed degradation.
Network condition metrics are included in the media link statistics and delivered through two channels:
The network condition is a score that reflects the overall health of the network connection for a given transport (local or remote). The score is derived from metrics such as packet loss and estimated available bandwidth. Higher values indicate better network conditions.
| Score | Description |
|---|---|
| Unknown | Network condition could not be determined. |
| Excellent | Excellent network conditions. Video quality is optimal and estimated bandwidth can accommodate the maximum bitrate for the current resolution. |
| Good | Good network conditions. Minor or temporary issues may occur. |
| Fair | Moderate network conditions. Video quality may be restricted by the sender. |
| Warning | Poor network conditions. Video quality is heavily impacted, and a video disable warning is triggered if audio fallback is enabled. |
| Critical | Severe network issues. If audio fallback is enabled, the SDK disables video to preserve call stability. |
Note: The network quality score is relative to the current media configuration and bandwidth demands. It reflects how well the network supports the active requirements (e.g., video resolution, bitrate, frame rate). For example, if the application is configured to use a low camera resolution or lower bitrate, the network may be rated as excellent because the bandwidth demand is minimal. Higher resolutions or bitrates will require more network capacity and may result in different quality scores under the same network conditions.
Each network condition score is accompanied by a reason indicating the primary factor driving the assessment:
The network degradation source identifies which side of the connection is primarily responsible for any observed network degradation. This metric is available for subscribers and provides critical insights into whether performance issues originate from the subscriber's downlink or the remote publisher's uplink.
Network degradation source helps applications pinpoint the root cause of network issues, enabling targeted troubleshooting and user communication. Rather than reporting only that network conditions are poor, it indicates whether the problem lies with the local subscriber's connection quality or the remote publisher's connection quality.
Possible Values:
The network condition reporting is aligned with the audio fallback mechanism. When audio fallback events are triggered at the warning or critical levels, the reported network condition reflects the same severity. The network condition indicates the corresponding warning or critical state for the publisher, the subscriber, or both, ensuring consistent signaling across network and media fallback APIs.
The opposite can also occur: the network condition may report a warning or critical level without audio fallback being triggered, which happens when audio fallback is disabled.
Network condition reporting builds upon multiple features working together. The more features you enable, the richer and more accurate the network condition data becomes:
Without these features enabled, some network condition data may be limited or unavailable.
To receive network condition changed events, register a callback or listener for network condition changes on the publisher or subscriber. The event includes the current media link statistics containing network condition and transport metrics. For details, see the developer guide for each client SDK in the Enabling audio and video statistics collection section.
The RTC stats report API provides access to low-level, standardized WebRTC statistics for the published and subscribed media stream. This allows applications to retrieve detailed metrics in the format defined by the WebRTC specification, enabling advanced monitoring and analysis beyond the custom client observability metrics.
Note: This API provides low-level peer connection statistics. The Video SDK may optimize peer connections, transition between different topologies, or migrate to another backend server. These low-level stats do not aggregate the metrics of different peer connections in use or transitioned from. Therefore, it is preferable to rely on our audio and video statistics API for end-to-end monitoring.
In publisher or subscriber, listen to the corresponding statistics events. For details, see the related developer guide for each client SDK:
