W3cubDocs

/Web APIs

RTCIceCandidate

The RTCIceCandidate interface—part of the WebRTC API—represents a candidate Interactive Connectivity Establishment (ICE) configuration which may be used to establish an RTCPeerConnection.

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, see Lifetime of a WebRTC session. The article WebRTC connectivity provides additional useful details.

Constructor

RTCIceCandidate()

Creates an RTCIceCandidate 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 the candidate property instead of the configuration object.

Properties

address Read only

A DOMString containing the IP address of the candidate.

candidate Read only

A DOMString representing the transport address for the candidate that can be used for connectivity checks. The format of this address is a candidate-attribute as defined in RFC 5245. This string is empty ("") if the RTCIceCandidate is an "end of candidates" indicator.

component Read only

A string which indicates whether the candidate is an RTP or an RTCP candidate; its value is either rtp or rtcp, and is derived from the "component-id" field in the candidate a-line string.

foundation Read only

Returns a DOMString 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 same STUN server. This is used to help optimize ICE performance while prioritizing and correlating candidates that appear on multiple RTCIceTransport objects.

port Read only

An integer value indicating the candidate's port number.

priority Read only

A long integer value indicating the candidate's priority.

protocol Read only

A string indicating whether the candidate's protocol is "tcp" or "udp".

relatedAddress Read only

If the candidate is derived from another candidate, relatedAddress is a DOMString containing that host candidate's IP address. For host candidates, this value is null.

relatedPort Read only

For a candidate that is derived from another, such as a relay or reflexive candidate, the relatedPort is a number indicating the port number of the candidate from which this candidate is derived. For host candidates, the relatedPort property is null.

sdpMid Read only

A DOMString specifying the candidate's media stream identification tag which uniquely identifies the media stream within the component with which the candidate is associated, or null if no such association exists.

sdpMLineIndex Read only

If not null, sdpMLineIndex indicates the zero-based index number of the media description (as defined in RFC 4566) in the SDP with which the candidate is associated.

tcpType Read only

If protocol is "tcp", tcpType represents the type of TCP candidate. Otherwise, tcpType is null.

type Read only

A DOMString indicating the type of candidate as one of the strings listed on RTCIceCandidate.type.

usernameFragment Read only

A DOMString 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 same usernameFragment, even across ICE restarts.

Methods

toJSON()

Returns a JSON representation of the RTCIceCandidate's current configuration. The format of the representation is the same as the candidateInfo object that can optionally be passed to the RTCIceCandidate() constructor to configure a candidate.

Examples

For examples, see the article Signaling and video calling, which demonstrates the entire process.

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
RTCIceCandidate
23
15
44
22
No
15
11
≤37
25
44
22
14
11
1.5
RTCIceCandidate
23
15
44
Before Firefox 68, the constructor's options parameter was required.
22
Before Firefox 68, the constructor's options parameter was required.
No
15
11
≤37
25
44
Before Firefox 68, the constructor's options parameter was required.
22
Before Firefox 68, the constructor's options parameter was required.
14
11
1.5
address
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
candidate
23
15
22
No
15
11
≤37
25
Yes
14
11
1.5
component
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
foundation
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
port
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
priority
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
protocol
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
relatedAddress
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
relatedPort
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
sdpMid
23
15
22
No
15
11
≤37
25
Yes
14
11
1.5
sdpMLineIndex
23
15
22
No
15
11
≤37
25
Yes
14
11
1.5
tcpType
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
toJSON
43
15
27
No
30
11
43
43
27
30
11
4.0
type
74
79
No
No
62
14.1
74
74
No
53
14.5
11.0
usernameFragment
74
79
67
No
62
14.1
74
74
67
53
14.5
11.0

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