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]].
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.
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.
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):
The terms MediaStream, MediaStreamTrack, and Consumer are defined in [[!GETUSERMEDIA]].
The terms {{RTCPeerConnection}}, {{RTCDataChannel}}, {{RTCDtlsTransport}}, {{RTCDtlsTransportState}}, {{RTCIceTransport}}, {{RTCIceRole}}, {{RTCSctpTransport}}, {{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:
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.
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 in Id, or
they have type sequence<{{DOMString}}> and member names ending in Ids.
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 object =]s, 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.
dictionary 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:
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 {{RTCRtpStreamStats/transportId}}) are always a [= stats object reference =];
names ending in Ids (such as {{RTCMediaStreamStats/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 {{RTCDataChannelStats/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:
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 {{RTCPeerConnection/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 {{RTCPeerConnection/getStats()}}. When an object is [= deleted =], we can guarantee that no subsequent {{RTCPeerConnection/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 object =]s for deleted [= monitored object =]s will always be able to uniquely identify the object pointed to in the result of any {{RTCPeerConnection/getStats()}} call.
A call to {{RTCPeerConnection/getStats()}} touches many components of WebRTC and may take significant time to execute. The implementation may or may not utilize caching or throttling of {{RTCPeerConnection/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 {{RTCPeerConnection/getStats()}} calls must return
up-to-date dictionaries for the affected objects. For example, if a track is added with
{{RTCPeerConnection/addTrack()}} subsequent {{RTCPeerConnection/getStats()}} calls must resolve with a corresponding
{{RTCMediaHandlerStats}} object. If you call {{RTCPeerConnection/setRemoteDescription()}} removing a remote track,
upon the promise resolving or an associated event (stream's onremovetrack or track's
onmute) firing, calling {{RTCPeerConnection/getStats()}} must resolve with an up-to-date {{RTCMediaHandlerStats}}
object.
When a stats object is [= deleted =], subsequent {{RTCPeerConnection/getStats()}} calls MUST NOT return stats for that [= monitored object =].
This document, in its editors' draft form, serves as the repository for the currently defined set of stats object types including proposals for new standard types.
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.
The {{RTCStats/type}} member, of type {{RTCStatsType}}, indicates the type of the object that the {{RTCStats}} object represents. An object with a given {{RTCStats/type}} can have only one IDL dictionary type, but multiple {{RTCStats/type}} values may indicate the same IDL dictionary type; for example, {{RTCStatsType/"local-candidate"}} and {{RTCStatsType/"remote-candidate"}} both use the IDL dictionary type {{RTCIceCandidateStats}}.
This specification is normative for the allowed values of {{RTCStatsType}}.
enum RTCStatsType {
"codec",
"inbound-rtp",
"outbound-rtp",
"remote-inbound-rtp",
"remote-outbound-rtp",
"media-source",
"csrc",
"peer-connection",
"data-channel",
"stream",
"track",
"transceiver",
"sender",
"receiver",
"transport",
"sctp-transport",
"candidate-pair",
"local-candidate",
"remote-candidate",
"certificate",
"ice-server"
};
The following strings are valid values for {{RTCStatsType}}:
Statistics for a codec that is currently being used by RTP streams being sent or received by this {{RTCPeerConnection}} object. It is accessed by the {{RTCCodecStats}}.
Statistics for an inbound RTP stream that is currently received with this {{RTCPeerConnection}} object. It is accessed by the {{RTCInboundRtpStreamStats}}.
Statistics for an outbound RTP stream that is currently sent with this {{RTCPeerConnection}} object. It is accessed by the {{RTCOutboundRtpStreamStats}}.
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 the {{RTCRtpStreamStats/ssrc}} member, and all these senders will have a reference to the same {{RTCStatsType/"sender"}} object (of type {{RTCAudioSenderStats}} or {{RTCVideoSenderStats}}) and {{RTCStatsType/"track"}} object (of type {{RTCSenderAudioTrackAttachmentStats}} or {{RTCSenderVideoTrackAttachmentStats}}). RTX streams do not show up as separate {{RTCOutboundRtpStreamStats}} objects but affect the {{RTCSentRtpStreamStats/packetsSent}}, {{RTCSentRtpStreamStats/bytesSent}}, {{RTCOutboundRtpStreamStats/retransmittedPacketsSent}} and {{RTCOutboundRtpStreamStats/retransmittedBytesSent}} counters of the relevant {{RTCOutboundRtpStreamStats}} objects.
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 the {{RTCRemoteInboundRtpStreamStats}}.
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 the {{RTCRemoteOutboundRtpStreamStats}}.
Statistics for the media produced by a {{MediaStreamTrack}} that is
currently attached to an {{RTCRtpSender}}. This reflects the media that is
fed to the encoder; after getUserMedia() constraints have been applied
(i.e. not the raw media produced by the camera). It is either an
{{RTCAudioSourceStats}} or {{RTCVideoSourceStats}}
depending on its kind.
Statistics for a contributing source (CSRC) that contributed to an inbound RTP stream. It is accessed by the {{RTCRtpContributingSourceStats}}.
Statistics related to the {{RTCPeerConnection}} object. It is accessed by the {{RTCPeerConnectionStats}}.
Statistics related to each {{RTCDataChannel}} id. It is accessed by the {{RTCDataChannelStats}}.
This is now obsolete. Contains statistics related to a specific {{MediaStream}}. It is accessed by the obsolete dictionary {{RTCMediaStreamStats}}.
Statistics related to a specific {{MediaStreamTrack}}'s attachment to an {{RTCRtpSender}} and the corresponding media-level metrics. It is accessed by {{RTCSenderVideoTrackAttachmentStats}}, {{RTCSenderAudioTrackAttachmentStats}}, {{RTCReceiverVideoTrackAttachmentStats}} or {{RTCReceiverAudioTrackAttachmentStats}}, all inherited from {{RTCMediaHandlerStats}}.
The monitored {{RTCStatsType/"track"}} object is [= deleted =] when the sender it reports on has its {{RTCRtpSender/track}} value changed to no longer refer to the same track.
All "track" stats have been made obsolete. The relevant metrics have been moved to "media-source", "sender", "outbound-rtp", "receiver" and "inbound-rtp" stats.
Statistics related to a specific {{RTCRtpTransceiver}}. It is accessed by the {{RTCRtpTransceiverStats}} dictionary.
Statistics related to a specific {{RTCRtpSender}} and the corresponding
media-level metrics. It is accessed by the {{RTCAudioSenderStats}} or
the {{RTCVideoSenderStats}} depending on kind.
Statistics related to a specific receiver and the corresponding media-level
metrics. It is accessed by the {{RTCAudioReceiverStats}} or the
{{RTCVideoReceiverStats}} depending on kind.
Transport statistics related to the {{RTCPeerConnection}} object. It is accessed by the {{RTCTransportStats}}.
SCTP transport statistics related to an {{RTCSctpTransport}} object. It is accessed by the {{RTCSctpTransportStats}} dictionary.
ICE candidate pair statistics related to the {{RTCIceTransport}} objects. It is accessed by the {{RTCIceCandidatePairStats}}.
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 {{RTCIceTransportState/"new"}}. The candidate pair that is the current pair for a transport is [= deleted =] after an ICE restart when the {{RTCIceTransport}} switches to using a candidate pair generated from the new candidates; this time doesn't correspond to any other externally observable event.
ICE local candidate statistics related to the {{RTCIceTransport}} objects. It is accessed by the {{RTCIceCandidateStats}} 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.
ICE remote candidate statistics related to the {{RTCIceTransport}} objects. It is accessed by the {{RTCIceCandidateStats}} 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.
Information about a certificate used by an {{RTCIceTransport}}. It is accessed by the {{RTCCertificateStats}}.
Information about the connection to an ICE server (e.g. STUN or TURN). It is accessed by the {{RTCIceServerStats}}.
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 object =]s 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).
{{RTCRemoteOutboundRtpStreamStats}}: Stats relevant to the remote sending end of an RTP stream, usually computed based on an RTCP SR.
dictionary RTCRtpStreamStats : RTCStats {
required unsigned long ssrc;
required DOMString kind;
DOMString transportId;
DOMString codecId;
};
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.
Either "audio" or "video". This MUST match the media
type part of the information in the corresponding {{RTCCodecStats/codecType}} member of {{RTCCodecStats}}, and
MUST match the kind attribute of the related {{MediaStreamTrack}}.
It is a unique identifier that is associated to the object that was inspected to produce the {{RTCTransportStats}} associated with this RTP stream.
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.
dictionary RTCCodecStats : RTCStats {
required unsigned long payloadType;
RTCCodecType codecType;
required DOMString transportId;
required DOMString mimeType;
unsigned long clockRate;
unsigned long channels;
DOMString sdpFmtpLine;
};
Payload type as used in RTP encoding or decoding.
{{RTCCodecType/"encode"}} or {{RTCCodecType/"decode"}}, depending on whether this object represents a media format that the implementation is prepared to encode or decode. If the dictionary member is not present, it means that this media format can be both encoded and decoded.
The unique identifier of the transport on which this codec is being used, which can be used to look up the corresponding {{RTCTransportStats}} object.
The codec MIME media type/subtype. e.g., video/vp8 or equivalent.
Represents the media sampling rate.
Use 2 for stereo, missing for most other cases.
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.
enum RTCCodecType {
"encode",
"decode",
};
| Enumeration description | |
|---|---|
| encode |
The attached {{RTCCodecStats}} represents a media format that is being encoded, or that the implementation is prepared to encode. |
| decode |
The attached {{RTCCodecStats}} represents a media format that the implementation is prepared to decode. |
dictionary RTCReceivedRtpStreamStats : RTCRtpStreamStats {
unsigned long long packetsReceived;
long long packetsLost;
double jitter;
unsigned long long packetsDiscarded;
unsigned long long packetsRepaired;
unsigned long long burstPacketsLost;
unsigned long long burstPacketsDiscarded;
unsigned long burstLossCount;
unsigned long burstDiscardCount;
double burstLossRate;
double burstDiscardRate;
double gapLossRate;
double gapDiscardRate;
unsigned long framesDropped;
unsigned long partialFramesLost;
unsigned long fullFramesLost;
};
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.
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.
Packet Jitter measured in seconds for this SSRC. Calculated as defined in section 6.4.1. of [[!RFC3550]].
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.
The cumulative number of lost RTP packets repaired after applying an error-resilience mechanism [[XRBLOCK-STATS]]. It is measured for the primary source RTP packets and only counted for RTP packets that have no further chance of repair. To clarify, the value is upper-bound to the cumulative number of lost packets. Calculated as defined in [[!RFC7509]] section 3.1 and Appendix A.b.
The cumulative number of RTP packets lost during loss bursts, Appendix A (c) of [[!RFC6958]].
The cumulative number of RTP packets discarded during discard bursts, Appendix A (b) of [[!RFC7003]].
The cumulative number of bursts of lost RTP packets, Appendix A (e) of [[!RFC6958]].
[[!RFC3611]] recommends a Gmin (threshold) value of 16 for classifying a sequence of packet losses or discards as a burst.
The cumulative number of bursts of discarded RTP packets, Appendix A (e) of [[!RFC8015]].
The fraction of RTP packets lost during bursts to the total number of RTP packets expected in the bursts. As defined in Appendix A (a) of [[!RFC7004]], however, the actual value is reported without multiplying by 32768.
The fraction of RTP packets discarded during bursts to the total number of RTP packets expected in bursts. As defined in Appendix A (e) of [[!RFC7004]], however, the actual value is reported without multiplying by 32768.
The fraction of RTP packets lost during the gap periods. Appendix A (b) of [[!RFC7004]], however, the actual value is reported without multiplying by 32768.
The fraction of RTP packets discarded during the gap periods. Appendix A (f) of [[!RFC7004]], however, the actual value is reported without multiplying by 32768.
Only [= map/exist =]s 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]].
Only [= map/exist =]s for video. The cumulative number of partial frames lost. The measurement begins when the receiver is created and is a cumulative metric as defined in Appendix A (j) of [[!RFC7004]]. This metric is incremented when the frame is sent to the decoder. If the partial frame is received and recovered via retransmission or FEC before decoding, the {{RTCInboundRtpStreamStats/framesReceived}} counter is incremented.
Only [= map/exist =]s for video. The cumulative number of full frames lost. The measurement begins when the receiver is created and is a cumulative metric as defined in Appendix A (i) of [[!RFC7004]].
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.
dictionary RTCInboundRtpStreamStats : RTCReceivedRtpStreamStats {
required DOMString receiverId;
DOMString remoteId;
unsigned long framesDecoded;
unsigned long keyFramesDecoded;
unsigned long frameWidth;
unsigned long frameHeight;
unsigned long frameBitDepth;
double framesPerSecond;
unsigned long long qpSum;
double totalDecodeTime;
double totalInterFrameDelay;
double totalSquaredInterFrameDelay;
boolean voiceActivityFlag;
DOMHighResTimeStamp lastPacketReceivedTimestamp;
double averageRtcpInterval;
unsigned long long headerBytesReceived;
unsigned long long fecPacketsReceived;
unsigned long long fecPacketsDiscarded;
unsigned long long bytesReceived;
unsigned long long packetsFailedDecryption;
unsigned long long packetsDuplicated;
record<USVString, unsigned long long> perDscpPacketsReceived;
unsigned long nackCount;
unsigned long firCount;
unsigned long pliCount;
unsigned long sliCount;
double totalProcessingDelay;
DOMHighResTimeStamp estimatedPlayoutTimestamp;
double jitterBufferDelay;
unsigned long long jitterBufferEmittedCount;
unsigned long long totalSamplesReceived;
unsigned long long totalSamplesDecoded;
unsigned long long samplesDecodedWithSilk;
unsigned long long samplesDecodedWithCelt;
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;
};
The stats ID used to look up the {{RTCAudioReceiverStats}} or {{RTCVideoReceiverStats}} object receiving this stream.
The {{remoteId}} is used for looking up the remote {{RTCRemoteOutboundRtpStreamStats}} object for the same SSRC.
Only [= map/exist =]s 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.
Only [= map/exist =]s 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.
Only [= map/exist =]s for video. Represents the width of the last decoded frame. Before the first frame is decoded this member does not [= map/exist =].
Only [= map/exist =]s for video. Represents the height of the last decoded frame. Before the first frame is decoded this member does not [= map/exist =].
Only [= map/exist =]s for video. Represents the bit depth per pixel of the last decoded frame. Typical values are 24, 30, or 36 bits. Before the first frame is decoded this member does not [= map/exist =].
Only [= map/exist =]s for video. The number of decoded frames in the last second.
Only [= map/exist =]s 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.
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 with {{framesDecoded}}. 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.
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}}, and {{framesDecoded}} according to the formula: ({{totalSquaredInterFrameDelay}} - {{totalInterFrameDelay}}^2/ {{framesDecoded}})/{{framesDecoded}}.
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.
Only [= map/exist =]s for audio. Whether the last RTP packet whose frame was delivered to the
{{RTCRtpReceiver}}'s {{MediaStreamTrack}} for playout contained voice activity or not based
on the presence of the V bit in the extension header, as defined in [[RFC6464]]. This
is the stats-equivalent of {{RTCRtpSynchronizationSource}}.voiceActivityFlag
in [[WEBRTC].
Represents the timestamp at which the last packet was received for this SSRC. This differs from {{RTCStats/timestamp}}, which represents the time at which the statistics were generated by the local endpoint.
The average RTCP interval between two consecutive compound RTCP packets. This is calculated by the sending endpoint when sending compound RTCP reports. Compound packets must contain at least a RTCP RR or SR block and an SDES packet with the CNAME item.
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.
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).
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}}.
Total number of bytes received for this SSRC. Calculated as defined in [[!RFC3550]] section 6.4.1.
The cumulative number of RTP packets that failed to be decrypted according to the procedures in [[!RFC3711]]. These packets are not counted by {{RTCReceivedRtpStreamStats/packetsDiscarded}}.
Total number of packets received for this SSRC, per Differentiated Services code point (DSCP) [[RFC2474]]. DSCPs are identified as decimal integers in string form. Note that due to network remapping and bleaching, these numbers are not expected to match the numbers seen on sending. Not all OSes make this information available.
Only [= map/exist =]s 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]].
Only [= map/exist =]s 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.
Count the total number of Negative ACKnowledgement (NACK) packets sent by this receiver. Calculated as defined in [[!RFC4585]] section 6.2.1.
Only [= map/exist =]s for video. Count the total number of Slice Loss Indication (SLI) packets sent by this receiver. Calculated as defined in [[!RFC4585]] section 6.3.2.
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., {{RTCReceivedRtpStreamStats/framesDropped}}, {{RTCReceivedRtpStreamStats/partialFramesLost}}, The average processing delay can be calculated by dividing the {{totalProcessingDelay}} with the {{totalSamplesDecoded}} for audio or {{framesDecoded}} for video.
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}}.
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 the {{jitterBufferDelay}} with the {{jitterBufferEmittedCount}}.
The total number of audio samples or video frames that have come out of the jitter buffer (increasing {{jitterBufferDelay}}).
Only [= map/exist =]s for audio. The total number of samples that have been received on this RTP stream. This includes {{concealedSamples}}.
Only [= map/exist =]s for audio. The total number of samples that have been decoded on this RTP stream.
Only [= map/exist =]s for audio and when the audio codec is Opus. The total number of samples decoded by the SILK portion of the Opus codec.
Only [= map/exist =]s for audio and when the audio codec is Opus. The total number of samples decoded by the CELT portion of the Opus codec.
Only [= map/exist =]s 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 {{RTCReceivedRtpStreamStats/packetsLost}}) or samples from packets that arrive too late to be played out (reported in {{RTCReceivedRtpStreamStats/packetsDiscarded}}).
Only [= map/exist =]s 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}}.
Only [= map/exist =]s 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.
Only [= map/exist =]s 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.
Only [= map/exist =]s 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.
Only [= map/exist =]s 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 under {{totalAudioEnergy}}. The interval used is implementation dependent.
Only [= map/exist =]s 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 formula
Math.sqrt(totalAudioEnergy/totalSamplesDuration). This calculation
can also be performed using the differences between the values of two different
{{RTCPeerConnection/getStats()}} calls, in order to compute the average audio level over
any desired time interval. In other words, do Math.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 to
{{totalAudioEnergy}}. If another 10ms packet with an RMS of 0.1 is
received, this should similarly add 0.0001 to
{{totalAudioEnergy}}. Then,
Math.sqrt(totalAudioEnergy/totalSamplesDuration) becomes
Math.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.
Only [= map/exist =]s 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 with {{totalAudioEnergy}} to compute an average audio level over different intervals.
Only [= map/exist =]s for video. Represents the total number of complete frames received on this RTP stream. This metric is incremented when the complete frame is received.
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.
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.
dictionary RTCRemoteInboundRtpStreamStats : RTCReceivedRtpStreamStats {
DOMString localId;
double roundTripTime;
double totalRoundTripTime;
double fractionLost;
unsigned long long reportsReceived;
unsigned long long roundTripTimeMeasurements;
};
The {{localId}} is used for looking up the local {{RTCOutboundRtpStreamStats}} object for the same SSRC.
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.
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 by {{roundTripTimeMeasurements}}.
The fraction packet loss reported for this SSRC. Calculated as defined in [[!RFC3550]] section 6.4.1 and Appendix A.3.
Represents the total number of RTCP RR blocks received for this SSRC.
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.
dictionary RTCSentRtpStreamStats : RTCRtpStreamStats {
unsigned long packetsSent;
unsigned long long bytesSent;
};
Total number of RTP packets sent for this SSRC. This includes retransmissions. Calculated as defined in [[!RFC3550]] section 6.4.1.
Total number of bytes sent for this SSRC. This includes retransmissions. Calculated as defined in [[!RFC3550]] section 6.4.1.
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.
dictionary RTCOutboundRtpStreamStats : RTCSentRtpStreamStats {
unsigned long rtxSsrc;
DOMString mediaSourceId;
DOMString senderId;
DOMString remoteId;
DOMString rid;
DOMHighResTimeStamp lastPacketSentTimestamp;
unsigned long long headerBytesSent;
unsigned long packetsDiscardedOnSend;
unsigned long long bytesDiscardedOnSend;
unsigned long fecPacketsSent;
unsigned long long retransmittedPacketsSent;
unsigned long long retransmittedBytesSent;
double targetBitrate;
unsigned long long totalEncodedBytesTarget;
unsigned long frameWidth;
unsigned long frameHeight;
unsigned long frameBitDepth;
double framesPerSecond;
unsigned long framesSent;
unsigned long hugeFramesSent;
unsigned long framesEncoded;
unsigned long keyFramesEncoded;
unsigned long framesDiscardedOnSend;
unsigned long long qpSum;
unsigned long long totalSamplesSent;
unsigned long long samplesEncodedWithSilk;
unsigned long long samplesEncodedWithCelt;
boolean voiceActivityFlag;
double totalEncodeTime;
double totalPacketSendDelay;
double averageRtcpInterval;
RTCQualityLimitationReason qualityLimitationReason;
record<DOMString, double> qualityLimitationDurations;
unsigned long qualityLimitationResolutionChanges;
record<USVString, unsigned long long> perDscpPacketsSent;
unsigned long nackCount;
unsigned long firCount;
unsigned long pliCount;
unsigned long sliCount;
DOMString encoderImplementation;
};
If RTX is negotiated as a separate stream, this is the SSRC of the RTX stream that is associated with this stream's {{RTCRtpStreamStats/ssrc}}. If RTX is not negotiated, this value is not present. Whether or not RTX is negotiated, retransmissions are accounted for in the {{RTCSentRtpStreamStats/bytesSent}} and {{RTCOutboundRtpStreamStats/retransmittedBytesSent}} stats of this object.
The stats ID used to look up the {{RTCAudioSenderStats}} or {{RTCVideoSenderStats}} object sending this stream.
The {{remoteId}} is used for looking up the remote {{RTCRemoteInboundRtpStreamStats}} object for the same SSRC.
Exposes the {{RTCRtpCodingParameters/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.
Represents the timestamp at which the last packet was sent for this SSRC. This differs from {{RTCStats/timestamp}}, which represents the time at which the statistics were generated by the local endpoint.
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.
Total number of RTP packets for this SSRC that have been discarded due to socket errors, i.e. a socket error occured when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.
Total number of bytes for this SSRC that have been discarded due to socket errors, i.e. a socket error occured 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.
Total number of RTP FEC packets sent for this SSRC. This counter can also be incremented when sending FEC packets in-band with media packets (e.g., with Opus).
The total number of packets that were retransmitted for this SSRC. This is a subset of {{RTCSentRtpStreamStats/packetsSent}}. If RTX is not negotiated, retransmitted packets are sent over this {{RTCRtpStreamStats/ssrc}}. If RTX was negotiated, retransmitted packets are sent over a separate {{RTCOutboundRtpStreamStats/rtxSsrc}}.
The total number of bytes that were retransmitted for this SSRC, only including payload bytes. This is a subset of {{RTCSentRtpStreamStats/bytesSent}}. If RTX is not negotiated, retransmitted bytes are sent over this {{RTCRtpStreamStats/ssrc}}. If RTX was negotiated, retransmitted bytes are sent over a separate {{RTCOutboundRtpStreamStats/rtxSsrc}}.
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 {{RTCSentRtpStreamStats/bytesSent}} and {{RTCOutboundRtpStreamStats/retransmittedBytesSent}}. The {{targetBitrate}} is defined in the same way as the Transport Independent Application Specific (TIAS) bitrate [[!RFC3890]].
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.
Only [= map/exist =]s 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 [= map/exist =].
Only [= map/exist =]s 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 [= map/exist =].
Only [= map/exist =]s for video. Represents the bit depth per pixel of the last encoded frame. Typical values are 24, 30, or 36 bits. Before the first frame is encoded this member does not [= map/exist =].
Only [= map/exist =]s for video. The number of encoded frames during the last second. This may be lower than the media source frame rate (see {{RTCVideoSourceStats.framesPerSecond}}).
Only [= map/exist =]s for video. Represents the total number of frames sent on this RTP stream.
Only [= map/exist =]s 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.
Only [= map/exist =]s for video. It represents the total number of frames successfully encoded for this RTP media stream.
Only [= map/exist =]s 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.
Total number of video frames that have been discarded for this SSRC due to socket errors, i.e. a socket error occured when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.
Only [= map/exist =]s 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.
Only [= map/exist =]s for audio. The total number of samples that have been sent over this RTP stream.
Only [= map/exist =]s for audio and when the audio codec is Opus. The total number of samples encoded by the SILK portion of the Opus codec.
Only [= map/exist =]s for audio and when the audio codec is Opus. The total number of samples encoded by the CELT portion of the Opus codec.
Only [= map/exist =]s for audio. Whether the last RTP packet sent contained voice activity or not based on the presence of the V bit in the extension header, as defined in [[RFC6464]].
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 with {{framesEncoded}}. 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.
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}} when {{RTCSentRtpStreamStats/packetsSent}} is incremented.
The average RTCP interval between two consecutive compound RTCP packets. This is calculated by the sending endpoint when sending compound RTCP reports. Compound packets must contain at least a RTCP RR or SR block and an SDES packet with the CNAME item.
Only [= map/exist =]s for video. The current reason for limiting the resolution and/or framerate, or {{RTCQualityLimitationReason/"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".
The 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".
Only [= map/exist =]s 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 {{RTCQualityLimitationReason/"none"}}.
The sum of all entries minus {{qualityLimitationDurations}}[{{RTCQualityLimitationReason/"none"}}] gives the total time that the stream has been limited.
Only [= map/exist =]s for video. The number of times that the resolution has changed because we are quality limited ({{qualityLimitationReason}} has a value other than {{RTCQualityLimitationReason/"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.
Total number of packets sent for this SSRC, per DSCP. DSCPs are identified as decimal integers in string form.
Count the total number of Negative ACKnowledgement (NACK) packets received by this sender. Calculated as defined in [[!RFC4585]] section 6.2.1.
Only [= map/exist =]s 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]].
Only [= map/exist =]s 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.
Only [= map/exist =]s for video. Count the total number of Slice Loss Indication (SLI) packets received by this sender. Calculated as defined in [[!RFC4585]] section 6.3.2.
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.
enum RTCQualityLimitationReason {
"none",
"cpu",
"bandwidth",
"other",
};
| Enumeration 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. |
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.
dictionary RTCRemoteOutboundRtpStreamStats : RTCSentRtpStreamStats {
DOMString localId;
DOMHighResTimeStamp remoteTimestamp;
unsigned long long reportsSent;
double roundTripTime;
double totalRoundTripTime;
unsigned long long roundTripTimeMeasurements;
};
The {{localId}} is used for looking up the local {{RTCInboundRtpStreamStats}} object for the same SSRC.
{{remoteTimestamp}}, of type {{DOMHighResTimeStamp}} [[!HIGHRES-TIME]], represents the remote timestamp at which these statistics were sent by the remote endpoint. This differs from {{RTCStats/timestamp}}, which represents the time at which the statistics were generated or received by the local endpoint. The {{remoteTimestamp}}, 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.
Represents the total number of RTCP SR blocks sent for this SSRC.
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.
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 by {{roundTripTimeMeasurements}}.
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.
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 {{RTCStats/type}} is the same
({{RTCStatsType/"media-source"}}) but {{RTCMediaSourceStats/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.
dictionary RTCMediaSourceStats : RTCStats {
required DOMString trackIdentifier;
required DOMString kind;
boolean relayedSource;
};
The value of the {{MediaStreamTrack}}'s id attribute.
The value of the {{MediaStreamTrack}}'s kind attribute.
This is either "audio" or "video". If it is
"audio" then this stats object is of type
{{RTCAudioSourceStats}}. If it is "video" then this stats
object is of type {{RTCVideoSourceStats}}.
true if the source is remote, for instance if it is
sourced from another host via an {{RTCPeerConnection}}.
false otherwise.
The RTCAudioSourceStats dictionary represents an audio track that is attached
to one or more senders. It is an {{RTCMediaSourceStats}} whose
{{RTCMediaSourceStats/kind}} is "audio".
dictionary RTCAudioSourceStats : RTCMediaSourceStats {
double audioLevel;
double totalAudioEnergy;
double totalSamplesDuration;
double echoReturnLoss;
double echoReturnLossEnhancement;
};
Represents the audio level of the media source. For audio levels of remotely sourced tracks, see {{RTCAudioReceiverStats}} 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 under {{totalAudioEnergy}}. The interval used is implementation dependent.
Represents the audio energy of the media source. For audio energy of remotely sourced tracks, see {{RTCAudioReceiverStats}} 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 formula
Math.sqrt(totalAudioEnergy/totalSamplesDuration). This calculation
can also be performed using the differences between the values of two different
{{RTCPeerConnection/getStats()}} calls, in order to compute the average audio level over
any desired time interval. In other words, do Math.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 to
{{totalAudioEnergy}}. If another 10ms packet with an RMS of 0.1 is
received, this should similarly add 0.0001 to
{{totalAudioEnergy}}. Then,
Math.sqrt(totalAudioEnergy/totalSamplesDuration) becomes
Math.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.
Represents the audio duration of the media source. For audio durations of remotely sourced tracks, see {{RTCAudioReceiverStats}} 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.
Only [= map/exist =]s 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.
Only [= map/exist =]s 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.
The RTCVideoSourceStats dictionary represents a video track that is attached
to one or more senders. It is an {{RTCMediaSourceStats}} whose
{{RTCMediaSourceStats/kind}} is "video".
dictionary RTCVideoSourceStats : RTCMediaSourceStats {
unsigned long width;
unsigned long height;
unsigned long bitDepth;
unsigned long frames;
double framesPerSecond;
};
The width, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not [= map/exist =].
The height, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not [= map/exist =].
The bit depth per pixel of the last frame originating from this source. Before a frame has been produced this member does not [= map/exist =].
The total number of frames originating from this source.
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 [= map/exist =].
The {{RTCRtpContributingSourceStats}} dictionary represents the measurement metrics for a contributing source (CSRC) that is contributing to an incoming RTP stream. Each contributing source produces a stream of RTP packets, which are combined by a mixer into a single stream of RTP packets that is ultimately received by the WebRTC endpoint. Information about the sources that contributed to this combined stream may be provided in the CSRC list or [[RFC6465]] header extension of received RTP packets. The {{RTCStats/timestamp}} of this stats object is the most recent time an RTP packet the source contributed to was received and counted by {{RTCRtpContributingSourceStats/packetsContributedTo}}.
dictionary RTCRtpContributingSourceStats : RTCStats {
required unsigned long contributorSsrc;
required DOMString inboundRtpStreamId;
unsigned long packetsContributedTo;
double audioLevel;
};
The SSRC identifier of the contributing source represented by this stats object, as defined by [[!RFC3550]]. It is a 32-bit unsigned integer that appears in the CSRC list of any packets the relevant source contributed to.
The ID of the {{RTCInboundRtpStreamStats}} object representing the inbound RTP stream that this contributing source is contributing to.
The total number of RTP packets that this contributing source contributed to. This value is incremented each time a packet is counted by {{RTCInboundRtpStreamStats}}.{{RTCReceivedRtpStreamStats/packetsReceived}}, and the packet's CSRC list (as defined by [[!RFC3550]] section 5.1) contains the SSRC identifier of this contributing source, {{contributorSsrc}}.
Present if the last received RTP packet that this source contributed to contained an [[!RFC6465]] mixer-to-client audio level header extension. The value of {{audioLevel}} 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 [[!RFC6465]] header extension contains values in the range 0..127, in units
of -dBov, where 127 represents silence. To convert these values to the linear
0..1 range of {{audioLevel}}, a value of 127 is converted to 0, and all
other values are converted using the equation: f(rfc6465_level) =
10^(-rfc6465_level/20).
dictionary RTCPeerConnectionStats : RTCStats {
unsigned long dataChannelsOpened;
unsigned long dataChannelsClosed;
unsigned long dataChannelsRequested;
unsigned long dataChannelsAccepted;
};
Represents the number of unique {{RTCDataChannel}}s that have entered the {{RTCDataChannelState/"open"}} state during their lifetime.
Represents the number of unique {{RTCDataChannel}}s that have left the {{RTCDataChannelState/"open"}} state during their lifetime (due to being closed by either end or the underlying transport being closed). {{RTCDataChannel}}s that transition from {{RTCDataChannelState/"connecting"}} to {{RTCDataChannelState/"closing"}} or {{RTCDataChannelState/"closed"}} without ever being {{RTCDataChannelState/"open"}} are not counted in this number.
Represents the number of unique {{RTCDataChannel}}s returned from a successful {{RTCPeerConnection/createDataChannel()}} call on the {{RTCPeerConnection}}. If the underlying data transport is not established, these may be in the {{RTCDataChannelState/"connecting"}} state.
Represents the number of unique {{RTCDataChannel}}s signaled in a {{RTCPeerConnection/ondatachannel}} event on the {{RTCPeerConnection}}.
The total number of open data channels at any time can be calculated as {{RTCPeerConnectionStats/dataChannelsOpened}} - {{RTCPeerConnectionStats/dataChannelsClosed}}. This number is always positive.
The sum of {{RTCPeerConnectionStats/dataChannelsRequested}} and {{RTCPeerConnectionStats/dataChannelsAccepted}} is always greater than or equal to {{RTCPeerConnectionStats/dataChannelsOpened}} - the difference is equal to the number of channels that have been requested, but have not reached the {{RTCDataChannelState/"open"}} state.
An {{RTCRtpTransceiverStats}} stats object represents an {{RTCRtpTransceiver}} of an {{RTCPeerConnection}}.
It appears as soon as the monitored {{RTCRtpTransceiver}} object is created, such as by invoking {{RTCPeerConnection/addTransceiver()}}, {{RTCPeerConnection/addTrack()}} or {{RTCPeerConnection/setRemoteDescription()}}. {{RTCRtpTransceiverStats}} objects can only be deleted if the corresponding {{RTCRtpTransceiver}} is removed - this can only happen if a remote description is rolled back.
dictionary RTCRtpTransceiverStats : RTCStats {
required DOMString senderId;
required DOMString receiverId;
DOMString mid;
};
The identifier of the stats object representing the {{RTCRtpSender}} associated with the {{RTCRtpTransceiver}} represented by this stats object.
The identifier of the stats object representing the {{RTCRtpReceiver}} associated with the {{RTCRtpTransceiver}} represented by this stats object.
If the {{RTCRtpTransceiver}} that this stats object represents has a {{RTCRtpTransceiver/mid}} value that is not null, this is that value, otherwise this member is not present.
dictionary RTCMediaHandlerStats : RTCStats {
DOMString trackIdentifier;
boolean ended;
required DOMString kind;
};
Represents the id property of the track.
Reflects the ended state of the track.
Either "audio" or "video". This reflects the kind
attribute of the {{MediaStreamTrack}}, see [[!GETUSERMEDIA]].
dictionary RTCVideoHandlerStats : RTCMediaHandlerStats {
};
An {{RTCVideoSenderStats}} object represents the stats about one video sender of a {{RTCPeerConnection}} object for which one calls {{RTCPeerConnection/getStats()}}.
It appears in the stats as soon as the sender is added by either addTrack or addTransceiver, or by media negotiation.
dictionary RTCVideoSenderStats : RTCVideoHandlerStats {
DOMString mediaSourceId;
};
The identifier of the stats object representing the track currently attached to this sender, an {{RTCMediaSourceStats}}.
An {{RTCVideoReceiverStats}} object represents the stats about one video receiver of a {{RTCPeerConnection}} object for which one calls {{RTCPeerConnection/getStats()}}.
It appears in the stats as soon as the {{RTCRtpReceiver}} is added by either {{RTCPeerConnection/addTrack()}} or {{RTCPeerConnection/addTransceiver()}}, or by media negotiation.
dictionary RTCVideoReceiverStats : RTCVideoHandlerStats {
};
dictionary RTCAudioHandlerStats : RTCMediaHandlerStats {
};
An {{RTCAudioSenderStats}} object represents the stats about one audio sender of a {{RTCPeerConnection}} object for which one calls {{RTCPeerConnection/getStats()}}.
It appears in the stats as soon as the {{RTCRtpSender}} is added by either {{RTCPeerConnection/addTrack()}} or {{RTCPeerConnection/addTransceiver()}}, or by media negotiation.
dictionary RTCAudioSenderStats : RTCAudioHandlerStats {
DOMString mediaSourceId;
};
The identifier of the stats object representing the track currently attached to this sender, an {{RTCMediaSourceStats}}.
An {{RTCAudioReceiverStats}} object represents the stats about one audio receiver of a {{RTCPeerConnection}} object for which one calls {{RTCPeerConnection.getStats()}}.
It appears in the stats as soon as the {{RTCRtpReceiver}} is added by either {{RTCPeerConnection/addTrack()}} or {{RTCPeerConnection/addTransceiver()}}, or by media negotiation.
dictionary RTCAudioReceiverStats : RTCAudioHandlerStats {
};
dictionary 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;
};
The {{RTCDataChannel/id}} attribute of the {{RTCDataChannel}} object.
Represents the total number of API "message" events sent.
Represents the total number of payload bytes sent on this {{RTCDataChannel}}, i.e., not including headers or padding.
Represents the total number of API "message" events received.
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 RTCP multiplexing is used, one transport is used for both RTP and RTCP. Otherwise, RTP and RTCP will be sent on separate transports, and {{RTCTransportStats/rtcpTransportStatsId}} can be used to pair the resulting {{RTCTransportStats}} objects. Additionally, 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. RTCP multiplexing and bundling are described in [[!WEBRTC]].
dictionary RTCTransportStats : RTCStats {
unsigned long long packetsSent;
unsigned long long packetsReceived;
unsigned long long bytesSent;
unsigned long long bytesReceived;
DOMString rtcpTransportStatsId;
RTCIceRole iceRole;
DOMString iceLocalUsernameFragment;
required RTCDtlsTransportState dtlsState;
RTCIceTransportState iceState;
DOMString selectedCandidatePairId;
DOMString localCertificateId;
DOMString remoteCertificateId;
DOMString tlsVersion;
DOMString dtlsCipher;
DOMString srtpCipher;
DOMString tlsGroup;
unsigned long selectedCandidatePairChanges;
};
Represents the total number of packets sent over this transport.
Represents the total number of packets received on this transport.
Represents the total number of payload bytes sent on this {{RTCIceTransport}}, i.e., not including headers, padding or ICE connectivity checks.
Represents the total number of payload bytes received on this {{RTCIceTransport}}, i.e., not including headers, padding or ICE connectivity checks.
If RTP and RTCP are not multiplexed, this is the {{RTCStats/id}} of the transport that gives stats for the RTCP component, and this record has only the RTP component stats.
Set to the current value of the {{RTCIceTransport/role}} attribute of the underlying {{RTCDtlsTransport}}.{{RTCDtlsTransport/iceTransport}}.
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.
Set to the current value of the {{RTCDtlsTransport/state}} attribute of the underlying {{RTCDtlsTransport}}.
Set to the current value of the {{RTCIceTransport/state}} attribute of the underlying {{RTCIceTransport}}.
It is a unique identifier that is associated to the object that was inspected to produce the {{RTCIceCandidatePairStats}} associated with this transport.
For components where DTLS is negotiated, give local certificate.
For components where DTLS is negotiated, give remote certificate.
For components where DTLS is negotiated, the TLS version agreed. Only [= map/exist =]s after DTLS negotiation is complete.
The value comes from ServerHello.supported_versions if present, otherwise from
ServerHello.version. It is represented as four upper case
hexadecimal digits, representing the two
bytes of the version.
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]].
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]].
Descriptive name of the group used for the encryption, as defined in the "Description" column of the IANA TLS Supported Groups registry [[!IANA-TLS-GROUPS]].
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.
An {{RTCSctpTransportStats}} object represents the stats corresponding to an {{RTCSctpTransport}} described in [[!WEBRTC]].
There is only one {{RTCSctpTransportStats}} object, since the PeerConnection can only have one SCTP transport.
dictionary RTCSctpTransportStats : RTCStats {
DOMString transportId;
double smoothedRoundTripTime;
unsigned long congestionWindow;
unsigned long receiverWindow;
unsigned long mtu;
unsigned long unackData;
};
The identifier of the object that was inspected to produce the {{RTCTransportStats}} for the DTLSTransport and ICETransport supporting the SCTP transport.
The latest smoothed round-trip time value, corresponding to spinfo_srtt defined in [[RFC6458]] but converted to seconds. If there has been no round-trip time measurements yet, this value is undefined.
The latest congestion window, corresponding to spinfo_cwnd defined in [[RFC6458]].
The latest receiver window, corresponding to sstat_rwnd defined in [[RFC6458]].
The latest maximum transmission unit, corresponding to spinfo_mtu defined in [[RFC6458]].
The number of unacknowledged DATA chunks, corresponding to sstat_unackdata defined in [[RFC6458]].
{{RTCIceCandidateStats}} reflects the properties of a candidate in
Section 15.1 of [[!RFC5245]]. It corresponds to a {{RTCIceCandidate}} object.
dictionary RTCIceCandidateStats : RTCStats {
required DOMString transportId;
DOMString? address;
long port;
DOMString protocol;
required RTCIceCandidateType candidateType;
long priority;
DOMString url;
DOMString relayProtocol;
};
It is a unique identifier that is associated to the object that was inspected to produce the {{RTCTransportStats}} associated with this candidate.
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 the {{RTCIceCandidateStats/address}} member as null in the
{{RTCIceCandidateStats}} dictionary of any remote candidate. Once a {{RTCPeerConnection}}
instance learns on an address by the web application using {{RTCPeerConnection/addIceCandidate()}},
the user agent can expose the 'address' member value in any remote
{{RTCIceCandidateStats}} dictionary of the corresponding {{RTCPeerConnection}} that
matches the newly learnt address.
It is the port number of the candidate.
Valid values for transport is one of "udp" and "tcp". Based
on the "transport" defined in [[!RFC5245]] section 15.1.
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".
This enumeration is defined in [[WEBRTC]].
Calculated as defined in [[!RFC5245]] section 15.1.
For local candidates this is the URL of the ICE server from which the candidate was obtained. It is the same as the {{RTCPeerConnectionIceEvent/url}} surfaced in the {{RTCPeerConnectionIceEvent}}.
For remote candidates, this property is not present.
dictionary 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;
DOMHighResTimeStamp firstRequestTimestamp;
DOMHighResTimeStamp lastRequestTimestamp;
DOMHighResTimeStamp lastResponseTimestamp;
double totalRoundTripTime;
double currentRoundTripTime;
double availableOutgoingBitrate;
double availableIncomingBitrate;
unsigned long circuitBreakerTriggerCount;
unsigned long long requestsReceived;
unsigned long long requestsSent;
unsigned long long responsesReceived;
unsigned long long responsesSent;
unsigned long long retransmissionsReceived;
unsigned long long retransmissionsSent;
unsigned long long consentRequestsSent;
DOMHighResTimeStamp consentExpiredTimestamp;
unsigned long packetsDiscardedOnSend;
unsigned long long bytesDiscardedOnSend;
unsigned long long requestBytesSent;
unsigned long long consentRequestBytesSent;
unsigned long long responseBytesSent;
};
It is a unique identifier that is associated to the object that was inspected to produce the {{RTCTransportStats}} associated with this candidate pair.
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.
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.
Represents the state of the checklist for the local and remote candidates in a pair.
Related to updating the nominated flag described in Section 7.1.3.2.4 of [[!RFC5245]].
Represents the total number of packets sent on this candidate pair.
Represents the total number of packets received on this candidate pair.
Represents the total number of payload bytes sent on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.
Represents the total number of payload bytes received on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.
Represents the timestamp at which the last packet was sent on this particular candidate pair, excluding STUN packets.
Represents the timestamp at which the last packet was received on this particular candidate pair, excluding STUN packets.
Represents the timestamp at which the first STUN request was sent on this particular candidate pair.
Represents the timestamp at which the last STUN request was sent on this
particular candidate pair. The average interval between two consecutive
connectivity checks sent can be calculated with (lastRequestTimestamp -
firstRequestTimestamp) / requestsSent.
Represents the timestamp at which the last STUN response was received on this particular candidate pair.
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 by {{responsesReceived}}.
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]].
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.
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.
Represents the number of times the circuit breaker is triggered for this particular 5-tuple. Ceasing transmission when a circuit breaker is triggered is defined in Section 4.5 of [[!RFC8083]]. The field MUST return undefined for user-agents that do not implement the circuit-breaker algorithm.
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.
Represents the total number of connectivity check requests sent (not including retransmissions).
Represents the total number of connectivity check responses received.
Represents the total number of connectivity check responses sent. Since we cannot distinguish connectivity check requests and consent requests, all responses are counted.
Represents the total number of connectivity check request retransmissions received. Retransmissions are defined as connectivity check requests with a TRANSACTION_TRANSMIT_COUNTER attribute where the "req" field is larger than 1, as defined in [[!RFC7982]].
Represents the total number of connectivity check request retransmissions sent.
Represents the total number of consent requests sent.
Represents the timestamp at which the latest valid STUN binding response expired, as defined in [[!RFC7675]] section 5.1. If a valid STUN binding response has not been made ({{responsesReceived}} is zero) or the latest one has not expired this value must be undefined.
Total number of packets for this candidate pair that have been discarded due to socket errors, i.e. a socket error occured when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.
Total number of bytes for this candidate pair that have been discarded due to socket errors, i.e. a socket error occured 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.
requestBytesSent of type unsigned long long
Total number of bytes sent for connectivity checks.
consentRequestBytesSent of type unsigned long long
Total number of bytes sent for consent requests.
responseBytesSent of type unsigned long long
Total number of bytes sent for connectivity check responses.
enum RTCStatsIceCandidatePairState {
"frozen",
"waiting",
"in-progress",
"failed",
"succeeded"
};
| Enumeration 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]]. |
dictionary RTCCertificateStats : RTCStats {
required DOMString fingerprint;
required DOMString fingerprintAlgorithm;
required DOMString base64Certificate;
DOMString issuerCertificateId;
};
The fingerprint of the certificate. Only use the fingerprint value as defined in Section 5 of [[!RFC4572]].
The hash function used to compute the certificate fingerprint. For instance,
"sha-256".
The DER-encoded base-64 representation of the certificate.
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.
dictionary RTCIceServerStats : RTCStats {
required DOMString url;
long port;
DOMString relayProtocol;
unsigned long totalRequestsSent;
unsigned long totalResponsesReceived;
double totalRoundTripTime;
};
The URL of the ICE server (e.g. TURN or STUN server).
It is the port number used by the client.
relayProtocol of type DOMString
It is the protocol used by the endpoint to communicate with the ICE server.
Valid values are udp, tcp, or tls as
defined in {{RTCIceCandidateStats}}.
This is the same value that is used for the relay protocol of local ICE candidates.
The total amount of requests that have been sent to this server.
The total amount of responses received from this server.
The sum of RTTs for all requests that have been sent where a response has been received.
dictionary 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).
stream.id property
This is the {{RTCStats/id}} of the stats object, not the track.id.
An RTCSenderVideoTrackAttachmentStats object represents the stats about one attachment of a video MediaStreamTrack to the RTCPeerConnection object for which one calls getStats.
It appears in the stats as soon as it is attached (via addTrack, via addTransceiver, via replaceTrack on an RTCRtpSender object).
If a video track is attached twice (via addTransceiver or replaceTrack), there will be two RTCSenderVideoTrackAttachmentStats objects, one for each attachment. They will have the same "trackIdentifier" member, but different "id" members.
This dictionary was made obsolete after its members were moved to "media-source", "sender" and "outbound-rtp" (to enable simulcast stats) and the "onstatsended" event was removed, making the "track" stats redundant.
dictionary RTCSenderVideoTrackAttachmentStats : RTCVideoSenderStats {
};
An RTCSenderAudioTrackAttachmentStats object represents the stats about one attachment of an audio MediaStreamTrack to the RTCPeerConnection object for which one calls getStats.
It appears in the stats as soon as it is attached (via addTrack, via addTransceiver, via replaceTrack on an RTCRtpSender object).
If an audio track is attached twice (via addTransceiver or replaceTrack), there will be two RTCSenderAudioTrackAttachmentStats objects, one for each attachment. They will have the same "trackIdentifier" member, but different "id" members.
This dictionary was made obsolete after its members were moved to "media-source", "sender" and "outbound-rtp" (to enable simulcast stats) and the "onstatsended" event was removed, making the "track" stats redundant.
dictionary RTCSenderAudioTrackAttachmentStats : RTCAudioSenderStats {
};
The {{RTCReceiverVideoTrackAttachmentStats}} is a copy of {{RTCVideoReceiverStats}}. It adds no new information, it only exists for backwards-compatibility reasons as an obsolete dictionary.
dictionary RTCReceiverVideoTrackAttachmentStats : RTCVideoReceiverStats {};
The {{RTCReceiverAudioTrackAttachmentStats}} is a copy of
RTCAudioReceiverStats. It adds no new information, it
only exists for backwards-compatibility reasons as an obsolete
dictionary.
dictionary RTCReceiverAudioTrackAttachmentStats : RTCAudioReceiverStats {};
partial dictionary RTCCodecStats {
DOMString implementation;
};
This was moved to {{RTCInboundRtpStreamStats}}.{{RTCInboundRtpStreamStats}}/decoderImplementation}} and {{RTCOutboundRtpStreamStats}}.{{RTCOutboundRtpStreamStats/encoderImplementation}} in August 2019.
partial dictionary RTCIceCandidateStats {
boolean deleted = false;
boolean isRemote;
};
This field was obsoleted because if the ICE candidate is deleted it no longer appears in {{RTCPeerConnection/getStats()}}.
false indicates that this represents a local candidate;
true indicates that this represents a remote candidate.
partial dictionary RTCIceCandidatePairStats {
double totalRtt;
double currentRtt;
unsigned long long priority;
};
This field got renamed to {{totalRoundTripTime}} in Dec 2016.
This field got renamed to {{currentRoundTripTime}} in Dec 2016.
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.
partial dictionary RTCRtpStreamStats {
DOMString mediaType;
double averageRTCPInterval;
};
This field got renamed to {{kind}} in Feb 2018.
This field got renamed to {{averageRtcpInterval}} in Jan 2018.
partial dictionary RTCInboundRtpStreamStats {
DOMString trackId;
double fractionLost;
};
The identifier of the stats object representing the receiving track, an {{RTCReceiverAudioTrackAttachmentStats}} or {{RTCReceiverVideoTrackAttachmentStats}}.
This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.
This field was moved to {{RTCRemoteInboundRtpStreamStats}} in December 2017.
partial dictionary RTCOutboundRtpStreamStats {
DOMString trackId;
};
The identifier of the stats object representing the current track attachment to the sender of this stream, an {{RTCSenderAudioTrackAttachmentStats}} or {{RTCSenderVideoTrackAttachmentStats}}.
This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.
partial dictionary RTCMediaHandlerStats {
RTCPriorityType priority;
boolean remoteSource;
};
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.
Only applicable for {{RTCStatsType/"track"}} stats.
false if the track attachment is on an
{{RTCRtpSender}}, true if the track attachment is on
an {{RTCRtpReceiver}}.
This was originally defined as {{RTCMediaSourceStats/relayedSource}} but implementations had implemented it according to this current definition. With "track" stats made obsolete, and this information being available elsewhere, this metric was made obsolete in April, 2020.
partial dictionary RTCAudioHandlerStats {
double audioLevel;
double totalAudioEnergy;
double totalSamplesDuration;
boolean voiceActivityFlag;
};
This field was moved to {{RTCAudioReceiverStats}} and {{RTCAudioSourceStats}} in June 2019.
This field was moved to {{RTCAudioReceiverStats}} and {{RTCAudioSourceStats}} in June 2019.
This field was moved to {{RTCAudioReceiverStats}} and {{RTCAudioSourceStats}} in June 2019.
This field was moved to {{RTCOutboundRtpStreamStats}} and {{RTCInboundRtpStreamStats}} in August 2019.
partial dictionary RTCAudioSenderStats {
unsigned long long totalSamplesSent;
double echoReturnLoss;
double echoReturnLossEnhancement;
};
This was moved to {{RTCOutboundRtpStreamStats}} in August 2019.
This was moved to {{RTCAudioSourceStats}} in August 2019.
This was moved to {{RTCAudioSourceStats}} in August 2019.
partial dictionary RTCAudioReceiverStats {
DOMHighResTimeStamp estimatedPlayoutTimestamp;
double jitterBufferDelay;
unsigned long long jitterBufferEmittedCount;
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;
};
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
partial dictionary RTCVideoHandlerStats {
unsigned long frameWidth;
unsigned long frameHeight;
double framesPerSecond;
};
This was moved to {{RTCOutboundRtpStreamStats}} and {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCOutboundRtpStreamStats}} and {{RTCInboundRtpStreamStats}} in August 2019.
For the sending case, this was replaced by {{RTCVideoSourceStats}}.{{RTCVideoSourceStats/framesPerSecond}} in May 2019 representing the frame rate of the track. For the receiving case, this was moved to {{RTCInboundRtpStreamStats}} in August 2019 representing the decoding frame rate. In August 2019, {{RTCOutboundRtpStreamStats/framesPerSecond}} was also added to {{RTCOutboundRtpStreamStats}}, representing the encoding frame rate (which may be lower than the source frame rate).
partial dictionary RTCVideoSenderStats {
unsigned long keyFramesSent;
unsigned long framesCaptured;
unsigned long framesSent;
unsigned long hugeFramesSent;
};
This field was replaced by {{RTCOutboundRtpStreamStats/keyFramesEncoded}} in {{RTCOutboundRtpStreamStats}} in June 2019. There were no known implementations supporting the old field at the time of the change.
This was replaced by {{RTCVideoSourceStats}}.frames in May 2019.
This was moved to {{RTCOutboundRtpStreamStats}} in August 2019.
This was moved to {{RTCOutboundRtpStreamStats}} in August 2019.
partial dictionary RTCVideoReceiverStats {
unsigned long keyFramesReceived;
DOMHighResTimeStamp estimatedPlayoutTimestamp;
double jitterBufferDelay;
unsigned long long jitterBufferEmittedCount;
unsigned long framesReceived;
unsigned long framesDecoded;
unsigned long framesDropped;
unsigned long partialFramesLost;
unsigned long fullFramesLost;
};
This field was replaced by {{RTCInboundRtpStreamStats/keyFramesDecoded}} in {{RTCInboundRtpStreamStats}} in June 2019. There were no known implementations supporting the old field at the time of the change.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
This was moved to {{RTCInboundRtpStreamStats}} in August 2019.
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 {{RTCAudioSourceStats/audioLevel}} statistic).
The following stats are deemed to be sensitive, and MUST NOT be reported for an isolated media stream:
| {{RTCStatsType}} | Dictionary | Fields |
|---|---|---|
| {{RTCStatsType/"codec"}} | {{RTCCodecStats}} | |
| {{RTCStatsType/"inbound-rtp"}} | {{RTCInboundRtpStreamStats}} | |
| {{RTCStatsType/"outbound-rtp"}} | {{RTCOutboundRtpStreamStats}} | |
| {{RTCStatsType/"remote-inbound-rtp"}} | {{RTCRemoteInboundRtpStreamStats}} | |
| {{RTCStatsType/"remote-outbound-rtp"}} | {{RTCRemoteOutboundRtpStreamStats}} | |
| {{RTCStatsType/"media-source"}} | {{RTCAudioSourceStats}} {{RTCVideoSourceStats}} | |
| {{RTCStatsType/"csrc"}} | {{RTCRtpContributingSourceStats}} | |
| {{RTCStatsType/"peer-connection"}} | {{RTCPeerConnectionStats}} | |
| {{RTCStatsType/"data-channel"}} | {{RTCDataChannelStats}} | |
| {{RTCStatsType/"transceiver"}} | {{RTCRtpTransceiverStats}} | |
| {{RTCStatsType/"sender"}} | {{RTCAudioSenderStats}} {{RTCVideoSenderStats}} | |
| {{RTCStatsType/"receiver"}} | {{RTCMediaHandlerStats}} | |
| {{RTCStatsType/"transport"}} | {{RTCTransportStats}} | |
| {{RTCStatsType/"sctp-transport"}} | {{RTCSctpTransportStats}} | |
| {{RTCStatsType/"candidate-pair"}} | {{RTCIceCandidatePairStats}} | |
| {{RTCStatsType/"local-candidate"}} | {{RTCIceCandidateStats}} | |
| {{RTCStatsType/"remote-candidate"}} | {{RTCIceCandidateStats}} | |
| {{RTCStatsType/"certificate"}} | {{RTCCertificateStats}} | |
| {{RTCStatsType/"ice-server"}} | {{RTCIceServerStats}} |
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.