W3cubDocs

/Web APIs

RTCIceCandidatePairStats

The RTCIceCandidatePairStats dictionary of the WebRTC API is used to report statistics that provide insight into the quality and performance of an RTCPeerConnection while connected and configured as described by the specified pair of ICE candidates.

The statistics can be obtained by iterating the RTCStatsReport returned by RTCPeerConnection.getStats() until you find an entry with the type of "candidate-pair".

Instance properties

availableIncomingBitrate Optional

Provides a value representing the available inbound capacity of the network by reporting the total number of bits per second available for all of the candidate pair's incoming RTP streams. This does not take into account the size of the IP overhead, nor any other transport layers such as TCP or UDP.

availableOutgoingBitrate Optional

Provides an informative value representing the available outbound capacity of the network by reporting the total number of bits per second available for all of the candidate pair's outgoing RTP streams. This does not take into account the size of the IP overhead, nor any other transport layers such as TCP or UDP.

bytesReceived Optional

The total number of payload bytes received (that is, the total number of bytes received minus any headers, padding, or other administrative overhead) on this candidate pair so far.

bytesSent Optional

The total number of payload bytes sent (that is, the total number of bytes sent minus any headers, padding, or other administrative overhead) so far on this candidate pair.

currentRoundTripTime Optional

A floating-point value indicating 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.

lastPacketReceivedTimestamp Optional

A DOMHighResTimeStamp 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.

lastPacketSentTimestamp Optional

A DOMHighResTimeStamp 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.

localCandidateId Optional

The unique ID string corresponding to the RTCIceCandidate from the data included in the RTCIceCandidateStats object providing statistics for the candidate pair's local candidate.

nominated Optional

A Boolean value which, if true, 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. See RFC 5245, section 7.1.3.2.4 for details.

remoteCandidateId Optional

The unique ID string corresponding to the remote candidate from which data was taken to construct the RTCIceCandidateStats object describing the remote end of the connection.

requestsReceived Optional

The total number of connectivity check requests that have been received, including retransmissions. This value includes both connectivity checks and STUN consent checks.

requestsSent Optional

The total number of connectivity check requests that have been sent, not including retransmissions.

responsesReceived Optional

The total number of connectivity check responses that have been received.

responsesSent Optional

The total number of connectivity check responses that have been sent. This includes both connectivity check requests and STUN consent requests.

state Optional

A string which indicates the state of the connection between the two candidates.

totalRoundTripTime Optional

A floating-point value 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 by responsesReceived.

transportId Optional

A string that uniquely identifies the RTCIceTransport that was inspected to obtain the transport-related statistics (as found in RTCTransportStats) 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

A DOMHighResTimeStamp 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 the compatibility table for details on which browsers support them and in which versions.

priority Deprecated Optional

An integer value indicating the candidate pair's priority.

readable Deprecated Optional Non-standard

A Boolean value indicating whether or not data can be sent over the connection described by the candidate pair.

writable Deprecated Optional Non-standard

A Boolean value indicating whether or not data can be received on the connection described by the candidate pair.

Non-standard properties

selected Non-standard Optional

A Firefox-specific Boolean value which is true 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 type transport, which is an RTCTransportStats object. That object's selectedCandidatePairId 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 the RTCIceTransport method getSelectedCandidatePair(), which returns an RTCIceCandidatePair object, or null if there isn't a pair selected. The active candidate pair describes the current configuration of the two ends of the RTCPeerConnection.

Any candidate pair that isn't the active pair of candidates for a transport gets deleted if the RTCIceTransport performs an ICE restart, at which point the state of the ICE transport returns to new and negotiation starts once again. For more information, see ICE restart.

Example

This example computes the average time elapsed between connectivity checks.

js

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 at rtcStats to see if its type is candidate-pair. If it is, then we know that rtcStats is in fact an RTCIceCandidatePairStats object. We can then compute the average time elapsed between STUN connectivity checks and log that information.

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
RTCIceCandidatePairStats 58 79 29 No 45 11 58 58 29 43 11 7.0
availableOutgoingBitrate 58 79 No No 45 11–16.2 58 58 No 43 11–16.2 7.0
bytesDiscardedOnSend 96 96 No No 82 No 96 96 No 67 No 17.0
bytesReceived 58 79 56 No 45 11 58 58 56 43 11 7.0
bytesSent 58 79 56 No 45 11 58 58 56 43 11 7.0
consentRequestsSent 80 80 No No 67 No 80 80 No 57 No 13.0
currentRoundTripTime 7158 7979 No No 5845 11–16.2 7158 7158 No 5043 11–16.2 10.07.0
id 80 80 72 No 67 13.1 80 80 79 57 13.4 13.0
lastPacketReceivedTimestamp 109 109 56 No 95 No 109 109 56 74 No 21.0
lastPacketSentTimestamp 109 109 56 No 95 No 109 109 56 74 No 21.0
localCandidateId 58 79 29 No 45 11 58 58 29 43 11 7.0
nominated 58 79 56 No 45 11 58 58 56 43 11 7.0
packetsDiscardedOnSend 96 96 No No 82 No 96 96 No 67 No 17.0
packetsReceived 96 96 No No 82 No 96 96 No 67 No 17.0
packetsSent 96 96 No No 82 No 96 96 No 67 No 17.0
priority 58 79 4229 No 45 11 58 58 4229 43 11 7.0
remoteCandidateId 58 79 29 No 45 11 58 58 29 43 11 7.0
requestsReceived 58 79 No No 45 11 58 58 No 43 11 7.0
requestsSent 58 79 No No 45 11 58 58 No 43 11 7.0
responsesReceived 58 79 No No 45 11 58 58 No 43 11 7.0
responsesSent 58 79 No No 45 11 58 58 No 43 11 7.0
state 58 79 29 No 45 11 58 58 29 43 11 7.0
timestamp 80 80 72 No 67 13.1 80 80 79 57 13.4 13.0
totalRoundTripTime 7158 7979 No No 5845 11 7158 7158 No 5043 11 10.07.0
transportId 58 79 5629 No 45 11 58 58 5629 43 11 7.0
type 80 80 72 No 67 13.1 80 80 79 57 13.4 13.0

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidatePairStats