媒體品質統計資料

進行中通話的媒體品質統計資料

媒體質量統計資料是核心 Call API 的擴充功能。 您必須先取得 mediaStatsFeature API 物件：

const mediaStatsFeature = call.feature(Features.MediaStats);

若要接收媒體統計數據數據，您可以訂閱 sampleReported 事件或 summaryReported 事件。

事件 sampleReported 會每秒觸發一次。 它適合作為 UI 顯示或您自己的資料管線的資料來源。

此 summaryReported 事件包含間隔內數據的匯總值，當您只需要摘要時，這非常有用。

如果您想要控制 summaryReported 事件的間隔，您必須定義類型為 MediaStatsCollectorOptions 的 mediaStatsCollectorOptions。 否則，此 SDK 會使用預設值。

const mediaStatsCollectorOptions: SDK.MediaStatsCollectorOptions = {
    aggregationInterval: 10,
    dataPointsPerAggregation: 6
};

const mediaStatsCollector = mediaStatsFeature.createCollector(mediaStatsSubscriptionOptions);

mediaStatsCollector.on('sampleReported', (sample) => {
    console.log('media stats sample', sample);
});

mediaStatsCollector.on('summaryReported', (summary) => {
    console.log('media stats summary', summary);
});

如果您不需要使用媒體統計數據收集器，您可以呼叫 dispose 的 mediaStatsCollector方法。

mediaStatsCollector.dispose();

每次呼叫結束時，您都不需要呼叫 dispose 方法 mediaStatsCollector ，因為呼叫結束時會在內部回收收集器。

MediaStatsCollectorOptions

MediaStatsCollectorOptions 是選擇性的，且 MediaStatsCollectorOptions 中有兩個選擇性欄位。

• aggregationInterval 是彙總統計資料的間隔，以秒為單位。 預設值為 10。
• dataPointsPerAggregation 會定義每個彙總事件有多少個資料點。 預設值為 6。

這兩個值分別決定 SDK 發出 summaryReported 事件的頻率，以及報告中包含的彙總資料點數目。

summaryReported 事件每 aggregationInterval * dataPointsPerAggregation 秒引發一次。

例如，如果您設定下列值：

• aggregationInterval = 1
• dataPointsPerAggregation = 60

summaryReported 事件會每 60 秒引發一次，且每個記錄的統計資料會有 60 個唯一單位。

如果您設定下列值：

• aggregatinInterval = 60
• dataPointsPerAggregation = 1

事件 summaryReported 會每 60 秒引發一次，並針對每個記錄的統計數據包含一個 （1） 個唯一單位。

最佳作法

如果您想要收集資料以進行離線檢查，建議您收集資料，並在通話結束後將其傳送至管線擷取。 如果在通話期間傳輸資料，可能會使用維持 Azure 通訊服務通話所需的網際網路頻寬 (尤其是在可用頻寬較低時)。

sampleReported在事件或summaryReported事件中，媒體統計數據數據不只是簡單的索引鍵/值對應。

以下是事件所 sampleReported 報告事件數據的型別宣告。

export interface MediaStatsReportSample {
    audio: {
        send: OutgoingAudioMediaStats<number, string>[];
        receive: IncomingAudioMediaStats<number, string>[];
    };
    video: {
        send: OutgoingVideoMediaStats<number, string>[];
        receive: IncomingVideoMediaStats<number, string>[];
    };
    screenShare: {
        send: OutgoingScreenShareMediaStats<number, string>[];
        receive: IncomingScreenShareMediaStats<number, string>[];
    };
    transports: TransportMediaStats<number>[];
}

事件資料會提供通話中每個媒體串流的統計資料，包括傳送和接收方向。

建議您使用 console.log 來列印事件，以觀察其版面配置和值變更，因此您可以根據使用案例找到適當的方式來顯示或處理數據。

音訊傳送計量

音訊接收計量

jitterBufferDelayInMs 在早於 1.20.1 的 SDK 版本中為 jitterBufferInMs。

視訊傳送計量

從 SDK 1.20.1 版開始，影片傳送計量包含 altLayouts 計量欄位，可讓您更清楚地呈現模擬串流統計數據。

視訊接收計量

jitterBufferDelayInMs 在早於 1.20.1 的 SDK 版本中為 jitterBufferInMs。

螢幕共用傳送計量

目前，統計資料欄位與視訊傳送計量相同。

螢幕共用接收計量

目前，統計資料欄位與視訊接收計量相同。

傳輸計量

在 ACS Web SDK 1.20.1 之後，傳輸相關計量會區隔出來。

rttInMs 是舊版中位於音訊、視訊和螢幕共用統計資料中的 pairRttInMs。

availableIncomingBitrate 是過去位於音訊、視訊和螢幕共用的接收統計資料中的 availableBitrate。

availableOutgoingBitrate 是過去位於音訊、視訊和螢幕共用的傳送統計資料中的 availableBitrate。

SDK 1.20.1 版 (GA) 中的變更

1.20.1 (GA) 現已支援 MediaStats 功能 API。

相較於先前的搶鮮版 (Beta)，此 GA 版本也對 API 介面做了一些小幅度的變更。

在先前的搶鮮版 (Beta) 中，pairRttInMs、availableBitrate 包含在音訊、視訊和螢幕共用統計資料中。 現在，這些計量會分成傳輸計量。

我們在音訊、視訊、螢幕共用統計數據中引進 packets 和 packetsLost 計量欄位。 這些計量可用於計算兩個不同時間點之間傳送或接收的封包總數。

視訊和螢幕共用統計資料中的 frameRateOutput 已移除。 您可以改用 frameRateDecoded。

計量欄位 jitterBufferInMs 已重新命名為 jitterBufferDelayInMs ，以提供更清楚的描述，因為此計量表示封包停留在抖動緩衝區的持續時間。

進行中通話的媒體品質統計資料

媒體質量統計資料是核心 Call API 的擴充功能。 您必須先取得 MediaStatisticsCallFeature API 物件：

MediaStatisticsCallFeature mediaStatisticsCallFeature = call.feature(Features.MEDIA_STATISTICS);

MediaStatisticsCallFeature 物件具有下列 API 結構：

• OnReportReceivedListener 事件會接聽媒體統計資料的定期報告。
• getReportIntervalInSeconds 會取得產生媒體統計數據報表的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• updateReportIntervalInSeconds() 會更新媒體統計數據報告產生的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• MediaStatisticsReport包含傳出和傳入媒體統計數據的定義，依音訊、視訊和螢幕共享分類。
  • getOutgoingStatistics()：傳出媒體的媒體統計資料清單。
    • getAudioStatistics()：傳出音訊的媒體統計資料清單。
    • getVideoStatistics()：傳出視訊的媒體統計資料清單。
    • getScreenShareStatistics()：傳出螢幕共用的媒體統計資料清單。
    • getDataChannelStatistics()：數據通道的媒體統計數據清單。
  • getIncomingStatistics()：傳入媒體的媒體統計資料清單。
    • getAudioStatistics()：傳入音訊的媒體統計資料清單。
    • getVideoStatistics()：傳入視訊的媒體統計資料清單。
    • getScreenShareStatistics()：傳入螢幕共用的媒體統計資料清單。
    • getDataChannelStatistics()：數據通道的媒體統計數據清單。
  • getLastUpdatedAt()：產生報告的日期。

然後，訂閱 addOnReportReceivedListener 事件，以取得與目前的媒體品質統計資料有關的定期更新：

mediaStatisticsCallFeature.addOnReportReceivedListener(handleReportReceivedListener);
// Optionally, set the interval for media statistics report generation
mediaStatisticsCallFeature.updateReportIntervalInSeconds(15);

private void handleReportReceivedListener(MediaStatisticsReportEvent args) {
    // Obtain the media statistics report instance
    MediaStatisticsReport report = args.getReport();

    // Obtain the outgoing media statistics for audio
    List<OutgoingAudioStatistics> outgoingAudioStatistics = report.getOutgoingStatistics().getAudioStatistics();

    // Obtain the outgoing media statistics for video
    List<OutgoingVideoStatistics> outgoingVideoStatistics = report.getOutgoingStatistics().getVideoStatistics();

    // Obtain the outgoing media statistics for screen share
    List<OutgoingScreenShareStatistics> outgoingScreenShareStatistics = report.getOutgoingStatistics().getScreenShareStatistics();

    // Obtain the outgoing media statistics for data channel
    List<OutgoingDataChannelStatistics> outgoingDataChannelStatistics = report.getOutgoingStatistics().getDataChannelStatistics();

    // Obtain the incoming media statistics for audio
    List<IncomingAudioStatistics> incomingAudioStatistics = report.getIncomingStatistics().getAudioStatistics();

    // Obtain the incoming media statistics for video
    List<IncomingVideoStatistics> incomingVideoStatistics = report.getIncomingStatistics().getVideoStatistics();

    // Obtain the incoming media statistics for screen share
    List<IncomingScreenShareStatistics> incomingScreenShareStatistics = report.getIncomingStatistics().getScreenShareStatistics();

    // Obtain the incoming media statistics for data channel
    List<IncomingDataChannelStatistics> incomingDataChannelStatistics = report.getIncomingStatistics().getDataChannelStatistics();
}

最佳作法

如果您想要收集資料以進行離線檢查，建議您收集資料，並在通話結束後將其傳送至管線擷取。 如果在通話期間傳輸資料，可能會使用維持 Azure 通訊服務通話所需的網際網路頻寬 (尤其是在可用頻寬較低時)。

傳出音訊計量

傳入音訊計量

傳出視訊計量

傳入視訊計量

傳出畫面共用計量

目前，統計數據欄位與 傳出視訊計量相同。

傳入畫面共用計量

目前，統計數據欄位與 傳入視訊計量相同。

傳出數據通道計量

傳入數據通道計量

進行中通話的媒體品質統計資料

媒體質量統計資料是核心 Call API 的擴充功能。 您必須先取得 mediaStatisticsCallFeature API 物件：

var mediaStatisticsCallFeature = self.call.feature(Features.mediaStatistics)

mediaStatisticsCallFeature 物件具有下列 API 結構：

• didReceiveReport 委派方法會接聽媒體統計資料的定期報告。
• reportIntervalInSeconds 會取得產生媒體統計數據報表的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• updateReportInterval(inSeconds) 會更新媒體統計數據報告產生的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• MediaStatisticsReport 物件包含傳出和傳入媒體統計資料的定義，依音訊、視訊和螢幕共用分類。
  • outgoingMediaStatistics：傳出媒體的媒體統計資料清單。
    • audio：傳出音訊的媒體統計資料清單。
    • video：傳出視訊的媒體統計資料清單。
    • screenShare：傳出螢幕共用的媒體統計資料清單。
    • dataChannel：傳出數據通道的媒體統計數據清單。
  • incomingMediaStatistics：傳入媒體的媒體統計資料清單。
    • audio：傳入音訊的媒體統計資料清單。
    • video：傳入視訊的媒體統計資料清單。
    • screenShare：傳入螢幕共用的媒體統計資料清單。
    • dataChannel：傳入數據通道的媒體統計數據清單。
  • lastUpdated：產生報告的日期。

然後，實作 didReceiveReport 委派以取得目前媒體品質統計數據的一般更新：

// Optionally, set the interval for media statistics report generation
mediaStatisticsCallFeature.updateReportInterval(inSeconds: 15)
mediaStatisticsCallFeature.delegate = MediaStatisticsDelegate()


public class MediaStatisticsDelegate : MediaStatisticsCallFeatureDelegate
{
    public func mediaStatisticsCallFeature(_ mediaStatisticsCallFeature: MediaStatisticsCallFeature,
                                      didReceiveReport args: MediaStatisticsReportReceivedEventArgs) {
        let report = args.report

        // Obtain the outgoing media statistics for audio
        let outgoingAudioStatistics = report.outgoingStatistics.audio
    
        // Obtain the outgoing media statistics for video
        let outgoingVideoStatistics = report.outgoingStatistics.video
    
        // Obtain the outgoing media statistics for screen share
        let outgoingScreenShareStatistics = report.outgoingStatistics.screenShare

        // Obtain the outgoing media statistics for data channel
        let outgoingDataChannelStatistics = report.outgoingStatistics.dataChannel
    
        // Obtain the incoming media statistics for audio
        let incomingAudioStatistics = report.incomingStatistics.audio
    
        // Obtain the incoming media statistics for video
        let incomingVideoStatistics = report.incomingStatistics.video
    
        // Obtain the incoming media statistics for screen share
        let incomingScreenShareStatistics = report.incomingStatistics.screenShare

        // Obtain the incoming media statistics for data channel
        let incomingDataChannelStatistics = report.incomingStatistics.dataChannel
    }
}

最佳作法

如果您想要收集資料以進行離線檢查，建議您收集資料，並在通話結束後將其傳送至管線擷取。 如果在通話期間傳輸資料，可能會使用維持 Azure 通訊服務通話所需的網際網路頻寬 (尤其是在可用頻寬較低時)。

傳出音訊計量

傳入音訊計量

傳出視訊計量

傳入視訊計量

傳出畫面共用計量

目前，統計數據欄位與 傳出視訊計量相同。

傳入畫面共用計量

目前，統計數據欄位與 傳入視訊計量相同。

傳出數據通道計量

傳入數據通道計量

進行中通話的媒體品質統計資料

媒體質量統計資料是核心 CommunicationCall API 的擴充功能。 您必須先取得 MediaStatisticsCallFeature API 物件：

MediaStatisticsCallFeature mediaStatisticsCallFeature = call.Features.MediaStatistics;

MediaStatisticsCallFeature 功能物件具有下列 API 結構：

• ReportReceived 事件會接聽媒體統計資料的定期報告。
• ReportIntervalInSeconds 會取得產生媒體統計數據報表的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• UpdateReportIntervalInSeconds() 會更新媒體統計數據報告產生的間隔，以秒為單位。 SDK 會使用 10 第二個做為預設值。
• MediaStatisticsReport 物件包含傳出和傳入媒體統計資料的定義，依音訊、視訊和螢幕共用分類。
  • OutgoingMediaStatistics：傳出媒體的媒體統計資料清單。
    • Audio：傳出音訊的媒體統計資料清單。
    • Video：傳出視訊的媒體統計資料清單。
    • ScreenShare：傳出螢幕共用的媒體統計資料清單。
    • DataChannel：傳出數據通道的媒體統計數據清單。
  • IncomingMediaStatistics：傳入媒體的媒體統計資料清單。
    • Audio：傳入音訊的媒體統計資料清單。
    • Video：傳入視訊的媒體統計資料清單。
    • ScreenShare：傳入螢幕共用的媒體統計資料清單。
    • DataChannel：傳入數據通道的媒體統計數據清單。
  • LastUpdateAt：產生報告的日期。

然後，訂閱 SampleReported 事件，以取得與目前的媒體品質統計資料有關的定期更新：

mediaStatisticsCallFeature.ReportReceived += MediaStatisticsCallFeature_ReportReceived;
// Optionally, set the interval for media statistics report generation
mediaStatisticsCallFeature.UpdateReportIntervalInSeconds(15);

private void MediaStatisticsCallFeature_ReportReceived(object sender, MediaStatisticsReportReceivedEventArgs args)
    // Obtain the media statistics report instance
    MediaStatisticsReport report = args.Report;

    // Obtain the outgoing media statistics for audio
    IReadOnlyList<OutgoingAudioStatistics> outgoingAudioStatistics = report.OutgoingStatistics.Audio;

    // Obtain the outgoing media statistics for video
    IReadOnlyList<OutgoingVideoStatistics> outgoingVideoStatistics = report.OutgoingStatistics.Video;

    // Obtain the outgoing media statistics for screen share
    IReadOnlyList<OutgoingScreenShareStatistics> outgoingScreenShareStatistics = report.OutgoingStatistics.ScreenShare;

    // Obtain the outgoing media statistics for data channel
    IReadOnlyList<OutgoingDataChannelStatistics> outgoingDataChannelStatistics = report.OutgoingStatistics.DataChannel;

    // Obtain the incoming media statistics for audio
    IReadOnlyList<IncomingAudioStatistics> incomingAudioStatistics = report.IncomingStatistics.Audio;

    // Obtain the incoming media statistics for video
    IReadOnlyList<IncomingVideoStatistics> incomingVideoStatistics = report.IncomingStatistics.Video;

    // Obtain the incoming media statistics for screen share
    IReadOnlyList<IncomingScreenShareStatistics> incomingScreenShareStatistics = report.IncomingStatistics.ScreenShare;

    // Obtain the incoming media statistics for data channel
    IReadOnlyList<IncomingDataChannelStatistics> incomingDataChannelStatistics = report.IncomingStatistics.DataChannel;
}

最佳作法

如果您想要收集資料以進行離線檢查，建議您收集資料，並在通話結束後將其傳送至管線擷取。 如果在通話期間傳輸資料，可能會使用維持 Azure 通訊服務通話所需的網際網路頻寬 (尤其是在可用頻寬較低時)。

傳出音訊計量

傳入音訊計量

傳出視訊計量

傳入視訊計量

傳出畫面共用計量

目前，統計數據欄位與 傳出視訊計量相同。

傳入畫面共用計量

目前，統計數據欄位與 傳入視訊計量相同。

傳出數據通道計量

傳入數據通道計量