RTCIceCandidate

BaselineWidely available *

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

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

TheRTCIceCandidate interface—part of theWebRTC API—represents a candidate Interactive Connectivity Establishment (ICE) configuration which may be used to establish anRTCPeerConnection.

An ICE candidate describes the protocols and routing needed for WebRTC to be able to communicate with a remote device. When starting a WebRTC peer connection, typically a number of candidates are proposed by each end of the connection, until they mutually agree upon one which describes the connection they decide will be best. WebRTC then uses that candidate's details to initiate the connection.

For details on how the ICE process works, seeLifetime of a WebRTC session. The articleWebRTC connectivity provides additional useful details.

Constructor

RTCIceCandidate(): Creates anRTCIceCandidate object to represent a single ICE candidate, optionally configured based on a configuration object.
Note:For backwards compatibility, the constructor also accepts as input a string containing the value of thecandidate property instead of the configuration object.

Instance properties

addressRead only: A string containing the IP address of the candidate.
candidateRead only: A string representing the transport address for the candidate that can be used for connectivity checks. The format of this address is acandidate-attribute as defined inRFC 5245. This string is empty ("") if theRTCIceCandidate is an "end of candidates" indicator.
componentRead only: A string which indicates whether the candidate is an RTP or an RTCP candidate; its value is eitherrtp orrtcp, and is derived from the"component-id" field in thecandidate a-line string.
foundationRead only: Returns a string containing a unique identifier that is the same for any candidates of the same type, share the same base (the address from which the ICE agent sent the candidate), and come from the sameSTUN server. This is used to help optimize ICE performance while prioritizing and correlating candidates that appear on multipleRTCIceTransport objects.
portRead only: An integer value indicating the candidate's port number.
priorityRead only: A long integer value indicating the candidate's priority.
protocolRead only: A string indicating whether the candidate's protocol is"tcp" or"udp".
relatedAddressRead only: If the candidate is derived from another candidate,relatedAddress is a string containing that host candidate's IP address. For host candidates, this value isnull.
relatedPortRead only: For a candidate that is derived from another, such as a relay or reflexive candidate, therelatedPort is a number indicating the port number of the candidate from which this candidate is derived. For host candidates, therelatedPort property isnull.
sdpMidRead only: A string specifying the candidate's media stream identification tag which uniquely identifies the media stream within the component with which the candidate is associated, ornull if no such association exists.
sdpMLineIndexRead only: If notnull,sdpMLineIndex indicates the zero-based index number of the media description (as defined inRFC 4566) in theSDP with which the candidate is associated.
tcpTypeRead only: Ifprotocol is"tcp",tcpType represents the type of TCP candidate. Otherwise,tcpType isnull.
typeRead only: A string indicating the type of candidate as one of the strings listed onRTCIceCandidate.type.
usernameFragmentRead only: A string containing a randomly-generated username fragment ("ice-ufrag") which ICE uses for message integrity along with a randomly-generated password ("ice-pwd"). You can use this string to verify generations of ICE generation; each generation of the same ICE process will use the sameusernameFragment, even across ICE restarts.

Instance methods

toJSON(): Returns aJSON representation of theRTCIceCandidate's current configuration.The format of the representation is the same as thecandidateInfo object that can optionally be passed to theRTCIceCandidate() constructor to configure a candidate.