This is an unofficial proposal.
Unofficial additions to WebRTC's RTCPeerConnection.getStats()
API.
This document contains unofficial additions to the Identifiers for WebRTC's Statistics API specification [[WEBRTC-STATS]]. If a metric gains consensus it should be moved to the official spec.
{{RTCStats}} and dictionaries that are extended in this document are
defined in [[WEBRTC-STATS]]. The term RTCPeerConnection is defined in
[[WEBRTC]] and {{DOMHighResTimeStamp}} is defined in [[HR-TIME]].
enum RTCCodecType {
"encode",
"decode",
};
| Enum value | 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. |
partial dictionary RTCCodecStats {
RTCCodecType codecType;
};
{{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.
partial dictionary RTCMediaSourceStats {
boolean relayedSource;
};
true if the source is remote, for instance if it is
sourced from another host via an RTCPeerConnection.
false otherwise.
partial dictionary RTCVideoSourceStats {
unsigned long bitDepth;
};
The bit depth per pixel of the last frame originating from this source. Before a frame has been produced this member does not exist.
dictionary RTCRtpTransceiverStats : RTCStats {
required DOMString senderId;
required DOMString receiverId;
DOMString mid;
};
The identifier for the {{RTCRtpSenderStats}} stats object representing
the RTCRtpSender associated with the
RTCRtpTransceiver that this stats object represents.
The identifier for the {{RTCRtpReceiverStats}} stats object
representing the RTCRtpReceiver associated with the
RTCRtpTransceiver that this stats object represents.
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 RTCRtpSenderStats : RTCStats {
DOMString mediaSourceId;
};
The identifier of the stats object representing the track currently attached to this sender, an {{RTCMediaSourceStats}}.
dictionary RTCRtpReceiverStats : RTCStats {
required DOMString trackIdentifier;
required DOMString kind;
};
The id property of the {{RTCMediaStreamTrack}} attached
to the {{RTCRtpReceiver}} that this stats object represents.
Either "audio" or "video". The
kind property of the {{RTCMediaStreamTrack}} attached to
the {{RTCRtpReceiver}} that this stats object represents.
partial dictionary RTCOutboundRtpStreamStats {
DOMString contentType;
DOMHighResTimeStamp lastPacketSentTimestamp;
unsigned long packetsDiscardedOnSend;
unsigned long long bytesDiscardedOnSend;
unsigned long fecPacketsSent;
unsigned long frameBitDepth;
unsigned long framesDiscardedOnSend;
unsigned long long totalSamplesSent;
unsigned long long samplesEncodedWithSilk;
unsigned long long samplesEncodedWithCelt;
boolean voiceActivityFlag;
double averageRtcpInterval;
record<USVString, unsigned long long> perDscpPacketsSent;
unsigned long sliCount;
};
contentType of type
DOMString
This metric exposes the video-content-type
of the last key frame sent. This value is updated every time the last
packet of a key frame is sent, and it is updated as follows: if this
packet contained the video-content-type RTP header extension value
0x00, contentType is "unspecified", if it is
0x01, contentType is "screenshare". In all
other cases, such as if the header extension is missing, its value is
invalid or no last packet of a key frame has been sent yet,
contentType is missing.
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 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).
Only exists 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 exist.
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 exists for audio. The total number of samples that have been sent over this
RTP stream.
Only exists for audio and when the audio codec is Opus. The total number of samples encoded by the SILK portion of the Opus codec.
Only exists for audio and when the audio codec is Opus. The total number of samples encoded by the CELT portion of the Opus codec.
Only exists 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]].
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 packets sent for this SSRC, per DSCP. DSCPs are identified as
decimal integers in string form.
Only exists 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.
partial dictionary RTCReceivedRtpStreamStats {
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 partialFramesLost;
unsigned long fullFramesLost;
};
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 exists 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 framesReceived counter is incremented.
Only exists 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]].
partial dictionary RTCInboundRtpStreamStats {
DOMString contentType;
unsigned long frameBitDepth;
boolean voiceActivityFlag;
double averageRtcpInterval;
unsigned long long packetsFailedDecryption;
unsigned long long packetsDuplicated;
record<USVString, unsigned long long> perDscpPacketsReceived;
unsigned long sliCount;
unsigned long long totalSamplesDecoded;
unsigned long long samplesDecodedWithSilk;
unsigned long long samplesDecodedWithCelt;
};
contentType of type
DOMString
This metric exposes the video-content-type
of the last key frame received. This value is updated every time the
last packet of a key frame is received, and it is updated as follows:
if this packet contained the video-content-type RTP header extension
value 0x00, contentType is "unspecified", if
it is 0x01, contentType is "screenshare". In
all other cases, such as if the header extension is missing, its value
is invalid or no last packet of a key frame has been received yet,
contentType is missing.
Only exists 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 exist.
Only exists 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].
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.
The cumulative number of RTP packets that failed to be decrypted according to the
procedures in [[!RFC3711]]. These packets are not counted by
packetsDiscarded.
RTCReceivedRtpStreamStats/packetsDiscarded.RTCReceivedRtpStreamStats/packetsLost; this will always result in a positive
number, but not the same number as RFC 3550 would calculate.
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 exists 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.
Only exists for audio. The total number of samples that have been decoded on this RTP stream.
Only exists for audio and when the audio codec is Opus. The total number of samples decoded by the SILK portion of the Opus codec.
Only exists for audio and when the audio codec is Opus. The total number of samples decoded by the CELT portion of the Opus codec.
partial dictionary RTCRemoteInboundRtpStreamStats {
unsigned long long reportsReceived;
unsigned long long packetsDiscarded;
};
Represents the total number of RTCP RR blocks received for this SSRC.
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.
partial dictionary RTCAudioReceiverStats {
unsigned long long jitterBufferFlushes;
};
jitterBufferFlushes of type
unsigned long long
Experimental stat which is available under origin trial in Chromium starting from M72 version. Counts the total number of times the jitter buffer reaches its maximum capacity and gets flushed.
partial dictionary RTCVideoReceiverStats {
double totalFramesDuration;
double sumOfSquaredFramesDuration;
};
totalFramesDuration of type
double
Total duration of all rendered video frames, in seconds. This value is updated when a frame is rendered.
sumOfSquaredFramesDuration of type
double
Sum of squared duration of all rendered frames. It can be used to calculate harmonic frame rate:
{{ RTCVideoReceiverStats/totalFramesDuration}} / sumOfSquaredFrameDurations
partial dictionary RTCIceServerStats {
RTCNetworkType networkType;
required DOMString url;
long port;
DOMString relayProtocol;
unsigned long totalRequestsSent;
unsigned long totalResponsesReceived;
double totalRoundTripTime;
};
networkType of type RTCNetworkType
Represents the type of network interface used.
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.
partial dictionary RTCIceCandidateStats {
RTCNetworkType networkType;
};
networkType of type RTCNetworkType
Represents the type of network interface used by the base of a local candidate (the address the ICE agent sends from). Only present for local candidates; it's not possible to know what type of network interface a remote candidate is using.
networkType of the
relevant candidate would be "wifi", even when the next hop is over a
cellular connection.
This reveals information that would otherwise not be available to web pages, which increases the fingerprint surface.
partial dictionary RTCIceCandidatePairStats {
DOMHighResTimeStamp firstRequestTimestamp;
DOMHighResTimeStamp lastRequestTimestamp;
DOMHighResTimeStamp lastResponseTimestamp;
unsigned long circuitBreakerTriggerCount;
unsigned long long retransmissionsReceived;
unsigned long long retransmissionsSent;
DOMHighResTimeStamp consentExpiredTimestamp;
unsigned long long requestBytesSent;
unsigned long long consentRequestBytesSent;
unsigned long long responseBytesSent;
};
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 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 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 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.
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.
partial dictionary RTCTransportStats {
DOMString rtcpTransportStatsId;
DOMString tlsGroup;
};
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.
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]].
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]].
partial dictionary RTCPeerConnectionStats {
unsigned long dataChannelsRequested;
unsigned long dataChannelsAccepted;
};
Represents the number of unique RTCDataChannels returned from a successful
RTCPeerConnection/createDataChannel() call on the RTCPeerConnection. If the underlying data
transport is not established, these may be in the "connecting" state.
Represents the number of unique RTCDataChannels signaled in a RTCPeerConnection.ondatachannel event on
the RTCPeerConnection.
The sum of dataChannelsRequested and dataChannelsAccepted is always greater than or
equal to dataChannelsOpened - the difference is equal to the number of channels that
have been requested, but have not reached the "open" state.
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).
enum RTCNetworkType {
"bluetooth",
"cellular",
"ethernet",
"wifi",
"wimax",
"vpn",
"unknown"
};
| Enumeration description | |
|---|---|
bluetooth
|
A Bluetooth connection. |
cellular
|
A cellular connection (e.g., EDGE, HSPA, LTE, etc.). |
ethernet
|
An Ethernet connection. |
wifi
|
A Wi-Fi connection. |
wimax
|
A WiMAX connection. |
vpn
|
The connection runs over a VPN. The underlying network type is not available. |
unknown
|
The user agent is unable or unwilling to identify the underlying connection technology. |