RTCStats method

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Getter to retrieve the RTCStats objects that the stats report is composed of.

The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.

Syntax

var retval = RTCStatsReport.RTCStats(id);

Parameters

• id [optional]
  Type: DOMString

  Nullable

Return value

Type: getter

IDs for all of the RTCStats objects generated for this stats report.

Standards information

• Object RTC (ORTC) API for WebRTC

RTC Stats Dictionary

An RTCStats dictionary represents the stats gathered by inspecting a specific object. The RTCStats dictionary is a base type that specifies a set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.

Note  While stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.

Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations MUST return synchronized values for all stats in a RTCStats object.

dictionary RTCStats {
             DOMHighResTimeStamp timestamp;
             RTCStatsType      type;
             DOMString         id;
};

RTCStatsType DOMString

RTCStatsType is equal to one of the following strings defined in [IANA-TOBE]:

RTCP matching rules

Since statistics are retrieved from objects within the ORTC API, and information within RTCP packets is used to maintain some of the statistics, the handling of RTCP packets is important to the operation of the statistics API.

RTCP packets arriving on an RTCDtlsTransport are decrypted and a notification is sent to all RTCRtpSender and RTCRtpReceiver objects utilizing that transport. RTCRtpSender and RTCRtpReceiver objects then examine the RTCP packets to determine the information relevant to their operation and the statistics maintained by them.

RTCP packets should be queued for 30 seconds and all RTCRtpSender and RTCRtpReceiver objects on the related RTCDTlsTransport have access to those packets until the packet is removed from the queue, should the RTCRtpSender or RTCRtpReceiver objects need to examine them.

Relevant SSRC fields within selected RTCP packets are summarized within [RFC3550] Section 6.4.1 (Sender Report), Section 6.4.2 (Receiver Report), Section 6.5 (SDES), Section 6.6 (BYE), [RFC4585] Section 6.1 (Feedback Messages), and [RFC3611] Section 2 (Extended Reports).

Example

Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:

var mySender = new RTCRtpSender(myTrack); 
var myPreviousReport = null;

// ... wait a bit
setTimeout(function () {
        mySender.getStats().then(function (report) {
        processStats(report);
        myPreviousReport = report;
    });
}, aBit);

function processStats(currentReport) {
    if (myPreviousReport === null) return;
    // currentReport + myPreviousReport are an RTCStatsReport interface
    // compare the elements from the current report with the baseline
    for (var i in currentReport) {
        var now = currentReport[i]; 
        if (now.type != "outboundrtp")
            continue;
        // get the corresponding stats from the previous report
        base = myPreviousReport[now.id];
        // base + now will be of RTCRtpStreamStats dictionary type
        if (base) {
            remoteNow = currentReport[now.associateStatsId];
            remoteBase = myPreviousReport[base.associateStatsId];
            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;
            // if fractionLost is > 0.3, we have probably found the culprit
            var fractionLost = (packetsSent - packetsReceived) / packetsSent;
        }
    }
}

See also

RTCStatsReport