クライアントの観測可能性：iOS（Swift）

Vonage Video SDKは、ほとんどのユースケースで推奨される高レベルの統計APIを通じて、詳細なストリーム品質メトリクスを公開します。このAPIは、音声、ビデオ、ネットワーク、および送信者側の統計を、ピア接続の遷移をまたいで安定したまま、統一されたセッション認識形式で提供します。高度なデバッグのために、SDKは未処理のピア接続データを反映する生のWebRTC統計レポートへのアクセスも提供します。

SDKはまた、パブリッシャーとサブスクライバーの両方に対して、接続の健全性をハイレベルで評価するネットワーク・コンディション・メトリクスを公開します。これらのメトリクスには、ネットワーク・コンディション・スコア、そのスコアの理由、およびサブスクライバについては、観察された問題の原因が接続のどちらにあるかを示すデグラデーション・ソースが含まれます。参照 ネットワークの状態と劣化の原因 詳細はこちら。

オーディオ、ビデオ、メディアリンク統計API

Vonage Video iOS SDKは、パブリッシャーとサブスクライバーの両方に対して、オーディオ、ビデオ、メディアリンクの統計情報を定期的に送信します。これらには、パケットカウント、ビットレート、フレームレートデータ、一時停止/フリーズメトリクス、コーデック情報、および帯域幅推定やネットワーク状態スコアリングなどのトランスポートレベルのネットワークメトリクスが含まれます。

統計は以下の方法で配信される：

  • OTPublisherKitNetworkStatsDelegate - パブリッシャー側の統計（オーディオ、ビデオ）

  • OTSubscriberKitNetworkStatsDelegate - 加入者側の統計（オーディオ、ビデオ）

それを受け取るには、パブリッシャーかサブスクライバーで適切なデリゲートを有効にしてください。

パブリッシャー向け統計の有効化

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
    }
}

コールバックを実装する：

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)")
    }
}

ルーティングされたセッション( ビデオ・メディア・ルーター), の統計情報を定義する1つのオブジェクトが含まれます。 の統計情報を定義します。 中継セッションの場合、stats 配列には公開ストリームの加入者ごとのオブジェクトが含まれます。 オブジェクトが含まれます。

パブリッシャーでのビデオ品質イベントの受信

ビデオ画質のイベントにも興味がある場合は、このコールバックを実装してください：

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

パブリッシャーでのネットワーク状況イベントの受信

パブリッシャーのネットワーク状態変更イベントを受け取るには publisher(_:networkConditionChanged:mediaLinkStats:reason:) コールバック：

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)")
    }
}

このコールバックは、パブリッシャーに対するネットワーク状態の重大な変化が 検出されたときにトリガーされる。このコールバックには、トランスポートメトリックを含む現在のメディアリンク統計が含まれます。参照 ネットワークの状態と劣化の原因 ネットワーク・コンディション・スコアの解釈とその理由の詳細については、こちらをご覧ください。

購読者の統計を有効にする

を採用するクラスを付ける。 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!)
    }
}

コールバックを実装する：

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)")
}

加入者のビデオ品質イベントの受信

さらに、加入者のビデオ品質が変更されたイベントを処理する：

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

加入者のネットワーク状態イベントの受信

サブスクライバのネットワーク条件変更イベントを受信するには subscriber(_:networkConditionChanged:mediaLinkStats:reason:) コールバック：

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)")
}

このコールバックは、サブスクライバーまたはリモートパブリッシャーのネッ トワーク状態の重大な変化が検知されたときにトリガーされる。このコールバックは、ローカルおよびリモートのトランスポートメトリッ クと劣化ソースを含む、現在のメディアリンクの統計情報を含む。参照 ネットワークの状態と劣化の原因 ネットワーク・コンディション・スコアの解釈とその理由の詳細については、こちらをご覧ください。

統計データ構造

このセクションでは、iOS オーディオ/ビデオ統計 API が提供する構造体とプロパティの概要を説明します。すべての Video SDK プラットフォームが同じ統計情報セットを公開していますが、各プラットフォームで個々のフィールドの構造や名前の付け方に若干の違いがある場合があります。これらの違いは、基本的なメトリクスの違いではなく、プラットフォーム固有の SDK 設計規約を反映しています。

利用可能な統計とそれが表すものについてのプラットフォームに依存しない説明については、以下を参照のこと。 顧客の観測可能性の概要.

OTTransportStats

共有トランスポート・レベルのメトリクスを表します。

  • connectionEstimatedBandwidth - 利用可能な接続帯域幅の推定値（bps）。
  • networkCondition - 現在のネットワーク・コンディション・スコアOTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGoodあるいは OTNetworkConditionExcellent).
  • networkConditionReason - ネットワーク状況に影響を与える主な理由OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidthあるいは OTNetworkReasonPacketLoss).

OTPublisherKitVideoNetworkStats

パブリッシャーのビデオトラックに関する統計を提供します。これには以下が含まれます：

  • connectionId - リレーセッションの場合、ストリームを購読しているクライアントのコネクションID。ルーティングされたセッションでは未定義。
  • subscriberId - リレーセッションの場合、ストリームを購読するクライアントの購読ID。ルーティングされたセッションでは未定義。
  • videoPacketsLost - 失われたビデオパケットの推定値。
  • videoPacketsSent - ビデオパケットの送信。
  • videoBytesSent - ビデオバイトが送信された。
  • timestamp - 統計情報が収集されたミリ秒単位のUnixタイムスタンプ。
  • startTime - Unixエポックからのミリ秒単位のタイムスタンプ。
  • videoLayers - ビデオレイヤーの統計情報の配列 ( OTPublisherKitVideoLayerStats).
  • transport - 運輸統計

OTPublisherKitAudioNetworkStats

パブリッシャーのオーディオトラックに関する統計を提供します。以下を含みます：

  • connectionId - リレーセッションの場合、ストリームを購読しているクライアントのコネクションID。ルーティングされたセッションでは未定義。
  • subscriberId - リレーセッションの場合、ストリームを購読するクライアントの購読ID。ルーティングされたセッションでは未定義。
  • audioPacketsLost - 失われたパケットの推定値。
  • audioPacketsSent - オーディオパケットを送信。
  • audioBytesSent - 送信されたオーディオ・バイト。
  • timestamp - ミリ秒単位のUnixタイムスタンプ。
  • startTime - Unixエポックからのミリ秒単位のタイムスタンプ。
  • transport - 運輸統計

OTPublisherKitVideoLayerStats

1つのサイマルキャスト・レイヤーまたはSVCレイヤーを表す。

  • width - エンコードされたフレーム幅。
  • height - エンコードされたフレームの高さ。
  • encodedFrameRate - エンコードされた1秒あたりのフレーム数。
  • bitrate - レイヤーのビットレート（bps）。
  • totalBitrate - RTPオーバーヘッドを含むレイヤービットレート（bps）。
  • scalabilityMode - SVC/スケーラビリティ記述子（例えば "L3T3"）。
  • qualityLimitationReason - 品質制限の理由（帯域幅、CPU、コーデック、解像度、レイヤーの変更）。
  • codec - このビデオレイヤーが使用するコーデック。

OTSenderStats

送信側の推定メトリクス（オーディオとビデオの両方に反映される）。

  • connectionMaxAllocatedBitrate - 送信側接続で推定される最大ビットレート。
  • connectionEstimatedBandwidth - 現在の推定帯域幅（bps）。

OTSubscriberKitVideoNetworkStats

加入者のビデオトラックに関する統計情報を提供します。これには以下が含まれます：

  • videoPacketsLost - 失われたビデオパケットの推定値。
  • videoPacketsReceived - ビデオパケットを受信。
  • videoBytesReceived - 受信したビデオバイト。
  • timestamp - 統計情報が収集されたミリ秒単位のUnixタイムスタンプ。
  • senderStats - 送信側のメトリクス（オプション）。
  • width - デコードされたフレーム幅（ピクセル）。
  • height - デコードされたフレームの高さ（ピクセル）。
  • decodedFrameRate - デコードされたフレーム/秒。
  • bitrate - ビデオ・ビットレート（bps）。
  • totalBitrate - RTPオーバーヘッドを含むビットレート（bps）。
  • pauseCount - ポーズ（最後のフレームから5秒以上）の数。意図的な無効化とオーディオフォールバックの場合を含む。
  • totalPausesDuration - 全休止時間（ms）。
  • freezeCount - フリーズカウント（WebRTC定義のフリーズイベント）。
  • totalFreezesDuration - 合計フリーズ時間（ms）。
  • codec - 現在のデコーダーコーデック。

OTSubscriberKitAudioNetworkStats

加入者のオーディオトラックに関する統計情報を提供します。これには以下が含まれます：

  • audioPacketsLost - 失われたパケットの推定値。
  • audioPacketsReceived - パケットを受信した。
  • audioBytesReceived - 受信したバイト数。
  • timestamp - ミリ秒単位のUnixタイムスタンプ。
  • senderStats - 送信側のメトリクス（オプション）。

OTPublisherKitMediaLinkStats

パブリッシャー接続のトランスポートレベルの統計情報を提供します。

  • transport - このパブリッシャーのアップリンク接続のトランスポート統計 ( OTTransportStats)

OTSubscriberKitMediaLinkStats

リモートパブリッシャーのネットワークパフォーマンスの可視性を含む、サブスクライバーの接続のトランスポートレベルの統計情報を提供します。これにより、アプリケーションは、接続の問題が加入者のダウンリンクに起因するのか、パブリッシャーのアップリンクに起因するのかを診断できます。

  • transport - この加入者のダウンリンク接続のトランスポート統計（以下を参照。 OTTransportStats)
  • remotePublisherTransport - リモートパブリッシャーのアップリンク接続のトランスポート統計情報（以下の方法で取得）。 送信側統計参照 OTTransportStats).送信側統計が有効でない場合、これらの統計は制限されることがある。
  • networkDegradationSource - ネットワーク劣化の原因を示すOTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemote, OTNetworkDegradationSourceBothOrUnclearあるいは OTNetworkDegradationSourceUnknown)

送信側統計

参照 送信側統計の概要.

送信側統計の有効化

送信者側の統計情報は、購読者が受け取る。送信者側の統計を受け取るには、ストリームのパブリッシャーで senderStatsTrack プロパティ true のために OTPublisherKitSettings オブジェクトはパブリッシャーの作成に使われました。

let settings = OTPublisherKitSettings()
settings.senderStatsTrack = true

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

もし senderStatsTrack が有効でない場合、このパブリッシャーに対して送信者統計チャンネルは発行されません。デフォルト値は NO.

送信側統計の受信

パブリッシャーが送信者側の統計情報を有効にしていれば、購読者は自動的に OTSubscriberKitNetworkStatsDelegate コールバック 前述.その senderStats の両方のプロパティを持つ。 OTSubscriberKitVideoNetworkStats そして OTSubscriberKitAudioNetworkStats は2つの指標を提供する：

  • connectionMaxAllocatedBitrate - 接続時に推定可能な最大ビットレート
  • connectionEstimatedBandwidth - 接続の現在の推定帯域幅

これらのメトリクスは、オーディオとビデオのバンドルごとに計算されるため、ビデオとオーディオの両方の統計に同じ値が表示されます。

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)")
    }
}

ネットワークの状態と劣化の原因

SDKは、パブリッシャーとサブスクライバーの両方に対して、コンディションのスコア、そのスコアを駆動する理由、サブスクライバーの劣化ソースを含むリアルタイムのネットワーク・コンディション・メトリクスを提供します。ネットワーク・コンディション・モデル、スコア、理由、およびそれを有効にする方法の詳細については 顧客の観測可能性の概要.

ネットワーク・コンディション・データは2つのチャンネルから入手できる：

  • 定期的な統計： について transport プロパティを含む。 networkCondition そして networkConditionReason.加入者の統計も公開 remotePublisherTransport そして networkDegradationSource.参照 統計構造 詳細はこちら。
  • ネットワーク状態の変更イベント： 両方の専用コールバック 出版社 そして 契約者 は、ネットワーク状態の重大な変化が検出されたときにトリガーされる。

以下の例では、加入者ネットワークの状態データを使用して、劣化の原因を特定する方法を示しています：

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統計レポート

低レベルのストリーム統計を取得するには getRtcStatsReport() メソッド OTPublisherKit.これはメディアストリームのRTC統計レポートを非同期で提供する。

このメソッドを呼び出す前に rtcStatsReportDelegate プロパティを実装し、デリゲートメソッド publisher(_:rtcStatsReport:) より OTPublisherKitRtcStatsReportDelegate.統計情報が利用可能になると、このメソッドは OTPublisherRtcStats オブジェクトを含む。各オブジェクトには jsonArrayOfReports プロパティは、ウェブブラウザのWebRTCで使用される形式に似たRTC統計レポートのJSON配列です。

例

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)")
        }
    }
}

参照 Mozillaのドキュメント. こちらも参照 このW3Cドキュメント.

サンプル

について Vonage Video iOS SDK Client Observability サンプルアプリ は、iOS Client SDKでビルドされたモバイルアプリで、クライアントの観測可能な機能を実証しています。