Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Concepts and Signalling

The Offer/Answer Handshake

Understand the WebRTC offer/answer model: signalling states, setLocalDescription and setRemoteDescription, provisional answers, rollback and renegotiation.

Two peers cannot connect until they agree on a few things: which media each side will send, which codecs both understand, which encryption keys to expect, and where the other side can be reached. WebRTC settles this with a short conversation called the offer/answer handshake, defined by JSEP (the JavaScript Session Establishment Protocol). One peer proposes (the offer), the other accepts or narrows the proposal (the answer), and both then apply the result.

The handshake is mostly invisible when you use addTrack and createOffer, but errors such as InvalidStateError: Failed to set remote answer sdp: Called in wrong state: stable come straight from it. Learning the signalling state machine turns those errors from mysteries into one-line fixes.

Local and remote descriptions

Each RTCPeerConnection stores two descriptions:

  • localDescription: what I said I will send and accept.
  • remoteDescription: what they said.

The handshake is complete when each side holds an offer and an answer, one local and one remote. The caller holds local = offer, remote = answer; the callee holds remote = offer, local = answer.

The signalling state machine

pc.signalingState tracks where the conversation stands:

stateDiagram-v2
  [*] --> stable
  stable --> have_local_offer: setLocalDescription(offer)
  stable --> have_remote_offer: setRemoteDescription(offer)
  have_local_offer --> stable: setRemoteDescription(answer)
  have_remote_offer --> stable: setLocalDescription(answer)
  have_local_offer --> stable: rollback
  have_remote_offer --> stable: rollback
  have_local_offer --> have_local_pranswer: setLocalDescription(pranswer)
  have_remote_offer --> have_remote_pranswer: setRemoteDescription(pranswer)
  stable --> closed: close()

The state names use hyphens in code: have-local-offer, have-remote-offer, stable, closed.

Only certain calls are legal in each state. In stable you may apply an offer (either local or remote). In have-local-offer you may only apply an answer (or roll back). Break the rules and the call rejects with InvalidStateError. This table is worth memorising:

You are in Allowed next steps
stable setLocalDescription(offer) or setRemoteDescription(offer)
have-local-offer setRemoteDescription(answer) or rollback
have-remote-offer setLocalDescription(answer) or rollback

The next example prints the state after every call, and then deliberately breaks the rules so you can see the error.

Watch the signalling state change

Offers describe, answers choose

An offer lists everything the offerer supports: every codec, every header extension, every media section (m-line). The answer must be a subset: for each m-line it keeps only the codecs both sides share and cannot add new media sections. That is why an answerer cannot "offer" extra video back; to add something, one side starts a new negotiation with a new offer.

Direction matters too. Each media section has a direction attribute:

Direction Meaning
sendrecv Send and receive
sendonly Only send
recvonly Only receive
inactive Neither (the section is kept but paused)

The answer mirrors the offer: if you offer sendonly, the other side's answer says recvonly (or inactive). The RTCRtpTransceiver.direction and currentDirection properties expose this; we use them in transceivers and senders.

Provisional answers and rollback

Two rarely used features complete the picture:

  • A provisional answer (pranswer) is a tentative answer that lets media start flowing early while a final answer may still change. Most apps never use it.
  • A rollback ({ type: 'rollback' }) abandons a pending offer and returns to stable. It is the key tool for resolving the case where both peers offer at the same time (called glare), described in perfect negotiation.
Rolling back an offer

Renegotiation

A call is rarely static. The user turns on the camera, shares the screen, or you add a data channel after the connection is up. Each such change requires a new offer/answer round on the same connection. The connection tells you when with the negotiationneeded event:

JavaScript
pc.onnegotiationneeded = async () => {
  await pc.setLocalDescription();          // creates the right offer for the state
  signal.send({ description: pc.localDescription });
};

Renegotiation reuses the existing ICE and DTLS connection, so it is fast and does not interrupt media that is already flowing. negotiationneeded fires after adding a track, a transceiver or the first data channel, and when a direction change requires it. It does not fire again while an offer is pending, so a change made during have-local-offer is picked up after the handshake completes.

Here is a connection that starts with a data channel and later adds a second one; the second does not need a new offer because data channels share one SCTP association, but adding a track does:

When does negotiationneeded fire?

You should see negotiationneeded fire for the first data channel and for the video track, but not for the second data channel.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A caller has applied its own offer. What is its signalingState?

    After setLocalDescription(offer) the connection waits for an answer in the have-local-offer state.
  2. 2. What must the answer be, relative to the offer?

    The answer picks from what was offered (shared codecs, matching sections). New media needs a new offer.
  3. 3. Which call returns a connection with a pending offer to stable without an answer?

    A rollback abandons the pending description and returns to stable. It is how perfect negotiation resolves glare.
  4. 4. When does negotiationneeded fire?

    Adding tracks or transceivers (and the first data channel) require renegotiation, so the browser fires the event.

Summary

  • The handshake is one offer and one answer; each side stores a local and a remote description.
  • signalingState moves between stable, have-local-offer and have-remote-offer; calls made in the wrong state reject with InvalidStateError.
  • Answers can only narrow an offer; changes require a new offer on the same connection (renegotiation), triggered by negotiationneeded.
  • A rollback abandons a pending offer.

Next: SDP Explained