CARVIEW |
Identifiers for WebRTC's Statistics API
W3C Candidate Recommendation Draft
More details about this document
- This version:
- https://www.w3.org/TR/2022/CRD-webrtc-stats-20220630/
- Latest published version:
- https://www.w3.org/TR/webrtc-stats/
- Latest editor's draft:
- https://w3c.github.io/webrtc-stats/
- History:
- https://www.w3.org/standards/history/webrtc-stats
- Commit history
- Test suite:
- https://github.com/web-platform-tests/wpt/tree/master/webrtc-stats
- Implementation report:
- https://wpt.fyi/webrtc-stats
- Editors:
- Harald Alvestrand (Google)
- Varun Singh (callstats.io)
- Henrik Boström (Google)
- Feedback:
- GitHub w3c/webrtc-stats (pull requests, new issue, open issues)
- public-webrtc@w3.org with subject line [webrtc-stats] … message topic … (archives)
- Participate
- Mailing list
Copyright © 2014-2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
Abstract
This document defines a set of WebIDL objects that allow access to the statistical
information about a RTCPeerConnection
.
These objects are returned from the getStats API that is specified in [WEBRTC].
Status of This Document
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Since the previous publication as a Candidate Recommendation, the stats objects were significantly reorganized to better match the underlying data sources. In addition, the networkType
property was deprecated for preserving privacy, and the statsended
event was removed as no longer needed.
This document was published by the Web Real-Time Communications Working Group as a Candidate Recommendation Draft using the Recommendation track.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.
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 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 2 November 2021 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 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 words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification defines the conformance criteria that applies to a single product: the user agent.
Implementations that use ECMAScript to implement the objects 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.
This specification does not define what objects a conforming implementation should generate. Specifications that refer to this specification have the need to specify conformance. They should put in their document text that could like this (EXAMPLE ONLY):
- An implementation MUST support generating statistics for the type
RTCInboundRtpStreamStats
, with memberspacketsReceived
,bytesReceived
,packetsLost
, andjitter
. - It MUST support generating statistics for the type
RTCOutboundRtpStreamStats
, with memberspacketsSent
,bytesSent
. - For all subclasses of
RTCRtpStreamStats
, it MUST includessrc
andkind
. When stats exist for both sides of a connection, in the form of an "inbound-rtp
" / "remote-outbound-rtp
" pair or an "outbound-rtp
" / "remote-inbound-rtp
" pair, the membersremoteId
andlocalId
MUST also be present. - It MAY support generating other stats.
The terms RTCPeerConnection
, RTCDataChannel
,
RTCDtlsTransport
, RTCDtlsTransportState
, RTCIceTransport
,
RTCIceRole
, RTCIceTransportState
, RTCDataChannelState
,
RTCIceCandidateType
, RTCStats
, RTCCertificate
are defined in [WEBRTC].
RTCPriorityType is defined in [WEBRTC-PRIORITY].
The term RTP stream is defined in [RFC7656].
The terms Synchronization Source (SSRC), RTCP Sender Report, RTCP Receiver Report are defined in [RFC3550].
The term RTCP Extended Report is defined in [RFC3611].
An audio sample refers to having a sample in any channel of an audio track - if multiple audio channels are used, metrics based on samples do not increment at a higher rate, simultaneously having samples in multiple channels counts as a single sample.
The basic object of the stats model is the stats object. The following terms are defined to describe it:
- Monitored object
-
An internal object that keeps a set of data values. Most monitored objects are object defined in the WebRTC API; they may be thought of as being internal properties of those objects.
- Stats object
- This is a set of values, copied out from a monitored object at a specific moment in time. It is returned as a WebIDL dictionary through the getStats API call.
- Stats object reference
-
A monitored object has a stable identifier id, which is reflected in all stats objects produced from the monitored object. Stats objects may contain references to other stats objects using this id value. In a stats object, these references are represented by a
DOMString
containing id value of the referenced stats object.All stats object references have type
DOMString
and member names ending inId
, or they have typesequence<
and member names ending inDOMString
>Ids
. - Stats value
- Refers to a single value within a stats object.
A monitored object changes the values it contains continuously over its lifetime, but is never visible through the getStats API call. A stats object, once returned, never changes.
The stats API is defined in [WEBRTC]. It is defined to return a collection of stats objects, each of which is a dictionary inheriting directly or indirectly from the
RTCStats
dictionary. This API is normatively defined in [WEBRTC], but is
reproduced here for ease of reference.
WebIDLdictionary RTCStats
{
required DOMHighResTimeStamp timestamp
;
required RTCStatsType
type
;
required DOMString id
;
};
Timestamps are expressed with DOMHighResTimeStamp
[HIGHRES-TIME], and are defined as
Performance
.timeOrigin
+
Performance
.now
()
at the time the information is
collected.
When introducing a new stats object, the following principles should be followed:
- An
RTCStats
object should correspond to an object defined in the specification it supports. - The object MUST define a new value in the
RTCStatsType
enum, and MUST define the syntax of the stats object it returns either by reference to an existing sub-dictionary ofRTCStats
or by defining a new sub-dictionary ofRTCStats
. - All members of the new object need to have definitions that make them consistently implementable. References to other specifications are a good way of doing this.
- All members need to have defined behavior for what happens before the thing it counts happens, or when the information it's supposed to show is not available. Usually, this will be "start at zero" or "do not populate the value".
The new members of the stats dictionary need to be named according to standard practice (camelCase), as per [API-DESIGN-PRINCIPLES].
Names ending in Id
(such as transportId
) are always a stats object reference;
names ending in Ids
(such as trackIds
) are always of type sequence<DOMString>,
where each DOMString
is a stats object reference.
If the natural name for a stats value would end in id
(such as when the stats value is
an in-protocol identifier for the monitored object), the recommended practice is to let
the name end in identifier
, such as dataChannelIdentifier
.
Stats are sampled by Javascript. In general, an application will not have overall control over how often stats are sampled, and the implementation cannot know what the intended use of the stats is. There is, by design, no control surface for the application to influence how stats are generated.
Therefore, letting the implementation compute "average" rates is not a good idea, since that implies some averaging time interval that can't be set beforehand. Instead, the recommended approach is to count the number of measurements of a value and sum the measurements given even if the sum is meaningless in itself; the JS application can then compute averages over any desired time interval by calling getStats() twice, taking the difference of the two sums and dividing by the difference of the two counts.
For stats that are measured against time, such as byte counts, no separate counter is needed; one can instead divide by the difference in the timestamps.
When implementing stats objects, the following guidelines should be adhered to:
- When a feature is not implemented on the platform, omit the dictionary member that is tracking usage of the feature.
- When a feature is not applicable to an instance of an object (for example
audioLevel
on a video stream), omit the dictionary member. Do NOT report a count of zero, -1 or "empty string". - When a counted feature hasn't been used yet, but may happen in the future, report a count of zero.
The object descriptions will say what the lifetime of a monitored object from the perspective of stats is. When a monitored object is deleted, it no longer appears in stats; until this happens, it will appear. This may or may not correspond to the actual lifetime of an object in an implementation; what matters for this specification is what appears in stats.
If a monitored object can only exist in a few instances over the lifetime of a
RTCPeerConnection
, it may be simplest to consider it "eternal" and never delete it from
the set of objects reported on in stats. This type of object will remain visible until
the RTCPeerConnection
is no longer available; it is also visible in getStats
()
after
pc.close(). This is the default when no lifetime is mentioned in its specification.
Objects that might exist in many instances over time should have a defined time at which
they are deleted, at which time they stop appearing in subsequent calls to getStats
()
.
When an object is deleted, we can guarantee that no subsequent getStats
()
call will
contain a stats object reference that references the deleted object. We also
guarantee that the stats id of the deleted object will never be reused for another
object. This ensures that an application that collects stats objects for deleted
monitored objects will always be able to uniquely identify the object pointed to
in the result of any getStats
()
call.
4.4
Guidelines for getStats
()
results caching/throttling
A call to getStats
()
touches many components of WebRTC and may take significant time to
execute. The implementation may or may not utilize caching or throttling of getStats
()
calls for performance benefits, however any implementation must adhere to the following:
When the state of the RTCPeerConnection
visibly changes as a result of an API call, a
promise resolving or an event firing, subsequent new getStats
()
calls must return
up-to-date dictionaries for the affected objects.
When a stats object is deleted, subsequent getStats
()
calls MUST NOT return stats
for that monitored object.
This document specifies the interoperable stats object types. Proposals for new object types may be made in the editors draft maintained on GitHub. New standard types may appear in future revisions of the W3C Recommendation.
If a need for a new stats object type or stats value within a stats object is found, an issue should be raised on Github, and a review process will decide on whether the stat should be added to the editors draft or not.
A pull request for a change to the editors draft may serve as guidance for the discussion, but the eventual merge is dependent on the review process.
While the WebRTC WG exists, it will serve as the review body; once it has disbanded, the W3C will have to establish appropriate review.
The level of review sought is that of the IETF process' "expert review", as defined in [RFC5226] section 4.1. The documentation needed includes the names of the new stats, their data types, and the definitions they are based on, specified to a level that allows interoperable implementation. The specification may consist of references to other documents.
Another specification that wishes to refer to a specific version (for instance for conformance) should refer to a dated version; these will be produced regularly when updates happen.
At times, it makes sense to retire the definition for a stats object or a stats value. When this happens, it is not advisable to simply delete it from the spec, since there may be implementations out there that use it, and it is important that the name is reserved from re-use for another, incompatible definition.
Therefore, retired stats objects are moved to a separate section in this document. Retired stats objects are moved there in their entirety; retired stats values are moved to a "partial dictionary".
If there is no evidence that the retired object definition has ever been used (such as an object that is added to the spec and renamed, redefined or removed prior to implementation), the editors can decide to just remove the object from the spec.
6.
RTCStatsType
The type
member, of type RTCStatsType
, indicates the type of the
object that the RTCStats
object represents. An object with a given type
can
have only one IDL dictionary type, but multiple type
values may indicate the same IDL
dictionary type; for example, "local-candidate
" and "remote-candidate
" both use the IDL
dictionary type RTCIceCandidateStats
.
This specification is normative for the allowed values of RTCStatsType
.
WebIDLenum RTCStatsType
{
"codec
",
"inbound-rtp
",
"outbound-rtp
",
"remote-inbound-rtp
",
"remote-outbound-rtp
",
"media-source
",
"peer-connection
",
"data-channel
",
"stream
",
"track
",
"transport
",
"candidate-pair
",
"local-candidate
",
"remote-candidate
",
"certificate
"
};
The following strings are valid values for RTCStatsType
:
-
codec
-
Statistics for a codec that is currently being used by RTP streams being sent or received by this
RTCPeerConnection
object. It is accessed by theRTCCodecStats
. -
inbound-rtp
-
Statistics for an inbound RTP stream that is currently received with this
RTCPeerConnection
object. It is accessed by theRTCInboundRtpStreamStats
. -
outbound-rtp
-
Statistics for an outbound RTP stream that is currently sent with this
RTCPeerConnection
object. It is accessed by theRTCOutboundRtpStreamStats
.When there are multiple RTP streams connected to the same sender due to using simulcast, there will be one
RTCOutboundRtpStreamStats
per RTP stream, with distinct values of thessrc
member, and all these streams will have a reference to the same "track
" object (of typeRTCMediaStreamTrackStats
). RTX streams do not show up as separateRTCOutboundRtpStreamStats
objects but affect thepacketsSent
,bytesSent
,retransmittedPacketsSent
andretransmittedBytesSent
counters of the relevantRTCOutboundRtpStreamStats
objects. -
remote-inbound-rtp
-
Statistics for the remote endpoint's inbound RTP stream corresponding to an outbound stream that is currently sent with this
RTCPeerConnection
object. It is measured at the remote endpoint and reported in an RTCP Receiver Report (RR) or RTCP Extended Report (XR). It is accessed by theRTCRemoteInboundRtpStreamStats
. -
remote-outbound-rtp
-
Statistics for the remote endpoint's outbound RTP stream corresponding to an inbound stream that is currently received with this
RTCPeerConnection
object. It is measured at the remote endpoint and reported in an RTCP Sender Report (SR). It is accessed by theRTCRemoteOutboundRtpStreamStats
. -
media-source
-
Statistics for the media produced by a
MediaStreamTrack
that is currently attached to anRTCRtpSender
. This reflects the media that is fed to the encoder; aftergetUserMedia()
constraints have been applied (i.e. not the raw media produced by the camera). It is either anRTCAudioSourceStats
orRTCVideoSourceStats
depending on itskind
. -
peer-connection
-
Statistics related to the
RTCPeerConnection
object. It is accessed by theRTCPeerConnectionStats
. -
data-channel
-
Statistics related to each
RTCDataChannel
id. It is accessed by theRTCDataChannelStats
. -
stream
-
This is now obsolete. Contains statistics related to a specific
MediaStream
. It is accessed by the obsolete dictionaryRTCMediaStreamStats
. -
track
-
This is now obsolete. Statistics related to a specific
MediaStreamTrack
's attachment to anRTCRtpSender
orRTCRtpReceiver
. It is accessed by the obsolete dictionaryRTCMediaStreamTrackStats
.The monitored "
track
" object is deleted when the sender it reports on has itstrack
value changed to no longer refer to the same track.NoteAll "track" stats have been made obsolete. The relevant metrics have been moved to "media-source", "outbound-rtp" and "inbound-rtp" stats.
-
transport
-
Transport statistics related to the
RTCPeerConnection
object. It is accessed by theRTCTransportStats
. -
candidate-pair
-
ICE candidate pair statistics related to the
RTCIceTransport
objects. It is accessed by theRTCIceCandidatePairStats
.A candidate pair that is not the current pair for a transport is deleted when the
RTCIceTransport
does an ICE restart, at the time the state changes to "new
". The candidate pair that is the current pair for a transport is deleted after an ICE restart when theRTCIceTransport
switches to using a candidate pair generated from the new candidates; this time doesn't correspond to any other externally observable event. -
local-candidate
-
ICE local candidate statistics related to the
RTCIceTransport
objects. It is accessed by theRTCIceCandidateStats
for the local candidate.A local candidate is deleted when the
RTCIceTransport
does an ICE restart, and the candidate is no longer a member of any non-deleted candidate pair. -
remote-candidate
-
ICE remote candidate statistics related to the
RTCIceTransport
objects. It is accessed by theRTCIceCandidateStats
for the remote candidate.A remote candidate is deleted when the
RTCIceTransport
does an ICE restart, and the candidate is no longer a member of any non-deleted candidate pair. -
certificate
-
Information about a certificate used by an
RTCIceTransport
. It is accessed by theRTCCertificateStats
.
The dictionaries for RTP statistics are structured as a hierarchy, so that those stats that make sense in many different contexts are represented just once in IDL.
The metrics exposed here correspond to local measurements and those reported by RTCP packets. Compound RTCP packets contain multiple RTCP report blocks, such as Sender Report (SR) and Receiver Report (RR) whereas a non-compound RTCP packets may contain just a single RTCP SR or RR block.
The lifetime of all RTP monitored objects starts when the RTP stream is first used: When the first RTP packet is sent or received on the SSRC it represents, or when the first RTCP packet is sent or received that refers to the SSRC of the RTP stream.
RTP monitored objects are not deleted.
The hierarchy is as follows:
RTCRtpStreamStats
: Stats that apply to any end of any RTP stream
-
RTCReceivedRtpStreamStats
: Stats measured at the receiving end of an RTP stream, known either because they're measured locally or transmitted via an RTCP Receiver Report (RR) or Extended Report (XR) block.-
RTCInboundRtpStreamStats
: Stats that can only be measured at the local receiving end of an RTP stream. -
RTCRemoteInboundRtpStreamStats
: Stats relevant to the remote receiving end of an RTP stream - usually computed by combining local data with data received via an RTCP RR or XR block.
-
-
RTCSentRtpStreamStats
: Stats measured at the sending end of an RTP stream, known either because they're measured locally or because they're received via RTCP, usually in an RTCP Sender Report (SR).-
RTCOutboundRtpStreamStats
: Stats measured locally. -
RTCRemoteOutboundRtpStreamStats
: Stats relevant to the remote sending end of an RTP stream, usually computed based on an RTCP SR.
-
WebIDLdictionary RTCRtpStreamStats
: RTCStats
{
required unsigned long ssrc
;
required DOMString kind
;
DOMString transportId
;
DOMString codecId
;
};
Dictionary RTCRtpStreamStats
Members
-
ssrc
of type unsigned long -
The synchronization source (ssrc) identifier is an unsigned integer value per [RFC3550] used to identify the stream of RTP packets that this stats object is describing.
For outbound and inbound local, ssrc describes the stats for the track that were sent and received, respectively by those endpoints. For the remote inbound and remote outbound, ssrc describes the stats for the track that were received by and sent to the remote endpoint.
-
kind
of type DOMString -
Either "
audio
" or "video
". This MUST match thekind
attribute of the relatedMediaStreamTrack
. -
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 -
It is a unique identifier that is associated to the object that was inspected to produce the
RTCCodecStats
associated with this RTP stream.
This object is created when a codec type is registered for an RTP transport. It may be referenced by multiple RTP streams in media sections using that transport, but similar codecs in different transports have different RTCCodecStats objects.
User agents are expected to coalesce information into a single
"codec"
entry per payload type per transport, unless
sdpFmtpLine
differs per direction, in which case two
entries (one for encode and one for decode) are needed.
WebIDLdictionary RTCCodecStats
: RTCStats
{
required unsigned long payloadType
;
required DOMString transportId
;
required DOMString mimeType
;
unsigned long clockRate
;
unsigned long channels
;
DOMString sdpFmtpLine
;
};
Dictionary RTCCodecStats
Members
-
payloadType
of type unsigned long -
Payload type as used in RTP encoding or decoding.
-
transportId
of type DOMString -
The unique identifier of the transport on which this codec is being used, which can be used to look up the corresponding
RTCTransportStats
object. -
mimeType
of type DOMString -
The codec MIME media type/subtype. e.g., video/vp8 or equivalent.
-
clockRate
of type unsigned long -
Represents the media sampling rate.
-
channels
of type unsigned long -
When present, indicates the number of channels (mono=1, stereo=2).
-
sdpFmtpLine
of type DOMString -
The a=fmtp line in the SDP corresponding to the codec, i.e., after the colon following the PT. This defined by [JSEP] in Section 5.7.
WebIDLdictionary RTCReceivedRtpStreamStats
: RTCRtpStreamStats
{
unsigned long long packetsReceived
;
long long packetsLost
;
double jitter
;
unsigned long framesDropped
;
};
Dictionary RTCReceivedRtpStreamStats
Members
-
packetsReceived
of type unsigned long long -
Total number of RTP packets received for this SSRC. At the receiving endpoint, this is calculated as defined in [RFC3550] section 6.4.1. At the sending endpoint the
packetsReceived
is estimated by subtracting the Cumulative Number of Packets Lost from the Extended Highest Sequence Number Received, both reported in the RTCP Receiver Report, and then subtracting the initial Extended Sequence Number that was sent to this SSRC in a RTCP Sender Report and then adding one, to mirror what is discussed in Appendix A.3 in [RFC3550], but for the sender side. If no RTCP Receiver Report has been received yet, then return 0. -
packetsLost
of type long long -
Total number of RTP packets lost for this SSRC. Calculated as defined in [RFC3550] section 6.4.1. Note that because of how this is estimated, it can be negative if more packets are received than sent.
-
jitter
of type double -
Packet Jitter measured in seconds for this SSRC. Calculated as defined in section 6.4.1. of [RFC3550].
-
framesDropped
of type unsigned long -
Only exists for video. The total number of frames dropped prior to decode or dropped because the frame missed its display deadline for this receiver's track. The measurement begins when the receiver is created and is a cumulative metric as defined in Appendix A (g) of [RFC7004].
7.5
RTCInboundRtpStreamStats
dictionary
The RTCInboundRtpStreamStats
dictionary represents the measurement metrics for
the incoming RTP media stream. The timestamp reported in the statistics object is the
time at which the data was sampled.
WebIDLdictionary RTCInboundRtpStreamStats
: RTCReceivedRtpStreamStats
{
required DOMString trackIdentifier
;
required DOMString kind
;
DOMString mid
;
DOMString remoteId
;
unsigned long framesDecoded
;
unsigned long keyFramesDecoded
;
unsigned long frameWidth
;
unsigned long frameHeight
;
double framesPerSecond
;
unsigned long long qpSum
;
double totalDecodeTime
;
double totalInterFrameDelay
;
double totalSquaredInterFrameDelay
;
DOMHighResTimeStamp lastPacketReceivedTimestamp
;
unsigned long long headerBytesReceived
;
unsigned long long packetsDiscarded
;
unsigned long long fecPacketsReceived
;
unsigned long long fecPacketsDiscarded
;
unsigned long long bytesReceived
;
unsigned long nackCount
;
unsigned long firCount
;
unsigned long pliCount
;
double totalProcessingDelay
;
DOMHighResTimeStamp estimatedPlayoutTimestamp
;
double jitterBufferDelay
;
double jitterBufferTargetDelay
;
unsigned long long jitterBufferEmittedCount
;
double jitterBufferMinimumDelay
;
unsigned long long totalSamplesReceived
;
unsigned long long concealedSamples
;
unsigned long long silentConcealedSamples
;
unsigned long long concealmentEvents
;
unsigned long long insertedSamplesForDeceleration
;
unsigned long long removedSamplesForAcceleration
;
double audioLevel
;
double totalAudioEnergy
;
double totalSamplesDuration
;
unsigned long framesReceived
;
DOMString decoderImplementation
;
};
Dictionary RTCInboundRtpStreamStats
Members
-
trackIdentifier
of type DOMString -
The value of the
MediaStreamTrack
'sid
attribute. -
kind
of type DOMString -
The value of the
MediaStreamTrack
'skind
attribute. This is either"audio"
or"video"
. -
mid
of type DOMString -
If the
RTCRtpTransceiver
owning this stream has amid
value that is not null, this is that value, otherwise this member is not present. -
remoteId
of type DOMString -
The
remoteId
is used for looking up the remoteRTCRemoteOutboundRtpStreamStats
object for the same SSRC. -
framesDecoded
-
Only exists for video. It represents the total number of frames correctly decoded for this RTP stream, i.e., frames that would be displayed if no frames are dropped.
-
keyFramesDecoded
of type unsigned long -
Only exists for video. It represents the total number of key frames, such as key frames in VP8 [RFC6386] or IDR-frames in H.264 [RFC6184], successfully decoded for this RTP media stream. This is a subset of
framesDecoded
.framesDecoded - keyFramesDecoded
gives you the number of delta frames decoded. -
frameWidth
of type unsigned long -
Only exists for video. Represents the width of the last decoded frame. Before the first frame is decoded this member does not exist.
-
frameHeight
of type unsigned long -
Only exists for video. Represents the height of the last decoded frame. Before the first frame is decoded this member does not exist.
-
framesPerSecond
of type double -
Only exists for video. The number of decoded frames in the last second.
-
qpSum
of type unsigned long long -
Only exists for video. The sum of the QP values of frames decoded by this receiver. The count of frames is in
framesDecoded
.The definition of QP value depends on the codec; for VP8, the QP value is the value carried in the frame header as the syntax element
y_ac_qi
, and defined in [RFC6386] section 19.2. Its range is 0..127.Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.
-
totalDecodeTime
of type double -
Total number of seconds that have been spent decoding the
framesDecoded
frames of this stream. The average decode time can be calculated by dividing this value withframesDecoded
. The time it takes to decode one frame is the time passed between feeding the decoder a frame and the decoder returning decoded data for that frame. -
totalInterFrameDelay
of type double -
Sum of the interframe delays in seconds between consecutively decoded frames, recorded just after a frame has been decoded. The interframe delay variance be calculated from
totalInterFrameDelay
,totalSquaredInterFrameDelay
, andframesDecoded
according to the formula: (totalSquaredInterFrameDelay
-totalInterFrameDelay
^2/framesDecoded
)/framesDecoded
. -
totalSquaredInterFrameDelay
of type double -
Sum of the squared interframe delays in seconds between consecutively decoded frames, recorded just after a frame has been decoded. See
totalInterFrameDelay
for details on how to calculate the interframe delay variance. -
lastPacketReceivedTimestamp
of type DOMHighResTimeStamp -
Represents the timestamp at which the last packet was received for this SSRC. This differs from
timestamp
, which represents the time at which the statistics were generated by the local endpoint. -
headerBytesReceived
of type unsigned long long -
Total number of RTP header and padding bytes received for this SSRC. This does not include the size of transport layer headers such as IP or UDP.
headerBytesReceived + bytesReceived
equals the number of bytes received as payload over the transport. -
packetsDiscarded
of type unsigned long 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.
-
fecPacketsReceived
of type unsigned long long -
Total number of RTP FEC packets received for this SSRC. This counter can also be incremented when receiving FEC packets in-band with media packets (e.g., with Opus).
-
fecPacketsDiscarded
of type unsigned long long -
Total number of RTP FEC packets received for this SSRC where the error correction payload was discarded by the application. This may happen 1. if all the source packets protected by the FEC packet were received or already recovered by a separate FEC packet, or 2. if the FEC packet arrived late, i.e., outside the recovery window, and the lost RTP packets have already been skipped during playout. This is a subset of
fecPacketsReceived
. -
bytesReceived
of type unsigned long long -
Total number of bytes received for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.
-
firCount
of type unsigned long -
Only exists for video. Count the total number of Full Intra Request (FIR) packets sent by this 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 -
Only exists for video. Count the total number of Picture Loss Indication (PLI) packets sent by this receiver. Calculated as defined in [RFC4585] section 6.3.1.
-
totalProcessingDelay
of type double -
It is the sum of the time, in seconds, each audio sample or video frame takes from the time the first RTP packet is received (reception timestamp) and to the time the corresponding sample or frame is decoded (decoded timestamp). At this point the audio sample or video frame is ready for playout by the MediaStreamTrack. Typically ready for playout here means after the audio sample or video frame is fully decoded by the decoder.
Given the complexities involved, the time of arrival or the reception timestamp is measured as close to the network layer as possible and the decoded timestamp is measured as soon as the complete sample or frame is decoded.
In the case of audio, several samples are received in the same RTP packet, all samples will share the same reception timestamp and different decoded timestamps. In the case of video, the frame is received over several RTP packets, in this case the earliest timestamp containing the frame is counted as the reception timestamp, and the decoded timestamp corresponds to when the complete frame is decoded.
This metric is not incremented for frames that are not decoded, i.e.
framesDropped
. The average processing delay can be calculated by dividing thetotalProcessingDelay
with theframesDecoded
for video (or povisional stats spectotalSamplesDecoded
for audio). -
nackCount
of type unsigned long -
Count the total number of Negative ACKnowledgement (NACK) packets sent by this receiver. Calculated as defined in [RFC4585] section 6.2.1.
-
estimatedPlayoutTimestamp
of type DOMHighResTimeStamp -
This is the estimated playout time of this receiver's track. The playout time is the NTP timestamp of the last playable audio sample or video frame that has a known timestamp (from an RTCP SR packet mapping RTP timestamps to NTP timestamps), extrapolated with the time elapsed since it was ready to be played out. This is the "current time" of the track in NTP clock time of the sender and can be present even if there is no audio currently playing.
This can be useful for estimating how much audio and video is out of sync for two tracks from the same source, audioTrackStats.
estimatedPlayoutTimestamp
- videoTrackStats.estimatedPlayoutTimestamp
. -
jitterBufferDelay
of type double -
The purpose of the jitter buffer is to recombine RTP packets into frames (in the case of video) and have smooth playout. The model described here assumes that the samples or frames are still compressed and have not yet been decoded. It is the sum of the time, in seconds, each audio sample or a video frame takes from the time the first packet is received by the jitter buffer (ingest timestamp) to the time it exits the jitter buffer (emit timestamp). In the case of audio, several samples belong to the same RTP packet, hence they will have the same ingest timestamp but different jitter buffer emit timestamps. In the case of video, the frame maybe is received over several RTP packets, hence the ingest timestamp is the earliest packet of the frame that entered the jitter buffer and the emit timestamp is when the whole frame exits the jitter buffer. This metric increases upon samples or frames exiting, having completed their time in the buffer (and incrementing
jitterBufferEmittedCount
). The average jitter buffer delay can be calculated by dividing thejitterBufferDelay
with thejitterBufferEmittedCount
. -
jitterBufferTargetDelay
of type double -
This value is increased by the target jitter buffer delay every time a sample is emitted by the jitter buffer. The added target is the target delay, in seconds, at the time that the sample was emitted from the jitter buffer. To get the average target delay, divide by
jitterBufferEmittedCount
. -
jitterBufferEmittedCount
of type unsigned long long -
The total number of audio samples or video frames that have come out of the jitter buffer (increasing
jitterBufferDelay
). -
jitterBufferMinimumDelay
of type double -
There are various reasons why the jitter buffer delay might be increased to a higher value, such as to achieve AV synchronization or because a playoutDelay was set on a RTCRtpReceiver. When using one of these mechanisms, it can be useful to keep track of the minimal jitter buffer delay that could have been achieved, so WebRTC clients can track the amount of additional delay that is being added.
This metric works the same way as
jitterBufferTargetDelay
, except that it is not affected by external mechanisms that increase the jitter buffer target delay, such as playoutDelay (see link above), AV sync, or any other mechanisms. This metric is purely based on the network characteristics such as jitter and packet loss, and can be seen as the minimum obtainable jitter buffer delay if no external factors would affect it. The metric is updated every timejitterBufferEmittedCount
is updated. -
totalSamplesReceived
of type unsigned long long -
Only exists for audio. The total number of samples that have been received on this RTP stream. This includes
concealedSamples
. -
concealedSamples
of type unsigned long long -
Only exists for audio. The total number of samples that are concealed samples. A concealed sample is a sample that was replaced with synthesized samples generated locally before being played out. Examples of samples that have to be concealed are samples from lost packets (reported in
packetsLost
) or samples from packets that arrive too late to be played out (reported inpacketsDiscarded
). -
silentConcealedSamples
of type unsigned long long -
Only exists for audio. The total number of concealed samples inserted that are "silent". Playing out silent samples results in silence or comfort noise. This is a subset of
concealedSamples
. -
concealmentEvents
of type unsigned long long -
Only exists for audio. The number of concealment events. This counter increases every time a concealed sample is synthesized after a non-concealed sample. That is, multiple consecutive concealed samples will increase the
concealedSamples
count multiple times but is a single concealment event. -
insertedSamplesForDeceleration
of type unsigned long long -
Only exists for audio. When playout is slowed down, this counter is increased by the difference between the number of samples received and the number of samples played out. If playout is slowed down by inserting samples, this will be the number of inserted samples.
-
removedSamplesForAcceleration
of type unsigned long long -
Only exists for audio. When playout is sped up, this counter is increased by the difference between the number of samples received and the number of samples played out. If speedup is achieved by removing samples, this will be the count of samples removed.
-
audioLevel
of type double -
Only exists for audio. Represents the audio level of the receiving track. For audio levels of tracks attached locally, see
RTCAudioSourceStats
instead.The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.
The
audioLevel
is averaged over some small interval, using the algorithm described undertotalAudioEnergy
. The interval used is implementation dependent. -
totalAudioEnergy
of type double -
Only exists for audio. Represents the audio energy of the receiving track. For audio energy of tracks attached locally, see
RTCAudioSourceStats
instead.This value MUST be computed as follows: for each audio sample that is received (and thus counted by
totalSamplesReceived
), add the sample's value divided by the highest-intensity encodable value, squared and then multiplied by the duration of the sample in seconds. In other words,duration * Math.pow(energy/maxEnergy, 2)
.This can be used to obtain a root mean square (RMS) value that uses the same units as
audioLevel
, as defined in [RFC6464]. It can be converted to these units using the formulaMath.sqrt(totalAudioEnergy/totalSamplesDuration)
. This calculation can also be performed using the differences between the values of two differentgetStats
()
calls, in order to compute the average audio level over any desired time interval. In other words, doMath.sqrt((energy2 - energy1)/(duration2 - duration1))
.For example, if a 10ms packet of audio is produced with an RMS of 0.5 (out of 1.0), this should add
0.5 * 0.5 * 0.01 = 0.0025
tototalAudioEnergy
. If another 10ms packet with an RMS of 0.1 is received, this should similarly add0.0001
tototalAudioEnergy
. Then,Math.sqrt(totalAudioEnergy/totalSamplesDuration)
becomesMath.sqrt(0.0026/0.02) = 0.36
, which is the same value that would be obtained by doing an RMS calculation over the contiguous 20ms segment of audio.If multiple audio channels are used, the audio energy of a sample refers to the highest energy of any channel.
-
totalSamplesDuration
of type double -
Only exists for audio. Represents the audio duration of the receiving track. For audio durations of tracks attached locally, see
RTCAudioSourceStats
instead.Represents the total duration in seconds of all samples that have been received (and thus counted by
totalSamplesReceived
). Can be used withtotalAudioEnergy
to compute an average audio level over different intervals. -
framesReceived
of type unsigned long -
Only exists for video. Represents the total number of complete frames received on this RTP stream. This metric is incremented when the complete frame is received.
-
decoderImplementation
of type DOMString -
Identifies the decoder 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.
7.6
RTCRemoteInboundRtpStreamStats
dictionary
The RTCRemoteInboundRtpStreamStats
dictionary represents the remote endpoint's
measurement metrics for a particular incoming RTP stream (corresponding to an outgoing
RTP stream at the sending endpoint). The timestamp reported in the statistics object is
the time at which the corresponding RTCP RR was received.
WebIDLdictionary RTCRemoteInboundRtpStreamStats
: RTCReceivedRtpStreamStats
{
DOMString localId
;
double roundTripTime
;
double totalRoundTripTime
;
double fractionLost
;
unsigned long long roundTripTimeMeasurements
;
};
Dictionary RTCRemoteInboundRtpStreamStats
Members
-
localId
of type DOMString -
The
localId
is used for looking up the localRTCOutboundRtpStreamStats
object for the same SSRC. -
roundTripTime
of type double -
Estimated round trip time for this SSRC based on the RTCP timestamps in the RTCP Receiver Report (RR) and measured in seconds. Calculated as defined in section 6.4.1. of [RFC3550]. If no RTCP Receiver Report is received with a DLSR value other than 0, the round trip time is left undefined.
-
totalRoundTripTime
of type double -
Represents the cumulative sum of all round trip time measurements in seconds since the beginning of the session. The individual round trip time is calculated based on the RTCP timestamps in the RTCP Receiver Report (RR) [RFC3550], hence undefined roundtrip times are not added. The average round trip time can be computed from
totalRoundTripTime
by dividing it byroundTripTimeMeasurements
. -
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.
-
roundTripTimeMeasurements
of type unsigned long long -
Represents the total number of RTCP RR blocks received for this SSRC that contain a valid round trip time. This counter will not increment if the
roundTripTime
is undefined.
WebIDLdictionary RTCSentRtpStreamStats
: RTCRtpStreamStats
{
unsigned long packetsSent
;
unsigned long long bytesSent
;
};
Dictionary RTCSentRtpStreamStats
Members
-
packetsSent
of type unsigned long long -
Total number of RTP packets sent for this SSRC. This includes retransmissions. Calculated as defined in [RFC3550] section 6.4.1.
-
bytesSent
of type unsigned long long -
Total number of bytes sent for this SSRC. This includes retransmissions. Calculated as defined in [RFC3550] section 6.4.1.
7.8
RTCOutboundRtpStreamStats
dictionary
The RTCOutboundRtpStreamStats
dictionary represents the measurement metrics
for the outgoing RTP stream. The timestamp reported in the statistics object is the time
at which the data was sampled.
WebIDLdictionary RTCOutboundRtpStreamStats
: RTCSentRtpStreamStats
{
DOMString mid
;
DOMString mediaSourceId
;
DOMString remoteId
;
DOMString rid
;
unsigned long long headerBytesSent
;
unsigned long long retransmittedPacketsSent
;
unsigned long long retransmittedBytesSent
;
double targetBitrate
;
unsigned long long totalEncodedBytesTarget
;
unsigned long frameWidth
;
unsigned long frameHeight
;
double framesPerSecond
;
unsigned long framesSent
;
unsigned long hugeFramesSent
;
unsigned long framesEncoded
;
unsigned long keyFramesEncoded
;
unsigned long long qpSum
;
double totalEncodeTime
;
double totalPacketSendDelay
;
RTCQualityLimitationReason
qualityLimitationReason
;
record<DOMString, double> qualityLimitationDurations
;
unsigned long qualityLimitationResolutionChanges
;
unsigned long nackCount
;
unsigned long firCount
;
unsigned long pliCount
;
DOMString encoderImplementation
;
};
Dictionary RTCOutboundRtpStreamStats
Members
-
mid
of type DOMString -
If the
RTCRtpTransceiver
owning this stream has amid
value that is not null, this is that value, otherwise this member is not present. -
mediaSourceId
of type DOMString -
The identifier of the stats object representing the track currently attached to the sender of this stream, an
RTCMediaSourceStats
. -
remoteId
of type DOMString -
The
remoteId
is used for looking up the remoteRTCRemoteInboundRtpStreamStats
object for the same SSRC. -
rid
of type DOMString -
Exposes the
rid
encoding parameter of this RTP stream if it has been set, otherwise it is undefined. If set this value will be present regardless if the RID RTP header extension has been negotiated. -
headerBytesSent
of type unsigned long long -
Total number of RTP header and padding bytes sent for this SSRC. This does not include the size of transport layer headers such as IP or UDP.
headerBytesSent + bytesSent
equals the number of bytes sent as payload over the transport. -
retransmittedPacketsSent
of type unsigned long long -
The total number of packets that were retransmitted for this SSRC. This is a subset of
packetsSent
. If RTX is not negotiated, retransmitted packets are sent over thisssrc
. If RTX was negotiated, retransmitted packets are sent over a separate ssrc but is still accounted for here. -
retransmittedBytesSent
of type unsigned long long -
The total number of bytes that were retransmitted for this SSRC, only including payload bytes. This is a subset of
bytesSent
. If RTX is not negotiated, retransmitted bytes are sent over thisssrc
. If RTX was negotiated, retransmitted bytes are sent over a separate ssrc but is still accounted for here. -
targetBitrate
of type double -
Reflects the current encoder target in bits per second. The target is an instantanous value reflecting the encoder's settings, but the resulting payload bytes sent per second, excluding retransmissions, SHOULD closely correlate to the target. See also
bytesSent
andretransmittedBytesSent
. ThetargetBitrate
is defined in the same way as the Transport Independent Application Specific (TIAS) bitrate [RFC3890]. -
totalEncodedBytesTarget
of type unsigned long long -
This value is increased by the target frame size in bytes every time a frame has been encoded. The actual frame size may be bigger or smaller than this number. This value goes up every time
framesEncoded
goes up. -
frameWidth
of type unsigned long -
Only exists for video. Represents the width of the last encoded frame. The resolution of the encoded frame may be lower than the media source (see
RTCVideoSourceStats
.width
). Before the first frame is encoded this member does not exist. -
frameHeight
of type unsigned long -
Only exists for video. Represents the height of the last encoded frame. The resolution of the encoded frame may be lower than the media source (see
RTCVideoSourceStats
.height
). Before the first frame is encoded this member does not exist. -
framesPerSecond
of type double -
Only exists for video. The number of encoded frames during the last second. This may be lower than the media source frame rate (see
RTCVideoSourceStats
.framesPerSecond
). -
framesSent
of type unsigned long -
Only exists for video. Represents the total number of frames sent on this RTP stream.
-
hugeFramesSent
of type unsigned long -
Only exists for video. Represents the total number of huge frames sent by this RTP stream. Huge frames, by definition, are frames that have an encoded size at least 2.5 times the average size of the frames. The average size of the frames is defined as the target bitrate per second divided by the target FPS at the time the frame was encoded. These are usually complex to encode frames with a lot of changes in the picture. This can be used to estimate, e.g slide changes in the streamed presentation.
The multiplier of 2.5 is choosen from analyzing encoded frame sizes for a sample presentation using WebRTC standalone implementation. 2.5 is a reasonably large multiplier which still caused all slide change events to be identified as a huge frames. It, however, produced 1.4% of false positive slide change detections which is deemed reasonable.
-
framesEncoded
of type unsigned long -
Only exists for video. It represents the total number of frames successfully encoded for this RTP media stream.
-
keyFramesEncoded
of type unsigned long -
Only exists for video. It represents the total number of key frames, such as key frames in VP8 [RFC6386] or IDR-frames in H.264 [RFC6184], successfully encoded for this RTP media stream. This is a subset of
framesEncoded
.framesEncoded - keyFramesEncoded
gives you the number of delta frames encoded. -
qpSum
of type unsigned long long -
Only exists for video. The sum of the QP values of frames encoded by this sender. The count of frames is in
framesEncoded
.The definition of QP value depends on the codec; for VP8, the QP value is the value carried in the frame header as the syntax element
y_ac_qi
, and defined in [RFC6386] section 19.2. Its range is 0..127.Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.
-
totalEncodeTime
of type double -
Total number of seconds that has been spent encoding the
framesEncoded
frames of this stream. The average encode time can be calculated by dividing this value withframesEncoded
. The time it takes to encode one frame is the time passed between feeding the encoder a frame and the encoder returning encoded data for that frame. This does not include any additional time it may take to packetize the resulting data. -
totalPacketSendDelay
of type double -
The total number of seconds that packets have spent buffered locally before being transmitted onto the network. The time is measured from when a packet is emitted from the RTP packetizer until it is handed over to the OS network socket. This measurement is added to
totalPacketSendDelay
whenpacketsSent
is incremented. -
qualityLimitationReason
of typeRTCQualityLimitationReason
-
Only exists for video. The current reason for limiting the resolution and/or framerate, or "
none
" if not limited.The implementation reports the most limiting factor. If the implementation is not able to determine the most limiting factor because multiple may exist, the reasons MUST be reported in the following order of priority: "bandwidth", "cpu", "other".
NoteThe consumption of CPU and bandwidth resources is interdependent and difficult to estimate, making it hard to determine what the "most limiting factor" is. The priority order promoted here is based on the heuristic that "bandwidth" is generally more varying and thus a more likely and more useful signal than "cpu".
-
qualityLimitationDurations
of type record<DOMString, double> -
Only exists for video. A record of the total time, in seconds, that this stream has spent in each quality limitation state. The record includes a mapping for all
RTCQualityLimitationReason
types, including "none
".The sum of all entries minus
qualityLimitationDurations
["none
"] gives the total time that the stream has been limited. -
qualityLimitationResolutionChanges
of type unsigned long -
Only exists for video. The number of times that the resolution has changed because we are quality limited (
qualityLimitationReason
has a value other than "none
"). The counter is initially zero and increases when the resolution goes up or down. For example, if a 720p track is sent as 480p for some time and then recovers to 720p,qualityLimitationResolutionChanges
will have the value 2. -
nackCount
of type unsigned long -
Count the total number of Negative ACKnowledgement (NACK) packets received by this sender. Calculated as defined in [RFC4585] section 6.2.1.
-
firCount
of type unsigned long -
Only exists for video. Count the total number of Full Intra Request (FIR) packets received by this sender. 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 -
Only exists for video. Count the total number of Picture Loss Indication (PLI) packets received by this sender. Calculated as defined in [RFC4585] section 6.3.1.
-
encoderImplementation
of type DOMString -
Identifies the encoder 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.
WebIDLenum RTCQualityLimitationReason
{
"none
",
"cpu
",
"bandwidth
",
"other
",
};
Enum value | Description |
---|---|
none
|
The resolution and/or framerate is not limited. |
cpu
|
The resolution and/or framerate is primarily limited due to CPU load. |
bandwidth
|
The resolution and/or framerate is primarily limited due to congestion cues during bandwidth estimation. Typical, congestion control algorithms use inter-arrival time, round-trip time, packet or other congestion cues to perform bandwidth estimation. |
other
|
The resolution and/or framerate is primarily limited for a reason other than the above. |
7.10
RTCRemoteOutboundRtpStreamStats
dictionary
The RTCRemoteOutboundRtpStreamStats
dictionary represents the remote
endpoint's measurement metrics for its outgoing RTP stream (corresponding to an outgoing
RTP stream at the sending endpoint). The timestamp reported in the statistics object is
the time at which the corresponding RTCP SR was received.
WebIDLdictionary RTCRemoteOutboundRtpStreamStats
: RTCSentRtpStreamStats
{
DOMString localId
;
DOMHighResTimeStamp remoteTimestamp
;
unsigned long long reportsSent
;
double roundTripTime
;
double totalRoundTripTime
;
unsigned long long roundTripTimeMeasurements
;
};
Dictionary RTCRemoteOutboundRtpStreamStats
Members
-
localId
of type DOMString -
The
localId
is used for looking up the localRTCInboundRtpStreamStats
object for the same SSRC. -
remoteTimestamp
of type DOMHighResTimeStamp -
remoteTimestamp
, of typeDOMHighResTimeStamp
[HIGHRES-TIME], represents the remote timestamp at which these statistics were sent by the remote endpoint. This differs fromtimestamp
, which represents the time at which the statistics were generated or received by the local endpoint. TheremoteTimestamp
, if present, is derived from the NTP timestamp in an RTCP Sender Report (SR) block, which reflects the remote endpoint's clock. That clock may not be synchronized with the local clock. -
reportsSent
of type unsigned long long -
Represents the total number of RTCP SR blocks sent for this SSRC.
-
roundTripTime
of type double -
Estimated round trip time for this SSRC based on the latest RTCP Sender Report (SR) that contains a DLRR report block as defined in [RFC3611]. The Calculation of the round trip time is defined in section 4.5. of [RFC3611]. If the latest SR does not contain the DLRR report block, or if the last RR timestamp in the DLRR report block is zero, or if the delay since last RR value in the DLRR report block is zero, the round trip time is left undefined.
-
totalRoundTripTime
of type double -
Represents the cumulative sum of all round trip time measurements in seconds since the beginning of the session. The individual round trip time is calculated based on the DLRR report block in the RTCP Sender Report (SR) [RFC3611], hence undefined roundtrip times are not added. The average round trip time can be computed from
totalRoundTripTime
by dividing it byroundTripTimeMeasurements
. -
roundTripTimeMeasurements
of type unsigned long long -
Represents the total number of RTCP Sender Report (SR) blocks received for this SSRC that can derive a valid round trip time according to [RFC3611]. This counter will not increment if the
roundTripTime
is undefined.
7.11
RTCMediaSourceStats
dictionary
The RTCMediaSourceStats
dictionary represents a track that is currently
attached to one or more senders. It contains information about media sources such as
frame rate and resolution prior to encoding. This is the media passed from the
MediaStreamTrack
to the RTCRtpSender
s. This is in contrast to
RTCOutboundRtpStreamStats
whose members describe metrics as measured after
the encoding step. For example, a track may be captured from a high-resolution camera,
its frames downscaled due to track constraints and then further downscaled by the
encoders due to CPU and network conditions. This dictionary reflects the video frames or
audio samples passed out from the track - after track constraints have been applied but
before any encoding or further donwsampling occurs.
Media source objects are of either subdictionary RTCAudioSourceStats
or
RTCVideoSourceStats
. The type
is the same
("media-source
") but kind
is different ("audio"
or
"video"
) depending on the kind of track.
The media source stats objects are created when a track is attached to any
RTCRtpSender
and may subsequently be attached to multiple senders during its
life. The life of this object ends when the track is no longer attached to any sender of
the same RTCPeerConnection
. If a track whose media source object ended is
attached again this results in a new media source stats object whose counters (such as
number of frames) are reset.
WebIDLdictionary RTCMediaSourceStats
: RTCStats
{
required DOMString trackIdentifier
;
required DOMString kind
;
};
Dictionary RTCMediaSourceStats
Members
-
trackIdentifier
of type DOMString -
The value of the
MediaStreamTrack
'sid
attribute. -
kind
of type DOMString -
The value of the
MediaStreamTrack
'skind
attribute. This is either"audio"
or"video"
. If it is"audio"
then this stats object is of typeRTCAudioSourceStats
. If it is"video"
then this stats object is of typeRTCVideoSourceStats
.
7.12
RTCAudioSourceStats
dictionary
The RTCAudioSourceStats
dictionary represents an audio track that is attached
to one or more senders. It is an RTCMediaSourceStats
whose
kind
is "audio"
.
WebIDLdictionary RTCAudioSourceStats
: RTCMediaSourceStats
{
double audioLevel
;
double totalAudioEnergy
;
double totalSamplesDuration
;
double echoReturnLoss
;
double echoReturnLossEnhancement
;
};
Dictionary RTCAudioSourceStats
Members
-
audioLevel
of type double -
Represents the audio level of the media source. For audio levels of remotely sourced tracks, see
RTCInboundRtpStreamStats
instead.The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.
The
audioLevel
is averaged over some small interval, using the algorithm described undertotalAudioEnergy
. The interval used is implementation dependent. -
totalAudioEnergy
of type double -
Represents the audio energy of the media source. For audio energy of remotely sourced tracks, see
RTCInboundRtpStreamStats
instead.This value MUST be computed as follows: for each audio sample produced by the media source during the lifetime of this stats object, add the sample's value divided by the highest-intensity encodable value, squared and then multiplied by the duration of the sample in seconds. In other words,
duration * Math.pow(energy/maxEnergy, 2)
.This can be used to obtain a root mean square (RMS) value that uses the same units as
audioLevel
, as defined in [RFC6464]. It can be converted to these units using the formulaMath.sqrt(totalAudioEnergy/totalSamplesDuration)
. This calculation can also be performed using the differences between the values of two differentgetStats
()
calls, in order to compute the average audio level over any desired time interval. In other words, doMath.sqrt((energy2 - energy1)/(duration2 - duration1))
.For example, if a 10ms packet of audio is produced with an RMS of 0.5 (out of 1.0), this should add
0.5 * 0.5 * 0.01 = 0.0025
tototalAudioEnergy
. If another 10ms packet with an RMS of 0.1 is received, this should similarly add0.0001
tototalAudioEnergy
. Then,Math.sqrt(totalAudioEnergy/totalSamplesDuration)
becomesMath.sqrt(0.0026/0.02) = 0.36
, which is the same value that would be obtained by doing an RMS calculation over the contiguous 20ms segment of audio.If multiple audio channels are used, the audio energy of a sample refers to the highest energy of any channel.
-
totalSamplesDuration
of type double -
Represents the audio duration of the media source. For audio durations of remotely sourced tracks, see
RTCInboundRtpStreamStats
instead.Represents the total duration in seconds of all samples that have been produced by this source for the lifetime of this stats object. Can be used with
totalAudioEnergy
to compute an average audio level over different intervals. -
echoReturnLoss
of type double -
Only exists when the
MediaStreamTrack
is sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.14.If multiple audio channels are used, the channel of the least audio energy is considered for any sample.
-
echoReturnLossEnhancement
of type double -
Only exists when the
MediaStreamTrack
is sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.15.If multiple audio channels are used, the channel of the least audio energy is considered for any sample.
7.13
RTCVideoSourceStats
dictionary
The RTCVideoSourceStats
dictionary represents a video track that is attached
to one or more senders. It is an RTCMediaSourceStats
whose
kind
is "video"
.
WebIDLdictionary RTCVideoSourceStats
: RTCMediaSourceStats
{
unsigned long width
;
unsigned long height
;
unsigned long frames
;
double framesPerSecond
;
};
Dictionary RTCVideoSourceStats
Members
-
width
of type unsigned long -
The width, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not exist.
-
height
of type unsigned long -
The height, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not exist.
-
frames
of type unsigned long -
The total number of frames originating from this source.
-
framesPerSecond
of type double -
The number of frames originating from this source, measured during the last second. For the first second of this object's lifetime this member does not exist.
WebIDLdictionary RTCPeerConnectionStats
: RTCStats
{
unsigned long dataChannelsOpened
;
unsigned long dataChannelsClosed
;
};
Dictionary RTCPeerConnectionStats
Members
-
dataChannelsOpened
of type unsigned long -
Represents the number of unique
RTCDataChannel
s that have entered the "open
" state during their lifetime. -
dataChannelsClosed
of type unsigned long -
Represents the number of unique
RTCDataChannel
s that have left the "open
" state during their lifetime (due to being closed by either end or the underlying transport being closed).RTCDataChannel
s that transition from "connecting
" to "closing
" or "closed
" without ever being "open
" are not counted in this number.
The total number of open data channels at any time can be calculated as
dataChannelsOpened
- dataChannelsClosed
. This number is always positive.
WebIDLdictionary RTCDataChannelStats
: RTCStats
{
DOMString label
;
DOMString protocol
;
unsigned short dataChannelIdentifier
;
required RTCDataChannelState state
;
unsigned long messagesSent
;
unsigned long long bytesSent
;
unsigned long messagesReceived
;
unsigned long long bytesReceived
;
};
Dictionary RTCDataChannelStats
Members
-
label
of type DOMString -
The
label
value of theRTCDataChannel
object. -
protocol
of type DOMString -
The
protocol
value of theRTCDataChannel
object. -
dataChannelIdentifier
of type unsigned short -
The
id
attribute of theRTCDataChannel
object. -
state
of typeRTCDataChannelState
-
The
readyState
value of theRTCDataChannel
object. -
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.
An RTCTransportStats
object represents the stats corresponding to an
RTCDtlsTransport
and its underlying
RTCIceTransport
. When bundling is used, a single
transport will be used for all MediaStreamTrack
s in the bundle group.
If bundling is not used, different MediaStreamTrack
will use
different transports. Bundling is described in [WEBRTC].
WebIDLdictionary RTCTransportStats
: RTCStats
{
unsigned long long packetsSent
;
unsigned long long packetsReceived
;
unsigned long long bytesSent
;
unsigned long long bytesReceived
;
RTCIceRole iceRole
;
DOMString iceLocalUsernameFragment
;
required RTCDtlsTransportState dtlsState
;
RTCIceTransportState iceState
;
DOMString selectedCandidatePairId
;
DOMString localCertificateId
;
DOMString remoteCertificateId
;
DOMString tlsVersion
;
DOMString dtlsCipher
;
RTCDtlsRole
dtlsRole
;
DOMString srtpCipher
;
unsigned long selectedCandidatePairChanges
;
};
Dictionary RTCTransportStats
Members
-
packetsSent
of type unsigned long long -
Represents the total number of packets sent over this transport.
-
packetsReceived
of type unsigned long long -
Represents the total number of packets received on this transport.
-
bytesSent
of type unsigned long long -
Represents the total number of payload bytes sent on this
RTCIceTransport
, i.e., not including headers, padding or ICE connectivity checks. -
bytesReceived
of type unsigned long long -
Represents the total number of payload bytes received on this
RTCIceTransport
, i.e., not including headers, padding or ICE connectivity checks. -
iceRole
of typeRTCIceRole
-
Set to the current value of the
role
attribute of the underlyingRTCDtlsTransport
.iceTransport
. -
iceLocalUsernameFragment
of type DOMString -
Set to the current value of the local username fragment used in message validation procedures [RFC5245] for this
RTCIceTransport
. It may be updated on setLocalDescription() and on ICE restart. -
dtlsState
of typeRTCDtlsTransportState
-
Set to the current value of the
state
attribute of the underlyingRTCDtlsTransport
. -
iceState
of typeRTCIceTransportState
-
Set to the current value of the
state
attribute of the underlyingRTCIceTransport
. -
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.
-
tlsVersion
of type DOMString -
For components where DTLS is negotiated, the TLS version agreed. Only exists after DTLS negotiation is complete.
The value comes from
ServerHello.supported_versions
if present, otherwise fromServerHello.version
. It is represented as four upper case hexadecimal digits, representing the two bytes of the version. -
dtlsCipher
of type DOMString -
Descriptive name of the cipher suite used for the DTLS transport, as defined in the "Description" column of the IANA cipher suite registry [IANA-TLS-CIPHERS].
-
dtlsRole
of type RTCDtlsRole -
"
client
" or "server
" depending on the DTLS role. "unknown
" before the DTLS negotiation starts. -
srtpCipher
of type DOMString -
Descriptive name of the protection profile used for the SRTP transport, as defined in the "Profile" column of the IANA DTLS-SRTP protection profile registry [IANA-DTLS-SRTP] and described further in [RFC5764].
-
selectedCandidatePairChanges
of type unsigned long -
The number of times that the selected candidate pair of this transport has changed. Going from not having a selected candidate pair to having a selected candidate pair, or the other way around, also increases this counter. It is initially zero and becomes one when an initial candidate pair is selected.
WebIDLenum RTCDtlsRole
{
"client
",
"server
",
"unknown
",
};
Enum value | Description |
---|---|
client
|
The RTCPeerConnection is acting as a DTLS client as defined in [RFC6347]. |
server
|
The RTCPeerConnection is acting as a DTLS server as defined in [RFC6347]. |
unknown
|
The DTLS role of the RTCPeerConnection has not been determined yet. |
RTCIceCandidateStats
reflects the properties of a candidate
in
Section 15.1 of [RFC5245]. It corresponds to a RTCIceCandidate
object.
WebIDLdictionary RTCIceCandidateStats
: RTCStats
{
required DOMString transportId
;
DOMString? address
;
long port
;
DOMString protocol
;
required RTCIceCandidateType candidateType
;
long priority
;
DOMString url
;
DOMString relayProtocol
;
};
Dictionary RTCIceCandidateStats
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. -
address
of type DOMString -
It is the address of the candidate, allowing for IPv4 addresses, IPv6 addresses, and fully qualified domain names (FQDNs). See [RFC5245] section 15.1 for details.
The user agent should make sure that only remote candidate addresses that the web application has configured on the corresponding
RTCPeerConnection
are exposed; This is especially important for peer reflexive remote candidates. By default, the user agent MUST leave theaddress
member asnull
in theRTCIceCandidateStats
dictionary of any remote candidate. Once aRTCPeerConnection
instance learns on an address by the web application usingaddIceCandidate
()
, the user agent can expose the 'address' member value in any remoteRTCIceCandidateStats
dictionary of the correspondingRTCPeerConnection
that matches the newly learnt address. -
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 typeRTCIceCandidateType
-
This enumeration is defined in [WEBRTC].
-
priority
of type long -
Calculated as defined in [RFC5245] section 15.1.
-
url
of type DOMString -
For local candidates this is the URL of the ICE server from which the candidate was obtained. It is the same as the
url
surfaced in theRTCPeerConnectionIceEvent
.For remote candidates, this property is not present.
-
relayProtocol
of type DOMString -
It is the protocol used by the endpoint to communicate with the TURN server. This is only present for local candidates. Valid values are
"udp"
,"tcp"
, or"tls"
.
WebIDLdictionary RTCIceCandidatePairStats
: RTCStats
{
required DOMString transportId
;
required DOMString localCandidateId
;
required DOMString remoteCandidateId
;
required RTCStatsIceCandidatePairState
state
;
boolean nominated
;
unsigned long long packetsSent
;
unsigned long long packetsReceived
;
unsigned long long bytesSent
;
unsigned long long bytesReceived
;
DOMHighResTimeStamp lastPacketSentTimestamp
;
DOMHighResTimeStamp lastPacketReceivedTimestamp
;
double totalRoundTripTime
;
double currentRoundTripTime
;
double availableOutgoingBitrate
;
double availableIncomingBitrate
;
unsigned long long requestsReceived
;
unsigned long long requestsSent
;
unsigned long long responsesReceived
;
unsigned long long responsesSent
;
unsigned long long consentRequestsSent
;
unsigned long packetsDiscardedOnSend
;
unsigned long long bytesDiscardedOnSend
;
};
Dictionary 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
RTCIceCandidateStats
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
RTCIceCandidateStats
for the remote candidate associated with this candidate pair. -
state
of typeRTCStatsIceCandidatePairState
-
Represents the state of the checklist for the local and remote candidates in a pair.
-
nominated
of type boolean -
Related to updating the nominated flag described in Section 7.1.3.2.4 of [RFC5245].
-
packetsSent
of type unsigned long long -
Represents the total number of packets sent on this candidate pair.
-
packetsReceived
of type unsigned long long -
Represents the total number of packets received on this candidate pair.
-
bytesSent
of type unsigned long long -
Represents the total number of payload bytes sent on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.
-
bytesReceived
of type unsigned long long -
Represents the total number of payload bytes received on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.
-
lastPacketSentTimestamp
of type DOMHighResTimeStamp -
Represents the timestamp at which the last packet was sent on this particular candidate pair, excluding STUN packets.
-
lastPacketReceivedTimestamp
of type DOMHighResTimeStamp -
Represents the timestamp at which the last packet was received on this particular candidate pair, excluding STUN packets.
-
totalRoundTripTime
of type double -
Represents the sum of all round trip time measurements in seconds since the beginning of the session, based on STUN connectivity check [STUN-PATH-CHAR] responses (responsesReceived), including those that reply to requests that are sent in order to verify consent [RFC7675]. The average round trip time can be computed from
totalRoundTripTime
by dividing it byresponsesReceived
. -
currentRoundTripTime
of type double -
Represents the latest round trip time measured in seconds, computed from both STUN connectivity checks [STUN-PATH-CHAR], including those that are sent for consent verification [RFC7675].
-
availableOutgoingBitrate
of type double -
It is calculated by the underlying congestion control by combining the available bitrate for all the outgoing RTP streams using this candidate pair. 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.
Implementations that do not calculate a sender-side estimate MUST leave this undefined. Additionally, the value MUST be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets sent at
lastPacketSentTimestamp
, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined. -
availableIncomingBitrate
of type double -
It is calculated by the underlying congestion control by combining the available bitrate for all the incoming RTP streams using this candidate pair. 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.
Implementations that do not calculate a receiver-side estimate MUST leave this undefined. Additionally, the value should be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets received at
lastPacketReceivedTimestamp
, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined. -
requestsReceived
of type unsigned long long -
Represents the total number of connectivity check requests received (including retransmissions). It is impossible for the receiver to tell whether the request was sent in order to check connectivity or check consent, so all connectivity checks requests are counted here.
-
requestsSent
of type unsigned long long -
Represents the total number of connectivity check requests sent (not including retransmissions).
-
responsesReceived
of type unsigned long long -
Represents the total number of connectivity check responses received.
-
responsesSent
of type unsigned long long -
Represents the total number of connectivity check responses sent. Since we cannot distinguish connectivity check requests and consent requests, all responses are counted.
-
consentRequestsSent
of type unsigned long long -
Represents the total number of consent requests sent.
-
packetsDiscardedOnSend
of type unsigned long -
Total number of packets for this candidate pair that have been discarded due to socket errors, i.e. a socket error occurred when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.
-
bytesDiscardedOnSend
of type unsigned long long -
Total number of bytes for this candidate pair that have been discarded due to socket errors, i.e. a socket error occurred when handing the packets containing the bytes to the socket. This might happen due to various reasons, including full buffer or no available memory. Calculated as defined in [RFC3550] section 6.4.1.
WebIDLenum RTCStatsIceCandidatePairState
{
"frozen
",
"waiting
",
"in-progress
",
"failed
",
"succeeded
"
};
Enum value | Description |
---|---|
frozen
|
Defined in Section 5.7.4 of [RFC5245]. |
waiting
|
Defined in Section 5.7.4 of [RFC5245]. |
in-progress
|
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]. |
WebIDLdictionary RTCCertificateStats
: RTCStats
{
required DOMString fingerprint
;
required DOMString fingerprintAlgorithm
;
required DOMString base64Certificate
;
DOMString issuerCertificateId
;
};
Dictionary RTCCertificateStats
Members
-
fingerprint
of type DOMString -
The fingerprint of the certificate. Only use the fingerprint value as defined in Section 5 of [RFC4572].
-
fingerprintAlgorithm
of type DOMString -
The hash function used to compute the certificate fingerprint. For instance,
"sha-256"
. -
base64Certificate
of type DOMString -
The DER-encoded base-64 representation of the certificate.
-
issuerCertificateId
of type DOMString -
The
issuerCertificateId
refers to the stats object that contains the next certificate in the certificate chain. If the current certificate is at the end of the chain (i.e. a self-signed certificate), this will not be set.
This section is non-normative.
WebIDLdictionary RTCMediaStreamStats
: RTCStats
{
DOMString streamIdentifier
;
sequence<DOMString> trackIds
;
};
This entire dictionary was made obsolete in September, 2019 due to
sender, receiver and transceiver stats objects being a better fit to
describe the modern RTCPeerConnection
model (Unified Plan).
-
streamIdentifier
of type DOMString -
stream.id
property -
trackIds
of type sequence<DOMString> -
This is the
id
of the stats object, not thetrack.id
.
Obsolete RTCCodecStats
members
WebIDLpartial dictionary RTCCodecStats
{
DOMString implementation
;
};
-
implementation
of type DOMString -
This was moved to
RTCInboundRtpStreamStats
.RTCInboundRtpStreamStats
/decoderImplementation}} andRTCOutboundRtpStreamStats
.encoderImplementation
in August 2019.
Obsolete RTCIceCandidateStats
members
WebIDLpartial dictionary RTCIceCandidateStats
{
boolean deleted
= false;
boolean isRemote
;
};
-
deleted
of type boolean -
This field was obsoleted because if the ICE candidate is deleted it no longer appears in
getStats
()
. -
isRemote
of type boolean -
false
indicates that this represents a local candidate;true
indicates that this represents a remote candidate.
Obsolete RTCIceCandidatePairStats
members
WebIDLpartial dictionary RTCIceCandidatePairStats
{
double totalRtt
;
double currentRtt
;
unsigned long long priority
;
};
-
totalRtt
-
This field got renamed to
totalRoundTripTime
in Dec 2016. -
currentRtt
-
This field got renamed to
currentRoundTripTime
in Dec 2016. -
priority
-
This field got removed in Feb 2018, as it cannot be represented in 53 bits. It can be recalculated if needed as defined in [RFC5245] section 5.7.2.
Obsolete RTCRtpStreamStats
members
WebIDLpartial dictionary RTCRtpStreamStats
{
DOMString mediaType
;
};
-
mediaType
of type DOMString -
This field got renamed to
kind
in Feb 2018.
Obsolete RTCInboundRtpStreamStats
members
WebIDLpartial dictionary RTCInboundRtpStreamStats
{
DOMString trackId
;
double fractionLost
;
};
-
trackId
of type DOMString -
The identifier of the stats object representing the receiving track, an
RTCMediaStreamTrackStats
.This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.
-
fractionLost
of type double -
This field was moved to
RTCRemoteInboundRtpStreamStats
in December 2017.
Obsolete RTCOutboundRtpStreamStats
members
WebIDLpartial dictionary RTCOutboundRtpStreamStats
{
DOMString trackId
;
};
-
trackId
of type DOMString -
The identifier of the stats object representing the current track attachment to the sender of this stream, an
RTCMediaStreamTrackStats
.This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.
Obsolete RTCMediaStreamTrackStats
members
WebIDLdictionary RTCMediaStreamTrackStats
{
DOMString trackIdentifier
;
boolean ended
;
required DOMString kind
;
RTCPriorityType priority
;
boolean remoteSource
;
DOMHighResTimeStamp estimatedPlayoutTimestamp
;
double jitterBufferDelay
;
unsigned long long jitterBufferEmittedCount
;
// Audio-only, send and receive side.
double audioLevel
;
double totalAudioEnergy
;
double totalSamplesDuration
;
// Audio-only, send side.
double echoReturnLoss
;
double echoReturnLossEnhancement
;
// Audio-only, receive side.
unsigned long long totalSamplesReceived
;
unsigned long long concealedSamples
;
unsigned long long silentConcealedSamples
;
unsigned long long concealmentEvents
;
unsigned long long insertedSamplesForDeceleration
;
unsigned long long removedSamplesForAcceleration
;
// Video-only, send and receive side.
unsigned long frameWidth
;
unsigned long frameHeight
;
double framesPerSecond
;
// Video-only, send side.
unsigned long keyFramesSent
;
unsigned long framesCaptured
;
unsigned long framesSent
;
unsigned long hugeFramesSent
;
// Video-only, receive side.
unsigned long keyFramesReceived
;
unsigned long framesReceived
;
unsigned long framesDecoded
;
unsigned long framesDropped
;
};
-
trackIdentifier
of type DOMString -
Represents the
id
property of the track. -
ended
of type boolean -
Reflects the
ended
state of the track. -
kind
of type DOMString -
Either "
audio
" or "video
". This reflects thekind
attribute of theMediaStreamTrack
, see [GETUSERMEDIA]. -
priority
of typeRTCPriorityType
-
Indicates the priority that has been set for the track. It is defined in [RTCWEB-TRANSPORT], Section 4, but was removed from [WEBRTC] due to lack of implementation and moved to [WEBRTC-PRIORITY], with some changes to its definition.
-
remoteSource
of type boolean -
Only applicable for "
track
" stats.false
if the track attachment is on anRTCRtpSender
,true
if the track attachment is on anRTCRtpReceiver
.With "track" stats made obsolete, and this information being available elsewhere, this metric was made obsolete in April, 2020.
-
estimatedPlayoutTimestamp
of type DOMHighResTimeStamp -
This was moved to
RTCInboundRtpStreamStats
in August 2019. -
jitterBufferDelay
of type double -
This was moved to
RTCInboundRtpStreamStats
in August 2019. -
jitterBufferEmittedCount
of type unsigned long long -
This was moved to
RTCInboundRtpStreamStats
in August 2019. -
audioLevel
of type double -
Audio-only. This field was moved to
RTCAudioSourceStats
andRTCInboundRtpStreamStats
in June 2019. -
totalAudioEnergy
of type double -
Audio-only. This field was moved to
RTCAudioSourceStats
andRTCInboundRtpStreamStats
in June 2019. -
totalSamplesDuration
of type double -
Audio-only. This field was moved to
RTCAudioSourceStats
andRTCInboundRtpStreamStats
in June 2019. -
echoReturnLoss
of type double -
Audio-only. This was moved to
RTCAudioSourceStats
in August 2019. -
echoReturnLossEnhancement
of type double -
Audio-only. This was moved to
RTCAudioSourceStats
in August 2019. -
totalSamplesReceived
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
concealedSamples
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
silentConcealedSamples
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
concealmentEvents
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
insertedSamplesForDeceleration
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
removedSamplesForAcceleration
of type unsigned long long -
Audio-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
frameWidth
of type unsigned long -
Video-only. This was moved to
RTCOutboundRtpStreamStats
andRTCInboundRtpStreamStats
in August 2019. -
frameHeight
of type unsigned long -
Video-only. This was moved to
RTCOutboundRtpStreamStats
andRTCInboundRtpStreamStats
in August 2019. -
framesPerSecond
of type double -
Video-only. For the sending case, this was replaced by
RTCVideoSourceStats
.framesPerSecond
in May 2019 representing the frame rate of the track. For the receiving case, this was moved toRTCInboundRtpStreamStats
in August 2019 representing the decoding frame rate. In August 2019,framesPerSecond
was also added toRTCOutboundRtpStreamStats
, representing the encoding frame rate (which may be lower than the source frame rate). -
keyFramesSent
of type unsigned long -
Video-only. This field was replaced by
keyFramesEncoded
inRTCOutboundRtpStreamStats
in June 2019. There were no known implementations supporting the old field at the time of the change. -
framesCaptured
of type unsigned long -
Video-only. This was replaced by
RTCVideoSourceStats
.frames in May 2019. -
framesSent
of type unsigned long -
Video-only. This was moved to
RTCOutboundRtpStreamStats
in August 2019. -
hugeFramesSent
of type unsigned long -
Video-only. This was moved to
RTCOutboundRtpStreamStats
in August 2019. -
keyFramesReceived
of type unsigned long -
Video-only. This field was replaced by
keyFramesDecoded
inRTCInboundRtpStreamStats
in June 2019. There were no known implementations supporting the old field at the time of the change. -
framesReceived
of type unsigned long -
Video-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
framesDecoded
of type unsigned long -
Video-only. This was moved to
RTCInboundRtpStreamStats
in August 2019. -
framesDropped
of type unsigned long -
Video-only. This was moved to
RTCInboundRtpStreamStats
in August 2019.
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 sender = pc.getSenders()[0];
sender.getStats().then(function (report) {
baselineReport = report;
})
.then(function() {
return new Promise(function(resolve) {
setTimeout(resolve, aBit); // ... wait a bit
});
})
.then(function() {
return sender.getStats();
})
.then(function (report) {
currentReport = report;
processStats();
})
.catch(function (error) {
console.log(error.toString());
});
function processStats() {
// compare the elements from the current report with the baseline
for (let now of currentReport.values()) {
if (now.type != "outbound-rtp")
continue;
// get the corresponding stats from the baseline report
let base = baselineReport.get(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 intervalFractionLoss is > 0.3, we've probably found the culprit
var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
}
});
}
The data exposed by WebRTC Statistics include most of the media and network data also exposed by [GETUSERMEDIA] and [WEBRTC] - as such, all the privacy and security considerations of these specifications related to data exposure apply as well to this specifciation.
In addition, the properties exposed by RTCReceivedRtpStreamStats
,
RTCRemoteInboundRtpStreamStats
, RTCSentRtpStreamStats
,
RTCOutboundRtpStreamStats
, RTCRemoteOutboundRtpStreamStats
,
RTCIceCandidatePairStats
, RTCTransportStats
expose network-layer data not
currently available to the JavaScript layer.
Beyond the risks associated with revealing IP addresses as discussed in the WebRTC 1.0 specification, some combination of the network properties uniquely exposed by this specification can be correlated with location.
For instance, the round-trip time exposed in RTCRemoteInboundRtpStreamStats
can give
some coarse indication on how far aparts the peers are located, and thus, if one of the
peer's location is known, this may reveal information about the other peer.
When applied to isolated streams, media metrics may allow an application to infer some
characteristics of the isolated stream, such as if anyone is speaking (by watching the
audioLevel
statistic).
The following stats are deemed to be sensitive, and MUST NOT be reported for an isolated media stream:
The editors wish to thank the Working Group chairs, Stefan Håkansson, and the Team Contact, Dominique Hazaël-Massieux, for their support. The editors would like to thank Bernard Aboba, Taylor Brandstetter, Henrik Boström, Jan-Ivar Bruaroey, Karthik Budigere, Cullen Jennings, and Lennart Schulte for their contributions to this specification.
- [API-DESIGN-PRINCIPLES]
- Web Platform Design Principles. Sangwhan Moon. W3C. 16 December 2021. W3C Working Group Note. URL: https://www.w3.org/TR/design-principles/
- [ECHO]
- Digital network echo cancellers. ITU-T G.168. ITU-T. Standard. URL: https://www.itu.int/rec/T-REC-G.168/en
- [GETUSERMEDIA]
- Media Capture and Streams. Cullen Jennings; Bernard Aboba; Jan-Ivar Bruaroey; Henrik Boström; youenn fablet. W3C. 16 June 2022. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
- [HIGHRES-TIME]
- High Resolution Time. Yoav Weiss. W3C. 28 January 2022. W3C Working Draft. URL: https://www.w3.org/TR/hr-time-3/
- [IANA-DTLS-SRTP]
- DTLS-SRTP Protection Profiles. IANA. URL: https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml
- [IANA-TLS-CIPHERS]
- TLS Cipher Suite Registry. IANA. URL: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4
- [infra]
- Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
- [JSEP]
- JavaScript Session Establishment Protocol (JSEP). J. Uberti; C. Jennings; E. Rescorla, Ed.. IETF. January 2021. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8829
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
- [RFC3550]
- RTP: A Transport Protocol for Real-Time Applications. H. Schulzrinne; S. Casner; R. Frederick; V. Jacobson. IETF. July 2003. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3550
- [RFC3611]
- RTP Control Protocol Extended Reports (RTCP XR). T. Friedman, Ed.; R. Caceres, Ed.; A. Clark, Ed.. IETF. November 2003. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3611
- [RFC3890]
- A Transport Independent Bandwidth Modifier for the Session Description Protocol (SDP). M. Westerlund. IETF. September 2004. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3890
- [RFC4572]
- Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP). J. Lennox. IETF. July 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4572
- [RFC4585]
- Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF). J. Ott; S. Wenger; N. Sato; C. Burmeister; J. Rey. IETF. July 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4585
- [RFC5104]
- Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF). S. Wenger; U. Chandra; M. Westerlund; B. Burman. IETF. February 2008. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5104
- [RFC5226]
- Guidelines for Writing an IANA Considerations Section in RFCs. T. Narten; H. Alvestrand. IETF. May 2008. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5226
- [RFC5245]
- Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. J. Rosenberg. IETF. April 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5245
- [RFC5764]
- Datagram Transport Layer Security (DTLS) Extension to Establish Keys for the Secure Real-time Transport Protocol (SRTP). D. McGrew; E. Rescorla. IETF. May 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5764
- [RFC6184]
- RTP Payload Format for H.264 Video. Y.-K. Wang; R. Even; T. Kristensen; R. Jesup. IETF. May 2011. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6184
- [RFC6347]
- Datagram Transport Layer Security Version 1.2. E. Rescorla; N. Modadugu. IETF. January 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6347
- [RFC6386]
- VP8 Data Format and Decoding Guide. J. Bankoski; J. Koleszar; L. Quillio; J. Salonen; P. Wilkins; Y. Xu. IETF. November 2011. Informational. URL: https://www.rfc-editor.org/rfc/rfc6386
- [RFC6464]
- A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication. J. Lennox, Ed.; E. Ivov; E. Marocco. IETF. December 2011. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6464
- [RFC7002]
- RTP Control Protocol (RTCP) Extended Report (XR) Block for Discard Count Metric Reporting. A. Clark; G. Zorn; Q. Wu. IETF. September 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7002
- [RFC7004]
- RTP Control Protocol (RTCP) Extended Report (XR) Blocks for Summary Statistics Metrics Reporting. G. Zorn; R. Schott; Q. Wu, Ed.; R. Huang. IETF. September 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7004
- [RFC7656]
- A Taxonomy of Semantics and Mechanisms for Real-Time Transport Protocol (RTP) Sources. J. Lennox; K. Gross; S. Nandakumar; G. Salgueiro; B. Burman, Ed.. IETF. November 2015. Informational. URL: https://www.rfc-editor.org/rfc/rfc7656
- [RFC7675]
- Session Traversal Utilities for NAT (STUN) Usage for Consent Freshness. M. Perumal; D. Wing; R. Ravindranath; T. Reddy; M. Thomson. IETF. October 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7675
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
- [STUN-PATH-CHAR]
- Discovery of path characteristics using STUN. T. Reddy; D. Wing; P. Martinsen; V. Singh. IETF. Internet Draft. URL: https://datatracker.ietf.org/doc/html/draft-reddy-tram-stun-path-data
- [WEBIDL]
- Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/
- [WEBRTC]
- WebRTC 1.0: Real-Time Communication Between Browsers. Cullen Jennings; Henrik Boström; Jan-Ivar Bruaroey. W3C. 26 January 2021. W3C Recommendation. URL: https://www.w3.org/TR/webrtc/
- [WEBRTC-IDENTITY]
- Identity for WebRTC 1.0. Cullen Jennings; Martin Thomson. W3C. 27 September 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/webrtc-identity/
- [WEBRTC-PRIORITY]
- WebRTC Priority Control API. Harald Alvestrand. W3C. 18 March 2021. W3C Candidate Recommendation. URL: https://www.w3.org/TR/webrtc-priority/
- [XRBLOCK-STATS]
- RTCP XR Metrics for WebRTC. Varun Singh; Rachel Huang; Roni Even; Dan Romascanu; Lingli Deng. IETF. Internet Draft. URL: https://datatracker.ietf.org/doc/html/draft-ietf-xrblock-rtcweb-rtcp-xr-metrics
- [RFC2032]
- RTP Payload Format for H.261 Video Streams. T. Turletti; C. Huitema. IETF. October 1996. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2032
- [RFC4587]
- RTP Payload Format for H.261 Video Streams. R. Even. IETF. August 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4587
- [RTCWEB-TRANSPORT]
- Transports for WebRTC. H. Alvestrand. IETF. January 2021. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8835
Referenced in:
- § 6.1 RTCStatsType enum (2) (3) (4) (5) (6) (7)
- § 7.1 The RTP statistics hierarchy (2) (3) (4) (5) (6) (7)
- § Dictionary RTCRtpStreamStats Members (2)
- § Dictionary RTCInboundRtpStreamStats Members (2)
- § 7.6 RTCRemoteInboundRtpStreamStats dictionary (2)
- § 7.8 RTCOutboundRtpStreamStats dictionary
- § Dictionary RTCOutboundRtpStreamStats Members (2)
- § 7.10 RTCRemoteOutboundRtpStreamStats dictionary (2)
- § Dictionary RTCIceCandidatePairStats Members (2)
Referenced in:
- § 7.1 The RTP statistics hierarchy (2)
- § Dictionary RTCReceivedRtpStreamStats Members (2) (3)
- § Dictionary RTCInboundRtpStreamStats Members (2) (3) (4) (5) (6)
- § Dictionary RTCRemoteInboundRtpStreamStats Members (2) (3) (4)
- § Dictionary RTCSentRtpStreamStats Members (2)
- § Dictionary RTCOutboundRtpStreamStats Members (2) (3) (4)
- § Dictionary RTCRemoteOutboundRtpStreamStats Members (2) (3) (4)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 3. Terminology
- § 4. Basic concepts
- § 4.1 Guidelines for design of stats objects (2) (3)
- § 6. RTCStatsType
- § 7.2 RTCRtpStreamStats dictionary
- § 7.3 RTCCodecStats dictionary
- § 7.11 RTCMediaSourceStats dictionary
- § 7.14 RTCPeerConnectionStats dictionary
- § 7.15 RTCDataChannelStats dictionary
- § 7.16 RTCTransportStats dictionary
- § 7.17 RTCIceCandidateStats dictionary
- § 7.18 RTCIceCandidatePairStats dictionary
- § 7.19 RTCCertificateStats dictionary
- § Obsolete RTCMediaStreamStats members
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 2. Conformance
- § 6.1 RTCStatsType enum
- § 7.1 The RTP statistics hierarchy
- § 7.5 RTCInboundRtpStreamStats dictionary (2)
- § Dictionary RTCInboundRtpStreamStats Members
- § Dictionary RTCRemoteOutboundRtpStreamStats Members
- § Dictionary RTCAudioSourceStats Members (2) (3)
- § Obsolete RTCCodecStats members (2)
- § Obsolete RTCInboundRtpStreamStats members (2)
- § Obsolete RTCMediaStreamTrackStats members (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18) (19)
- § 10. Security and Privacy Considerations (2)
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 6.1 RTCStatsType enum
- § 7.1 The RTP statistics hierarchy
- § 7.6 RTCRemoteInboundRtpStreamStats dictionary (2)
- § Dictionary RTCRemoteInboundRtpStreamStats Members
- § Dictionary RTCOutboundRtpStreamStats Members
- § Obsolete RTCInboundRtpStreamStats members
- § 10. Security and Privacy Considerations (2)
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 2. Conformance
- § 6.1 RTCStatsType enum (2) (3) (4)
- § 7.1 The RTP statistics hierarchy
- § Dictionary RTCRemoteInboundRtpStreamStats Members
- § 7.8 RTCOutboundRtpStreamStats dictionary (2)
- § Dictionary RTCOutboundRtpStreamStats Members
- § 7.11 RTCMediaSourceStats dictionary
- § Obsolete RTCCodecStats members
- § Obsolete RTCOutboundRtpStreamStats members (2)
- § Obsolete RTCMediaStreamTrackStats members (2) (3) (4) (5) (6)
- § 10. Security and Privacy Considerations
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 6.1 RTCStatsType enum
- § Dictionary RTCInboundRtpStreamStats Members (2) (3)
- § 7.11 RTCMediaSourceStats dictionary
- § Dictionary RTCMediaSourceStats Members
- § 7.12 RTCAudioSourceStats dictionary (2)
- § Dictionary RTCAudioSourceStats Members
- § Obsolete RTCMediaStreamTrackStats members (2) (3) (4) (5)
- § 10. Security and Privacy Considerations (2) (3)
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
- § 6.1 RTCStatsType enum
- § Dictionary RTCOutboundRtpStreamStats Members (2) (3)
- § 7.11 RTCMediaSourceStats dictionary
- § Dictionary RTCMediaSourceStats Members
- § 7.13 RTCVideoSourceStats dictionary (2)
- § Dictionary RTCVideoSourceStats Members
- § Obsolete RTCMediaStreamTrackStats members (2)
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 6.1 RTCStatsType enum
- § Dictionary RTCRtpStreamStats Members
- § Dictionary RTCCodecStats Members
- § 7.16 RTCTransportStats dictionary (2)
- § Dictionary RTCTransportStats Members
- § Dictionary RTCIceCandidateStats Members
- § Dictionary RTCIceCandidatePairStats Members
- § 10. Security and Privacy Considerations
- § A. Summary of WebRTC stats fields per type
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: