The read-only property candidate
on the RTCIceCandidate
interface returns a DOMString
describing the candidate in detail. Most of the other properties of RTCIceCandidate
are actually extracted from this string.
This property can be configured by specifying the value of the candidate
property when constructing the new candidate object using RTCIceCandidate()
.
Syntax
var candidate = RTCIceCandidate.candidate;
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:
foundation
= 4234997325component
="rtp"
(the number 1 is encoded to this string; 2 becomes"rtcp"
)protocol
="udp"
priority
= 2043278322ip
="192.168.0.56"
port
= 44323type
="host"
Example
In this example, we see a function which receives as input an SDP string containing an ICE candidate received from the remote peer during the signaling process.
function handleNewIceCandidate(candidateSDP) {
var candidateObj = new RTCIceCandidate(candidateSDP);
myPeerConnection.addIceCandidate(candidateObj).catch({
/* handle the error thrown by addIceCandidate() */
});
}
The handleNewIceCandidate()
function shown here passes the received candidate's SDP text into RTCIceCandidate()
to receive an RTCIceCanddiate
object in return, which represents the candidate.
The new candidate is then passed into RTCPeerConnection.addIceCandidate()
to add the candidate to the list of candidates for WebRTC to consider using for the connection being established.
This example could be simplified somewhat; you may more often see the code look something like this, taking advantage of more advanced ECMAScript 2016 features:
let handleNewIceCandidate = candidateSDP =>
myPeerConnection.addIceCandidate(new RTCIceCandidate(candidateSDP));
Specifications
Specification | Status | Comment |
WebRTC 1.0: Real-time Communication Between BrowsersThe definition of 'RTCIceCandidate.candidate' in that specification. | Candidate Recommendation | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
candidate
|
Chrome
Full support 23 |
Edge
Full support 15 |
Firefox
Full support 22 |
IE
No support No |
Opera
Full support 15 |
Safari
Full support Yes |
WebView Android
Full support Yes |
Chrome Android
Full support 25 |
Firefox Android
Full support Yes |
Opera Android
Full support 14 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 1.5 |
Legend
- Full support
- Full support
- No support
- No support
RTCIceCandidate.candidate by Mozilla Contributors is licensed under CC-BY-SA 2.5.