Copyright © 2014-2015 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 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 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
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].
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.
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 MembersassociateStatsId 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 falsefalse 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, mediaType of type DOMString, Either "audio" or "video". This MUST match the media type part
of the information in the corresponding
codec member of
RTCCodec.
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.
dictionary RTCCodec : RTCStats {
unsigned long payloadType;
DOMString codec;
unsigned long clockRate;
unsigned long channels;
DOMString parameters;
};RTCCodec Memberschannels 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.
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;
};RTCInboundRTPStreamStats MembersbytesReceived 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.
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 MembersbytesSent 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.
The following example code shows the association of remote
statistics with local statistics in a RTCStats
dictionary.
dictionary RTCPeerConnectionStats : RTCStats {
unsigned long dataChannelsOpened;
unsigned long dataChannelsClosed;
};RTCPeerConnectionStats MembersdataChannelsClosed of type unsigned long, Represents the number of unique datachannels closed.
dataChannelsOpened of type unsigned long, Represents the number of unique datachannels opened.
dictionary RTCMediaStreamStats : RTCStats {
DOMString streamIdentifier;
sequence trackIds;
};RTCMediaStreamStats MembersstreamIdentifier of type DOMString, stream.id property
trackIds of type sequence, This is the id of the stats object, not the
track.id.
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;
};RTCMediaStreamTrackStats MembersaudioLevel 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.
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 MembersbytesReceived 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, 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 MembersactiveConnection 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.
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;
};RTCIceCandidateAttributes MembersaddressSourceUrl 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.
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]. |
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 MembersavailableIncomingBitrate 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.
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 Membersbase64Certificate 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, 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.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); }
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 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.