RTCIceCandidatePairStats

BaselineWidely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

TheRTCIceCandidatePairStats dictionary of theWebRTC API is used to report statistics that provide insight into the quality and performance of anRTCPeerConnection while connected and configured as described by the specified pair ofICE candidates.

The statistics can be obtained by iterating theRTCStatsReport returned byRTCPeerConnection.getStats() until you find an entry with thetype of"candidate-pair".

Instance properties

availableIncomingBitrateOptional: A number representing the available inbound capacity of the network.This reports the total number of bits per second available for all of the candidate pair's incomingRTP streams.It does not take into account the size of the Internet Protocol (IP) overhead, nor any other transport layers such asTCP orUDP.
availableOutgoingBitrateOptional: A number representing the approximate available outbound capacity of the network.This reports the total number of bits per second available for all of the candidate pair's outgoingRTP streams.It does not take into account the size of the IP overhead, nor any other transport layers such asTCP orUDP.
bytesDiscardedOnSendOptionalExperimental: An integer representing the total number of bytes discarded due to socket errors on this candidate pair.
bytesReceivedOptional: An integer representing the total number of payload bytes received on this candidate pair.
bytesSentOptional: An integer representing the total number of payload bytes sent on this candidate pair (the total number of bytes sent excluding any headers, padding, or other protocol overhead).
consentRequestsSentOptionalExperimental: An integer representing the total number of STUN consent requests sent on this candidate pair.
currentRoundTripTimeOptional: A number representing the total time, in seconds, that elapsed between the most recently-sent STUN request and the response being received.This may be based upon requests that were involved in confirming permission to open the connection.
lastPacketReceivedTimestampOptional: ADOMHighResTimeStamp value indicating the time at which the last packet was received by the local peer from the remote peer for this candidate pair. Timestamps are not recorded for STUN packets.
lastPacketSentTimestampOptional: ADOMHighResTimeStamp value indicating the time at which the last packet was sent from the local peer to the remote peer for this candidate pair. Timestamps are not recorded for STUN packets.
localCandidateIdOptional: A string representing the unique ID corresponding to theRTCIceCandidate from the data included in theRTCIceCandidateStats object providing statistics for the candidate pair's local candidate.
nominatedOptional: A Boolean value which, iftrue, indicates that the candidate pair described by this object is one which has been proposed for use, and will be (or was) used if its priority is the highest among the nominated candidate pairs. SeeRFC 5245, section 7.1.3.2.4 for details.
packetsDiscardedOnSendOptionalExperimental: An integer representing the total number of packets discarded due to socket errors on this candidate pair.
packetsReceivedOptionalExperimental: An integer representing the total number of packets received on this candidate pair.
packetsSentOptionalExperimental: An integer representing the total number of packets sent on this candidate pair.
remoteCandidateIdOptional: A string containing a unique ID corresponding to the remote candidate from which data was taken to construct theRTCIceCandidateStats object describing the remote end of the connection.
requestsReceivedOptional: An integer representing the total number of connectivity check requests that have been received, including retransmissions. This value includes both connectivity checks and STUN consent checks.
requestsSentOptional: An integer representing the total number of connectivity check requests that have been sent,not including retransmissions.
responsesReceivedOptional: An integer representing the total number of connectivity check responses that have been received.
responsesSentOptional: An integer representing the total number of connectivity check responses that have been sent. This includes both connectivity check requests and STUN consent requests.
stateOptional: A string which indicates the state of the connection between the two candidates.
totalRoundTripTimeOptional: A number indicating the total time, in seconds, that has elapsed between sending STUN requests and receiving responses to them, for all such requests made to date on this candidate pair.This includes both connectivity check and consent check requests. You can compute the average round trip time (RTT) by dividing this value byresponsesReceived.
transportIdOptional: A string that uniquely identifies theRTCIceTransport that was inspected to obtain the transport-related statistics (as found inRTCTransportStats) used in generating this object.

Common instance properties

The following properties are common to all WebRTC statistics objects.

id: A string that uniquely identifies the object that is being monitored to produce this set of statistics.
timestamp: ADOMHighResTimeStamp object indicating the time at which the sample was taken for this statistics object.
type: A string with the value"candidate-pair", indicating the type of statistics that the object contains.

Deprecated properties

The following properties have been removed from the specification and should no longer be used.You should update any existing code to avoid using them as soon as is practical.Check thecompatibility table for details on which browsers support them and in which versions.

priorityDeprecatedOptional Non-standard: An integer value indicating the candidate pair's priority.
readableDeprecatedOptional Non-standard: A Boolean value indicating whether or not data can be sent over the connection described by the candidate pair.
writableDeprecatedOptional Non-standard: A Boolean value indicating whether or not data can be received on the connection described by the candidate pair.

Non-standard properties

selectedNon-standardOptional: A Firefox-specific Boolean value which istrue if the candidate pair described by this object is the one currently in use.The spec-compliant way to determine the selected candidate pair is to look for a stats object of typetransport, which is an RTCTransportStats object.That object'sselectedCandidatePairId property indicates whether or not the specified transport is the one being used.

Usage notes

The currently-active ICE candidate pair—if any—can be obtained by calling theRTCIceTransport methodgetSelectedCandidatePair(), which returns anRTCIceCandidatePair object, ornull if there isn't a pair selected.The active candidate pair describes the current configuration of the two ends of theRTCPeerConnection.

Any candidate pair that isn't the active pair of candidates for a transport gets deleted if theRTCIceTransport performs an ICE restart, at which point thestate of the ICE transport returns tonew and negotiation starts once again.For more information, seeICE restart.

Example

This example computes the average time elapsed between connectivity checks.

if (rtcStats && rtcStats.type === "candidate-pair") {  let elapsed =    (rtcStats.lastRequestTimestamp - rtcStats.firstRequestTimestamp) /    rtcStats.requestsSent;  console.log(`Average time between ICE connectivity checks: ${elapsed} ms.`);}

The code begins by looking atrtcStats to see if itstype iscandidate-pair.If it is, then we know thatrtcStats is in fact anRTCIceCandidatePairStats object.We can then compute the average time elapsed between STUN connectivity checks and log that information.