Copyright © 2014-2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines a set of Javascript APIs that allow access to the statistical information about a PeerConnection.
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 implementation. However, early experimentation is encouraged.
This document was published by the Web Real-Time Communications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. 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 a Working 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 September 2015 W3C Process Document.
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.
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.
The EventHandler
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].
RTCStatsType object is initialized to the name of the dictionary that the
RTCStats represents.
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.
RTCRTPStreamStats dictionary
dictionary RTCRTPStreamStats : RTCStats {
DOMString ssrc;
DOMString associateStatsId;
boolean isRemote = false;
DOMString mediaType;
DOMString mediaTrackId;
DOMString transportId;
DOMString codecId;
unsigned long firCount;
unsigned long pliCount;
unsigned long nackCount;
unsigned long sliCount;
};
RTCRTPStreamStats Members
ssrc of type DOMString
associateStatsId of type DOMString
The associateStatsId is used for looking up the corresponding
(local/remote) RTCStats object for a given SSRC.
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.
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.
mediaTrackId 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.
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].
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.
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.
RTCCodecStats dictionary
dictionary RTCCodecStats : RTCStats {
unsigned long payloadType;
DOMString codec;
unsigned long clockRate;
unsigned long channels;
DOMString parameters;
DOMString implementation;
};
RTCCodecStats Members
payloadType of type unsigned long
Payload type as used in RTP encoding.
codec of type DOMString
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.
parameters of type DOMString
From the SDP description line.
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.
![]()
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;
unsigned long packetsDiscarded;
unsigned long packetsRepaired;
};
RTCInboundRTPStreamStats 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 [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.
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.
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;
};
RTCOutboundRTPStreamStats Members
packetsSent of type unsigned long
Total number of RTP packets sent for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.
bytesSent of type unsigned
long long
Total number of bytes sent for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.
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.
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.
The following example code shows the association of remote statistics with local
statistics in a RTCStats dictionary.
RTCPeerConnectionStats dictionary
dictionary RTCPeerConnectionStats : RTCStats {
unsigned long dataChannelsOpened;
unsigned long dataChannelsClosed;
};
RTCPeerConnectionStats Members
dataChannelsOpened of type unsigned long
Represents the number of unique datachannels opened.
dataChannelsClosed of type unsigned long
Represents the number of unique datachannels closed.
RTCMediaStreamStats dictionary
dictionary RTCMediaStreamStats : RTCStats {
DOMString streamIdentifier;
sequence<DOMString> trackIds;
};
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.
RTCMediaStreamTrackStats dictionary
An RTCMediaStreamTrackStats object represents the stats about a MediaStreamTrack's connection 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 it is detached (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;
sequence<DOMString> 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;
};
RTCMediaStreamTrackStats Members
trackIdentifier of type DOMString
Represents the track.id property.
remoteSource of type boolean
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.
ssrcIds of type sequence<DOMString>
frameWidth of type unsigned long
Only makes sense for video media streams and represents the width of the video frame for this SSRC.
frameHeight of type unsigned long
Only makes sense for video media streams and represents the height of the video frame for this SSRC.
framesPerSecond of type double
Only valid for video. It represents the nominal FPS value.
framesSent of type unsigned long
Only valid for video. It represents the total number of frames sent for this SSRC.
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.
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].
framesCorrupted of type unsigned long
Only valid for video.Same definition as corruptedVideoFrames in
Section 5 of [MEDIA-SOURCE].
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.
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;
};
RTCDataChannelStats Members
label of type DOMString
protocol of type DOMString
datachannelid of type long
the "id" attribute of the RTCDataChannel object
state of type RTCDataChannelState
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.
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;
};
RTCTransportStats Members
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.
activeConnection of type boolean
Set to true when transport is active.
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.
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 ip;
long port;
DOMString protocol;
RTCIceCandidateType candidateType;
long priority;
DOMString url;
};
RTCIceCandidateStats Members
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.
candidateType of type RTCIceCandidateType
Thhis 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.
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;
};
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].
writable of type boolean
Has gotten ACK to an ICE request.
readable of type boolean
Has gotten a valid incoming ICE request.
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.
roundTripTime of type double
Represents the RTT computed by the STUN connectivity checks [STUN-PATH-CHAR].
availableOutgoingBitrate of type double
It is calculated by the underlying congestion control by combining the available bitrate for all the outgoing media streams. 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.
availableIncomingBitrate of type double
It is calculated by the underlying congestion control by combining the available bitrate for all the incoming media streams. 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.
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]. |
dictionary RTCCertificateStats : RTCStats {
DOMString fingerprint;
DOMString fingerprintAlgorithm;
DOMString base64Certificate;
DOMString issuerCertificateId;
};
RTCCertificateStats Members
fingerprint of type DOMString
Only use the fingerprint value as defined in Section 5 of [RFC4572].
fingerprintAlgorithm of type DOMString
For instance, "sha-256".
base64Certificate of type DOMString
For example, DER-encoded, base-64 representation of a certifiate.
issuerCertificateId of type DOMString
Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:
var 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.associateStatsId]; remoteBase = baselineReport[base.associateStatsId]; var packetsSent = now.packetsSent - base.packetsSent; var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived; // if fractionLost is > 0.3, we have probably found the culprit var fractionLost = (packetsSent - packetsReceived) / packetsSent; } } } function logError(error) { log(error.name + ": " + error.message); }
Some stats identifiers may expose personally identifiable information, for example the IP addresses of the participating endpoints when a TURN relay is not used.
This section will be removed before publication. The entries are in reverse chronological order.
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.