Abstract

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

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 http://www.w3.org/TR/.

This document is incomplete, and as such is not yet suitable for commercial implementation. However, early experimentation is encouraged. The API is based on preliminary work done in the WHATWG.

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

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 August 2014 W3C Process Document.

Table of Contents

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 APIs and 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 word MUST is 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 APIs 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.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

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 are defined in [WEBRTC].

4. RTCStatsType

RTCStatsType object is initialized to the name of the dictionary that the RTCStats represents.
Note
OPEN ISSUE: Need to define an IANA registry for the RTCStatsType and populate it with the following set as baseline.

4.1 RTCStatsType DOMString

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

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

"outboundrtp"

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

"session"

Related to the RTCDataChannel and RTCPeerConnection object.

"datachannel"

Statistics related to each RTCDataChannel id.

"track"

Contains the sequence of tracks related to a specific media stream and the corresponding media-level metrics.

"transport"

Transport statistics related to the RTCPeerConnection object.

"candidatepair"

ICE candidate pair statistics related to the RTCIceTransport objects.

"localcandidate"

ICE local candidate statistics related to the RTCIceTransport objects.

"remotecandidate"

ICE remote candidate statistics related to the RTCIceTransport objects.

4.2 RTCRTPStreamStats dictionary

dictionary RTCRTPStreamStats : RTCStats {
    DOMString     ssrc;
    DOMString     associateStatsId;
    boolean       isRemote = false;
    DOMString     mediaTrackId;
    DOMString     transportId;
    DOMString     codecId;
    unsigned long firCount;
    unsigned long pliCount;
    unsigned long nackCount;
    unsigned long sliCount;
};

4.2.1 Dictionary RTCRTPStreamStats Members

associateStatsId of type DOMString

The associateStatsId is used for looking up the corresponding (local/remote) RTCStats object for a given SSRC.

codecId of type DOMString

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].

isRemote of type boolean, defaulting to false

false indicates that the statistics are measured locally, while true indicates that the measurements were done at the remote endpoint and reported in an RTCP RR/XR.

mediaTrackId of type DOMString

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.

pliCount of type unsigned long

Count the total number of Packet Loss Indication (PLI) packets received by the sender and is sent by receiver. Calculated as defined in [RFC4585] section 6.3.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.

ssrc of type DOMString

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.

4.2.2 RTCCodec dictionary

dictionary RTCCodec : RTCStats {
    unsigned long payloadType;
    DOMString     codec;
    unsigned long clockRate;
    unsigned long channels;
    DOMString     parameters;
};
4.2.2.1 Dictionary RTCCodec Members
channels of type unsigned long

Use 2 for stereo, missing for most other cases.

clockRate of type unsigned long

Represents the media sampling rate.

codec of type DOMString

e.g., video/vp8 or equivalent.

parameters of type DOMString

From the SDP description line.

payloadType of type unsigned long

Payload type as used in RTP encoding.

4.2.3 RTCInboundRTPStreamStats dictionary

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

dictionary RTCInboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsReceived;
    unsigned long long bytesReceived;
    unsigned long      packetsLost;
    double             jitter;
    double             fractionLost;
};
4.2.3.1 Dictionary RTCInboundRTPStreamStats Members
bytesReceived of type unsigned long long

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

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.

jitter of type double

Packet Jitter measured in seconds 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.

packetsReceived of type unsigned long

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

Issue 1
Open Issue: Possible additional metrics that are useful for RTP, defined in [XRBLOCK-STATS]:
  • packetsDiscarded.
  • packetsRepaired.

4.2.4 RTCOutboundRTPStreamStats dictionary

RTCOutboundRTPStreamStats dictionary represents the measurement metrics for the outgoing media stream. 

dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsSent;
    unsigned long long bytesSent;
    double             targetBitrate;
    double             roundTripTime;
};
4.2.4.1 Dictionary RTCOutboundRTPStreamStats Members
bytesSent of type unsigned long long

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

packetsSent of type unsigned long

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

roundTripTime of type double

Estimated round trip time (seconds) for this SSRC based on the RTCP timestamp. Calculated as defined in [RFC3550] section 6.4.1.

targetBitrate of type double

Presently configured bitrate target of this SSRC, in bits per second. Typically this is a configuration parameter provided to the codec's encoder.

4.2.5 Example

The following example code shows the association of remote statistics with local statistics in a RTCStats dictionary.

4.3 RTCPeerConnectionStats dictionary

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

4.3.1 Dictionary RTCPeerConnectionStats Members

dataChannelsClosed of type unsigned long

Represents the number of unique datachannels closed.

dataChannelsOpened of type unsigned long

Represents the number of unique datachannels opened.

4.4 RTCMediaStreamStats dictionary

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

4.4.1 Dictionary RTCMediaStreamStats Members

streamIdentifier of type DOMString

stream.id property

trackIds of type sequence

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

4.4.2 RTCMediaStreamTrackStats dictionary

dictionary RTCMediaStreamTrackStats : RTCStats {
    DOMString     trackIdentifier;
    boolean       remoteSource;
    sequence      ssrcIds;
    unsigned long frameWidth;
    unsigned long frameHeight;
    double        framesPerSecond;
    unsigned long framesSent;
    unsigned long framesReceived;
    unsigned long framesDecoded;
    unsigned long framesDropped;
    unsigned long framesCorrupted;
    double        audioLevel;
    double        echoReturnLoss;
    double        echoReturnLossEnhancement;
};
4.4.2.1 Dictionary RTCMediaStreamTrackStats Members
audioLevel of type double

Only valid for audio, and the value is between 0..1 (linear), where 1.0 represents 0 dBov. Calculated as defined in [RFC6464].

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.

frameHeight of type unsigned long

Only makes sense for video media streams and represents the height of the video frame for this SSRC.

frameWidth of type unsigned long

Only makes sense for video media streams and represents the width of the video frame for this SSRC.

framesCorrupted of type unsigned long

Only valid for video.Same definition as corruptedVideoFrames in Section 5 of [MEDIA-SOURCE].

framesDecoded of type unsigned long

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].

framesDropped of type unsigned long

Only valid for video. Same definition as droppedVideoFrames in Section 5 of [MEDIA-SOURCE].

framesPerSecond of type double

Only valid for video. It represents the nominal FPS value.

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 SSRC.

framesSent of type unsigned long

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

remoteSource of type boolean

ssrcIds of type sequence

trackIdentifier of type DOMString

Represents the track.id property.

4.5 RTCDataChannelStats dictionary

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

4.5.1 Dictionary RTCDataChannelStats Members

bytesReceived of type unsigned long long

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

bytesSent of type unsigned long long

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

datachannelid of type long

the "id" attribute of the RTCDataChannel object

label of type DOMString

messagesReceived of type unsigned long

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

messagesSent of type unsigned long

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

protocol of type DOMString

state of type RTCDataChannelState

4.6 RTCTransportStats dictionary

A Transport carries a part of an SDP session, consisting of RTP and RTCP. When Bundle is in use, an SDP session will have only one Transport per Bundle group. When Bundle is not in use, there is one Transport per m-line. 

dictionary RTCTransportStats : RTCStats {
    unsigned long long bytesSent;
    unsigned long long bytesReceived;
    DOMString          rtcpTransportStatsId;
    boolean            activeConnection;
    DOMString          selectedCandidatePairId;
    DOMString          localCertificateId;
    DOMString          remoteCertificateId;
};

4.6.1 Dictionary RTCTransportStats Members

activeConnection of type boolean

Set to true when transport is active.

bytesReceived of type unsigned long long

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

bytesSent of type unsigned long long

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

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.

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.

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.

4.7 RTCIceCandidateAttributes dictionary

RTCIceCandidateAttributes reflects the properties of a candidate in Section 15.1 of [RFC5245]. 

dictionary RTCIceCandidateAttributes : RTCStats {
    DOMString                ipAddress;
    long                     portNumber;
    DOMString                transport;
    RTCStatsIceCandidateType candidateType;
    long                     priority;
    DOMString                addressSourceUrl;
};

4.7.1 Dictionary RTCIceCandidateAttributes Members

addressSourceUrl of type DOMString

The URL of the TURN or STUN server indicated in the RTCIceServers that translated this IP address.

candidateType of type RTCStatsIceCandidateType

The enumeration RTCStatsIceCandidateType is based on the cand-type defined in [RFC5245] section 15.1.

ipAddress of type DOMString

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

portNumber of type long

It is the port number of the candidate.

priority of type long

Calculated as defined in [RFC5245] section 15.1.

transport of type DOMString

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

4.7.2 RTCStatsIceCandidateType enum

enum RTCStatsIceCandidateType {
    "host",
    "serverreflexive",
    "peerreflexive",
    "relayed"
};
Enumeration description
host

Defined in Section 4.1.1.1 of [RFC5245].

serverreflexive

Defined in Section 4.1.1.2 of [RFC5245].

peerreflexive

Defined in Section 4.1.1.2 of [RFC5245].

relayed

Defined in Section 7.1.3.2.1 of [RFC5245].

4.8 RTCIceCandidatePairStats dictionary

dictionary RTCIceCandidatePairStats : RTCStats {
    DOMString                     transportId;
    DOMString                     localCandidateId;
    DOMString                     remoteCandidateId;
    RTCStatsIceCandidatePairState state;
    unsigned long long            priority;
    boolean                       nominated;
    boolean                       writable;
    boolean                       readable;
    unsigned long long            bytesSent;
    unsigned long long            bytesReceived;
    double                        roundTripTime;
    double                        availableOutgoingBitrate;
    double                        availableIncomingBitrate;
};

4.8.1 Dictionary RTCIceCandidatePairStats Members

availableIncomingBitrate of type double

Measured in Bits per second, and is implementation dependent. It may be calculated by the underlying congestion control.

availableOutgoingBitrate of type double

Measured in Bits per second, and is implementation dependent. It may be calculated by the underlying congestion control.

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.

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.

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.

nominated of type boolean

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

priority of type unsigned long long

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

readable of type boolean

Has gotten a valid incoming ICE request.

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.

roundTripTime of type double

Represents the RTT computed by the STUN connectivity checks [STUN-PATH-CHAR].

state of type RTCStatsIceCandidatePairState

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

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.

writable of type boolean

Has gotten ACK to an ICE request.

Note
OPEN ISSUE: do the bitrate metrics need refs?

4.8.2 RTCStatsIceCandidatePairState enum

enum RTCStatsIceCandidatePairState {
    "frozen",
    "waiting",
    "inprogress",
    "failed",
    "succeeded",
    "cancelled"
};
Enumeration description
frozen

Defined in Section 5.7.4 of [RFC5245].

waiting

Defined in Section 5.7.4 of [RFC5245].

inprogress

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].

cancelled

Defined in Section 5.7.4 of [RFC5245].

4.9 RTCCertificateStats dictionary

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

4.9.1 Dictionary RTCCertificateStats Members

base64Certificate of type DOMString

For example, DER-encoded, base-64 representation of a certifiate.

fingerprint of type DOMString

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

fingerprintAlgorithm of type DOMString

For instance, "sha-256".

issuerCertificateId of type DOMString

5. 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:

Example 1
var baselineReport, currentReport;
var selector = pc.getRemoteStreams()[0].getAudioTracks()[0];

pc.getStats(selector, function (report) {
    baselineReport = report;
}, logError);

// ... wait a bit
setTimeout(function () {
    pc.getStats(selector, function (report) {
        currentReport = report;
        processStats();
    }, logError);
}, aBit);

function processStats() {
    // compare the elements from the current report with the baseline
    for (var i in currentReport) {
        var now = currentReport[i];
        if (now.type != "outbund-rtp")
            continue;

        // get the corresponding stats from the baseline report
        base = baselineReport[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 fractionLost is > 0.3, we have probably found the culprit
            var fractionLost = (packetsSent - packetsReceived) / packetsSent;
        }
    }
}

function logError(error) {
    log(error.name + ": " + error.message);
}

6. 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.

7. Change Log

This section will be removed before publication.

7.1 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.

7.2 Acknowledgements

The editors wish to thank the Working Group chairs, Stefan Håkansson, and Team Contact, Dominique Hazaël-Massieux, for their support. The editors would like to thank Cullen Jennings for their contributions to this specification.

A. References

A.1 Normative references

[ECHO]
ITU-T G.168. Digital network echo cancellers. Standard. URL: https://www.itu.int/rec/T-REC-G.168/en
[GETUSERMEDIA]
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan. Media Capture and Streams. 3 September 2013. W3C Working Draft. URL: http://www.w3.org/TR/mediacapture-streams/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[MEDIA-SOURCE]
Aaron Colwell; Adrian Bateman; Mark Watson. Media Source Extensions. 17 July 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/media-source/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3550]
H. Schulzrinne; S. Casner; R. Frederick; V. Jacobson. RTP: A Transport Protocol for Real-Time Applications. July 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3550
[RFC4572]
J. Lennox. Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP). July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4572
[RFC4585]
J. Ott; S. Wenger; N. Sato; C. Burmeister; J. Rey. Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF). July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4585
[RFC5104]
S. Wenger; U. Chandra; M. Westerlund; B. Burman. Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF). February 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5104
[RFC5245]
J. Rosenberg. Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. April 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5245
[RFC6464]
J. Lennox, Ed.; E. Ivov; E. Marocco. A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6464
[STUN-PATH-CHAR]
T. Reddy; D. Wing; P. Martinsen; V. Singh. Discovery of path characteristics using STUN. Internet Draft. URL: https://tools.ietf.org/html/draft-reddy-tram-stun-path-data
[WEBRTC]
Adam Bergkvist; Daniel Burnett; Cullen Jennings; Anant Narayanan. WebRTC 1.0: Real-time Communication Between Browsers. 10 September 2013. W3C Working Draft. URL: http://www.w3.org/TR/webrtc/

A.2 Informative references

[RFC2032]
T. Turletti; C. Huitema. RTP Payload Format for H.261 Video Streams. October 1996. Proposed Standard. URL: https://tools.ietf.org/html/rfc2032
[RFC4587]
R. Even. RTP Payload Format for H.261 Video Streams. August 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4587
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/
[XRBLOCK-STATS]
Varun Singh; Rachel Huang; Roni Even; Dan Romascanu; Lingli Deng. RTCP XR Metrics for WebRTC. Internet Draft. URL: https://tools.ietf.org/html/draft-ietf-xrblock-rtcweb-rtcp-xr-metrics