webrtc P2P

RTCIceCandidate

Signature

const candidate = new RTCIceCandidate(candidateInit);
// candidateInit: { candidate, sdpMid, sdpMLineIndex, usernameFragment }

What it does

Describes one candidate transport address discovered during ICE gathering. Candidates are exchanged over signaling and added to the connection until a working pair is found.

Key members

Member Kind Purpose
candidate property The raw SDP candidate attribute string.
sdpMid property The media stream identification this candidate applies to.
sdpMLineIndex property Index of the m-line in the SDP.
usernameFragment property The ICE ufrag the candidate belongs to.
foundation property Identifier shared by candidates of the same type and base.
protocol property Transport protocol: udp or tcp.
type property Candidate type: host, srflx, prflx, or relay.
address / port property The candidate's IP address and port.

Behaviour & constraints

  • Most read-only members are null until the candidate string is parsed by the browser.
  • Pass the object received from the remote icecandidate event straight to addIceCandidate().
  • An empty candidate string signals end-of-candidates for that generation.
  • type relay means a TURN server is in the path; STUN-only setups never produce relay candidates.
  • Candidates are useless without their sdpMid or sdpMLineIndex to bind them to a media section.

Example

pc.onicecandidate = ({ candidate }) => {
  if (candidate) signalingSend(candidate.toJSON());
};

// remote side
signalingOn('candidate', (init) => {
  pc.addIceCandidate(new RTCIceCandidate(init));
});

See also