Client Observability: Linux

The Vonage Video SDK exposes detailed stream-quality metrics through a high-level statistics API—recommended for most use cases—which provides audio, video, network, and sender-side statistics in a unified, session-aware form that remains stable across peer-connection transitions. For advanced debugging, the SDK also offers access to the raw WebRTC stats report, which reflects unprocessed peer-connection data.

The SDK also exposes network condition metrics that provide a high-level assessment of connection health for both publishers and subscribers. These metrics include a network condition score, the reason driving that score, and—for subscribers—a degradation source indicating which side of the connection is responsible for any observed issues. See Network condition and degradation source for details.

The Vonage Video Linux SDK sends periodic audio, video, and media link network statistics for both publishers and subscribers. These include packet counts, bitrates, frame rate data, pause/freeze metrics, codec information, and transport-level network metrics such as bandwidth estimation and network condition scoring.

Statistics are delivered through:

  • otc_publisher_callbacks — publisher-side stats

  • otc_subscriber_callbacks — subscriber-side stats

To receive them, enable the appropriate callback on the publisher or subscriber.

Enabling Statistics for Publishers

Use the on_audio_stats() and on_video_stats() callback functions of the otc_publisher_callbacks to monitor statistics for a publisher's stream. To register callbacks methods for periodic reports of audio and video statistics for a publisher, set the on_audio_stats() and on_video_stats() callback functions when you initialize the otc_publisher_callbacks struct to be used by the publisher.

Register a otc_publisher_callbacks struct when creating the publisher:

And implement the callbacks:

These callback functions are called periodically to report audio and video statistics for the publisher. Each function is passed in the following: A pointer to the publisher struct, a pointer to the user_data you set for the publisher, an array of stats, and the number of stats in the array. The stats parameter is defined by the otc_publisher_audio_stats and otc_publisher_video_stats structs. For a publisher in a routed session (one that uses the OpenTok Media Router), the array includes one object, defining the statistics for the single audio or video media stream that is sent to the Vonage Video Media Router. In a relayed session, the array includes an object for each subscriber to the published stream.

Receiving Video Quality Events on the Publishers

For publisher video quality events:

Receiving Network Condition Events on the Publisher

To receive network condition change events for the publisher, set the on_network_condition_changed callback in the otc_publisher_callbacks struct:

Register it alongside the other callbacks:

This callback is triggered when a significant change in network condition is detected for the publisher. It includes the current media link statistics with transport metrics.

Enabling Statistics for Subscribers

Use the on_audio_stats() and on_video_stats() callback functions of the otc_subscriber_callbacks to monitor statistics for a subscriber's stream.

Register a otc_subscriber_callbacks struct when creating the subscriber:

Implement the callbacks:

Receiving Video Quality Events on the Subscribers

For publisher video quality events:

Receiving Network Condition Events on the Subscriber

To receive network condition change events for the subscriber, set the on_network_condition_changed callback in the otc_subscriber_callbacks struct:

Register it alongside the other callbacks:

sub_callbacks.on_network_condition_changed = handle_subscriber_network_condition;

This callback is triggered when a significant change in network condition is detected for the subscriber or the remote publisher. It includes the current media link statistics with local and remote transport metrics and degradation source.

Statistics Data Structures

This section outlines the structs and fields provided by the C SDK audio and video statistics API. While all Video SDK platforms expose the same set of statistics, there may be minor differences in how each platform structures or names individual fields. These variations reflect platform-specific SDK design conventions rather than differences in the underlying metrics.

For a platform-independent explanation of the available statistics and what they represent, refer to client observability overview.

otc_transport_stats

Represents shared transport-level metrics.

  • connection_estimated_bandwidth — Estimated available connection bandwidth (bps)
  • network_condition — Current network condition score (OTC_NETWORK_CONDITION_UNKNOWN, OTC_NETWORK_CONDITION_CRITICAL, OTC_NETWORK_CONDITION_WARNING, OTC_NETWORK_CONDITION_FAIR, OTC_NETWORK_CONDITION_GOOD, or OTC_NETWORK_CONDITION_EXCELLENT)
  • network_condition_reason — Primary reason impacting the network condition (OTC_NETWORK_REASON_NONE, OTC_NETWORK_REASON_UNKNOWN, OTC_NETWORK_REASON_BANDWIDTH, or OTC_NETWORK_REASON_PACKET_LOSS)

otc_publisher_video_stats

Provides statistics about a publisher’s video track:

  • connection_id — In a relayed session, the connection ID of the client subscribing to the stream
  • subscriber_id — In a relayed session, the subscriber ID of the client subscribing to the stream
  • packets_lost — Estimated video packets lost
  • packets_sent — Video packets sent
  • bytes_sent — Video bytes sent
  • timestamp — Unix timestamp in milliseconds
  • start_time — The timestamp, in milliseconds since the Unix epoch, from which the cumulative totals started accumulating
  • video_layers — Array of video layer statistics (see otc_publisher_video_layer_stats)

otc_publisher_audio_stats

Provides statistics about a publisher’s audio track:

  • connection_id — In a relayed session, the connection ID of the client subscribing to the stream
  • subscriber_id — In a relayed session, the subscriber ID
  • packets_lost — Estimated audio packets lost
  • packets_sent — Audio packets sent
  • bytes_sent — Audio bytes sent
  • timestamp — Unix timestamp in milliseconds
  • start_time — The timestamp, in milliseconds since the Unix epoch, from which the cumulative totals started accumulating

otc_publisher_video_layer_stats

Represents one simulcast or SVC layer:

  • width — Encoded frame width
  • height — Encoded frame height
  • encoded_frame_rate — Encoded fps
  • bitrate — Layer bitrate (bps)
  • total_bitrate — Layer bitrate including RTP overhead (bps)
  • scalability_mode — SVC/scalability descriptor (e.g., "L3T3")
  • quality_limitation_reason — Reason for quality limitation (bandwidth, CPU, codec, resolution, or layer change)
  • codec — Codec used for this video layer

otc_subscriber_video_stats

Provides statistics about a subscriber’s video track:

  • packets_lost — Estimated video packets lost
  • packets_received — Video packets received
  • bytes_received — Video bytes received
  • timestamp — Unix timestamp in milliseconds
  • sender_connection_max_allocated_bitrate — Optional sender-side max bitrate
  • sender_connection_estimated_bandwidth — Optional sender-side estimated bandwidth
  • width — Decoded frame width in pixels
  • height — Decoded frame height in pixels
  • decoded_frame_rate — Decoded frames per second
  • bitrate — Video bitrate (bps)
  • total_bitrate — Bitrate including RTP overhead (bps)
  • pause_count — Number of pauses (>5s since last frame)
  • total_pauses_duration — Total pause duration (ms)
  • freeze_count — Number of freezes
  • total_freezes_duration — Total freeze duration (ms)
  • codec — Current decoder codec

otc_subscriber_audio_stats

Provides statistics about a subscriber’s audio track:

  • packets_lost — Estimated packets lost
  • packets_received — Packets received
  • bytes_received — Bytes received
  • audio_level — Audio level (0–1.0)
  • timestamp — Unix timestamp in milliseconds
  • sender_connection_max_allocated_bitrate — Optional sender-side max bitrate
  • sender_connection_estimated_bandwidth — Optional sender-side estimated bandwidth
  • transport — Local transport and network statistics for this subscriber (see otc_transport_stats). May be limited if sender-side statistics and/or audio fallback are disabled.
  • remote_publisher_transport — Remote publisher transport and network statistics (see otc_transport_stats). May be limited if sender-side statistics and/or audio fallback are disabled.

otc_publisher_media_link_stats

Provides transport-level statistics for a publisher's connection.

  • transport — Transport statistics for this publisher (see otc_transport_stats)

otc_subscriber_media_link_stats

Provides transport-level statistics for a subscriber's connections.

  • transport — Transport statistics for this subscriber's downlink connection (see otc_transport_stats)
  • remote_publisher_transport — Transport statistics for the remote publisher's uplink connection (see otc_transport_stats). May be limited if sender-side statistics are not enabled.
  • network_degradation_source — Indicates the source of network degradation, if any (OTC_NETWORK_DEGRADATION_SOURCE_NONE, OTC_NETWORK_DEGRADATION_SOURCE_LOCAL, OTC_NETWORK_DEGRADATION_SOURCE_REMOTE, or OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR)

Sender-Side Statistics

See the sender-side statistics overview.

Enabling Sender-Side Statistics

Sender-side statistics are received on the subscribers. To receive sender-side statistics, enable them for the stream’s publisher by calling otc_publisher_settings_set_sender_stats_track() function before constructing the publisher:

If the sender stats track is not enabled, no sender statistics channel will be published for this publisher. The default value is OTC_FALSE.

Receiving Sender-Side Statistics

If the publisher has enabled sender-side statistics, subscribers receive them automatically via the stats callbacks described above. The otc_subscriber_video_stats and otc_subscriber_audio_stats structs include two sender-side fields:

  • sender_connection_max_allocated_bitrate — The maximum bitrate that can be estimated for the connection
  • sender_connection_estimated_bandwidth — The current estimated bandwidth for the connection

These metrics are calculated per audio-video bundle, so the same values appear in both video and audio statistics.

Network Condition and Degradation Source

The SDK provides real-time network condition metrics for both publishers and subscribers, including a condition score, the reason driving that score, and a degradation source for subscribers. For a full explanation of the network condition model, scores, reasons, and how to enable it, see the client observability overview.

Network condition data is available through two channels:

  • Periodic statistics: The transport field on publisher and subscriber stats structs includes network_condition and network_condition_reason. Subscriber stats also expose remote_publisher_transport and network_degradation_source. See Statistics structures for details.
  • Network condition changed events: Dedicated callbacks on both publisher and subscriber are triggered when a significant change in network condition is detected.

The following example shows how to use the subscriber network condition data to identify the source of degradation:

RTC Stats Report

To get low-level peer connection statistics for a publisher, use the otc_publisher_get_rtc_stats_report() function. This provides RTC stats reports for the media stream. This is an asynchronous operation. Create an otc_publisher_rtc_stats_report_cb struct and pass it into the otc_publisher_set_rtc_stats_report_cb function prior to calling otc_publisher_get_rtc_stats_report(). When the stats are available, the otc_publisher_rtc_stats_report_cb.on_rtc_stats_report() callback function is called. This function includes a stats parameter, which is a pointer to an array of otc_publisher_rtc_stats structs. This struct includes a json_array_of_reports property. This is a JSON array of RTC stats reports, which are similar to the format the RtcStatsReport object implemented in web browsers (see these Mozilla docs).

To get low-level peer connection statistics for a subscriber, To get more detailed stream statistics, use the otc_subscriber_get_rtc_stats_report() function. This provides an RTC stats report for the media stream.

This is an asynchronous operation. Create an otc_subscriber_rtc_stats_report_cb struct and pass it into the otc_subscriber_set_rtc_stats_report_cb function prior to calling otc_subscriber_get_rtc_stats_report(). When the stats are available, the otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report callback function is called.

This callback function includes a json_array_of_reports parameter. This is a JSON array of RTC stats reports, which are similar to the format the RtcStatsReport object implemented in web browsers (see these Mozilla docs).

Also see this W3C documentation.