Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Your First Loopback Call

Build your first WebRTC connection: two RTCPeerConnection objects in one page exchange an offer, an answer and ICE candidates, then send a message.

The best way to understand WebRTC is to make a connection yourself. A loopback call connects two RTCPeerConnection objects that live in the same page. It is not useful for users, but it is perfect for learning: you can watch every step of the handshake without a second computer or a server, and the code is nearly identical to what you would write between two real browsers.

In a real application the two peers would be in different browsers and the messages between them would travel over a signalling channel. Here, "sending a message to the other side" is just a function call. Keep that in mind: every place where we pass something from alice to bob is a place where a real app would use signalling.

The cast

  • Alice is the caller. She creates the offer.
  • Bob is the callee. He answers.
  • Signalling is us, copying values between them.
sequenceDiagram
  participant A as Alice
  participant B as Bob
  A->>A: createOffer, setLocalDescription
  A->>B: offer (SDP)
  B->>B: setRemoteDescription, createAnswer, setLocalDescription
  B->>A: answer (SDP)
  A->>A: setRemoteDescription
  A-->>B: ICE candidates
  B-->>A: ICE candidates
  A<<->>B: data channel open

The offer/answer exchange describes what each side can do; the ICE candidates describe how to reach each side.

Step by step

  1. Create two connections.
  2. Alice creates a data channel. This matters: a connection with nothing to send (no tracks, no channel) produces an offer with nothing to negotiate.
  3. Alice calls createOffer(), which returns a description (SDP) of what she wants. She applies it with setLocalDescription().
  4. The description goes to Bob, who applies it with setRemoteDescription().
  5. Bob calls createAnswer(), applies it locally, and sends it back.
  6. Alice applies the answer as her remote description.
  7. While this happens, each side discovers ICE candidates (possible network addresses) and passes them to the other with addIceCandidate().
  8. When a candidate pair works, the connection state becomes connected and the data channel opens.
A complete loopback connection

You should see the signalling state go to have-local-offer and then stable, the connection become connected, and the ping and pong messages. The order of some lines can differ slightly between browsers because network events are asynchronous.

Reading the code

createOffer() inspects what the connection currently wants to send or receive (here: a data channel) and returns an RTCSessionDescription whose type is "offer" and whose sdp is a block of text. It does not change the connection.

setLocalDescription(offer) commits the offer on Alice's side. This is also the moment she starts gathering ICE candidates, which is why onicecandidate events begin soon after. Calling setLocalDescription() with no argument creates the right description automatically, a shortcut used in perfect negotiation.

setRemoteDescription() tells a connection what the other side offered or answered. After Bob applies Alice's offer, his connection knows a data channel is coming and fires ondatachannel.

onicecandidate fires for each candidate and finally once with candidate === null (gathering finished). We forward every non-null candidate to the other peer.

The other way to write it: wait for gathering

Forwarding candidates one at a time is called trickle ICE. A simpler variant waits until gathering finishes and then sends one complete description with all candidates inside. It is slower to start but needs only two messages, which is great for copy-and-paste demos.

One message each way (no trickle)

JSON.stringify(pc.localDescription) works because RTCSessionDescription has a toJSON() method. Notice that nothing here calls addIceCandidate: the candidates travelled inside the SDP.

Common mistakes

  • Nothing to negotiate. Creating an offer with no track, transceiver or data channel gives an SDP with no media sections, so the connection never really connects. Add a channel or a track first.
  • Forgetting await. createOffer, setLocalDescription and friends return promises. Calling setRemoteDescription before the previous step finishes throws InvalidStateError.
  • Using offer instead of pc.localDescription. After setLocalDescription, localDescription may include extra data (such as candidates gathered so far). Sending it is the safer habit.
  • Adding candidates too early. addIceCandidate needs a remote description to exist. With real signalling, candidates can arrive before the answer; apps queue them. We cover this in signalling channels.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does Alice create a data channel before calling createOffer()?

    An offer describes the media and data sections the connection wants. With none added, there is nothing to connect.
  2. 2. Which call starts ICE candidate gathering?

    Gathering begins when a local description is applied, which is why onicecandidate events follow setLocalDescription().
  3. 3. What does onicecandidate receive at the end of gathering?

    A final event with candidate set to null signals that gathering is complete.
  4. 4. In our loopback example, what plays the role of the signalling channel?

    Passing descriptions and candidates by function call stands in for a WebSocket or other channel in a real app.

Summary

  • A call starts with an offer from the caller and an answer from the callee, both applied with setLocalDescription and setRemoteDescription.
  • Add a data channel or media track first, or the offer is empty.
  • ICE candidates travel separately (trickle ICE) or are bundled in the SDP after gathering finishes.
  • In a real app you replace the direct function calls with a signalling channel.

Next: WebRTC API Overview