Abstract

This document defines a set of WebIDL objects that allow access to the statistical information about a PeerConnection.

These objects are returned from the getStats API that is specified in [WEBRTC].

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document is incomplete, and as such is not yet suitable for implementation. However, early experimentation is encouraged.

This document was published by the Web Real-Time Communications Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to public-webrtc@w3.org (subscribe, archives).

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction

This section is non-normative.

Audio, video, or data packets transmitted over a peer-connection can be lost, and experience varying amounts of network delay. A web application implementing WebRTC expects to monitor the performance of the underlying network and media pipeline.

This document defines the statistic identifiers used by the web application to extract metrics from the user agent.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST are to be interpreted as described in [RFC2119].

This specification defines the conformance criteria that applies to a single product: the user agent.

Implementations that use ECMAScript to implement the objects defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this document uses that specification and terminology.

This specification does not define what objects a conforming implementation should generate. Specifications that refer to this specification have the need to specify conformance. They should put in their document text like this:

3. Terminology

The concepts queue a task, and fires a simple event are defined in [HTML5].

The terms event, event handlers, and event handler event types are defined in [HTML5].

The terms MediaStream, MediaStreamTrack, and Consumer are defined in [GETUSERMEDIA].

The terms RTCPeerConnection, RTCDataChannel, RTCDtlsTransport, RTCDtlsTransportState, RTCIceTransport, RTCIceRole and RTCPriorityType are defined in [WEBRTC].

The term RTP stream is defined in [RFC7656] section 2.1.10.

The terms RTCStats, The terms RTCStats.timestamp, RTCStats.type, RTCStats.id, RTCCertificate, are defined in [WEBRTC].

4. Basic concepts

This section is non-normative.

The basic object of the stats model is the stats object. The following terms are defined to describe it:

Monitored object

An internal object that keeps a set of data values. Most monitored objects are object defined in the WebRTC API; they may be thought of as being internal properties of those objects.

Stats object
This is a set of values, copied out from a monitored object at a specific moment in time. It is returned as a WebIDL dictionary through the getStats API call.
Stats object reference

A monitored object has a stable identifier "id", which is reflected in all stats objects produced from the monitored object. Stats objects may contain references to other stats objects using this "id" value. In a stats object, these references are represented by a DOMString containing "id" value of the referenced stats object.

All stats object references have type DOMString and attribute names ending in 'Id', or they have type sequence<DOMString> and attribute names ending in 'Ids'.

Stats value
Refers to a single value within a stats object.

A monitored object changes the values it contains continuously over its lifetime, but is never visible through the getStats API call. A stats object, once returned, never changes.

The stats API is defined in [WEBRTC]. It is defined to return a collection of stats objects, each of which is a dictionary inheriting directly or indirectly from the RTCStats dictionary. This API is normatively defined in [WEBRTC], but is reproduced here for ease of reference. 

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

Timestamps are expressed with DOMHighResTimeStamp [HIGHRES-TIME]. Unless otherwise specified, timestamps are relative to the UNIX epoch (Jan 1, 1970, UTC) and are measured by a local clock.

4.1 Guidelines for design of stats objects

When introducing a new stats object, the following principles should be followed:

The new members of the stats dictionary need to be named according to standard practice (camelCase).

Names ending in "Id" (such as "datachannelId") are always a stats object reference; names ending in "Ids" (such as "trackIds") are always of type sequence<DOMString>, where each DOMString is a stats object reference.

Stats are sampled by Javascript. In general, an application will not have overall control over how often stats are sampled, and the implementation cannot know what the intended use of the stats is. There is, by design, no control surface for the application to influence how stats are generated.

Therefore, letting the implementation compute "average" rates is not a good idea, since that implies some averaging time interval that can't be set beforehand. Instead, the recommended approach is to count the number of measurements of a value and sum the measurements given even if the sum is meaningless in itself; the JS application can then compute averages over any desired time interval by calling getStats() twice, taking the difference of the two sums and dividing by the difference of the two counts.

For stats that are measured against time, such as byte counts, no separate counter is needed; one can instead divide by the difference in the timestamps.

4.2 Guidelines for implementing stats objects

When implementing stats objects, the following guidelines should be adhered to:

4.3 Stats objects for deleted monitored objects

When a monitored object is destroyed, a final stats object is produced, carrying the values current at the time of destruction. This object will be returned, with a timestamp reflecting the time of destruction, whenever getStats() is called, as long as the PeerConnection exists. This is important in order to report consistently on short-lived objects and to be able to consistently report totals over the lifetime of a PeerConnection.

5. Maintenance procedures for stats object types

5.1 Adding new stats objects

This document, in its editors' draft form, serves as the repository for the currently defined set of stats object types.

If a need for a new stats object type or stats value within a stats object is found, an issue should be raised against this spec on Github, and a review process will decide on whether the stat should be added to the specification or not.

A pull request for a change to this document may serve as guidance for the discussion, but the eventual merge is dependent on the review process.

While the WebRTC WG exist, it will serve as the review body; once it has disbanded, the W3C will have to establish appropriate review.

The level of review sought is that of the IETF process' "expert review", as defined in [ RFC5226] section 4.1. The documentation needed includes the names of the new stats, their data types, and the definitions they are based on, specified to a level that allows interoperable implementation. The specification may consist of references to other documents.

Another specification that wishes to refer to a specific version (for instance for conformance) should refer to a dated version; these will be produced regularly when updates happen.

5.2 Retiring stats objects

At times, it makes sense to retire the definition for a stats object or a stats value. When this happens, it is not advisable to simply delete it from the spec, since there may be implementations out there that use it, and it is important that the name is reserved from re-use for another, incompatible definition.

Therefore, retired stats objects are moved to a separate section in this document. Retired stats objects are moved there in their entirety; retired stats values are moved to a "partial dictionary".

If there is no evidence that the retired object definition has ever been used (such as an object that is added to the spec and renamed, redefined or removed prior to implementation), the editors can decide to just remove the object from the spec.

6. RTCStatsType

The type element, of type RTCStatsType, indicates the type of the object that the RTCStats object represents. An object with a given "type" can have only one IDL dictionary type, but multiple "type" values may indicate the same IDL dictionary type; for example, "local-candidate" and "remote-candidate" both use the IDL dictionary type RTCIceCandidateStats.

This specification is normative for the allowed values of RTCStatsType.

6.1 RTCStatsType enum 

enum RTCStatsType {
    "codec",
    "inbound-rtp",
    "outbound-rtp",
    "remote-inbound-rtp",
    "remote-outbound-rtp",
    "csrc",
    "peer-connection",
    "data-channel",
    "stream",
    "track",
    "transport",
    "candidate-pair",
    "local-candidate",
    "remote-candidate",
    "certificate"
};

The following strings are valid values for RTCStatsType:

codec

Statistics for a codec that is currently being used by RTP streams being sent or received by this RTCPeerConnection object. It is accessed by the RTCCodecStats .

inbound-rtp

Statistics for an inbound RTP stream that is currently received with this RTCPeerConnection object. It is accessed by the RTCInboundRTPStreamStats .

outbound-rtp

Statistics for an outbound RTP stream that is currently sent with this RTCPeerConnection object. It is accessed by the RTCOutboundRTPStreamStats .

remote-inbound-rtp

Statistics for the remote endpoint's inbound RTP stream corresponding to an outbound stream that is currently sent with this RTCPeerConnection object. It is measured at the remote endpoint and reported in an RTCP Receiver Report (RR) or RTCP Extended Report (XR). It is accessed by the RTCRemoteInboundRTPStreamStats .

remote-outbound-rtp

Statistics for the remote endpoint's outbound RTP stream corresponding to an inbound stream that is currently received with this RTCPeerConnection object. It is measured at the remote endpoint and reported in an RTCP Sender Report (SR). It is accessed by the RTCRemoteOutboundRTPStreamStats .

csrc

Statistics for a contributing source (CSRC) that contributed to an inbound RTP stream. It is accessed by the RTCRTPContributingSourceStats .

peer-connection

Statistics related to the RTCPeerConnection object. It is accessed by the RTCPeerConnectionStats .

data-channel

Statistics related to each RTCDataChannel id. It is accessed by the RTCDataChannelStats .

stream

Contains statistics related to a specific MediaStream. It is accessed by the RTCMediaStreamStats .

track

Contains statistics related to a specific MediaStreamTrack and the corresponding media-level metrics. It is accessed by the RTCMediaStreamTrackStats .

transport

Transport statistics related to the RTCPeerConnection object. It is accessed by the RTCTransportStats .

candidate-pair

ICE candidate pair statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidatePairStats .

local-candidate

ICE local candidate statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidateStats for the local candidate.

remote-candidate

ICE remote candidate statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidateStats for the remote candidate.

certificate

Information about a certificate used by an RTCIceTransport. It is accessed by the RTCCertificateStats .

7. Stats dictionaries

7.1 RTCRTPStreamStats dictionary 

dictionary RTCRTPStreamStats : RTCStats {
    unsigned long      ssrc;
    DOMString          mediaType;
    DOMString          trackId;
    DOMString          transportId;
    DOMString          codecId;
    unsigned long      firCount;
    unsigned long      pliCount;
    unsigned long      nackCount;
    unsigned long      sliCount;
    unsigned long long qpSum;
};

Dictionary RTCRTPStreamStats Members

ssrc of type unsigned long

The 32-bit unsigned integer value per [RFC3550] used to identify the source of the stream of RTP packets that this stats object concerns.

mediaType of type DOMString

Either "audio" or "video". This MUST match the media type part of the information in the corresponding codec member of RTCCodecStats, and MUST match the "kind" attribute of the related MediaStreamTrack.

trackId of type DOMString
The unique identifier of the stats object representing the associated MediaStreamTrack.
transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this RTP stream.

codecId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCCodecStats associated with this RTP stream.

firCount of type unsigned long

Count the total number of Full Intra Request (FIR) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC5104] section 4.3.1. and does not use the metric indicated in [RFC2032], because it was deprecated by [RFC4587].

pliCount of type unsigned long

Count the total number of Packet Loss Indication (PLI) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC4585] section 6.3.1.

nackCount of type unsigned long

Count the total number of Negative ACKnowledgement (NACK) packets received by the sender and is sent by receiver. Calculated as defined in [RFC4585] section 6.2.1.

sliCount of type unsigned long

Count the total number of Slice Loss Indication (SLI) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC4585] section 6.3.2.

qpSum of type unsigned long long

The sum of the QP values of frames passed. The count of frames is in framesDecoded for inbound stream stats, and in framesEncoded for outbound stream stats.

The definition of QP value depends on the codec; for VP8, the QP value is the value carried in the frame header as the syntax element "y_ac_qi", and defined in [RFC6386] section 19.2. Its range is 0..127.

Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.

Only valid for video.

7.2 RTCCodecStats dictionary 

dictionary RTCCodecStats : RTCStats {
    unsigned long payloadType;
    RTCCodecType  codecType;
    DOMString     transportId;
    DOMString     mimeType;
    unsigned long clockRate;
    unsigned long channels;
    DOMString     sdpFmtpLine;
    DOMString     implementation;
};

Dictionary RTCCodecStats Members

payloadType of type unsigned long

Payload type as used in RTP encoding or decoding.

codecType of type RTCCodecType

"encode" or "decode", depending on whether this object represents a media format that the implementation is prepared to encode or decode.

transportId of type DOMString

The unique identifier of the transport on which this codec is being used, which can be used to look up the corresponding RTCTransportStats object.

mimeType of type DOMString

The codec MIME media type/subtype. e.g., video/vp8 or equivalent.

clockRate of type unsigned long

Represents the media sampling rate.

channels of type unsigned long

Use 2 for stereo, missing for most other cases.

sdpFmtpLine of type DOMString

The a=fmtp line in the SDP corresponding to the codec, i.e., after the colon following the PT. This defined by [JSEP] in Section 5.7.

implementation of type DOMString

Identifies the implementation used. This is useful for diagnosing interoperability issues.

If too much information is given here, it increases the fingerprint surface. Since it is only given for active tracks, the incremental exposure is small. (This is a fingerprinting vector.)

7.2.1 RTCCodecType enum 

enum RTCCodecType {
    "encode",
    "decode",
};
Enumeration description
encode

The attached RTCCodecStats represents a media format that is being encoded, or that the implementation is prepared to encode.

decode

The attached RTCCodecStats represents a media format that the implementation is prepared to decode.

7.3 RTCReceivedRTPStreamStats dictionary 

dictionary RTCReceivedRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsReceived;
    unsigned long long bytesReceived;
    unsigned long      packetsLost;
    double             jitter;
    double             fractionLost;
    unsigned long      packetsDiscarded;
    unsigned long      packetsRepaired;
    unsigned long      burstPacketsLost;
    unsigned long      burstPacketsDiscarded;
    unsigned long      burstLossCount;
    unsigned long      burstDiscardCount;
    double             burstLossRate;
    double             burstDiscardRate;
    double             gapLossRate;
    double             gapDiscardRate;
};

Dictionary RTCReceivedRTPStreamStats Members

packetsReceived of type unsigned long

Total number of RTP packets received for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

bytesReceived of type unsigned long long

Total number of bytes received for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

packetsLost of type unsigned long

Total number of RTP packets lost for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

jitter of type double

Packet Jitter measured in seconds for this SSRC. Calculated as defined in section 6.4.1. of [RFC3550].

fractionLost of type double

The fraction packet loss reported for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1 and Appendix A.3.

packetsDiscarded of type unsigned long

The cumulative number of RTP packets discarded by the jitter buffer due to late or early-arrival, i.e., these packets are not played out. RTP packets discarded due to packet duplication are not reported in this metric [XRBLOCK-STATS]. Calculated as defined in [RFC7002] section 3.2 and Appendix A.a.

packetsRepaired of type unsigned long

The cumulative number of lost RTP packets repaired after applying an error-resilience mechanism [XRBLOCK-STATS]. It is measured for the primary source RTP packets and only counted for RTP packets that have no further chance of repair. To clarify, the value is upper-bound to the cumulative number of lost packets. Calculated as defined in [RFC7509] section 3.1 and Appendix A.b.

burstPacketsLost of type unsigned long

The cumulative number of RTP packets lost during loss bursts, Appendix A (c) of [ RFC6958].

burstPacketsDiscarded of type unsigned long

The cumulative number of RTP packets discarded during discard bursts, Appendix A (b) of [RFC7003].

burstLossCount of type unsigned long

The cumulative number of bursts of lost RTP packets, Appendix A (e) of [ RFC6958].

[RFC3611] recommends a Gmin (threshold) value of 16 for classifying a sequence of packet losses or discards as a burst.

burstDiscardCount of type unsigned long

The cumulative number of bursts of discarded RTP packets, Appendix A (e) of [ RFC8015].

burstLossRate of type double

The fraction of RTP packets lost during bursts to the total number of RTP packets expected in the bursts. As defined in Appendix A (a) of [RFC7004], however, the actual value is reported without multiplying by 32768.

burstDiscardRate of type double

The fraction of RTP packets discarded during bursts to the total number of RTP packets expected in bursts. As defined in Appendix A (e) of [RFC7004], however, the actual value is reported without multiplying by 32768.

gapLossRate of type double

The fraction of RTP packets lost during the gap periods. Appendix A (b) of [ RFC7004], however, the actual value is reported without multiplying by 32768.

gapDiscardRate of type double

The fraction of RTP packets discarded during the gap periods. Appendix A (f) of [ RFC7004], however, the actual value is reported without multiplying by 32768.

7.4 RTCInboundRTPStreamStats dictionary

The RTCInboundRTPStreamStats dictionary represents the measurement metrics for the incoming RTP media stream. 

dictionary RTCInboundRTPStreamStats : RTCReceivedRTPStreamStats {
    DOMString           remoteId;
    unsigned long       framesDecoded;
    DOMHighResTimeStamp lastPacketReceivedTimestamp;
};

Dictionary RTCInboundRTPStreamStats Members

remoteId of type DOMString

The remoteId is used for looking up the remote RTCRemoteOutboundRTPStreamStats object for the same SSRC.

framesDecoded

Only valid for video. It represents the total number of frames correctly decoded for this SSRC. Same definition as totalVideoFrames in Section 5 of [ MEDIA-SOURCE].

lastPacketReceivedTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was received for this SSRC. This differs from timestamp, which represents the time at which the statistics were generated by the local endpoint.

7.5 RTCRemoteInboundRTPStreamStats dictionary

The RTCRemoteInboundRTPStreamStats dictionary represents the remote endpoint's measurement metrics for its incoming RTP stream (our outgoing RTP stream). 

dictionary RTCRemoteInboundRTPStreamStats : RTCReceivedRTPStreamStats {
    DOMString localId;
    double    roundTripTime;
};

Dictionary RTCRemoteInboundRTPStreamStats Members

localId of type DOMString

The localId is used for looking up the local RTCOutboundRTPStreamStats object for the same SSRC.

roundTripTime of type double

Estimated round trip time for this SSRC based on the RTCP timestamps in the RTCP Receiver Report (RR) and measured in seconds. Calculated as defined in section 6.4.1. of [RFC3550]. If no RTCP Receiver Report is received with a DLSR value other than 0, the round trip time is left undefined.

7.6 RTCSentRTPStreamStats dictionary 

dictionary RTCSentRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsSent;
    unsigned long      packetsDiscardedOnSend;
    unsigned long long bytesSent;
    unsigned long long bytesDiscardedOnSend;
};

Dictionary RTCSentRTPStreamStats Members

packetsSent of type unsigned long

Total number of RTP packets sent for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

packetsDiscardedOnSend of type unsigned long

Total number of RTP packets for this SSRC that have been discarded due to socket errors, i.e. a socket error occured when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.

bytesSent of type unsigned long long

Total number of bytes sent for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.

bytesDiscardedOnSend of type unsigned long long

Total number of bytes for this SSRC that have been discarded due to socket errors, i.e. a socket error occured when handing the packets containing the bytes to the socket. This might happen due to various reasons, including full buffer or no available memory. Calculated as defined in [RFC3550] section 6.4.1.

7.7 RTCOutboundRTPStreamStats dictionary

The RTCOutboundRTPStreamStats dictionary represents the measurement metrics for the outgoing RTP stream. 

dictionary RTCOutboundRTPStreamStats : RTCSentRTPStreamStats {
    DOMString           remoteId;
    DOMHighResTimeStamp lastPacketSentTimestamp;
    double              targetBitrate;
    unsigned long       framesEncoded;
    double              totalEncodeTime;
    double              averageRTCPInterval;
};

Dictionary RTCOutboundRTPStreamStats Members

remoteId of type DOMString

The remoteId is used for looking up the remote RTCRemoteInboundRTPStreamStats object for the same SSRC.

lastPacketSentTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was sent for this SSRC. This differs from timestamp, which represents the time at which the statistics were generated by the local endpoint.

targetBitrate of type double

It is the current target bitrate configured for this particular SSRC and is the Transport Independent Application Specific (TIAS) bitrate [RFC3890]. Typically, the target bitrate is a configuration parameter provided to the codec's encoder and does not count the size of the IP or other transport layers like TCP or UDP. It is measured in bits per second and the bitrate is calculated over a 1 second window.

framesEncoded of type long

Only valid for video. It represents the total number of frames successfully encoded for this RTP media stream.

totalEncodeTime of type double

Total number of seconds that has been spent encoding the framesEncoded frames of this stream. The average encode time can be calculated by dividing this value with framesEncoded. The time it takes to encode one frame is the time passed between feeding the encoder a frame and the encoder returning encoded data for that frame. This does not include any additional time it may take to packetize the resulting data.

averageRTCPInterval of type double

The average RTCP interval between two consecutive compound RTCP packets. This is calculated by the sending endpoint when sending compound RTCP reports. Compound packets must contain at least a RTCP RR or SR packet and an SDES packet with the CNAME item.

7.8 RTCRemoteOutboundRTPStreamStats dictionary

The RTCRemoteOutboundRTPStreamStats dictionary represents the remote endpoint's measurement metrics for its outgoing RTP stream (our incoming RTP stream). 

dictionary RTCRemoteOutboundRTPStreamStats : RTCSentRTPStreamStats {
    DOMString           localId;
    DOMHighResTimeStamp remoteTimestamp;
};

Dictionary RTCRemoteOutboundRTPStreamStats Members

localId of type DOMString

The localId is used for looking up the local RTCInboundRTPStreamStats object for the same SSRC.

remoteTimestamp of type DOMHighResTimeStamp

remoteTimestamp, of type DOMHighResTimeStamp [ HIGHRES-TIME], represents the remote timestamp at which these statistics were sent by the remote endpoint. This differs from timestamp, which represents the time at which the statistics were generated or received by the local endpoint. The remoteTimestamp, if present, is derived from the NTP timestamp in an RTCP Sender Report (SR) packet, which reflects the remote endpoint's clock. That clock may not be synchronized with the local clock.

7.9 RTCRTPContributingSourceStats dictionary

The RTCRTPContributingSourceStats dictionary represents the measurement metrics for a contributing source (CSRC) that is contributing to an incoming RTP stream. Each contributing source produces a stream of RTP packets, which are combined by a mixer into a single stream of RTP packets that is ultimately received by the WebRTC endpoint. Information about the sources that contributed to this combined stream may be provided in the CSRC list or [RFC6465] header extension of received RTP packets. The timestamp of this stats object is the most recent time an RTP packet the source contributed to was received and counted by packetsContributedTo . 

dictionary RTCRTPContributingSourceStats : RTCStats {
    unsigned long contributorSsrc;
    DOMString     inboundRtpStreamId;
    unsigned long packetsContributedTo;
    double        audioLevel;
};

Dictionary RTCRTPContributingSourceStats Members

contributorSsrc of type unsigned long

The SSRC identifier of the contributing source represented by this stats object, as defined by [RFC3550]. It is a 32-bit unsigned integer that appears in the CSRC list of any packets the relevant source contributed to.

inboundRtpStreamId of type DOMString

The ID of the RTCInboundRTPStreamStats object representing the inbound RTP stream that this contributing source is contributing to.

packetsContributedTo of type unsigned long

The total number of RTP packets that this contributing source contributed to. This value is incremented each time a packet is counted by RTCInboundRTPStreamStats.packetsReceived, and the packet's CSRC list (as defined by [RFC3550] section 5.1) contains the SSRC identifier of this contributing source, contributorSsrc .

audioLevel of type double

Present if the last received RTP packet that this source contributed to contained an [RFC6465] mixer-to-client audio level header extension. The value of audioLevel is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

The [RFC6465] header extension contains values in the range 0..127, in units of -dBov, where 127 represents silence. To convert these values to the linear 0..1 range of audioLevel, a value of 127 is converted to 0, and all other values are converted using the equation: f(rfc6465_level) = 10^(-rfc6465_level/20).

7.10 RTCPeerConnectionStats dictionary 

dictionary RTCPeerConnectionStats : RTCStats {
    unsigned long dataChannelsOpened;
    unsigned long dataChannelsClosed;
    unsigned long dataChannelsRequested;
    unsigned long dataChannelsAccepted;
};

Dictionary RTCPeerConnectionStats Members

dataChannelsOpened of type unsigned long

Represents the number of unique DataChannels that have entered the "open" state during their lifetime.

dataChannelsClosed of type unsigned long

Represents the number of unique DataChannels that have left the "open" state during their lifetime (due to being closed by either end or the underlying transport being closed). DataChannels that transition from "connecting" to "closing" or "closed" without ever being "open" are not counted in this number.

dataChannelsRequested of type unsigned long

Represents the number of unique DataChannels returned from a successful createDataChannel() call on the PeerConnection. If the underlying data transport is not established, these may be in the "connecting" state.

dataChannelsAccepted of type unsigned long

Represents the number of unique DataChannels signaled in a "datachannel" event on the PeerConnection.

The total number of open data channels at any time can be calculated as dataChannelsOpened - dataChannelsClosed. This number is always positive.

The sum of dataChannelsRequested and dataChannelsAccepted is always greater than or equal to dataChannelsOpened - the difference is equal to the number of channels that have been requested, but have not reached the "open" state.

7.11 RTCMediaStreamStats dictionary 

dictionary RTCMediaStreamStats : RTCStats {
    DOMString           streamIdentifier;
    sequence<DOMString> trackIds;
};

Dictionary RTCMediaStreamStats Members

streamIdentifier of type DOMString

stream.id property

trackIds of type sequence<DOMString>

This is the id of the stats object, not the track.id.

7.12 RTCMediaStreamTrackStats dictionary

An RTCMediaStreamTrackStats object represents the stats about one attachment of a MediaStreamTrack to the PeerConnection object for which one calls getStats.

It appears in the stats as soon as it is attached (via addTrack, via addTransceiver, via ReplaceTrack on an RTPSender object, or via being created on an RTPReceiver object).

If an outgoing track is attached twice (via addTransceiver or ReplaceTrack), there will be two RTCMediaStreamTrackStats objects, one for each attachment. They will have the same "trackIdentifier" attribute, but different "id" attributes.

If the track is detached from the PeerConnection (via removeTrack or via replaceTrack), it continues to appear, but with the "detached" member set to True. 

dictionary RTCMediaStreamTrackStats : RTCStats {
    DOMString           trackIdentifier;
    boolean             remoteSource;
    boolean             ended;
    boolean             detached;
    DOMString           kind;
    DOMHighResTimeStamp estimatedPlayoutTimestamp;
    unsigned long       frameWidth;
    unsigned long       frameHeight;
    double              framesPerSecond;
    unsigned long       framesCaptured;
    unsigned long       framesSent;
    unsigned long       framesReceived;
    unsigned long       framesDecoded;
    unsigned long       framesDropped;
    unsigned long       framesCorrupted;
    unsigned long       partialFramesLost;
    unsigned long       fullFramesLost;
    double              audioLevel;
    double              totalAudioEnergy;
    boolean             voiceActivityFlag;
    double              echoReturnLoss;
    double              echoReturnLossEnhancement;
    unsigned long long  totalSamplesSent;
    unsigned long long  totalSamplesReceived;
    double              totalSamplesDuration;
    unsigned long long  concealedSamples;
    unsigned long long  concealmentEvents;
    double              jitterBufferDelay;
    RTCPriorityType     priority;
};

Dictionary RTCMediaStreamTrackStats Members

trackIdentifier of type DOMString

Represents the id property of the track.

remoteSource of type boolean
True if the source is remote, for instance if it is sourced from another host via an RTCPeerConnection. False otherwise.
ended of type boolean

Reflects the "ended" state of the track.

detached of type boolean

True if the track has been detached from the PeerConnection object. If true, all stats reflect their values at the time when the track was detached.

kind of type DOMString

Either "audio" or "video". This reflects the "kind" attribute of the MediaStreamTrack.

estimatedPlayoutTimestamp of type DOMHighResTimeStamp

Only valid for remote sources. This is the estimated playout time of this track. The playout time is the NTP timestamp of the last playable audio sample or video frame that has a known timestamp (from an RTCP SR packet mapping RTP timestamps to NTP timestamps), extrapolated with the time elapsed since it was ready to be played out. This is the "current time" of the track in NTP clock time of the sender and can be present even if there is no audio or video currently playing.

This can be useful for estimating how much audio and video is out of sync for two tracks from the same source, audioTrackStats.estimatedPlayoutTimestamp - videoTrackStats.estimatedPlayoutTimestamp.

frameWidth of type unsigned long

Only valid for video MediaStreamTracks and represents the width of the last processed video frame for this track. Before the first frame is processed this attribute is missing.

frameHeight of type unsigned long

Only valid for video MediaStreamTracks and represents the height of the last processed video frame for this track. Before the first frame is processed this attribute is missing.

framesPerSecond of type double

Only valid for video. It represents the nominal FPS value before the degradation preference is applied. It is the number of complete frames in the last second. For sending tracks it is the current captured FPS and for the receiving tracks it is the current decoding framerate.

framesCaptured of type unsigned long

Only valid for local video. It represents the total number of frames captured for this MediaStreamTrack, before encoding. For example, if this track represents a camera this is the number of frames produced by the camera for this track, whose framerate could vary due to hardware limitations or environmental factors such as lighting conditions.

framesSent of type unsigned long

Only valid for video. It represents the total number of frames sent for this MediaStreamTrack.

framesReceived of type unsigned long

Only valid for video and when remoteSource is set to true. It represents the total number of frames received for this MediaStreamTrack.

framesDecoded of type unsigned long

Only valid for video and when remoteSource is set to true. It represents the total number of frames correctly decoded for this MediaStreamTrack, independent of which SSRC it was received from. It is defined as totalVideoFrames in Section 5 of [MEDIA-SOURCE].

framesDropped of type unsigned long

Only valid for video. It is the total number of frames dropped predecode or dropped because the frame missed its display deadline for this MediastreamTrack. It is the same definition as droppedVideoFrames in Section 5 of [ MEDIA-SOURCE].

framesCorrupted of type unsigned long

Only valid for video. It is the total number of corrupted frames that have been detected for this MediaStreamTrack. It is the same definition as corruptedVideoFrames in Section 5 of [MEDIA-SOURCE].

partialFramesLost of type unsigned long

Only valid for video. partialFramesLost is the cumulative number of partial frames lost, as defined in Appendix A (j) of [RFC7004].

fullFramesLost of type unsigned long

Only valid for video. fullFramesLost is the cumulative number of full frames lost, as defined in Appendix A (i) of [RFC7004].

audioLevel of type double

Only valid for audio. The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

The "audio level" value defined in [RFC6464] and used in the RTCRtpSynchronizationSource.audioLevel of [WEBRTC] (defined as 0..127, where 0 represents 0 dBov, 126 represents -126 dBov and 127 represents silence) is obtained by the calculation given in appendix A of [RFC6465]: informally, level = -round(log10(audioLevel) * 20), with audioLevel 0.0 and values above 127 mapped to 127.

totalAudioEnergy of type double

Only valid for audio. This value MUST be computed as follows: for each audio sample sent/received for this object (and counted by totalSamplesSent or totalSamplesReceived ), add the sample's value divided by the highest-intensity encodable value, squared and then multiplied by the duration of the sample in seconds. In other words, duration * Math.pow(energy/maxEnergy, 2).

This can be used to obtain a root mean square (RMS) value that uses the same units as audioLevel , as defined in [RFC6464]. It can be converted to these units using the formula Math.sqrt(totalAudioEnergy/totalSamplesDuration). This calculation can also be performed using the differences between the values of two different getStats() calls, in order to compute the average audio level over any desired time interval. In other words, do Math.sqrt((energy2 - energy1)/(duration2 - duration1)).

For example, if a 10ms packet of audio is received with an RMS of 0.5 (out of 1.0), this should add 0.5 * 0.5 * 0.01 = 0.0025 to totalAudioEnergy. If another 10ms packet with an RMS of 0.1 is received, this should similarly add 0.0001 to totalAudioEnergy. Then, Math.sqrt(totalAudioEnergy/totalSamplesDuration) becomes Math.sqrt(0.0026/0.02) = 0.36, which is the same value that would be obtained by doing an RMS calculation over the contiguous 20ms segment of audio.

voiceActivityFlag of type boolean

Only valid for audio. Whether the last RTP packet sent or played out by this track contained voice activity or not based on the presence of the V bit in the extension header, as defined in [RFC6464].

This value indicates the voice activity in the latest RTP packet played out from a given SSRC, and is defined in the RTCRtpSynchronizationSource.voiceActivityFlag of [[WEBRTC].

echoReturnLoss of type double

Only present on audio tracks sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.14.

echoReturnLossEnhancement of type double

Only present on audio tracks sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.15.

totalSamplesSent of type unsigned long long

Only present for outbound audio tracks. The total number of audio samples that have been sent for this track.

totalSamplesReceived of type unsigned long long

Only present for inbound audio tracks. The total number of audio samples that have been received for this track. This includes concealedSamples.

totalSamplesDuration of type double

Only present for audio tracks. Represents the total duration in seconds of all samples that have sent or received (and thus counted by totalSamplesSent or totalSamplesReceived ). Can be used with totalAudioEnergy to compute an average audio level over different intervals.

concealedSamples of type unsigned long long

Only present for inbound audio tracks. The total number of inbound audio samples that are concealed samples. A concealed sample is a sample that is based on data that was synthesized to conceal packet loss and does not represent incoming data.

concealmentEvents of type unsigned long long

Only present for inbound audio tracks. The number of concealment events. This counter increases every time a concealed sample is synthesized after a non-concealed sample. That is, multiple consecutive concealed samples will increase the concealedSamples count multiple times but is a single concealment event.

jitterBufferDelay of type double

It is the total time each audio sample or video frame takes from the time it is received to the time it is rendered. The delay is measured from the time the first packet belonging to an audio/video frame enters the jitter buffer to the time the complete frame is sent for rendering after decoding. The average jitter buffer delay can be calculated by dividing the jitterBufferDelay with the framesDecoded (for video) or totalSamplesReceived (for audio).

priority of type RTCPriorityType

Indicates the priority set for the track. It is specified in [ RTCWEB-TRANSPORT], Section 4.

7.13 RTCDataChannelStats dictionary 

dictionary RTCDataChannelStats : RTCStats {
    DOMString           label;
    DOMString           protocol;
    long                datachannelid;
    DOMString           transportId;
    RTCDataChannelState state;
    unsigned long       messagesSent;
    unsigned long long  bytesSent;
    unsigned long       messagesReceived;
    unsigned long long  bytesReceived;
};

Dictionary RTCDataChannelStats Members

label of type DOMString
The "label" value of the RTCDataChannel object.
protocol of type DOMString
The "protocol" value of the RTCDataChannel object.
datachannelid of type long

The "id" attribute of the RTCDataChannel object.

transportId of type DOMString
A stats object reference for the transport used to carry this datachannel.
state of type RTCDataChannelState
The "readyState" value of the RTCDataChannel object.
messagesSent of type unsigned long

Represents the total number of API "message" events sent.

bytesSent of type unsigned long long

Represents the total number of payload bytes sent on this RTCDatachannel, i.e., not including headers or padding.

messagesReceived of type unsigned long

Represents the total number of API "message" events received.

bytesReceived of type unsigned long long

Represents the total number of bytes received on this RTCDatachannel, i.e., not including headers or padding.

7.14 RTCTransportStats dictionary

An RTCTransportStats object represents the stats corresponding to an RTCDtlsTransport and its underlying RTCIceTransport. When RTCP multiplexing is used, one transport is used for both RTP and RTCP. Otherwise, RTP and RTCP will be sent on separate transports, and rtcpTransportStatsId can be used to pair the resulting RTCTransportStats objects. Additionally, when bundling is used, a single transport will be used for all MediaStreamTracks in the bundle group. If bundling is not used, different MediaStreamTrack will use different transports. RTCP multiplexing and bundling are described in [WEBRTC]. 

dictionary RTCTransportStats : RTCStats {
    unsigned long         packetsSent;
    unsigned long         packetsReceived;
    unsigned long long    bytesSent;
    unsigned long long    bytesReceived;
    DOMString             rtcpTransportStatsId;
    RTCIceRole            iceRole;
    RTCDtlsTransportState dtlsState;
    DOMString             selectedCandidatePairId;
    DOMString             localCertificateId;
    DOMString             remoteCertificateId;
};

Dictionary RTCTransportStats Members

packetsSent of type unsigned long

Represents the total number of packets sent over this transport.

packetsReceived of type unsigned long

Represents the total number of packets received on this transport.

bytesSent of type unsigned long long

Represents the total number of payload bytes sent on this PeerConnection, i.e., not including headers or padding.

bytesReceived of type unsigned long long

Represents the total number of bytes received on this PeerConnection, i.e., not including headers or padding.

rtcpTransportStatsId of type DOMString

If RTP and RTCP are not multiplexed, this is the id of the transport that gives stats for the RTCP component, and this record has only the RTP component stats.

iceRole of type RTCIceRole

Set to the current value of the "role" attribute of the underlying RTCDtlsTransport's "transport".

dtlsState of type RTCDtlsTransportState

Set to the current value of the "state" attribute of the underlying RTCDtlsTransport.

selectedCandidatePairId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidatePairStats associated with this transport.

localCertificateId of type DOMString

For components where DTLS is negotiated, give local certificate.

remoteCertificateId of type DOMString

For components where DTLS is negotiated, give remote certificate.

7.15 RTCIceCandidateStats dictionary

RTCIceCandidateStats reflects the properties of a candidate in Section 15.1 of [RFC5245]. It corresponds to a RTCIceCandidate object. 

dictionary RTCIceCandidateStats : RTCStats {
    DOMString           transportId;
    boolean             isRemote;
    DOMString           ip;
    long                port;
    DOMString           protocol;
    RTCIceCandidateType candidateType;
    long                priority;
    DOMString           url;
    DOMString           relayProtocol;
    boolean             deleted = false;
};

Dictionary RTCIceCandidateStats Members

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateStats associated with this candidate.

isRemote of type boolean

false indicates that this represents a local candidate; true indicates that this represents a remote candidate.

ip of type DOMString

It is the IP address of the candidate, allowing for IPv4 addresses and IPv6 addresses, but fully qualified domain names (FQDNs) are not allowed. See [ RFC5245] section 15.1 for details.

port of type long

It is the port number of the candidate.

protocol of type DOMString

Valid values for transport is one of udp and tcp. Based on the "transport" defined in [RFC5245] section 15.1.

relayProtocol of type DOMString

It is the protocol used by the endpoint to communicate with the TURN server. This is only present for local candidates. Valid values for the TURN URL protocol is one of udp, tcp, or tls.

candidateType of type RTCIceCandidateType

This enumeration is defined in [WEBRTC].

priority of type long

Calculated as defined in [RFC5245] section 15.1.

url of type DOMString

The URL of the TURN or STUN server indicated in the that translated this IP address. It is the URL address surfaced in an RTCPeerConnectionIceEvent.

deleted of type boolean, defaulting to false

For local candidates, true indicates that the candidate has been deleted/freed as described by [RFC5245]. For host candidates, this means that any network resources (typically a socket) associated with the candidate have been released. For TURN candidates, this means the TURN allocation is no longer active.

For remote candidates, this property is not applicable.

7.16 RTCIceCandidatePairStats dictionary 

dictionary RTCIceCandidatePairStats : RTCStats {
    DOMString                     transportId;
    DOMString                     localCandidateId;
    DOMString                     remoteCandidateId;
    RTCStatsIceCandidatePairState state;
    unsigned long long            priority;
    boolean                       nominated;
    unsigned long                 packetsSent;
    unsigned long                 packetsReceived;
    unsigned long long            bytesSent;
    unsigned long long            bytesReceived;
    DOMHighResTimeStamp           lastPacketSentTimestamp;
    DOMHighResTimeStamp           lastPacketReceivedTimestamp;
    DOMHighResTimeStamp           firstRequestTimestamp;
    DOMHighResTimeStamp           lastRequestTimestamp;
    DOMHighResTimeStamp           lastResponseTimestamp;
    double                        totalRoundTripTime;
    double                        currentRoundTripTime;
    double                        availableOutgoingBitrate;
    double                        availableIncomingBitrate;
    unsigned long                 circuitBreakerTriggerCount;
    unsigned long long            requestsReceived;
    unsigned long long            requestsSent;
    unsigned long long            responsesReceived;
    unsigned long long            responsesSent;
    unsigned long long            retransmissionsReceived;
    unsigned long long            retransmissionsSent;
    unsigned long long            consentRequestsSent;
    DOMHighResTimeStamp           consentExpiredTimestamp;
};

Dictionary RTCIceCandidatePairStats Members

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this candidate pair.

localCandidateId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateAttributes for the local candidate associated with this candidate pair.

remoteCandidateId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateAttributes for the remote candidate associated with this candidate pair.

state of type RTCStatsIceCandidatePairState

Represents the state of the checklist for the local and remote candidates in a pair.

priority of type unsigned long long

Calculated from candidate priorities as defined in [RFC5245] section 5.7.2.

nominated of type boolean

Related to updating the nominated flag described in Section 7.1.3.2.4 of [ RFC5245].

packetsSent of type unsigned long

Represents the total number of packets sent on this candidate pair.

packetsReceived of type unsigned long

Represents the total number of packets received on this candidate pair.

bytesSent of type unsigned long long

Represents the total number of payload bytes sent on this candidate pair, i.e., not including headers or padding.

bytesReceived of type unsigned long long

Represents the total number of payload bytes received on this candidate pair, i.e., not including headers or padding.

lastPacketSentTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was sent on this particular candidate pair, excluding STUN packets.

lastPacketReceivedTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was received on this particular candidate pair, excluding STUN packets.

firstRequestTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the first STUN request was sent on this particular candidate pair.

lastRequestTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last STUN request was sent on this particular candidate pair. The average interval between two consecutive connectivity checks sent can be calculated with (lastRequestTimestamp - firstRequestTimestamp) / requestsSent.

lastResponseTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last STUN response was received on this particular candidate pair.

totalRoundTripTime of type double

Represents the sum of all round trip time measurements in seconds since the beginning of the session, based on STUN connectivity check [STUN-PATH-CHAR] responses (responsesReceived), including those that reply to requests that are sent in order to verify consent [RFC7675]. The average round trip time can be computed from totalRoundTripTime by dividing it by responsesReceived.

currentRoundTripTime of type double

Represents the latest round trip time measured in seconds, computed from both STUN connectivity checks [STUN-PATH-CHAR], including those that are sent for consent verification [RFC7675].

availableOutgoingBitrate of type double

It is calculated by the underlying congestion control by combining the available bitrate for all the outgoing RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.

Implementations that do not calculate a sender-side estimate MUST leave this undefined. Additionally, the value MUST be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets sent at lastPacketSentTimestamp, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined.

availableIncomingBitrate of type double

It is calculated by the underlying congestion control by combining the available bitrate for all the incoming RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.

Implementations that do not calculate a receiver-side estimate MUST leave this undefined. Additionally, the value should be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets received at lastPacketReceivedTimestamp, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined.

circuitBreakerTriggerCount of type unsigned long

Represents the number of times the circuit breaker is triggered for this particular 5-tuple. Ceasing transmission when a circuit breaker is triggered is defined in Section 4.5 of [RFC8083]. The field MUST return undefined for user-agents that do not implement the circuit-breaker algorithm.

requestsReceived of type unsigned long long

Represents the total number of connectivity check requests received (including retransmissions). It is impossible for the receiver to tell whether the request was sent in order to check connectivity or check consent, so all connectivity checks requests are counted here.

requestsSent of type unsigned long long

Represents the total number of connectivity check requests sent (not including retransmissions).

responsesReceived of type unsigned long long

Represents the total number of connectivity check responses received.

responsesSent of type unsigned long long

Represents the total number of connectivity check responses sent. Since we cannot distinguish connectivity check requests and consent requests, all responses are counted.

retransmissionsReceived of type unsigned long long

Represents the total number of connectivity check request retransmissions received. Retransmissions are defined as connectivity check requests with a TRANSACTION_TRANSMIT_COUNTER attribute where the "req" field is larger than 1, as defined in [RFC7982].

retransmissionsSent of type unsigned long long

Represents the total number of connectivity check request retransmissions sent.

consentRequestsSent of type unsigned long long

Represents the total number of consent requests sent.

consentExpiredTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the latest valid STUN binding response expired, as defined in [RFC7675] section 5.1. If a valid STUN binding response has not been made (responsesReceived is zero) or the latest one has not expired this value must be undefined.

7.16.1 RTCStatsIceCandidatePairState enum 

enum RTCStatsIceCandidatePairState {
    "frozen",
    "waiting",
    "in-progress",
    "failed",
    "succeeded"
};
Enumeration description
frozen

Defined in Section 5.7.4 of [RFC5245].

waiting

Defined in Section 5.7.4 of [RFC5245].

in-progress

Defined in Section 5.7.4 of [RFC5245].

failed

Defined in Section 5.7.4 of [RFC5245].

succeeded

Defined in Section 5.7.4 of [RFC5245].

7.17 RTCCertificateStats dictionary 

dictionary RTCCertificateStats : RTCStats {
    DOMString fingerprint;
    DOMString fingerprintAlgorithm;
    DOMString base64Certificate;
    DOMString issuerCertificateId;
};

Dictionary RTCCertificateStats Members

fingerprint of type DOMString

The fingerprint of the certificate. Only use the fingerprint value as defined in Section 5 of [RFC4572].

fingerprintAlgorithm of type DOMString

The hash function used to compute the certificate fingerprint. For instance, "sha-256".

base64Certificate of type DOMString

The DER-encoded base-64 representation of the certifiate.

issuerCertificateId of type DOMString

The issuerCertificateId refers to the stats object that contains the next certificate in the certificate chain. If the current certificate is at the end of the chain (i.e. a self-signed certificate), this will not be set.

8. Obsolete stats 

partial dictionary RTCIceCandidatePairStats {
    double totalRtt;
    double currentRtt;
};

Obsolete RTCIceCandidatePairStats members

totalRtt

This field got renamed to "totalRoundTripTime" in Dec 2016.

currentRtt

This field got renamed to "currentRoundTripTime" in Dec 2016.

9. Examples

9.1 Example of a stats application

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:

Example 1
var baselineReport, currentReport;
var sender = pc.getSenders()[0];

sender.getStats().then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return sender.getStats();
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  console.log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    for (let now of currentReport.values()) {
        if (now.type != "outbound-rtp")
            continue;

        // get the corresponding stats from the baseline report
        let base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport[now.remoteId];
            remoteBase = baselineReport[base.remoteId];

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

            // if intervalFractionLoss is > 0.3, we've probably found the culprit
            var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
        }
    });
}

10. Security Considerations

Some stats identifiers may expose personally identifiable information, for example the IP addresses of the participating endpoints when a TURN relay is not used.

11. Change Log

This section will be removed before publication. The entries are in reverse chronological order.

11.1 Changes between 31 Mar 2017 and 14 Jun 2017

11.2 Changes between 14 Dec 2016 and 30 Mar 2017

11.3 Changes since 21 sep 2016

This list does not include infrastructure and minor editorials.

11.4 Changes since 26 May 2016

11.5 Changes since 23 October 2015

11.6 Changes since 03 February 2015

  1. [#10] Added RTCRTPStreamStats.mediaType.

11.7 Changes since 30 September 2014

  1. kept getStats() in webrtc-pc. Changed RTCStatsType from enum to DOMString.
  2. Added "datachannel" to RTCStatsType.
  3. Added fractionLost to RTCInboundRTPStreamStats.
  4. Clarified that bytesSent and bytesReceived do no include headers or paddings.

11.8 Acknowledgements

The editors wish to thank the Working Group chairs, Stefan Håkansson, and the Team Contact, Dominique Hazaël-Massieux, for their support. The editors would like to thank Bernard Aboba, Taylor Brandstetter, Henrik Boström, Jan-Ivar Bruaroey, Karthik Budigere, Cullen Jennings, and Lennart Schulte for their contributions to this specification.

A. References

A.1 Normative references

[ECHO]
Digital network echo cancellers. ITU-T G.168. ITU-T. Standard. URL: https://www.itu.int/rec/T-REC-G.168/en
[GETUSERMEDIA]
Media Capture and Streams. Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[HIGHRES-TIME]
High Resolution Time Level 2. Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. 1 November 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[HTML5]
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[JSEP]
Javascript Session Establishment Protocol. Justin Uberti; Cullen Jennings; Eric Rescorla. IETF. 16 January 2017. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-jsep/
[MEDIA-SOURCE]
Media Source Extensions™. Matthew Wolenetz; Jerry Smith; Mark Watson; Aaron Colwell; Adrian Bateman. W3C. 17 November 2016. W3C Recommendation. URL: https://www.w3.org/TR/media-source/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3550]
RTP: A Transport Protocol for Real-Time Applications. H. Schulzrinne; S. Casner; R. Frederick; V. Jacobson. IETF. July 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3550
[RFC3611]
RTP Control Protocol Extended Reports (RTCP XR). T. Friedman, Ed.; R. Caceres, Ed.; A. Clark, Ed.. IETF. November 2003. Proposed Standard. URL: https://tools.ietf.org/html/rfc3611
[RFC3890]
A Transport Independent Bandwidth Modifier for the Session Description Protocol (SDP). M. Westerlund. IETF. September 2004. Proposed Standard. URL: https://tools.ietf.org/html/rfc3890
[RFC4572]
Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP). J. Lennox. IETF. July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4572
[RFC4585]
Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF). J. Ott; S. Wenger; N. Sato; C. Burmeister; J. Rey. IETF. July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4585
[RFC5104]
Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF). S. Wenger; U. Chandra; M. Westerlund; B. Burman. IETF. February 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5104
[RFC5245]
Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. J. Rosenberg. IETF. April 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5245
[RFC6465]
A Real-time Transport Protocol (RTP) Header Extension for Mixer-to-Client Audio Level Indication. E. Ivov, Ed.; E. Marocco, Ed.; J. Lennox. IETF. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6465
[RFC6958]
RTP Control Protocol (RTCP) Extended Report (XR) Block for Burst/Gap Loss Metric Reporting. A. Clark; S. Zhang; J. Zhao; Q. Wu, Ed.. IETF. May 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc6958
[RFC7002]
RTP Control Protocol (RTCP) Extended Report (XR) Block for Discard Count Metric Reporting. A. Clark; G. Zorn; Q. Wu. IETF. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7002
[RFC7003]
RTP Control Protocol (RTCP) Extended Report (XR) Block for Burst/Gap Discard Metric Reporting. A. Clark; R. Huang; Q. Wu, Ed.. IETF. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7003
[RFC7004]
RTP Control Protocol (RTCP) Extended Report (XR) Blocks for Summary Statistics Metrics Reporting. G. Zorn; R. Schott; Q. Wu, Ed.; R. Huang. IETF. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7004
[RFC7509]
RTP Control Protocol (RTCP) Extended Report (XR) for Post-Repair Loss Count Metrics. R. Huang; V. Singh. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7509
[RFC7675]
Session Traversal Utilities for NAT (STUN) Usage for Consent Freshness. M. Perumal; D. Wing; R. Ravindranath; T. Reddy; M. Thomson. IETF. October 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7675
[RFC7982]
Measurement of Round-Trip Time and Fractional Loss Using Session Traversal Utilities for NAT (STUN). P. Martinsen; T. Reddy; D. Wing; V. Singh. IETF. September 2016. Proposed Standard. URL: https://tools.ietf.org/html/rfc7982
[RFC8015]
RTP Control Protocol (RTCP) Extended Report (XR) Block for Independent Reporting of Burst/Gap Discard Metrics. V. Singh; C. Perkins; A. Clark; R. Huang. IETF. November 2016. Proposed Standard. URL: https://tools.ietf.org/html/rfc8015
[RFC8083]
Multimedia Congestion Control: Circuit Breakers for Unicast RTP Sessions. C. Perkins; V. Singh. IETF. March 2017. Proposed Standard. URL: https://tools.ietf.org/html/rfc8083
[RTCWEB-TRANSPORT]
Transports for RTCWEB. H. Alvestrand. IETF. 31 October 2016. Active Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-ietf-rtcweb-transports/
[STUN-PATH-CHAR]
Discovery of path characteristics using STUN. T. Reddy; D. Wing; P. Martinsen; V. Singh. IETF. Internet Draft. URL: https://tools.ietf.org/html/draft-reddy-tram-stun-path-data
[WEBRTC]
WebRTC 1.0: Real-time Communication Between Browsers. Adam Bergkvist; Daniel Burnett; Cullen Jennings; Anant Narayanan; Bernard Aboba; Taylor Brandstetter. W3C. 5 June 2017. W3C Working Draft. URL: https://www.w3.org/TR/webrtc/

A.2 Informative references

[RFC2032]
RTP Payload Format for H.261 Video Streams. T. Turletti; C. Huitema. IETF. October 1996. Proposed Standard. URL: https://tools.ietf.org/html/rfc2032
[RFC4587]
RTP Payload Format for H.261 Video Streams. R. Even. IETF. August 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4587
[RFC5226]
Guidelines for Writing an IANA Considerations Section in RFCs. T. Narten; H. Alvestrand. IETF. May 2008. Best Current Practice. URL: https://tools.ietf.org/html/rfc5226
[RFC6386]
VP8 Data Format and Decoding Guide. J. Bankoski; J. Koleszar; L. Quillio; J. Salonen; P. Wilkins; Y. Xu. IETF. November 2011. Informational. URL: https://tools.ietf.org/html/rfc6386
[RFC6464]
A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication. J. Lennox, Ed.; E. Ivov; E. Marocco. IETF. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6464
[RFC7656]
A Taxonomy of Semantics and Mechanisms for Real-Time Transport Protocol (RTP) Sources. J. Lennox; K. Gross; S. Nandakumar; G. Salgueiro; B. Burman, Ed.. IETF. November 2015. Informational. URL: https://tools.ietf.org/html/rfc7656
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[XRBLOCK-STATS]
RTCP XR Metrics for WebRTC. Varun Singh; Rachel Huang; Roni Even; Dan Romascanu; Lingli Deng. IETF. Internet Draft. URL: https://tools.ietf.org/html/draft-ietf-xrblock-rtcweb-rtcp-xr-metrics