RTCIceCandidateInit.candidate

The optional property candidate in the RTCIceCandidateInit dictionary specifies the value of the RTCIceCandidate object's candidate property.

Value

A DOMString describing the properties of the candidate, taken directly from the SDP attribute "candidate". The candidate string specifies the network connectivity information for the candidate. If the candidate is an empty string (""), the end of the candidate list has been reached; this candidate is known as the "end-of-candidates" marker.

The syntax of the candidate string is described in RFC 5245, section 15.1. For an a-line (attribute line) that looks like this:

a=candidate:4234997325 1 udp 2043278322 192.168.0.56 44323 typ host

the corresponding candidate string's value will be "candidate:4234997325 1 udp 2043278322 192.168.0.56 44323 typ host".

The user agent always prefers candidates with the highest priority, all else being equal. In the example above, the priority is 2043278322. The attributes are all separated by a single space character, and are in a specific order. The complete list of attributes for this example candidate is:

Example

When a new ICE candidate is received by your signaling code from the remote peer, you need to construct the RTCIceCandidate object that encapsulates it. This is done in the event handler for the icecandidate event. If your client-side signaling layer builds and transmits a JSON string including the candidate to the remote peer, the remote peer might handle receiving that JSON message like this:

function gotICECandidateMessage(msg) {
  var iceCandidate = new RTCIceCandidate({
        candidate: msg.candidate;
  });

  pc.addIceCandidate(iceCandidate).catch({
    /* handle error */
  });
}

It's helpful to note that for backward compatibility with older versions of the WebRTC specification, the RTCIceCandidate() constructor accepts the value of candidate as its only input, in place of the RTCIceCandidateInit dictionary. That usage would change the above sample to look like this:

function gotICECandidateMessage(msg) {
  var iceCandidate = new RTCIceCandidate(msg.candidate);

  pc.addIceCandidate(iceCandidate).catch({
    /* handle error */
  });
}

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCIceCandidateInit.candidate' in that specification.
Candidate Recommendation Initial specification.

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
candidateChrome Full support YesEdge Full support ≤18Firefox Full support 22
Notes
Full support 22
Notes
Notes Prior to Firefox 68, the candidate property was required; Firefox 68 and later make it optional per a mid-2017 specification update.
IE No support NoOpera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Prior to Firefox 68, the candidate property was required; Firefox 68 and later make it optional per a mid-2017 specification update.
Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes

Legend

Full support
Full support
No support
No support
Compatibility unknown
Compatibility unknown
See implementation notes.
See implementation notes.

See also