Identifiers for WebRTC's Statistics API

Abstract

This document defines a set of WebIDL objects that allow access to the statistical information about a RTCPeerConnection.

These objects are returned from the getStats API that is specified in [WEBRTC].

The dictionaries for RTP statistics are structured as a hierarchy, so that those stats that make sense in many different contexts are represented just once in IDL.

The metrics exposed here correspond to local measurements and those reported by RTCP packets. Compound RTCP packets contain multiple RTCP report blocks, such as Sender Report (SR) and Receiver Report (RR) whereas a non-compound RTCP packets may contain just a single RTCP SR or RR block.

The lifetime of all RTP monitored objects starts when the RTP stream is first used: When the first RTP packet is sent or received on the SSRC it represents, or when the first RTCP packet is sent or received that refers to the SSRC of the RTP stream.

RTP monitored objects are not deleted.

The hierarchy is as follows:

RTCRtpStreamStats: Stats that apply to any end of any RTP stream

RTCReceivedRtpStreamStats: Stats measured at the receiving end of an RTP stream, known either because they're measured locally or transmitted via an RTCP Receiver Report (RR) or Extended Report (XR) block.
- RTCInboundRtpStreamStats: Stats that can only be measured at the local receiving end of an RTP stream.
- RTCRemoteInboundRtpStreamStats: Stats relevant to the remote receiving end of an RTP stream - usually computed by combining local data with data received via an RTCP RR or XR block.
RTCSentRtpStreamStats: Stats measured at the sending end of an RTP stream, known either because they're measured locally or because they're received via RTCP, usually in an RTCP Sender Report (SR).
- RTCOutboundRtpStreamStats: Stats measured locally.
- RTCRemoteOutboundRtpStreamStats: Stats relevant to the remote sending end of an RTP stream, usually computed based on an RTCP SR.

WebIDLdictionary RTCRtpStreamStats : RTCStats {
             required unsigned long       ssrc;
             required DOMString           kind;
             DOMString           transportId;
             DOMString           codecId;
};

ssrc of type unsigned long

The synchronization source (ssrc) identifier is an unsigned integer value per [RFC3550] used to identify the stream of RTP packets that this stats object is describing.

For outbound and inbound local, ssrc describes the stats for the track that were sent and received, respectively by those endpoints. For the remote inbound and remote outbound, ssrc describes the stats for the track that were received by and sent to the remote endpoint.

kind of type DOMString

Either "audio" or "video". This MUST match the kind attribute of the related MediaStreamTrack.

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this RTP stream.

codecId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCCodecStats associated with this RTP stream.

Codecs are created when registered for an RTP transport, but only the subset of codecs that are in use (referenced by an RTP stream) are exposed in getStats().

The RTCCodecStats object is created when one or more codecId references the codec. When there no longer exists any reference to the RTCCodecStats, the stats object is deleted. If the same codec is used again in the future, the RTCCodecStats object is revived with the same id as before.

Codec objects may be referenced by multiple RTP streams in media sections using the same transport, but similar codecs in different transports have different RTCCodecStats objects.

Note

User agents are expected to coalesce information into a single "codec" entry per payload type per transport, unless sdpFmtpLine differs per direction, in which case two entries (one for encode and one for decode) are needed.

WebIDLdictionary RTCCodecStats : RTCStats {
             required unsigned long payloadType;
             required DOMString     transportId;
             required DOMString     mimeType;
             unsigned long clockRate;
             unsigned long channels;
             DOMString     sdpFmtpLine;
};

payloadType of type unsigned long: Payload type as used in RTP encoding or decoding.
transportId of type DOMString: The unique identifier of the transport on which this codec is being used, which can be used to look up the corresponding RTCTransportStats object.
mimeType of type DOMString: The codec MIME media type/subtype. e.g., video/vp8 or equivalent.
clockRate of type unsigned long: Represents the media sampling rate.
channels of type unsigned long: When present, indicates the number of channels (mono=1, stereo=2).
sdpFmtpLine of type DOMString: The a=fmtp line in the SDP corresponding to the codec, i.e., after the colon following the PT. This defined by [JSEP] in Section 5.7.

WebIDLdictionary RTCReceivedRtpStreamStats : RTCRtpStreamStats {
             unsigned long long   packetsReceived;
             long long            packetsLost;
             double               jitter;
             unsigned long        framesDropped;
};

packetsReceived of type unsigned long long: Total number of RTP packets received for this SSRC. At the receiving endpoint, this is calculated as defined in [RFC3550] section 6.4.1. At the sending endpoint the packetsReceived is estimated by subtracting the Cumulative Number of Packets Lost from the Extended Highest Sequence Number Received, both reported in the RTCP Receiver Report, and then subtracting the initial Extended Sequence Number that was sent to this SSRC in a RTCP Sender Report and then adding one, to mirror what is discussed in Appendix A.3 in [RFC3550], but for the sender side. If no RTCP Receiver Report has been received yet, then return 0.
packetsLost of type long long: Total number of RTP packets lost for this SSRC. Calculated as defined in [RFC3550] section 6.4.1. Note that because of how this is estimated, it can be negative if more packets are received than sent.
jitter of type double: Packet Jitter measured in seconds for this SSRC. Calculated as defined in section 6.4.1. of [RFC3550].
framesDropped of type unsigned long: Only exists for video. The total number of frames dropped prior to decode or dropped because the frame missed its display deadline for this receiver's track. The measurement begins when the receiver is created and is a cumulative metric as defined in Appendix A (g) of [RFC7004].

The RTCInboundRtpStreamStats dictionary represents the measurement metrics for the incoming RTP media stream. The timestamp reported in the statistics object is the time at which the data was sampled.

WebIDLdictionary RTCInboundRtpStreamStats : RTCReceivedRtpStreamStats {
             required DOMString   trackIdentifier;
             required DOMString   kind;
             DOMString            mid;
             DOMString            remoteId;
             unsigned long        framesDecoded;
             unsigned long        keyFramesDecoded;
             unsigned long        frameWidth;
             unsigned long        frameHeight;
             double               framesPerSecond;
             unsigned long long   qpSum;
             double               totalDecodeTime;
             double               totalInterFrameDelay;
             double               totalSquaredInterFrameDelay;
             DOMHighResTimeStamp  lastPacketReceivedTimestamp;
             unsigned long long   headerBytesReceived;
             unsigned long long   packetsDiscarded;
             unsigned long long   fecPacketsReceived;
             unsigned long long   fecPacketsDiscarded;
             unsigned long long   bytesReceived;
             unsigned long        nackCount;
             unsigned long        firCount;
             unsigned long        pliCount;
             double               totalProcessingDelay;
             DOMHighResTimeStamp  estimatedPlayoutTimestamp;
             double               jitterBufferDelay;
             double               jitterBufferTargetDelay;
             unsigned long long   jitterBufferEmittedCount;
             double               jitterBufferMinimumDelay;
             unsigned long long   totalSamplesReceived;
             unsigned long long   concealedSamples;
             unsigned long long   silentConcealedSamples;
             unsigned long long   concealmentEvents;
             unsigned long long   insertedSamplesForDeceleration;
             unsigned long long   removedSamplesForAcceleration;
             double               audioLevel;
             double               totalAudioEnergy;
             double               totalSamplesDuration;
             unsigned long        framesReceived;
             DOMString            decoderImplementation;
             DOMString            playoutId;
            };

trackIdentifier of type DOMString

The value of the MediaStreamTrack's id attribute.

kind of type DOMString

The value of the MediaStreamTrack's kind attribute. This is either "audio" or "video".

mid of type DOMString

If the RTCRtpTransceiver owning this stream has a mid value that is not null, this is that value, otherwise this member is not present.

remoteId of type DOMString

The remoteId is used for looking up the remote RTCRemoteOutboundRtpStreamStats object for the same SSRC.

framesDecoded

Only exists for video. It represents the total number of frames correctly decoded for this RTP stream, i.e., frames that would be displayed if no frames are dropped.

keyFramesDecoded of type unsigned long

Only exists for video. It represents the total number of key frames, such as key frames in VP8 [RFC6386] or IDR-frames in H.264 [RFC6184], successfully decoded for this RTP media stream. This is a subset of framesDecoded. framesDecoded - keyFramesDecoded gives you the number of delta frames decoded.

frameWidth of type unsigned long

Only exists for video. Represents the width of the last decoded frame. Before the first frame is decoded this member does not exist.

frameHeight of type unsigned long

Only exists for video. Represents the height of the last decoded frame. Before the first frame is decoded this member does not exist.

framesPerSecond of type double

Only exists for video. The number of decoded frames in the last second.

qpSum of type unsigned long long

Only exists for video. The sum of the QP values of frames decoded by this receiver. The count of frames is in framesDecoded.

The definition of QP value depends on the codec; for VP8, the QP value is the value carried in the frame header as the syntax element y_ac_qi, and defined in [RFC6386] section 19.2. Its range is 0..127.

Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.

totalDecodeTime of type double

Total number of seconds that have been spent decoding the framesDecoded frames of this stream. The average decode time can be calculated by dividing this value 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.

totalInterFrameDelay of type double

Sum of the interframe delays in seconds between consecutively decoded frames, recorded just after a frame has been decoded. The interframe delay variance be calculated from totalInterFrameDelay, totalSquaredInterFrameDelay, and framesDecoded according to the formula: (totalSquaredInterFrameDelay - totalInterFrameDelay^2/ framesDecoded)/framesDecoded.

totalSquaredInterFrameDelay of type double

Sum of the squared interframe delays in seconds between consecutively decoded frames, recorded just after a frame has been decoded. See totalInterFrameDelay for details on how to calculate the interframe delay variance.

lastPacketReceivedTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was received for this SSRC. This differs from timestamp, which represents the time at which the statistics were generated by the local endpoint.

headerBytesReceived of type unsigned long long

Total number of RTP header and padding bytes received for this SSRC. This does not include the size of transport layer headers such as IP or UDP. headerBytesReceived + bytesReceived equals the number of bytes received as payload over the transport.

packetsDiscarded of type unsigned long long

The cumulative number of RTP packets discarded by the jitter buffer due to late or early-arrival, i.e., these packets are not played out. RTP packets discarded due to packet duplication are not reported in this metric [XRBLOCK-STATS]. Calculated as defined in [RFC7002] section 3.2 and Appendix A.a.

fecPacketsReceived of type unsigned long long

Total number of RTP FEC packets received for this SSRC. This counter can also be incremented when receiving FEC packets in-band with media packets (e.g., with Opus).

fecPacketsDiscarded of type unsigned long long

Total number of RTP FEC packets received for this SSRC where the error correction payload was discarded by the application. This may happen 1. if all the source packets protected by the FEC packet were received or already recovered by a separate FEC packet, or 2. if the FEC packet arrived late, i.e., outside the recovery window, and the lost RTP packets have already been skipped during playout. This is a subset of fecPacketsReceived.

bytesReceived of type unsigned long long

Total number of bytes received for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.

firCount of type unsigned long

Only exists for video. Count the total number of Full Intra Request (FIR) packets sent by this receiver. Calculated as defined in [RFC5104] section 4.3.1. and does not use the metric indicated in [RFC2032], because it was deprecated by [RFC4587].

pliCount of type unsigned long

Only exists for video. Count the total number of Picture Loss Indication (PLI) packets sent by this receiver. Calculated as defined in [RFC4585] section 6.3.1.

totalProcessingDelay of type double

It is the sum of the time, in seconds, each audio sample or video frame takes from the time the first RTP packet is received (reception timestamp) and to the time the corresponding sample or frame is decoded (decoded timestamp). At this point the audio sample or video frame is ready for playout by the MediaStreamTrack. Typically ready for playout here means after the audio sample or video frame is fully decoded by the decoder.

Given the complexities involved, the time of arrival or the reception timestamp is measured as close to the network layer as possible and the decoded timestamp is measured as soon as the complete sample or frame is decoded.

In the case of audio, several samples are received in the same RTP packet, all samples will share the same reception timestamp and different decoded timestamps. In the case of video, the frame is received over several RTP packets, in this case the earliest timestamp containing the frame is counted as the reception timestamp, and the decoded timestamp corresponds to when the complete frame is decoded.

This metric is not incremented for frames that are not decoded, i.e. framesDropped. The average processing delay can be calculated by dividing the totalProcessingDelay with the framesDecoded for video (or povisional stats spec totalSamplesDecoded for audio).

nackCount of type unsigned long

Count the total number of Negative ACKnowledgement (NACK) packets sent by this receiver. Calculated as defined in [RFC4585] section 6.2.1.

estimatedPlayoutTimestamp of type DOMHighResTimeStamp

This is the estimated playout time of this receiver's track. The playout time is the NTP timestamp of the last playable audio sample or video frame that has a known timestamp (from an RTCP SR packet mapping RTP timestamps to NTP timestamps), extrapolated with the time elapsed since it was ready to be played out. This is the "current time" of the track in NTP clock time of the sender and can be present even if there is no audio currently playing.

This can be useful for estimating how much audio and video is out of sync for two tracks from the same source, audioTrackStats.estimatedPlayoutTimestamp - videoTrackStats.estimatedPlayoutTimestamp.

jitterBufferDelay of type double

The purpose of the jitter buffer is to recombine RTP packets into frames (in the case of video) and have smooth playout. The model described here assumes that the samples or frames are still compressed and have not yet been decoded. It is the sum of the time, in seconds, each audio sample or a video frame takes from the time the first packet is received by the jitter buffer (ingest timestamp) to the time it exits the jitter buffer (emit timestamp). In the case of audio, several samples belong to the same RTP packet, hence they will have the same ingest timestamp but different jitter buffer emit timestamps. In the case of video, the frame maybe is received over several RTP packets, hence the ingest timestamp is the earliest packet of the frame that entered the jitter buffer and the emit timestamp is when the whole frame exits the jitter buffer. This metric increases upon samples or frames exiting, having completed their time in the buffer (and incrementing jitterBufferEmittedCount). The average jitter buffer delay can be calculated by dividing the jitterBufferDelay with the jitterBufferEmittedCount.

jitterBufferTargetDelay of type double

This value is increased by the target jitter buffer delay every time a sample is emitted by the jitter buffer. The added target is the target delay, in seconds, at the time that the sample was emitted from the jitter buffer. To get the average target delay, divide by jitterBufferEmittedCount.

jitterBufferEmittedCount of type unsigned long long

The total number of audio samples or video frames that have come out of the jitter buffer (increasing jitterBufferDelay).

jitterBufferMinimumDelay of type double

There are various reasons why the jitter buffer delay might be increased to a higher value, such as to achieve AV synchronization or because a playoutDelay was set on a RTCRtpReceiver. When using one of these mechanisms, it can be useful to keep track of the minimal jitter buffer delay that could have been achieved, so WebRTC clients can track the amount of additional delay that is being added.

This metric works the same way as jitterBufferTargetDelay, except that it is not affected by external mechanisms that increase the jitter buffer target delay, such as playoutDelay (see link above), AV sync, or any other mechanisms. This metric is purely based on the network characteristics such as jitter and packet loss, and can be seen as the minimum obtainable jitter buffer delay if no external factors would affect it. The metric is updated every time jitterBufferEmittedCount is updated.

totalSamplesReceived of type unsigned long long

Only exists for audio. The total number of samples that have been received on this RTP stream. This includes concealedSamples.

concealedSamples of type unsigned long long

Only exists for audio. The total number of samples that are concealed samples. A concealed sample is a sample that was replaced with synthesized samples generated locally before being played out. Examples of samples that have to be concealed are samples from lost packets (reported in packetsLost) or samples from packets that arrive too late to be played out (reported in packetsDiscarded).

silentConcealedSamples of type unsigned long long

Only exists for audio. The total number of concealed samples inserted that are "silent". Playing out silent samples results in silence or comfort noise. This is a subset of concealedSamples.

concealmentEvents of type unsigned long long

Only exists for audio. The number of concealment events. This counter increases every time a concealed sample is synthesized after a non-concealed sample. That is, multiple consecutive concealed samples will increase the concealedSamples count multiple times but is a single concealment event.

insertedSamplesForDeceleration of type unsigned long long

Only exists for audio. When playout is slowed down, this counter is increased by the difference between the number of samples received and the number of samples played out. If playout is slowed down by inserting samples, this will be the number of inserted samples.

removedSamplesForAcceleration of type unsigned long long

Only exists for audio. When playout is sped up, this counter is increased by the difference between the number of samples received and the number of samples played out. If speedup is achieved by removing samples, this will be the count of samples removed.

audioLevel of type double

Only exists for audio. Represents the audio level of the receiving track. For audio levels of tracks attached locally, see RTCAudioSourceStats instead.

The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

The audioLevel is averaged over some small interval, using the algorithm described under totalAudioEnergy. The interval used is implementation dependent.

totalAudioEnergy of type double

Only exists for audio. Represents the audio energy of the receiving track. For audio energy of tracks attached locally, see RTCAudioSourceStats instead.

This value MUST be computed as follows: for each audio sample that is received (and thus counted by totalSamplesReceived), add the sample's value divided by the highest-intensity encodable value, squared and then multiplied by the duration of the sample in seconds. In other words, duration * Math.pow(energy/maxEnergy, 2).

This can be used to obtain a root mean square (RMS) value that uses the same units as audioLevel, as defined in [RFC6464]. It can be converted to these units using the formula Math.sqrt(totalAudioEnergy/totalSamplesDuration). This calculation can also be performed using the differences between the values of two different 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.

totalSamplesDuration of type double

Only exists for audio. Represents the audio duration of the receiving track. For audio durations of tracks attached locally, see RTCAudioSourceStats instead.

Represents the total duration in seconds of all samples that have been received (and thus counted by totalSamplesReceived). Can be used with totalAudioEnergy to compute an average audio level over different intervals.

framesReceived of type unsigned long

Only exists for video. Represents the total number of complete frames received on this RTP stream. This metric is incremented when the complete frame is received.

decoderImplementation of type DOMString

Identifies the decoder implementation used. This is useful for diagnosing interoperability issues.

If too much information is given here, it increases the fingerprint surface. Since it is only given for active tracks, the incremental exposure is small.

playoutId of type DOMString

If audio playout is happening, this is used to look up the corresponding RTCAudioPlayoutStats.

The RTCRemoteInboundRtpStreamStats dictionary represents the remote endpoint's measurement metrics for a particular incoming RTP stream (corresponding to an outgoing RTP stream at the sending endpoint). The timestamp reported in the statistics object is the time at which the corresponding RTCP RR was received.

WebIDLdictionary RTCRemoteInboundRtpStreamStats : RTCReceivedRtpStreamStats {
             DOMString            localId;
             double               roundTripTime;
             double               totalRoundTripTime;
             double               fractionLost;
             unsigned long long   roundTripTimeMeasurements;
};

localId of type DOMString: The localId is used for looking up the local RTCOutboundRtpStreamStats object for the same SSRC.
roundTripTime of type double: Estimated round trip time for this SSRC based on the RTCP timestamps in the RTCP Receiver Report (RR) and measured in seconds. Calculated as defined in section 6.4.1. of [RFC3550]. If no RTCP Receiver Report is received with a DLSR value other than 0, the round trip time is left undefined.
totalRoundTripTime of type double: Represents the cumulative sum of all round trip time measurements in seconds since the beginning of the session. The individual round trip time is calculated based on the RTCP timestamps in the RTCP Receiver Report (RR) [RFC3550], hence undefined roundtrip times are not added. The average round trip time can be computed from totalRoundTripTime by dividing it by roundTripTimeMeasurements.
fractionLost of type double: The fraction packet loss reported for this SSRC. Calculated as defined in [RFC3550] section 6.4.1 and Appendix A.3.
roundTripTimeMeasurements of type unsigned long long: Represents the total number of RTCP RR blocks received for this SSRC that contain a valid round trip time. This counter will not increment if the roundTripTime is undefined.

WebIDLdictionary RTCSentRtpStreamStats : RTCRtpStreamStats {
             unsigned long      packetsSent;
             unsigned long long bytesSent;
};

packetsSent of type unsigned long long: Total number of RTP packets sent for this SSRC. This includes retransmissions. Calculated as defined in [RFC3550] section 6.4.1.
bytesSent of type unsigned long long: Total number of bytes sent for this SSRC. This includes retransmissions. Calculated as defined in [RFC3550] section 6.4.1.

The RTCOutboundRtpStreamStats dictionary represents the measurement metrics for the outgoing RTP stream. The timestamp reported in the statistics object is the time at which the data was sampled.

WebIDLdictionary RTCOutboundRtpStreamStats : RTCSentRtpStreamStats {
             DOMString            mid;
             DOMString            mediaSourceId;
             DOMString            remoteId;
             DOMString            rid;
             unsigned long long   headerBytesSent;
             unsigned long long   retransmittedPacketsSent;
             unsigned long long   retransmittedBytesSent;
             double               targetBitrate;
             unsigned long long   totalEncodedBytesTarget;
             unsigned long        frameWidth;
             unsigned long        frameHeight;
             double               framesPerSecond;
             unsigned long        framesSent;
             unsigned long        hugeFramesSent;
             unsigned long        framesEncoded;
             unsigned long        keyFramesEncoded;
             unsigned long long   qpSum;
             double               totalEncodeTime;
             double               totalPacketSendDelay;
             RTCQualityLimitationReason                 qualityLimitationReason;
             record<DOMString, double> qualityLimitationDurations;
             unsigned long        qualityLimitationResolutionChanges;
             unsigned long        nackCount;
             unsigned long        firCount;
             unsigned long        pliCount;
             DOMString            encoderImplementation;
             boolean              active;
};

mid of type DOMString

If the RTCRtpTransceiver owning this stream has a mid value that is not null, this is that value, otherwise this member is not present.

mediaSourceId of type DOMString

The identifier of the stats object representing the track currently attached to the sender of this stream, an RTCMediaSourceStats.

remoteId of type DOMString

The remoteId is used for looking up the remote RTCRemoteInboundRtpStreamStats object for the same SSRC.

rid of type DOMString

Exposes the rid encoding parameter of this RTP stream if it has been set, otherwise it is undefined. If set this value will be present regardless if the RID RTP header extension has been negotiated.

headerBytesSent of type unsigned long long

Total number of RTP header and padding bytes sent for this SSRC. This does not include the size of transport layer headers such as IP or UDP. headerBytesSent + bytesSent equals the number of bytes sent as payload over the transport.

retransmittedPacketsSent of type unsigned long long

The total number of packets that were retransmitted for this SSRC. This is a subset of packetsSent. If RTX is not negotiated, retransmitted packets are sent over this ssrc. If RTX was negotiated, retransmitted packets are sent over a separate ssrc but is still accounted for here.

retransmittedBytesSent of type unsigned long long

The total number of bytes that were retransmitted for this SSRC, only including payload bytes. This is a subset of bytesSent. If RTX is not negotiated, retransmitted bytes are sent over this ssrc. If RTX was negotiated, retransmitted bytes are sent over a separate ssrc but is still accounted for here.

targetBitrate of type double

Reflects the current encoder target in bits per second. The target is an instantanous value reflecting the encoder's settings, but the resulting payload bytes sent per second, excluding retransmissions, SHOULD closely correlate to the target. See also bytesSent and retransmittedBytesSent. The targetBitrate is defined in the same way as the Transport Independent Application Specific (TIAS) bitrate [RFC3890].

totalEncodedBytesTarget of type unsigned long long

This value is increased by the target frame size in bytes every time a frame has been encoded. The actual frame size may be bigger or smaller than this number. This value goes up every time framesEncoded goes up.

frameWidth of type unsigned long

Only exists for video. Represents the width of the last encoded frame. The resolution of the encoded frame may be lower than the media source (see RTCVideoSourceStats.width). Before the first frame is encoded this member does not exist.

frameHeight of type unsigned long

Only exists for video. Represents the height of the last encoded frame. The resolution of the encoded frame may be lower than the media source (see RTCVideoSourceStats.height). Before the first frame is encoded this member does not exist.

framesPerSecond of type double

Only exists for video. The number of encoded frames during the last second. This may be lower than the media source frame rate (see RTCVideoSourceStats.framesPerSecond).

framesSent of type unsigned long

Only exists for video. Represents the total number of frames sent on this RTP stream.

hugeFramesSent of type unsigned long

Only exists for video. Represents the total number of huge frames sent by this RTP stream. Huge frames, by definition, are frames that have an encoded size at least 2.5 times the average size of the frames. The average size of the frames is defined as the target bitrate per second divided by the target FPS at the time the frame was encoded. These are usually complex to encode frames with a lot of changes in the picture. This can be used to estimate, e.g slide changes in the streamed presentation.

The multiplier of 2.5 is choosen from analyzing encoded frame sizes for a sample presentation using WebRTC standalone implementation. 2.5 is a reasonably large multiplier which still caused all slide change events to be identified as a huge frames. It, however, produced 1.4% of false positive slide change detections which is deemed reasonable.

framesEncoded of type unsigned long

Only exists for video. It represents the total number of frames successfully encoded for this RTP media stream.

keyFramesEncoded of type unsigned long

Only exists for video. It represents the total number of key frames, such as key frames in VP8 [RFC6386] or IDR-frames in H.264 [RFC6184], successfully encoded for this RTP media stream. This is a subset of framesEncoded. framesEncoded - keyFramesEncoded gives you the number of delta frames encoded.

qpSum of type unsigned long long

Only exists for video. The sum of the QP values of frames encoded by this sender. The count of frames is in framesEncoded.

Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.

totalEncodeTime of type double

Total number of seconds that has been spent encoding the framesEncoded frames of this stream. The average encode time can be calculated by dividing this value 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.

totalPacketSendDelay of type double

The total number of seconds that packets have spent buffered locally before being transmitted onto the network. The time is measured from when a packet is emitted from the RTP packetizer until it is handed over to the OS network socket. This measurement is added to totalPacketSendDelay when packetsSent is incremented.

qualityLimitationReason of type RTCQualityLimitationReason

Only exists for video. The current reason for limiting the resolution and/or framerate, or "none" if not limited.

The implementation reports the most limiting factor. If the implementation is not able to determine the most limiting factor because multiple may exist, the reasons MUST be reported in the following order of priority: "bandwidth", "cpu", "other".

Note

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

qualityLimitationDurations of type record<DOMString, double>

Only exists for video. A record of the total time, in seconds, that this stream has spent in each quality limitation state. The record includes a mapping for all RTCQualityLimitationReason types, including "none".

The sum of all entries minus qualityLimitationDurations["none"] gives the total time that the stream has been limited.

qualityLimitationResolutionChanges of type unsigned long

Only exists for video. The number of times that the resolution has changed because we are quality limited (qualityLimitationReason has a value other than "none"). The counter is initially zero and increases when the resolution goes up or down. For example, if a 720p track is sent as 480p for some time and then recovers to 720p, qualityLimitationResolutionChanges will have the value 2.

nackCount of type unsigned long

Count the total number of Negative ACKnowledgement (NACK) packets received by this sender. Calculated as defined in [RFC4585] section 6.2.1.

firCount of type unsigned long

Only exists for video. Count the total number of Full Intra Request (FIR) packets received by this sender. Calculated as defined in [RFC5104] section 4.3.1. and does not use the metric indicated in [RFC2032], because it was deprecated by [RFC4587].

pliCount of type unsigned long

Only exists for video. Count the total number of Picture Loss Indication (PLI) packets received by this sender. Calculated as defined in [RFC4585] section 6.3.1.

encoderImplementation of type DOMString

Identifies the encoder implementation used. This is useful for diagnosing interoperability issues.

If too much information is given here, it increases the fingerprint surface. Since it is only given for active tracks, the incremental exposure is small.

active of type boolean

Indicates whether this RTP stream is configured to be sent or disabled. Note that an active stream can still not be sending, e.g. when being limited by network conditions.

WebIDLenum RTCQualityLimitationReason {
            "none",
            "cpu",
            "bandwidth",
            "other",
          };

`RTCQualityLimitationReason` Enumeration description
Enum value	Description
`none`	The resolution and/or framerate is not limited.
`cpu`	The resolution and/or framerate is primarily limited due to CPU load.
`bandwidth`	The resolution and/or framerate is primarily limited due to congestion cues during bandwidth estimation. Typical, congestion control algorithms use inter-arrival time, round-trip time, packet or other congestion cues to perform bandwidth estimation.
`other`	The resolution and/or framerate is primarily limited for a reason other than the above.

The RTCRemoteOutboundRtpStreamStats dictionary represents the remote endpoint's measurement metrics for its outgoing RTP stream (corresponding to an outgoing RTP stream at the sending endpoint). The timestamp reported in the statistics object is the time at which the corresponding RTCP SR was received.

WebIDLdictionary RTCRemoteOutboundRtpStreamStats : RTCSentRtpStreamStats {
             DOMString           localId;
             DOMHighResTimeStamp remoteTimestamp;
             unsigned long long  reportsSent;
             double              roundTripTime;
             double              totalRoundTripTime;
             unsigned long long  roundTripTimeMeasurements;
};

localId of type DOMString: The localId is used for looking up the local RTCInboundRtpStreamStats object for the same SSRC.
remoteTimestamp of type DOMHighResTimeStamp: remoteTimestamp, of type DOMHighResTimeStamp [HIGHRES-TIME], represents the remote timestamp at which these statistics were sent by the remote endpoint. This differs from 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.
reportsSent of type unsigned long long: Represents the total number of RTCP SR blocks sent for this SSRC.
roundTripTime of type double: Estimated round trip time for this SSRC based on the latest RTCP Sender Report (SR) that contains a DLRR report block as defined in [RFC3611]. The Calculation of the round trip time is defined in section 4.5. of [RFC3611]. If the latest SR does not contain the DLRR report block, or if the last RR timestamp in the DLRR report block is zero, or if the delay since last RR value in the DLRR report block is zero, the round trip time is left undefined.
totalRoundTripTime of type double: Represents the cumulative sum of all round trip time measurements in seconds since the beginning of the session. The individual round trip time is calculated based on the DLRR report block in the RTCP Sender Report (SR) [RFC3611], hence undefined roundtrip times are not added. The average round trip time can be computed from totalRoundTripTime by dividing it by roundTripTimeMeasurements.
roundTripTimeMeasurements of type unsigned long long: Represents the total number of RTCP Sender Report (SR) blocks received for this SSRC that can derive a valid round trip time according to [RFC3611]. This counter will not increment if the roundTripTime is undefined.

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 RTCRtpSenders. This is in contrast to RTCOutboundRtpStreamStats whose members describe metrics as measured after the encoding step. For example, a track may be captured from a high-resolution camera, its frames downscaled due to track constraints and then further downscaled by the encoders due to CPU and network conditions. This dictionary reflects the video frames or audio samples passed out from the track - after track constraints have been applied but before any encoding or further donwsampling occurs.

Media source objects are of either subdictionary RTCAudioSourceStats or RTCVideoSourceStats. The type is the same ("media-source") but kind is different ("audio" or "video") depending on the kind of track.

The media source stats objects are created when a track is attached to any RTCRtpSender and may subsequently be attached to multiple senders during its life. The life of this object ends when the track is no longer attached to any sender of the same RTCPeerConnection. If a track whose media source object ended is attached again this results in a new media source stats object whose counters (such as number of frames) are reset.

WebIDLdictionary RTCMediaSourceStats : RTCStats {
             required DOMString       trackIdentifier;
             required DOMString       kind;
};

trackIdentifier of type DOMString: The value of the MediaStreamTrack's id attribute.
kind of type DOMString: 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.

The RTCAudioSourceStats dictionary represents an audio track that is attached to one or more senders. It is an RTCMediaSourceStats whose kind is "audio".

WebIDLdictionary RTCAudioSourceStats : RTCMediaSourceStats {
              double              audioLevel;
              double              totalAudioEnergy;
              double              totalSamplesDuration;
              double              echoReturnLoss;
              double              echoReturnLossEnhancement;
              double              droppedSamplesDuration;
              double              totalCaptureDelay;
              unsigned long long  totalSamplesCaptured;
};

audioLevel of type double

Represents the audio level of the media source. For audio levels of remotely sourced tracks, see RTCInboundRtpStreamStats instead.

The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

The audioLevel is averaged over some small interval, using the algorithm described under totalAudioEnergy. The interval used is implementation dependent.

totalAudioEnergy of type double

Represents the audio energy of the media source. For audio energy of remotely sourced tracks, see RTCInboundRtpStreamStats instead.

This value MUST be computed as follows: for each audio sample produced by the media source during the lifetime of this stats object, add the sample's value divided by the highest-intensity encodable value, squared and then multiplied by the duration of the sample in seconds. In other words, duration * Math.pow(energy/maxEnergy, 2).

If multiple audio channels are used, the audio energy of a sample refers to the highest energy of any channel.

totalSamplesDuration of type double

Represents the audio duration of the media source. For audio durations of remotely sourced tracks, see RTCInboundRtpStreamStats instead.

Represents the total duration in seconds of all samples that have been produced by this source for the lifetime of this stats object. Can be used with totalAudioEnergy to compute an average audio level over different intervals.

totalSamplesDuration does not include samples dropped before reaching this media source, see droppedSamplesDuration.

echoReturnLoss of type double

Only exists when the MediaStreamTrack is sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.14.

If multiple audio channels are used, the channel of the least audio energy is considered for any sample.

echoReturnLossEnhancement of type double

Only exists when the MediaStreamTrack is sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.15.

If multiple audio channels are used, the channel of the least audio energy is considered for any sample.

droppedSamplesDuration of type double

Only applicable if this media source is backed by an audio capture device. The total duration, in seconds, of samples produced by the device that got dropped before reaching the media source.

totalCaptureDelay of type double

Only applicable if the audio source represents an audio capture device. This is the total delay, in seconds, for each audio sample between the time the sample was emitted by the capture device and the sample reaching the source. This can be used together with totalSamplesCaptured to calculate the average capture delay per sample.

totalSamplesCaptured of type unsigned long long

Only applicable if the audio source represents an audio capture device. This is the total number of captured samples reaching the audio source, i.e. that were not dropped by the capture pipeline. The frequency of the media source is not necessarily the same as the frequency of encoders later in the pipeline.

The RTCVideoSourceStats dictionary represents a video track that is attached to one or more senders. It is an RTCMediaSourceStats whose kind is "video".

WebIDLdictionary RTCVideoSourceStats : RTCMediaSourceStats {
             unsigned long   width;
             unsigned long   height;
             unsigned long   frames;
             double          framesPerSecond;
};

width of type unsigned long: The width, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not exist.
height of type unsigned long: The height, in pixels, of the last frame originating from this source. Before a frame has been produced this member does not exist.
frames of type unsigned long: The total number of frames originating from this source.
framesPerSecond of type double: The number of frames originating from this source, measured during the last second. For the first second of this object's lifetime this member does not exist.

Only applicable if the playout path represents an audio device. Represents one playout path - if the same playout stats object is referenced by multiple RTCInboundRtpStreamStats this is an indication that audio mixing is happening in which case sample counters in this stats object refer to the samples after mixing.

WebIDLdictionary RTCAudioPlayoutStats : RTCStats {
             double synthesizedSamplesDuration;
             double totalSamplesDuration;
             double totalPlayoutDelay;
             double totalSamplesCount;
};

synthesizedSamplesDuration of type double

If the playout path is unable to produce audio samples on time for device playout, samples are synthesized to be playout out instead. synthesizedSamplesDuration is measured in seconds and is incremented each time an audio sample is synthesized by this playout path. This metric can be used together with totalSamplesDuration to calculate the percentage of played out media being synthesized.

Synthesization typically only happens if the pipeline is underperforming. Samples synthesized by the RTCInboundRtpStreamStats are not counted for here, but in RTCInboundRtpStreamStats.concealedSamples.

totalSamplesDuration of type double

The total duration, in seconds, of all audio samples that have been playout. Includes both synthesized and non-synthesized samples.

totalPlayoutDelay of type double

When audio samples are pulled by the playout device, this counter is incremented with the estimated delay of the playout path for that audio sample. The playout delay includes the delay from being emitted to the actual time of playout on the device. This metric can be used together with totalSamplesCount to calculate the average playout delay per sample.

totalSamplesCount of type double

When audio samples are pulled by the playout device, this counter is incremented with the number of samples emitted for playout.

WebIDLdictionary RTCPeerConnectionStats : RTCStats {
            unsigned long dataChannelsOpened;
            unsigned long dataChannelsClosed;
};

dataChannelsOpened of type unsigned long: Represents the number of unique RTCDataChannels that have entered the "open" state during their lifetime.
dataChannelsClosed of type unsigned long: Represents the number of unique RTCDataChannels that have left the "open" state during their lifetime (due to being closed by either end or the underlying transport being closed). RTCDataChannels that transition from "connecting" to "closing" or "closed" without ever being "open" are not counted in this number.

The total number of open data channels at any time can be calculated as dataChannelsOpened - dataChannelsClosed. This number is always positive.

WebIDLdictionary RTCDataChannelStats : RTCStats {
             DOMString           label;
             DOMString           protocol;
             unsigned short      dataChannelIdentifier;
             required RTCDataChannelState state;
             unsigned long       messagesSent;
             unsigned long long  bytesSent;
             unsigned long       messagesReceived;
             unsigned long long  bytesReceived;
};

label of type DOMString: The label value of the RTCDataChannel object.
protocol of type DOMString: The protocol value of the RTCDataChannel object.
dataChannelIdentifier of type unsigned short: The id attribute of the RTCDataChannel object.
state of type RTCDataChannelState: The readyState value of the RTCDataChannel object.
messagesSent of type unsigned long: Represents the total number of API "message" events sent.
bytesSent of type unsigned long long: Represents the total number of payload bytes sent on this RTCDataChannel, i.e., not including headers or padding.
messagesReceived of type unsigned long: Represents the total number of API "message" events received.
bytesReceived of type unsigned long long: Represents the total number of bytes received on this RTCDataChannel, i.e., not including headers or padding.

An RTCTransportStats object represents the stats corresponding to an RTCDtlsTransport and its underlying RTCIceTransport. When bundling is used, a single transport will be used for all MediaStreamTracks in the bundle group. If bundling is not used, different MediaStreamTrack will use different transports. Bundling is described in [WEBRTC].

WebIDLdictionary RTCTransportStats : RTCStats {
             unsigned long long    packetsSent;
             unsigned long long    packetsReceived;
             unsigned long long    bytesSent;
             unsigned long long    bytesReceived;
             RTCIceRole            iceRole;
             DOMString             iceLocalUsernameFragment;
             required RTCDtlsTransportState dtlsState;
             RTCIceTransportState  iceState;
             DOMString             selectedCandidatePairId;
             DOMString             localCertificateId;
             DOMString             remoteCertificateId;
             DOMString             tlsVersion;
             DOMString             dtlsCipher;
             RTCDtlsRole           dtlsRole;
             DOMString             srtpCipher;
             unsigned long         selectedCandidatePairChanges;
};

packetsSent of type unsigned long long

Represents the total number of packets sent over this transport.

packetsReceived of type unsigned long long

Represents the total number of packets received on this transport.

bytesSent of type unsigned long long

Represents the total number of payload bytes sent on this RTCIceTransport, i.e., not including headers, padding or ICE connectivity checks.

bytesReceived of type unsigned long long

Represents the total number of payload bytes received on this RTCIceTransport, i.e., not including headers, padding or ICE connectivity checks.

iceRole of type RTCIceRole

Set to the current value of the role attribute of the underlying RTCDtlsTransport.iceTransport.

iceLocalUsernameFragment of type DOMString

Set to the current value of the local username fragment used in message validation procedures [RFC5245] for this RTCIceTransport. It may be updated on setLocalDescription() and on ICE restart.

dtlsState of type RTCDtlsTransportState

Set to the current value of the state attribute of the underlying RTCDtlsTransport.

iceState of type RTCIceTransportState

Set to the current value of the state attribute of the underlying RTCIceTransport.

selectedCandidatePairId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidatePairStats associated with this transport.

localCertificateId of type DOMString

For components where DTLS is negotiated, give local certificate.

remoteCertificateId of type DOMString

For components where DTLS is negotiated, give remote certificate.

tlsVersion of type DOMString

For components where DTLS is negotiated, the TLS version agreed. Only exists after DTLS negotiation is complete.

The value comes from ServerHello.supported_versions if present, otherwise from ServerHello.version. It is represented as four upper case hexadecimal digits, representing the two bytes of the version.

dtlsCipher of type DOMString

Descriptive name of the cipher suite used for the DTLS transport, as defined in the "Description" column of the IANA cipher suite registry [IANA-TLS-CIPHERS].

dtlsRole of type RTCDtlsRole

"client" or "server" depending on the DTLS role. "unknown" before the DTLS negotiation starts.

srtpCipher of type DOMString

Descriptive name of the protection profile used for the SRTP transport, as defined in the "Profile" column of the IANA DTLS-SRTP protection profile registry [IANA-DTLS-SRTP] and described further in [RFC5764].

selectedCandidatePairChanges of type unsigned long

The number of times that the selected candidate pair of this transport has changed. Going from not having a selected candidate pair to having a selected candidate pair, or the other way around, also increases this counter. It is initially zero and becomes one when an initial candidate pair is selected.

WebIDLenum RTCDtlsRole {
      "client",
      "server",
      "unknown",
};

`RTCDtlsRole` Enumeration description
Enum value	Description
`client`	The RTCPeerConnection is acting as a DTLS client as defined in [RFC6347].
`server`	The RTCPeerConnection is acting as a DTLS server as defined in [RFC6347].
`unknown`	The DTLS role of the RTCPeerConnection has not been determined yet.

RTCIceCandidateStats reflects the properties of a candidate in Section 15.1 of [RFC5245]. It corresponds to a RTCIceCandidate object.

WebIDLdictionary RTCIceCandidateStats : RTCStats {
             required DOMString       transportId;
             DOMString?               address;
             long                     port;
             DOMString                protocol;
             required RTCIceCandidateType candidateType;
             long                     priority;
             DOMString                url;
             DOMString                relayProtocol;
};

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this candidate.

address of type DOMString

It is the address of the candidate, allowing for IPv4 addresses, IPv6 addresses, and fully qualified domain names (FQDNs). See [RFC5245] section 15.1 for details.

The user agent should make sure that only remote candidate addresses that the web application has configured on the corresponding RTCPeerConnection are exposed; This is especially important for peer reflexive remote candidates. By default, the user agent MUST leave the 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 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.

port of type long

It is the port number of the candidate.

protocol of type DOMString

Valid values for transport is one of "udp" and "tcp". Based on the "transport" defined in [RFC5245] section 15.1.

candidateType of type RTCIceCandidateType

This enumeration is defined in [WEBRTC].

priority of type long

Calculated as defined in [RFC5245] section 15.1.

url of type DOMString

For local candidates this is the URL of the ICE server from which the candidate was obtained. It is the same as the url surfaced in the RTCPeerConnectionIceEvent.

For remote candidates, this property is not present.

relayProtocol of type DOMString

It is the protocol used by the endpoint to communicate with the TURN server. This is only present for local candidates. Valid values are "udp", "tcp", or "tls".

WebIDLdictionary RTCIceCandidatePairStats : RTCStats {
             required DOMString            transportId;
             required DOMString            localCandidateId;
             required DOMString            remoteCandidateId;
             required RTCStatsIceCandidatePairState state;
             boolean                       nominated;
             unsigned long long            packetsSent;
             unsigned long long            packetsReceived;
             unsigned long long            bytesSent;
             unsigned long long            bytesReceived;
             DOMHighResTimeStamp           lastPacketSentTimestamp;
             DOMHighResTimeStamp           lastPacketReceivedTimestamp;
             double                        totalRoundTripTime;
             double                        currentRoundTripTime;
             double                        availableOutgoingBitrate;
             double                        availableIncomingBitrate;
             unsigned long long            requestsReceived;
             unsigned long long            requestsSent;
             unsigned long long            responsesReceived;
             unsigned long long            responsesSent;
             unsigned long long            consentRequestsSent;
             unsigned long                 packetsDiscardedOnSend;
             unsigned long long            bytesDiscardedOnSend;
};

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this candidate pair.

localCandidateId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateStats for the local candidate associated with this candidate pair.

remoteCandidateId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateStats for the remote candidate associated with this candidate pair.

state of type RTCStatsIceCandidatePairState

Represents the state of the checklist for the local and remote candidates in a pair.

nominated of type boolean

Related to updating the nominated flag described in Section 7.1.3.2.4 of [RFC5245].

packetsSent of type unsigned long long

Represents the total number of packets sent on this candidate pair.

packetsReceived of type unsigned long long

Represents the total number of packets received on this candidate pair.

bytesSent of type unsigned long long

Represents the total number of payload bytes sent on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.

bytesReceived of type unsigned long long

Represents the total number of payload bytes received on this candidate pair, i.e., not including headers, padding or ICE connectivity checks.

lastPacketSentTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was sent on this particular candidate pair, excluding STUN packets.

lastPacketReceivedTimestamp of type DOMHighResTimeStamp

Represents the timestamp at which the last packet was received on this particular candidate pair, excluding STUN packets.

totalRoundTripTime of type double

Represents the sum of all round trip time measurements in seconds since the beginning of the session, based on STUN connectivity check [STUN-PATH-CHAR] responses (responsesReceived), including those that reply to requests that are sent in order to verify consent [RFC7675]. The average round trip time can be computed from totalRoundTripTime by dividing it by responsesReceived.

currentRoundTripTime of type double

Represents the latest round trip time measured in seconds, computed from both STUN connectivity checks [STUN-PATH-CHAR], including those that are sent for consent verification [RFC7675].

availableOutgoingBitrate of type double

It is calculated by the underlying congestion control by combining the available bitrate for all the outgoing RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.

Implementations that do not calculate a sender-side estimate MUST leave this undefined. Additionally, the value MUST be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets sent at lastPacketSentTimestamp, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined.

availableIncomingBitrate of type double

It is calculated by the underlying congestion control by combining the available bitrate for all the incoming RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.

Implementations that do not calculate a receiver-side estimate MUST leave this undefined. Additionally, the value should be undefined for candidate pairs that were never used. For pairs in use, the estimate is normally no lower than the bitrate for the packets received at lastPacketReceivedTimestamp, but might be higher. For candidate pairs that are not currently in use but were used before, implementations MUST return undefined.

requestsReceived of type unsigned long long

Represents the total number of connectivity check requests received (including retransmissions). It is impossible for the receiver to tell whether the request was sent in order to check connectivity or check consent, so all connectivity checks requests are counted here.

requestsSent of type unsigned long long

Represents the total number of connectivity check requests sent (not including retransmissions).

responsesReceived of type unsigned long long

Represents the total number of connectivity check responses received.

responsesSent of type unsigned long long

Represents the total number of connectivity check responses sent. Since we cannot distinguish connectivity check requests and consent requests, all responses are counted.

consentRequestsSent of type unsigned long long

Represents the total number of consent requests sent.

packetsDiscardedOnSend of type unsigned long

Total number of packets for this candidate pair that have been discarded due to socket errors, i.e. a socket error occurred when handing the packets to the socket. This might happen due to various reasons, including full buffer or no available memory.

bytesDiscardedOnSend of type unsigned long long

Total number of bytes for this candidate pair that have been discarded due to socket errors, i.e. a socket error occurred when handing the packets containing the bytes to the socket. This might happen due to various reasons, including full buffer or no available memory. Calculated as defined in [RFC3550] section 6.4.1.

WebIDLenum RTCStatsIceCandidatePairState {
    "frozen",
    "waiting",
    "in-progress",
    "failed",
    "succeeded"
};

`RTCStatsIceCandidatePairState` Enumeration description
Enum value	Description
`frozen`	Defined in Section 5.7.4 of [RFC5245].
`waiting`	Defined in Section 5.7.4 of [RFC5245].
`in-progress`	Defined in Section 5.7.4 of [RFC5245].
`failed`	Defined in Section 5.7.4 of [RFC5245].
`succeeded`	Defined in Section 5.7.4 of [RFC5245].

WebIDLdictionary RTCCertificateStats : RTCStats {
             required DOMString fingerprint;
             required DOMString fingerprintAlgorithm;
             required DOMString base64Certificate;
             DOMString issuerCertificateId;
};

fingerprint of type DOMString: The fingerprint of the certificate. Only use the fingerprint value as defined in Section 5 of [RFC4572].
fingerprintAlgorithm of type DOMString: The hash function used to compute the certificate fingerprint. For instance, "sha-256".
base64Certificate of type DOMString: The DER-encoded base-64 representation of the certificate.
issuerCertificateId of type DOMString: The issuerCertificateId refers to the stats object that contains the next certificate in the certificate chain. If the current certificate is at the end of the chain (i.e. a self-signed certificate), this will not be set.

This section is non-normative.

WebIDLdictionary RTCMediaStreamStats : RTCStats {
  DOMString streamIdentifier;
  sequence<DOMString> trackIds;
};

This entire dictionary was made obsolete in September, 2019 due to sender, receiver and transceiver stats objects being a better fit to describe the modern RTCPeerConnection model (Unified Plan).

streamIdentifier of type DOMString: stream.id property
trackIds of type sequence<DOMString>: This is the id of the stats object, not the track.id.

WebIDLpartial dictionary RTCCodecStats {
    DOMString implementation;
};

implementation of type DOMString: This was moved to RTCInboundRtpStreamStats.RTCInboundRtpStreamStats/decoderImplementation}} and RTCOutboundRtpStreamStats.encoderImplementation in August 2019.

WebIDLpartial dictionary RTCIceCandidateStats {
    boolean deleted = false;
    boolean isRemote;
};

deleted of type boolean: This field was obsoleted because if the ICE candidate is deleted it no longer appears in getStats().
isRemote of type boolean: false indicates that this represents a local candidate; true indicates that this represents a remote candidate.

WebIDLpartial dictionary RTCIceCandidatePairStats {
    double totalRtt;
    double currentRtt;
    unsigned long long priority;
};

totalRtt: This field got renamed to totalRoundTripTime in Dec 2016.
currentRtt: This field got renamed to currentRoundTripTime in Dec 2016.
priority: This field got removed in Feb 2018, as it cannot be represented in 53 bits. It can be recalculated if needed as defined in [RFC5245] section 5.7.2.

WebIDLpartial dictionary RTCRtpStreamStats {
    DOMString mediaType;
};

mediaType of type DOMString: This field got renamed to kind in Feb 2018.

WebIDLpartial dictionary RTCInboundRtpStreamStats {
    DOMString trackId;
    double fractionLost;
};

trackId of type DOMString

The identifier of the stats object representing the receiving track, an RTCMediaStreamTrackStats.

This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.

fractionLost of type double

This field was moved to RTCRemoteInboundRtpStreamStats in December 2017.

WebIDLpartial dictionary RTCOutboundRtpStreamStats {
    DOMString trackId;
};

trackId of type DOMString

The identifier of the stats object representing the current track attachment to the sender of this stream, an RTCMediaStreamTrackStats.

This field was made obsolete in April 2020 as a follow-up to "track" stats having been made obsolete.

WebIDLdictionary RTCMediaStreamTrackStats {
    DOMString           trackIdentifier;
    boolean             ended;
    required DOMString  kind;
    RTCPriorityType     priority;
    boolean             remoteSource;
    DOMHighResTimeStamp estimatedPlayoutTimestamp;
    double              jitterBufferDelay;
    unsigned long long  jitterBufferEmittedCount;

    // Audio-only, send and receive side.
    double              audioLevel;
    double              totalAudioEnergy;
    double              totalSamplesDuration;

    // Audio-only, send side.
    double              echoReturnLoss;
    double              echoReturnLossEnhancement;

    // Audio-only, receive side.
    unsigned long long  totalSamplesReceived;
    unsigned long long  concealedSamples;
    unsigned long long  silentConcealedSamples;
    unsigned long long  concealmentEvents;
    unsigned long long  insertedSamplesForDeceleration;
    unsigned long long  removedSamplesForAcceleration;

    // Video-only, send and receive side.
    unsigned long       frameWidth;
    unsigned long       frameHeight;
    double              framesPerSecond;

    // Video-only, send side.
    unsigned long       keyFramesSent;
    unsigned long       framesCaptured;
    unsigned long       framesSent;
    unsigned long       hugeFramesSent;

    // Video-only, receive side.
    unsigned long       keyFramesReceived;
    unsigned long       framesReceived;
    unsigned long       framesDecoded;
    unsigned long       framesDropped;
};

trackIdentifier of type DOMString

Represents the id property of the track.

ended of type boolean

Reflects the ended state of the track.

kind of type DOMString

Either "audio" or "video". This reflects the kind attribute of the MediaStreamTrack, see [GETUSERMEDIA].

priority of type RTCPriorityType

Indicates the priority that has been set for the track. It is defined in [RTCWEB-TRANSPORT], Section 4, but was removed from [WEBRTC] due to lack of implementation and moved to [WEBRTC-PRIORITY], with some changes to its definition.

remoteSource of type boolean

Only applicable for "track" stats. false if the track attachment is on an RTCRtpSender, true if the track attachment is on an RTCRtpReceiver.

With "track" stats made obsolete, and this information being available elsewhere, this metric was made obsolete in April, 2020.

estimatedPlayoutTimestamp of type DOMHighResTimeStamp

This was moved to RTCInboundRtpStreamStats in August 2019.

jitterBufferDelay of type double

This was moved to RTCInboundRtpStreamStats in August 2019.

jitterBufferEmittedCount of type unsigned long long

This was moved to RTCInboundRtpStreamStats in August 2019.

audioLevel of type double

Audio-only. This field was moved to RTCAudioSourceStats and RTCInboundRtpStreamStats in June 2019.

totalAudioEnergy of type double

Audio-only. This field was moved to RTCAudioSourceStats and RTCInboundRtpStreamStats in June 2019.

totalSamplesDuration of type double

Audio-only. This field was moved to RTCAudioSourceStats and RTCInboundRtpStreamStats in June 2019.

echoReturnLoss of type double

Audio-only. This was moved to RTCAudioSourceStats in August 2019.

echoReturnLossEnhancement of type double

Audio-only. This was moved to RTCAudioSourceStats in August 2019.

totalSamplesReceived of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

concealedSamples of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

silentConcealedSamples of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

concealmentEvents of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

insertedSamplesForDeceleration of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

removedSamplesForAcceleration of type unsigned long long

Audio-only. This was moved to RTCInboundRtpStreamStats in August 2019.

frameWidth of type unsigned long

Video-only. This was moved to RTCOutboundRtpStreamStats and RTCInboundRtpStreamStats in August 2019.

frameHeight of type unsigned long

Video-only. This was moved to RTCOutboundRtpStreamStats and RTCInboundRtpStreamStats in August 2019.

framesPerSecond of type double

Video-only. For the sending case, this was replaced by RTCVideoSourceStats.framesPerSecond in May 2019 representing the frame rate of the track. For the receiving case, this was moved to RTCInboundRtpStreamStats in August 2019 representing the decoding frame rate. In August 2019, framesPerSecond was also added to RTCOutboundRtpStreamStats, representing the encoding frame rate (which may be lower than the source frame rate).

keyFramesSent of type unsigned long

Video-only. This field was replaced by keyFramesEncoded in RTCOutboundRtpStreamStats in June 2019. There were no known implementations supporting the old field at the time of the change.

framesCaptured of type unsigned long

Video-only. This was replaced by RTCVideoSourceStats.frames in May 2019.

framesSent of type unsigned long

Video-only. This was moved to RTCOutboundRtpStreamStats in August 2019.

hugeFramesSent of type unsigned long

Video-only. This was moved to RTCOutboundRtpStreamStats in August 2019.

keyFramesReceived of type unsigned long

Video-only. This field was replaced by keyFramesDecoded in RTCInboundRtpStreamStats in June 2019. There were no known implementations supporting the old field at the time of the change.

framesReceived of type unsigned long

Video-only. This was moved to RTCInboundRtpStreamStats in August 2019.

framesDecoded of type unsigned long

Video-only. This was moved to RTCInboundRtpStreamStats in August 2019.

framesDropped of type unsigned long

Video-only. This was moved to RTCInboundRtpStreamStats in August 2019.

`RTCStatsType`	Dictionary	Fields
"`codec`"	`RTCStats`	`timestamp` `type` `id`
"`codec`"	`RTCCodecStats`	`payloadType` `transportId` `mimeType` `clockRate` `channels` `sdpFmtpLine`
"`inbound-rtp`"	`RTCStats`	`timestamp` `type` `id`
	`RTCRtpStreamStats`	`ssrc` `kind` `transportId` `codecId`
	`RTCReceivedRtpStreamStats`	`packetsReceived` `packetsLost` `jitter` `framesDropped`
	`RTCInboundRtpStreamStats`	`trackIdentifier` `kind` `mid` `remoteId` `framesDecoded` `keyFramesDecoded` `frameWidth` `frameHeight` `framesPerSecond` `qpSum` `totalDecodeTime` `totalInterFrameDelay` `totalSquaredInterFrameDelay` `lastPacketReceivedTimestamp` `headerBytesReceived` `packetsDiscarded` `fecPacketsReceived` `fecPacketsDiscarded` `bytesReceived` `nackCount` `firCount` `pliCount` `totalProcessingDelay` `estimatedPlayoutTimestamp` `jitterBufferDelay` `jitterBufferTargetDelay` `jitterBufferEmittedCount` `jitterBufferMinimumDelay` `totalSamplesReceived` `concealedSamples` `silentConcealedSamples` `concealmentEvents` `insertedSamplesForDeceleration` `removedSamplesForAcceleration` `audioLevel` `totalAudioEnergy` `totalSamplesDuration` `framesReceived` `decoderImplementation` `playoutId`
"`outbound-rtp`"	`RTCStats`	`timestamp` `type` `id`
	`RTCRtpStreamStats`	`ssrc` `kind` `transportId` `codecId`
	`RTCSentRtpStreamStats`	`packetsSent` `bytesSent`
	`RTCOutboundRtpStreamStats`	`mid` `mediaSourceId` `remoteId` `rid` `headerBytesSent` `retransmittedPacketsSent` `retransmittedBytesSent` `targetBitrate` `totalEncodedBytesTarget` `frameWidth` `frameHeight` `framesPerSecond` `framesSent` `hugeFramesSent` `framesEncoded` `keyFramesEncoded` `qpSum` `totalEncodeTime` `totalPacketSendDelay` `qualityLimitationReason` `qualityLimitationDurations` `qualityLimitationResolutionChanges` `nackCount` `firCount` `pliCount` `encoderImplementation` `active`
"`remote-inbound-rtp`"	`RTCStats`	`timestamp` `type` `id`
	`RTCRtpStreamStats`	`ssrc` `kind` `transportId` `codecId`
	`RTCReceivedRtpStreamStats`	`packetsReceived` `packetsLost` `jitter` `framesDropped`
	`RTCRemoteInboundRtpStreamStats`	`localId` `roundTripTime` `totalRoundTripTime` `fractionLost` `roundTripTimeMeasurements`
"`remote-outbound-rtp`"	`RTCStats`	`timestamp` `type` `id`
	`RTCRtpStreamStats`	`ssrc` `kind` `transportId` `codecId`
	`RTCSentRtpStreamStats`	`packetsSent` `bytesSent`
	`RTCRemoteOutboundRtpStreamStats`	`localId` `remoteTimestamp` `reportsSent` `roundTripTime` `totalRoundTripTime` `roundTripTimeMeasurements`
"`media-source`"	`RTCStats`	`timestamp` `type` `id`
	`RTCMediaSourceStats`	`trackIdentifier` `kind`
	`RTCAudioSourceStats`	`audioLevel` `totalAudioEnergy` `totalSamplesDuration` `echoReturnLoss` `echoReturnLossEnhancement` `droppedSamplesDuration` `totalCaptureDelay` `totalSamplesCaptured`
	`RTCVideoSourceStats`	`width` `height` `frames` `framesPerSecond`
"`peer-connection`"	`RTCStats`	`timestamp` `type` `id`
"`peer-connection`"	`RTCPeerConnectionStats`	`dataChannelsOpened` `dataChannelsClosed`
"`data-channel`"	`RTCStats`	`timestamp` `type` `id`
"`data-channel`"	`RTCDataChannelStats`	`label` `protocol` `dataChannelIdentifier` `state` `messagesSent` `bytesSent` `messagesReceived` `bytesReceived`
"`transport`"	`RTCStats`	`timestamp` `type` `id`
"`transport`"	`RTCTransportStats`	`packetsSent` `packetsReceived` `bytesSent` `bytesReceived` `iceRole` `iceLocalUsernameFragment` `dtlsState` `iceState` `selectedCandidatePairId` `localCertificateId` `remoteCertificateId` `tlsVersion` `dtlsCipher` `dtlsRole` `srtpCipher` `selectedCandidatePairChanges`
"`candidate-pair`"	`RTCStats`	`timestamp` `type` `id`
"`candidate-pair`"	`RTCIceCandidatePairStats`	`transportId` `localCandidateId` `remoteCandidateId` `state` `nominated` `packetsSent` `packetsReceived` `bytesSent` `bytesReceived` `lastPacketSentTimestamp` `lastPacketReceivedTimestamp` `totalRoundTripTime` `currentRoundTripTime` `availableOutgoingBitrate` `availableIncomingBitrate` `requestsReceived` `requestsSent` `responsesReceived` `responsesSent` `consentRequestsSent` `packetsDiscardedOnSend` `bytesDiscardedOnSend`
"`local-candidate`"	`RTCStats`	`timestamp` `type` `id`
"`local-candidate`"	`RTCIceCandidateStats`	`transportId` `address` `port` `protocol` `candidateType` `priority` `url` `relayProtocol`
"`remote-candidate`"	`RTCStats`	`timestamp` `type` `id`
"`remote-candidate`"	`RTCIceCandidateStats`	`transportId` `address` `port` `protocol` `candidateType` `priority` `url` `relayProtocol`
"`certificate`"	`RTCStats`	`timestamp` `type` `id`
"`certificate`"	`RTCCertificateStats`	`fingerprint` `fingerprintAlgorithm` `base64Certificate` `issuerCertificateId`

Identifiers for WebRTC's Statistics API

Abstract

Status of This Document

1. Introduction

2. Conformance

3. Terminology

4. Basic concepts

4.1 Guidelines for design of stats objects

4.2 Guidelines for implementing stats objects

4.3 Lifetime considerations for monitored objects

4.4 Guidelines for getStats() results caching/throttling

5. Maintenance procedures for stats object types

5.1 Adding new stats objects

5.2 Retiring stats objects

6. RTCStatsType

6.1 RTCStatsType enum

7. Stats dictionaries

7.1 The RTP statistics hierarchy

7.2 RTCRtpStreamStats dictionary

Dictionary RTCRtpStreamStats Members

7.3 RTCCodecStats dictionary

Dictionary RTCCodecStats Members

7.4 RTCReceivedRtpStreamStats dictionary

Dictionary RTCReceivedRtpStreamStats Members

7.5 RTCInboundRtpStreamStats dictionary

Dictionary RTCInboundRtpStreamStats Members

7.6 RTCRemoteInboundRtpStreamStats dictionary

Dictionary RTCRemoteInboundRtpStreamStats Members

7.7 RTCSentRtpStreamStats dictionary

Dictionary RTCSentRtpStreamStats Members

7.8 RTCOutboundRtpStreamStats dictionary

Dictionary RTCOutboundRtpStreamStats Members

7.9 RTCQualityLimitationReason enum

7.10 RTCRemoteOutboundRtpStreamStats dictionary

Dictionary RTCRemoteOutboundRtpStreamStats Members

7.11 RTCMediaSourceStats dictionary

Dictionary RTCMediaSourceStats Members

7.12 RTCAudioSourceStats dictionary

Dictionary RTCAudioSourceStats Members

7.13 RTCVideoSourceStats dictionary

Dictionary RTCVideoSourceStats Members

7.14 RTCAudioPlayoutStats dictionary

Dictionary RTCAudioPlayoutStats Members

7.15 RTCPeerConnectionStats dictionary

Dictionary RTCPeerConnectionStats Members

7.16 RTCDataChannelStats dictionary

Dictionary RTCDataChannelStats Members

7.17 RTCTransportStats dictionary

Dictionary RTCTransportStats Members

RTCDtlsRole enum

7.18 RTCIceCandidateStats dictionary

Dictionary RTCIceCandidateStats Members

7.19 RTCIceCandidatePairStats dictionary

Dictionary RTCIceCandidatePairStats Members

7.19.1 RTCStatsIceCandidatePairState enum

7.20 RTCCertificateStats dictionary

Dictionary RTCCertificateStats Members

8. Obsolete stats

Obsolete RTCMediaStreamStats members

Obsolete RTCCodecStats members

Obsolete RTCIceCandidateStats members

Obsolete RTCIceCandidatePairStats members

Obsolete RTCRtpStreamStats members

Obsolete RTCInboundRtpStreamStats members

Obsolete RTCOutboundRtpStreamStats members

Obsolete RTCMediaStreamTrackStats members

9. Examples

9.1 Example of a stats application

10. Security and Privacy Considerations

A. Summary of WebRTC stats fields per type

B. Acknowledgements

C. References

C.1 Normative references

C.2 Informative references

4.4 Guidelines for `getStats()` results caching/throttling

6. `RTCStatsType`

6.1 `RTCStatsType` enum

7.2 `RTCRtpStreamStats` dictionary

Dictionary `RTCRtpStreamStats` Members

7.3 `RTCCodecStats` dictionary

Dictionary `RTCCodecStats` Members

7.4 `RTCReceivedRtpStreamStats` dictionary

Dictionary `RTCReceivedRtpStreamStats` Members

7.5 `RTCInboundRtpStreamStats` dictionary

Dictionary `RTCInboundRtpStreamStats` Members

7.6 `RTCRemoteInboundRtpStreamStats` dictionary

Dictionary `RTCRemoteInboundRtpStreamStats` Members

7.7 `RTCSentRtpStreamStats` dictionary

Dictionary `RTCSentRtpStreamStats` Members

7.8 `RTCOutboundRtpStreamStats` dictionary

Dictionary `RTCOutboundRtpStreamStats` Members

7.9 `RTCQualityLimitationReason` enum

7.10 `RTCRemoteOutboundRtpStreamStats` dictionary

Dictionary `RTCRemoteOutboundRtpStreamStats` Members

7.11 `RTCMediaSourceStats` dictionary

Dictionary `RTCMediaSourceStats` Members

7.12 `RTCAudioSourceStats` dictionary

Dictionary `RTCAudioSourceStats` Members

7.13 `RTCVideoSourceStats` dictionary

Dictionary `RTCVideoSourceStats` Members

7.14 `RTCAudioPlayoutStats` dictionary

Dictionary `RTCAudioPlayoutStats` Members

7.15 `RTCPeerConnectionStats` dictionary

Dictionary `RTCPeerConnectionStats` Members

7.16 `RTCDataChannelStats` dictionary

Dictionary `RTCDataChannelStats` Members

7.17 `RTCTransportStats` dictionary

Dictionary `RTCTransportStats` Members

`RTCDtlsRole` enum

7.18 `RTCIceCandidateStats` dictionary

Dictionary `RTCIceCandidateStats` Members

7.19 `RTCIceCandidatePairStats` dictionary

Dictionary `RTCIceCandidatePairStats` Members

7.19.1 `RTCStatsIceCandidatePairState` enum

7.20 `RTCCertificateStats` dictionary

Dictionary `RTCCertificateStats` Members

Obsolete `RTCMediaStreamStats` members

Obsolete `RTCCodecStats` members

Obsolete `RTCIceCandidateStats` members

Obsolete `RTCIceCandidatePairStats` members

Obsolete `RTCRtpStreamStats` members

Obsolete `RTCInboundRtpStreamStats` members

Obsolete `RTCOutboundRtpStreamStats` members

Obsolete `RTCMediaStreamTrackStats` members