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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome Full support YesEdge Full support YesFirefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown

See also

Document Tags and Contributors

Contributors to this page: Sheppy
Last updated by: Sheppy,