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