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 RTCStatsType
The type of this object.
The type
attribute
MUST be initialized to the name
of the most specific type this
dictionary
represents.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)
object
for a given SSRC.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 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 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 RTCStatsIceCandidateType
The 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 RTCStatsIceCandidatePairState
transportId
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.