Client Observability: iOS (Swift)

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.

Audio, Video and Media Link Statistics API

The Vonage Video iOS SDK sends periodic audio, video, and media link 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:

OTPublisherKitNetworkStatsDelegate — publisher-side stats (audio, video)
OTSubscriberKitNetworkStatsDelegate — subscriber-side stats (audio, video)

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

Enabling Statistics for Publishers

Attach a class that adopts OTPublisherKitNetworkStatsDelegate:

class MyViewController: UIViewController, OTPublisherKitDelegate, OTPublisherKitNetworkStatsDelegate {
    var publisher: OTPublisher?

    func setupPublisher() {
        let settings = OTPublisherSettings()
        // Configure settings as needed
        publisher = OTPublisher(delegate: self, settings: settings)
        publisher?.networkStatsDelegate = self
    }
}

Implement the callbacks:

func publisher(_ publisher: OTPublisherKit, videoNetworkStatsUpdated stats: [OTPublisherKitVideoNetworkStats]) {
    let first = stats.first

    // For routed sessions, stats.first is enough.
    // For relayed sessions (one object per subscriber), you would iterate all elements.
    let connectionId = first.connectionId.isEmpty ? "<none>" : first.connectionId
    let subscriberId = first.subscriberId.isEmpty ? "<none>" : first.subscriberId

    print("Publisher Video Stats for connectionId: \(connectionId), subscriberId: \(subscriberId)")
    print("Video bytes sent: \(first.videoBytesSent)")
    print("Video packets sent: \(first.videoPacketsSent)")
    print("Video packets lost: \(first.videoPacketsLost)")
    print("Current average frame rate: \(first.videoFrameRate) fps")

    for layer in first.videoLayers {
        print("Layer: \(layer.width)x\(layer.height)")
        print("  Encoded FPS: \(layer.encodedFrameRate)")
        print("  Bitrate: \(layer.bitrate) bps")
        print("  Total bitrate (incl. RTP overhead): \(layer.totalBitrate) bps")
        print("  Codec: \(layer.codec ?? "<none>")")
        print("  Scalability mode: \(layer.scalabilityMode ?? "<none>")")
        print("  Quality limitation: \(layer.qualityLimitationReason.rawValue)")
    }

}

func publisher(_ publisher: OTPublisherKit, audioNetworkStatsUpdated stats: [OTPublisherKitAudioNetworkStats]) {
    let first = stats.first

    // For routed sessions, stats.first is enough.
    // For relayed sessions (one object per subscriber), you would iterate all elements.
    let connectionId = first.connectionId.isEmpty ? "<none>" : first.connectionId
    let subscriberId = first.subscriberId.isEmpty ? "<none>" : first.subscriberId

    print("Publisher Audio Stats for connectionId: \(connectionId), subscriberId: \(subscriberId)")
    print("Audio bytes sent: \(first.audioBytesSent)")
    print("Audio packets sent: \(first.audioPacketsSent)")
    print("Audio packets lost: \(first.audioPacketsLost)")
}

func publisher(_ publisher: OTPublisherKit, mediaLinkStatsUpdated mediaLinkStats: [OTPublisherKitMediaLinkStats]) {
    if let stats = mediaLinkStats.first {
        print("Publisher uplink bandwidth: \(stats.transport.connectionEstimatedBandwidth) bps")
        print("Network condition: \(stats.transport.networkCondition.rawValue)")
        print("Condition reason: \(stats.transport.networkConditionReason.rawValue)")
    }
}

For a publisher in a routed session (one that uses the Vonage Video Media Router), the stats 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 stats array includes an object for each subscriber to the published stream.

Receiving Video Quality Events on the Publishers

If you are also interested in video quality events implement this callback:

func publisher(_ publisher: OTPublisherKit, videoQualityChanged stats: OTPublisherKitVideoNetworkStats, reason: OTPublisherVideoEventReason) {
    print("Publisher video quality event: \(reason.rawValue)")
}

Receiving Network Condition Events on the Publishers

To receive network condition change events for the publisher, implement the publisher(_:networkConditionChanged:mediaLinkStats:reason:) callback:

func publisher(_ publisher: OTPublisherKit, networkConditionChanged mediaLinkStats: OTPublisherKitMediaLinkStats, reason: OTNetworkReason) {
    if let transport = mediaLinkStats.transport {
        print("Publisher network condition changed: \(transport.networkCondition.rawValue)")
        print("Reason: \(transport.networkConditionReason.rawValue)")
    }
}

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. See Network condition and degradation source for details on interpreting network condition scores and reasons.

Enabling Statistics for Subscribers

Attach a class that adopts OTSubscriberKitNetworkStatsDelegate:

class MyViewController: UIViewController, OTSubscriberKitDelegate, OTSubscriberKitNetworkStatsDelegate {
    var subscriber: OTSubscriber?

    func setupSubscriber(stream: OTStream, session: OTSession) {
        subscriber = OTSubscriber(stream: stream, delegate: self)
        subscriber?.networkStatsDelegate = self
        try? session.subscribe(subscriber!)
    }
}

Implement the callbacks:

func subscriber(_ subscriber: OTSubscriberKit, videoNetworkStatsUpdated stats: OTSubscriberKitVideoNetworkStats) {
    print("Video bytes received: \(stats.videoBytesReceived)")
}

func subscriber(_ subscriber: OTSubscriberKit, audioNetworkStatsUpdated stats: OTSubscriberKitAudioNetworkStats) {
    print("Audio packets received: \(stats.audioPacketsReceived)")
}

func subscriber(_ subscriber: OTSubscriberKit, mediaLinkStatsUpdated mediaLinkStats: OTSubscriberKitMediaLinkStats) {
    print("Local downlink bandwidth: \(mediaLinkStats.transport.connectionEstimatedBandwidth) bps")
    print("Remote publisher uplink bandwidth: \(mediaLinkStats.remotePublisherTransport.connectionEstimatedBandwidth) bps")
    print("Degradation source: \(mediaLinkStats.networkDegradationSource.rawValue)")
}

Receiving Video Quality Events on the Subscribers

Additionally handle subscriber video quality changed events:

func subscriber(_ subscriber: OTSubscriberKit, videoQualityChanged stats: OTSubscriberKitVideoNetworkStats, reason: OTSubscriberVideoEventReason) {
    print("Subscriber video quality event: \(reason.rawValue)")
}

Receiving Network Condition Events on the Subscribers

To receive network condition change events for the subscriber, implement the subscriber(_:networkConditionChanged:mediaLinkStats:reason:) callback:

func subscriber(_ subscriber: OTSubscriberKit, networkConditionChanged mediaLinkStats: OTSubscriberKitMediaLinkStats, reason: OTNetworkReason) {
    if let transport = mediaLinkStats.transport {
        print("Local network condition: \(transport.networkCondition.rawValue)")
    }
    if let remoteTransport = mediaLinkStats.remotePublisherTransport {
        print("Remote publisher network condition: \(remoteTransport.networkCondition.rawValue)")
    }
    print("Degradation source: \(mediaLinkStats.networkDegradationSource.rawValue)")
}

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. See Network condition and degradation source for details on interpreting network condition scores and reasons.

Statistics Data Structures

This section outlines the structs and properties provided by the iOS 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.

`OTTransportStats`

Represents shared transport-level metrics.

connectionEstimatedBandwidth – Estimated available connection bandwidth (bps).
networkCondition – Current network condition score (OTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGood, or OTNetworkConditionExcellent).
networkConditionReason – Primary reason impacting the network condition (OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidth, or OTNetworkReasonPacketLoss).

`OTPublisherKitVideoNetworkStats`

Provides statistics about a publisher’s video track. It includes:

connectionId – In a relayed session, the connection ID of the client subscribing to the stream. Undefined in a routed session.
subscriberId – In a relayed session, the subscribed ID of the client subscribing to the stream. Undefined in a routed session.
videoPacketsLost – Estimated video packets lost.
videoPacketsSent – Video packets sent.
videoBytesSent – Video bytes sent.
timestamp – Unix timestamp in milliseconds when stats were gathered.
startTime – The timestamp, in milliseconds since the Unix epoch, from which the cumulative totals started accumulating.
videoLayers – The array of video layer statistics (see OTPublisherKitVideoLayerStats).
transport – Transport statistics.

`OTPublisherKitAudioNetworkStats`

Provides statistics about a publisher’s audio track. It includes:

connectionId – In a relayed session, the connection ID of the client subscribing to the stream. Undefined in a routed session.
subscriberId – In a relayed session, the subscribed ID of the client subscribing to the stream. Undefined in a routed session.
audioPacketsLost – Estimated packets lost.
audioPacketsSent – Audio packets sent.
audioBytesSent – Audio bytes sent.
timestamp – Unix timestamp in milliseconds.
startTime – The timestamp, in milliseconds since the Unix epoch, from which the cumulative totals started accumulating.
transport – Transport statistics.

`OTPublisherKitVideoLayerStats`

Represents one simulcast layer or SVC layer.

width – Encoded frame width.
height – Encoded frame height.
encodedFrameRate – Encoded frames per second.
bitrate – Layer bitrate (bps).
totalBitrate – Layer bitrate including RTP overhead (bps).
scalabilityMode – SVC/scalability descriptor (e.g., "L3T3").
qualityLimitationReason – Reason for quality limitation (bandwidth, CPU, codec, resolution, or layer change).
codec – The codec used by this video layer.

`OTSenderStats`

Sender-side estimation metrics (mirrored on both audio and video).

connectionMaxAllocatedBitrate – Maximum bitrate estimated for the sender connection.
connectionEstimatedBandwidth – Current bandwidth estimation (bps).

`OTSubscriberKitVideoNetworkStats`

Provides statistics about a subscriber’s video track. It includes:

videoPacketsLost – Estimated video packets lost.
videoPacketsReceived – Video packets received.
videoBytesReceived – Video bytes received.
timestamp – Unix timestamp in milliseconds when stats were gathered.
senderStats – Sender-side metrics (optional).
width – Decoded frame width in pixels.
height – Decoded frame height in pixels.
decodedFrameRate – Decoded frames per second.
bitrate – Video bitrate (bps).
totalBitrate – Bitrate including RTP overhead (bps).
pauseCount – Number of pauses (>5s since last frame). Includes intentional disables and audio-fallback cases.
totalPausesDuration – Total pause duration (ms).
freezeCount – Freeze count (WebRTC-defined freeze event).
totalFreezesDuration – Total freeze duration (ms).
codec – Current decoder codec.

`OTSubscriberKitAudioNetworkStats`

Provides statistics about a subscriber’s audio track. It includes:

audioPacketsLost – Estimated packets lost.
audioPacketsReceived – Packets received.
audioBytesReceived – Bytes received.
timestamp – Unix timestamp in milliseconds.
senderStats – Sender-side metrics (optional).

`OTPublisherKitMediaLinkStats`

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

transport — Transport statistics for this publisher's uplink connection (see OTTransportStats)

`OTSubscriberKitMediaLinkStats`

Provides transport-level statistics for a subscriber's connections, including visibility into the remote publisher's network performance. This enables applications to diagnose whether connection issues originate from the subscriber's downlink or the publisher's uplink.

transport — Transport statistics for this subscriber's downlink connection (see OTTransportStats)
remotePublisherTransport — Transport statistics for the remote publisher's uplink connection (obtained via sender-side statistics, see OTTransportStats). These stats may be limited if sender-side statistics are not enabled.
networkDegradationSource — Indicates the source of network degradation (OTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemote, OTNetworkDegradationSourceBothOrUnclear, or OTNetworkDegradationSourceUnknown)

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 setting the senderStatsTrack property to true for the OTPublisherKitSettings object used to create the publisher.

let settings = OTPublisherKitSettings()
settings.senderStatsTrack = true

let publisher = OTPublisher(delegate: self, settings: settings)

If senderStatsTrack is not enabled, no sender statistics channel will be published for this publisher. The default value is NO.

Receiving Sender-Side Statistics

If the publisher has enabled sender-side statistics, subscribers receive them automatically via the OTSubscriberKitNetworkStatsDelegate callbacks described above. The senderStats property on both OTSubscriberKitVideoNetworkStats and OTSubscriberKitAudioNetworkStats provides two metrics:

connectionMaxAllocatedBitrate — The maximum bitrate that can be estimated for the connection
connectionEstimatedBandwidth — 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.

func subscriber(_ subscriber: OTSubscriberKit, videoNetworkStatsUpdated stats: OTSubscriberKitVideoNetworkStats) {
    if let sender = stats.senderStats {
        print("Connection max allocated bitrate: \(sender.connectionMaxAllocatedBitrate)")
        print("Connection current estimated bandwidth: \(sender.connectionEstimatedBandwidth)")
    }
}

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 property on publisher and subscriber stats objects includes networkCondition and networkConditionReason. Subscriber stats also expose remotePublisherTransport and networkDegradationSource. 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:

func subscriber(_ subscriber: OTSubscriberKit, networkConditionChanged videoStats: OTSubscriberKitVideoNetworkStats, audioStats: OTSubscriberKitAudioNetworkStats, reason: OTNetworkReason) {

    let localCondition = videoStats.transport?.networkCondition ?? .unknown
    let remoteCondition = videoStats.remotePublisherTransport?.networkCondition ?? .unknown
    let source = videoStats.networkDegradationSource

    switch source {
    case .local:
        print("Local network is degraded (condition: \(localCondition.rawValue))")
    case .remote:
        print("Remote publisher network is degraded (condition: \(remoteCondition.rawValue))")
    case .bothOrUnclear:
        print("Degradation source unclear — local: \(localCondition.rawValue), remote: \(remoteCondition.rawValue)")
    default:
        break
    }
}

RTC Stats Report

To get low level stream statistics, use the getRtcStatsReport() method on OTPublisherKit. This provides RTC stats reports for the media stream asynchronously.

Before calling this method, set the rtcStatsReportDelegate property on your publisher and implement the delegate method publisher(_:rtcStatsReport:) from OTPublisherKitRtcStatsReportDelegate. When the stats are available, this method is called with an array of OTPublisherRtcStats objects. Each object contains a jsonArrayOfReports property, which is a JSON array of RTC stats reports similar to the format used by WebRTC in web browsers.

Example

class MyViewController: UIViewController, OTPublisherKitRtcStatsReportDelegate {
    var publisher: OTPublisher?

    func setupPublisher() {
        // Create and configure the publisher
        publisher = OTPublisher(delegate: self, settings: OTPublisherKitSettings())
        publisher?.rtcStatsReportDelegate = self
    }

    func fetchRtcStats() {
        publisher?.getRtcStatsReport()
    }

    // Delegate method called when stats are ready
    func publisher(_ publisher: OTPublisherKit, rtcStatsReport stats: [OTPublisherRtcStats]) {
        for stat in stats {
            print("RTC Stats JSON: \(stat.jsonArrayOfReports)")
        }
    }
}

See these Mozilla docs. Also see this W3C documentation.

Sample

The Vonage Video iOS SDK Client Observability Sample App demonstrates client observability features in a mobile app built with the iOS client SDK.

Navigation

Client Observability: iOS (Swift)

Audio, Video and Media Link Statistics API

Enabling Statistics for Publishers

Receiving Video Quality Events on the Publishers

Receiving Network Condition Events on the Publishers

Enabling Statistics for Subscribers

Receiving Video Quality Events on the Subscribers

Receiving Network Condition Events on the Subscribers

Statistics Data Structures

OTTransportStats

OTPublisherKitVideoNetworkStats

OTPublisherKitAudioNetworkStats

OTPublisherKitVideoLayerStats

OTSenderStats

OTSubscriberKitVideoNetworkStats

OTSubscriberKitAudioNetworkStats

OTPublisherKitMediaLinkStats

OTSubscriberKitMediaLinkStats