Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. 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 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 a First Public 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 First Public 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 August 2014 W3C Process Document.
RTCStats MembersThis 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].
The browser maintains a set of statistics referenced by a
selector. The selector may, for example, be a
MediaStreamTrack. For a track to be a valid selector,
it MUST be a member of a
MediaStream that is sent or received by the
RTCPeerConnection object on which
the statistics were requested.
The getStats() method is defined in [WEBRTC] and the
browser emits (in the JavaScript) a set of metrics that it
believes are relevant to the selector.
An RTCStats dictionary represents the stats gathered by
inspecting a specific object relevant to a selector. The
RTCStats dictionary is a base type that specifies a set
of default attributes, such as timestamp and type.
Specific stats are added by extending the RTCStats dictionary.
dictionary RTCStats {
DOMHiResTimeStamp timestamp;
RTCStatsType type;
DOMString id;
};RTCStats Membersid of type DOMStringA unique id that is associated with the object that
was inspected to produce this RTCStats object.
Two RTCStats objects, extracted from two different
RTCStatsReport objects,
MUST have the same
id if they were produced by inspecting the same
underlying object. User agents are free to pick any format for the
id as long as it meets the requirements above.
timestamp of type DOMHiResTimeStampThe timestamp, of type DOMHiResTimeStamp
[HIGHRES-TIME], associated with this object. The time is relative
to the UNIX epoch (Jan 1, 1970, UTC). The timestamp for local
measurements corresponds to the to the local clock and for remote
measurements corresponds to the timestamp indicated in the incoming
RTCP Sender Report (SR), Receiver Report (RR) or Extended Report (XR).
type of type RTCStatsTypeThe type of this object.
The type attribute
MUST be initialized to the name
of the most specific type this RTCStats
enum RTCStatsType {
"inboundrtp",
"outboundrtp",
"session",
"track",
"transport",
"candidatepair",
"localcandidate",
"remotecandidate"
};| Enumeration description | |
|---|---|
inboundrtp | Statistics for the inbound RTP stream that is currently
received with this |
outboundrtp | Statistics for the outbound RTP stream that is currently
sent with this |
session | Related to the |
track | |
transport | Transport statistics related to the
|
candidatepair | ICE candidate pair statistics related to the
|
localcandidate | ICE local candidate statistics related to the
|
remotecandidate | ICE remote candidate statistics related to the
|
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;
};RTCRTPStreamStats MembersassociateStatsId of type DOMStringThe associateStatsId is used for looking up the
corresponding (local/remote) RTCStats
codecId of type DOMStringfirCount of type unsigned longCount 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 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 DOMStringnackCount of type unsigned longCount the total number of Negative ACKnowledgement (NACK) packets received by the sender and is sent by receiver. Calculated as in [RFC4585] section 6.2.1.
pliCount of type unsigned longCount the total number of Packet Loss Indication (PLI) packets received by the sender and is sent by receiver. Calculated as in [RFC4585] section 6.3.1.
sliCount of type unsigned longCount 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 in [RFC4585] section 6.3.2.
ssrc of type DOMStringtransportId of type DOMStringdictionary RTCCodec : RTCStats {
unsigned long payloadType;
DOMString codec;
unsigned long clockRate;
unsigned long channels;
DOMString parameters;
};RTCCodec Memberschannels of type unsigned longUse 2 for stereo, missing for most other cases.
clockRate of type unsigned longcodec of type DOMStringe.g., video/vp8 or equivalent.
parameters of type DOMStringFrom SDP description line.
payloadType of type unsigned longPayload 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;
};RTCInboundRTPStreamStats MembersbytesReceived of type unsigned long longTotal number of bytes received for this SSRC. Calculated as in [RFC3550] section 6.4.1.
jitter of type doublePacket Jitter measured in seconds for this SSRC. Calculated as in [RFC3550] section 6.4.1.
packetsLost of type unsigned longTotal number of RTP packets lost for this SSRC. Calculated as in [RFC3550] section 6.4.1.
packetsReceived of type unsigned longTotal number of RTP packets received for this SSRC. Calculated as 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 longTotal number of bytes sent for this SSRC. Calculated as in [RFC3550] section 6.4.1.
packetsSent of type unsigned longTotal number of RTP packets sent for this SSRC. Calculated as in [RFC3550] section 6.4.1.
roundTripTime of type doubleEstimated round trip time (seconds) for this SSRC based on the RTCP timestamp. Calculated as in [RFC3550] section 6.4.1.
targetBitrate of type doublePresently 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 longdataChannelsOpened of type unsigned longdictionary RTCMediaStreamStats : RTCStats {
DOMString streamIdentifier;
sequence trackIds;
};RTCMediaStreamStats MembersstreamIdentifier of type DOMStringstream.id property
trackIds of type sequenceThis 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 doubleOnly valid for audio, and the value is between 0..1 (linear),
where 1.0 represents 0 dBov. Calculated as in
[RFC6464].
echoReturnLoss of type doubleOnly 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 doubleOnly 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 longOnly makes sense for video media streams and represents the height of the video frame for this SSRC.
frameWidth of type unsigned longOnly makes sense for video media streams and represents the width of the video frame for this SSRC.
framesCorrupted of type unsigned longOnly valid for video.Same definition as
corruptedVideoFrames in Section 5 of [MEDIA-SOURCE].
framesDecoded of type unsigned longOnly 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 longOnly valid for video. Same definition as
droppedVideoFrames in Section 5 of [MEDIA-SOURCE].
framesPerSecond of type doubleOnly valid for video. It represents the nominal FPS value.
framesReceived of type unsigned longOnly 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 longOnly valid for video. It represents the total number of frames sent for this SSRC.
remoteSource of type booleanssrcIds of type sequencetrackIdentifier of type DOMStringRepresents 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 longRepresents the total number of bytes received on this
PeerConnection.
bytesSent of type unsigned long longRepresent the total number of bytes sent on this
PeerConnection.
datachannelid of type longthe "id" attribute of the RTCDataChannel object
label of type DOMStringmessagesReceived of type unsigned longRepresents the total number of API "message" events received.
messagesSent of type unsigned longRepresents the total number of API "message" events sent.
protocol of type DOMStringstate of type RTCDataChannelStateA 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 booleanbytesReceived of type unsigned long longbytesSent of type unsigned long longlocalCertificateId of type DOMStringFor components where DTLS is negotiated, give local certificate.
remoteCertificateId of type DOMStringFor components where DTLS is negotiated, give remote certificate.
rtcpTransportStatsId of type DOMStringIf 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
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 DOMStringThe URL of the TURN or STUN server indicated in the
RTCIceServers that translated this IP address.
candidateType of type RTCStatsIceCandidateTypeThe enumeration RTCStatsIceCandidateType is based on the
cand-type defined in [RFC5245] section 15.1.
ipAddress of type DOMStringIt 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 longIt is the port number of the candidate.
priority of type longCalculated as in [RFC5245] section 15.1.
transport of type DOMStringValid 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 doubleMeasured in Bits per second, and is implementation dependent. It may be calculated by the underlying congestion control.
availableOutgoingBitrate of type doubleMeasured in Bits per second, and is implementation dependent. It may be calculated by the underlying congestion control.
bytesReceived of type unsigned long longbytesSent of type unsigned long longlocalCandidateId of type DOMStringnominated of type booleanRelated to updating the nominated flag described in Section 7.1.3.2.4 of [RFC5245].
priority of type unsigned long longCalculated from candidate priorities. Calculated as in [RFC5245] section 5.7.2.
readable of type booleanHas gotten a valid incoming ICE request.
remoteCandidateId of type DOMStringroundTripTime of type doublestate of type RTCStatsIceCandidatePairStatetransportId of type DOMStringwritable of type booleanHas 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 DOMStringFor example, DER-encoded, base-64 representation of a certifiate.
fingerprint of type DOMStringOnly use the fingerprint value as defined in Section 5 of [RFC4572].
fingerprintAlgorithm of type DOMStringFor instance, "sha-256".
issuerCertificateId of type DOMStringSome 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 would like to thank [names] for their contributions to this specification.