Client observability

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:

  • High-level statistics API—the preferred mechanism in most cases. This API provides audio, video, and network performance metrics and accounts for peer-connection transitions and other internal adjustments. The SDK aggregates these details so the data maps cleanly to a publisher or subscriber abstraction. Whenever possible, use this API, as it offers a more accurate and stable representation of real session performance.
  • Low-level WebRTC stats report, which exposes the raw WebRTC RTCStatsReport for the underlying peer connection. This data is not adjusted for peer connection transitions or internal optimizations and reflects only the direct WebRTC statistics. It is useful for advanced debugging or when raw WebRTC data is explicitly required.

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 and the reason for the condition. For subscribers, they also include the network degradation source. See Network condition for details.

Publisher statistics

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:

  • Connection ID: The unique ID of the subscriber’s connection. This matches the ID property of the connection object delivered in the connection created event for that client.
  • Subscriber ID: The unique ID of the Subscriber object receiving this publisher’s stream. This matches the subscriber’s ID property in the subscribing client’s application.

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.

Audio metrics

  • Packets lost: Total number of audio packets that failed to reach the subscriber.
  • Packets sent: Total number of audio packets transmitted to the subscriber or the media router.
  • Bytes sent: Cumulative size of all audio data sent, including audio payload, headers and padding.
  • Audio level: Current loudness of the audio signal, normalized between 0 and 1.
  • Timestamp: Indicates when each measurement was taken.

Publisher transport and network condition metrics are available through the publisher media link statistics. See Media link statistics for details.

Video metrics

  • Packets lost: Number of video packets that did not reach their destination.
  • Packets sent: Total number of video packets transmitted to the subscriber or the media router.
  • Bytes sent: Total number of bytes transmitted to the subscriber or the media router, including video payload, headers and padding.
  • Timestamp: Indicates the start and current measurement points.
  • Video layers: Per-layer information for simulcast or scalable video coding (SVC). In a simulcast configuration, each object corresponds to one independent video encoding (e.g., low, medium, high resolution streams sent in parallel). For SVC (Scalable Video Coding), the publisher typically sends a single video encoding, with scalability (temporal, spatial, or both) internally encoded and described via the scalability mode field. It includes:
    • Encoded frame width: Width of the encoded video frames for this layer. This may differ from the camera’s capture resolution if scaling or adaptation is applied.
    • Encoded frame height: Height of the encoded video frames for this layer. As with width, the encoder may downscale frames based on bandwidth, CPU, or simulcast/SVC layer configuration.
    • Encoder output frame rate: Actual frame rate at which video frames are successfully encoded. This may differ from the camera’s capture frame rate (frames may be dropped before encoding) and from the frame rate actually transmitted (encoded frames may be discarded prior to sending).
    • Bitrate (video payload only): Estimated bitrate of the encoded video payload. This excludes RTP overhead and may vary based on encoder rate-control decisions.
    • Total bitrate (including overhead): Bitrate including RTP headers, padding, and other transport overhead. This better reflects actual network usage than payload bitrate alone.
    • Scalability mode: Indicates the spatial/temporal scalability structure (e.g., "L3T3").
    • Codec: The codec used for encoding this layer (e.g., VP8, VP9, H.264, AV1).
    • Quality limitation reason: Indicates why the encoder limited quality (bandwidth, CPU, other). Helps diagnose whether adaptation is caused by network conditions or device-side constraints.

Publisher media link statistics include:

  • Transport stats: Local transport and network statistics for the publisher, including:
    • Estimated available bandwidth of the uplink connection.
    • Network condition score. See Network condition for details.
    • Network condition reason. See Network condition for details.

These metrics are delivered through:

  • Media link stats event: A dedicated event triggered periodically to report media link statistics.
  • Network condition changed event: Triggered when a significant change in network condition is detected, delivering current media link statistics along with the reason for the change.

Publisher media link statistics describe the publisher's own uplink. Subscriber media link statistics additionally report the remote publisher's transport and a network degradation source. See [Network Condition by Publisher and Subscriber](#network_condition_by_publisher and_subscriber) for how the two perspectives relate and how to assess a specific subscriber's experience.

Subscriber statistics

Subscriber callbacks provide information about the media being received and rendered, helping applications detect playback issues, assess downstream performance, and make adaptive decisions.

Audio metrics

  • Packets received: How many audio packets were successfully received.
  • Packets lost: How many audio packets were not successfully received.
  • Bytes received: Total audio data received from the publisher or the Video API Media Router.
  • Audio level: Loudness of the remote audio.
  • Timestamp: When metrics were collected.
  • Sender-side statistics: Bandwidth estimations reported by the sender.

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.

Video metrics

  • Packets received: How many video packets were successfully received.
  • Packets lost: How many video packets were not successfully received.
  • Bytes received: Total video data received from the publisher or the Video API Media Router.
  • Decoded resolution: Width and height of frames after decoding.
  • Decoded frame rate: Actual frame rate produced by the decoder. This may differ from the number of frames received (some may be dropped before decoding) and from the number of frames rendered (some decoded frames may not be displayed depending on rendering conditions).
  • Bitrate: Current received media throughput, considering only video payload.
  • Total bitrate: Current received media throughput, including headers and padding.
  • Number of video freezes: Number of video freezes, as defined in WebRTC’s Statistics API freezeCount.
  • Total duration of video freezes: Total duration of video freezes.
  • Number of video pauses: Number of interruptions longer than 5 seconds, including intentional pauses (such as when the publisher disables the video track) and cases where video is turned off due to publisher or subscriber audio fallback.
  • Total duration of video pauses: Total duration of video pauses.
  • Codec: Current codec in use for the video stream.
  • Sender-side statistics: Bandwidth estimations reported by the sender.

Subscriber media link statistics include:

  • Local transport stats: Transport and network statistics for the subscriber's downlink connection, including:

    • Estimated available bandwidth of the downlink connection.
    • Network condition score. See Network condition for details.
    • Network condition reason. See Network condition for details.

  • 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:

    • None: No network degradation detected.
    • Local: The local subscriber's network is the primary cause.
    • Remote: The remote publisher's network is the primary cause.
    • Both or unclear: The source of degradation cannot be clearly attributed to one side.

Subscriber media link statistics are delivered through:

  • Media link stats event: A dedicated event triggered periodically to report media link statistics.
  • Network condition changed event: Triggered when a significant change in network condition is detected, delivering current media link statistics along with the reason for the change.

Video quality changed events

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:

  1. Degradation due to bandwidth limitation
  2. Degradation due to CPU limitation
  3. Other quality degradation reasons
  4. Codec changes
  5. Resolution or video layer changes

For a subscriber, the reasons are considered in the following priority order:

  1. Video interruption
  2. Codec changes
  3. Resolution changes

Call quality monitoring

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.

Sender-side statistics

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.

Enabling sender-side statistics

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:

  • The maximum bitrate that can be estimated for the connection.
  • The current bandwidth estimation for the connection.

Use cases

  • 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.

Notes

  • Depending on the SDK, sender-side statistics may not be immediately available the first time stats are requested or on the first stats event after subscription, due to network latency.
  • If you create a single peer connection session, the peer connection bandwidth is shared across all subscribers. The maximum bitrate represents the highest bitrate the peer connection can estimate, while the current bitrate reflects each audio-video bundle’s bitrate. All subscribers in the single peer connection share this maximum bitrate. When assessing the sender’s available bandwidth, take this into account. For example, a current bitrate of 2 Mbps may indicate good quality if multiple subscribers share the same single peer connection.

Known issues

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.

Network condition

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:

  • Periodic statistics: Network condition fields are included in the media link statistics provided with periodic media link stats events. See Media link statistics for details.
  • Network condition changed events: A dedicated callback or event is triggered whenever a significant change in network condition is detected. This event is distinct from video enabled/disabled or audio fallback events, and reports network health changes rather than changes in the media track state. Applications can use this event to respond to network issues, such as updating UI indicators, logging telemetry, or triggering adaptive behavior. The event includes the current media link statistics along with the reason for the change.

Network condition score

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.

Network condition reason

Each network condition score is accompanied by a reason indicating the primary factor driving the assessment:

  • None: No notable reason.
  • Bandwidth: Network condition impacted by available bandwidth.
  • Packet loss: Network condition impacted by packet loss.

Network Degradation Source

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:

  • None: No network degradation detected. Both local and remote connections are performing well.
  • Local: The local subscriber's network is the primary cause of degradation. Issues may include poor WiFi signal, high packet loss on the downlink, or limited available bandwidth on the subscriber's connection.
  • Remote: The remote publisher's network is the primary cause of degradation. The publisher is experiencing poor network conditions on their uplink, which affects the media quality received by this subscriber.
  • Both or unclear: Degradation is occurring on both sides of the connection, or the source cannot be clearly attributed to one side. This typically occurs when both the subscriber and publisher are experiencing network issues simultaneously.

Network Condition by Publisher and Subscriber

A publisher may serve many subscribers, while each subscriber receives a single stream from one publisher. Network condition reporting follows this shape: a publisher reports the condition of its own uplink, and a subscriber reports its downlink, the remote publisher's uplink, and which side is responsible for any degradation.

A publisher reports the link it owns. In a routed session, the publisher maintains only a peer connection to the Vonage Video Media Router, regardless of how many subscribers receive the stream. The Media Router terminates that connection and forwards the media onward to each subscriber over separate connections that it owns. Publisher transport metrics therefore describe the publisher-to-Media-Router media path segment — the segment the publisher can directly influence through its own encoding and rate control. This is also why a routed publisher's statistics array contains a single object with connection ID and subscriber ID undefined, as described in Publisher Statistics. In sessions with more than two participants, extending those metrics to every receiving subscriber would not scale, and would offer limited diagnostic value: the Media Router forwards the stream to an undetermined number of subscribers, so publisher-side data could neither isolate a network issue nor attribute a failure to a specific participant.

Reporting the local link keeps AMR transitions transparent. While Adaptive Media Routing (AMR) specifically handles two-participant calls where each publisher has a single subscriber, a relayed media path can still migrate to the Media Router mid-call when additional participants join or certain features are enabled. Because publisher media link statistics describe the publisher's own network link — its uplink, whether that link terminates at a subscriber or at the Media Router — their meaning and shape are unchanged across such a transition. Applications can consume publisher statistics consistently without tracking the current topology or adapting to it mid-call. This follows the design goal stated at the start of this guide, where the high-level statistics API maps cleanly onto the publisher and subscriber abstractions and remains stable across transitions.

For two-participant calls, rely on the subscriber's view. Where each participant publishes one stream and subscribes to one stream, subscriber statistics are sufficient to reason about both directions. If a subscriber reports a degradation source of Remote, the remote participant's uplink is constrained — and that participant's own subscriber is likely experiencing degraded conditions as well, since the common causes (weak WiFi signal, a congested access network, poor cellular coverage) affect both directions of a link. Treat this as an inference rather than a guarantee.

See also Correlate Publisher and Subscriber Metrics to Diagnose the Root Cause.

Relation to audio fallback

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.

Enabling network condition

Network condition reporting builds upon multiple features working together. The more features you enable, the richer and more accurate the network condition data becomes:

  • Sender-side statistics: Enable sender-side statistics on the publisher to allow subscribers to receive remote publisher transport metrics and more accurate network degradation source attribution.
  • Publisher audio fallback: Enable audio fallback on the publisher to improve the accuracy of publisher-side network condition scoring.
  • Subscriber audio fallback: Enable audio fallback on the subscriber to improve the accuracy of subscriber-side network condition scoring.

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.

Using Client Observability Insights

This section provides practical guidance on how to put those signals to work effectively, and common mistakes to avoid.

Best Practices

Let the SDK Adapt Quality Automatically, Then Act on the Result

The SDK already handles quality adaptation automatically:

  • Publisher-side: When bandwidth or CPU is constrained, the publisher automatically reduces resolution and frame rate. In simulcast or SVC configurations, this means the encoder may drop to a lower spatial or temporal layer.
  • SFU (routed sessions): The Vonage Video Media Router selects the appropriate simulcast layer for each subscriber based on that subscriber's available downlink bandwidth. A subscriber on a weak connection will receive a lower-resolution layer without any application intervention.
  • Relayed sessions: The publisher downscales directly for each peer, since it sends individual streams to each subscriber.

You do not need to, and should not, attempt to replicate this logic in your application. Instead, use the observability events to react to the outcome: update your UI, log telemetry, or trigger higher-level policy decisions based on what the SDK has already reported.

If you observe a quality_limitation_reason of bandwidth in publisher video metrics, the encoder is already throttling output. Use this signal to inform UX decisions (such as hiding a high-resolution preview) rather than issuing redundant resolution overrides. Similarly, if the reason is cpu, consider releasing CPU resources elsewhere in your application - for example, pausing non-essential animations, deferring background processing, or reducing UI rendering complexity—to give the encoder more headroom.

Display a Real-Time Network Quality Indicator

Use the network condition score from media link statistics to render a quality indicator in your UI—for example, signal-strength bars or a colored icon. Update the indicator only when the network condition changes (using the network condition changed event) rather than on every periodic stats tick. This avoids unnecessary re-renders while keeping the indicator responsive to meaningful shifts in quality.

For subscribers, the network degradation source tells you which side of the call is affected. Surface this in your UI so participants receive targeted, actionable feedback - for example, "Your connection is unstable" versus "The remote participant is experiencing network issues"—instead of a generic quality warning.

Use Events for Adaptive UX, Not Polling

Prefer event-driven callbacks over inspecting periodic stats arrays for threshold logic. The network condition changed event and video quality changed event are purpose-built for detecting meaningful transitions. Polling the periodic stats for threshold crossings on every tick introduces CPU overhead.

When you do need to act on periodic stats, debounce your logic over several consecutive samples before triggering any UX change.

Use Transport Statistics for Layout and Policy Decisions

The subscriber media link statistics expose transport metrics from two perspectives simultaneously:

  • Local transport stats reflect the bandwidth the sender (the publisher or the Vonage Video Media Router) estimates as available for the connection to this subscriber. Because bandwidth estimation in WebRTC is performed by the sender based on RTCP feedback, this figure represents the sender's view of the channel capacity—not a self-measurement by the subscriber.
  • Remote publisher transport stats reflect the publisher's own uplink transport metrics as reported from the publisher's side.

Together, these two views let you reason about the full path between publisher and subscriber. Use them to make proactive layout and policy decisions:

  • Limit the number of visible video tiles in a grid layout when estimated capacity is low, hiding lower-priority participants rather than displaying frozen or degraded video.
  • Trigger Quality on Demand (QoD) policies on mobile networks when the local transport bandwidth estimate drops below a defined threshold, for example switching from high-definition to standard-definition streams.
  • Show a capacity warning before adding a new high-bitrate stream (such as screen sharing) to a session when the local transport bandwidth estimate is already constrained.

In a multi-participant grid, you can extend this approach by using transport statistics and CPU limitation signals to allocate a quality budget across publishers. The SDK adapts each stream independently and has no knowledge of which participants are important in your layout—that prioritization is an application-level decision. Use setPreferredResolution and setPreferredFrameRate on the publisher to express it: grant the featured tile the full resolution ceiling, and cap background participants to lower values. When the active speaker changes or conditions shift, rebalance the ceilings accordingly. This is complementary to the SDK's automatic adaptation, which continues to operate within whatever ceiling the application has set.

Correlate Publisher and Subscriber Metrics to Diagnose the Root Cause

Network issues can originate on either side of the call. Use the combination of publisher media link statistics and subscriber media link statistics—along with the network degradation source—to reason about root cause:

  • A warning or critical network condition on the publisher's uplink combined with a Remote degradation source on the subscriber points to a publisher-side network problem.
  • A drop in available bandwidth on the subscriber's downlink combined with a Local degradation source points to the subscriber's own connection.
  • When both sides show degradation or the source is Both or unclear, treat the problem as a shared issue.

Log Statistics for Post-Call Analytics and Debugging

Store periodic statistics and network condition change events to a backend analytics pipeline. Key metrics worth capturing include:

  • Network condition score and reason over time per publisher and subscriber.
  • Video quality limitation reason and active layer (simulcast/SVC).
  • Estimated available bandwidth from media link statistics.
  • Number and total duration of video freezes and pauses.
  • MOS score (web SDK) as a proxy for perceived call quality.

Post-call analysis of these logs can surface patterns such as recurring degradation at specific times of day, on certain network types, or for specific device models, guiding infrastructure and UX improvements.

Anti-Patterns

Do Not Override the SDK's Automatic Quality Adaptation

The SDK already reduces resolution and frame rate when bandwidth or CPU is constrained. Issuing manual resolution overrides in response to every stats event typically conflicts with the encoder's rate control and can cause oscillation—rapidly switching between quality levels—which degrades perceived quality more than a smooth automatic downgrade would.

If you have specific quality requirements (for example, a maximum allowed resolution), configure them declaratively at session setup rather than reacting to stats events at runtime.

Do Not Manually Trigger Audio-Only Fallback Based on Transport Statistics

The SDK's audio fallback feature already monitors network conditions and automatically disables video when the connection deteriorates to a warning or critical level. Implementing your own logic to switch a subscriber to audio-only mode based on the local transport bandwidth estimate duplicates this built-in behavior and can conflict with it - for example, disabling video prematurely before the SDK's own thresholds are reached, or re-enabling it at a different point than the SDK would. If you need audio fallback behavior, use the SDK's audio fallback feature rather than driving it from transport statistics directly.

Do Not Trigger UI Changes on Every Periodic Stats Event

Periodic stats fire at a regular interval (typically every few seconds). Applying UI updates or business logic on every event, especially threshold checks on noisy metrics such as instantaneous packet loss, results in flickering indicators and spurious alerts. Always smooth your signals: require multiple consecutive samples below a threshold, or use the dedicated network condition changed event, before updating user-facing state.

Do Not Rely on Publisher-Side Metrics Alone to Diagnose the Subscriber's Experience

Publisher metrics reflect upstream transmission quality. A publisher may report excellent network conditions while one or more subscribers experience poor downlink quality. To assess a specific subscriber's experience, always combine publisher media link stats with subscriber-side metrics, including the network degradation source.

Do Not Use Raw Byte or Packet Counts as Quality Signals

Accumulated totals like bytesReceived or packetsLost grow monotonically and have no inherent meaning on their own. Always compute rates (delta over the interval between samples) or use the higher-level fields, such as estimated bitrate or the network condition score, which the SDK already derives from the raw counters.

Do Not Use Low-Level RTC Stats for End-to-End Quality Measurement

The RTC stats report reflects the state of a single underlying peer connection at a point in time. The SDK may migrate between peer connections or transition topologies during a session, so raw RTC stats do not aggregate across these transitions. For end-to-end quality measurement and long-running session monitoring, always prefer the high-level audio, video, and media link statistics APIs, which account for these internal changes.

Do Not Ignore Differences Between Routed and Relayed Sessions

In a routed session, the sender-side statistics are provided by the Vonage Video Media Router, and subscriber-facing bandwidth estimates reflect the subscriber's downlink to the media router—not a direct measurement of the publisher's uplink. In a relayed (peer-to-peer) session, the publisher sends individual streams to each subscriber, and publisher stats represent direct peer measurements. When building analytics or adaptive logic, account for the session mode to avoid misinterpreting the numbers.

RTC stats report

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.

Enabling audio and video statistics collection

In publisher or subscriber, listen to the corresponding statistics events. For details, see the related developer guide for each client SDK: