Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

The WebRTC API Overview

A map of the WebRTC API: RTCPeerConnection, MediaStream, RTCRtpSender, RTCDataChannel, getStats and the protocols (ICE, DTLS, SRTP, SCTP) beneath them.

WebRTC looks big because it is a family of objects and protocols working together. Once you know who does what, the API stops feeling random. This lesson is a map: the main interfaces, how they relate, and the network protocols hiding underneath. Later lessons zoom into each part.

The interfaces

flowchart TD
  MD["navigator.mediaDevices"] -->|"getUserMedia / getDisplayMedia"| MS["MediaStream"]
  MS --> MT["MediaStreamTrack (audio or video)"]
  MT -->|"addTrack"| PC["RTCPeerConnection"]
  PC --> TR["RTCRtpTransceiver"]
  TR --> SN["RTCRtpSender"]
  TR --> RC["RTCRtpReceiver"]
  PC --> DC["RTCDataChannel"]
  PC --> ICE["RTCIceTransport"]
  PC --> DTLS["RTCDtlsTransport"]
  PC --> SCTP["RTCSctpTransport"]
  PC -->|"getStats"| ST["RTCStatsReport"]

Media comes from mediaDevices as tracks, flows through a peer connection and arrives as tracks on the other side.

Media capture

  • navigator.mediaDevices lists devices (enumerateDevices) and opens them (getUserMedia) or the screen (getDisplayMedia).
  • MediaStream is a bundle of tracks that should be played together, such as one audio and one video track.
  • MediaStreamTrack is a single source of audio or video. It has kind, enabled, muted, readyState, stop() and applyConstraints().

The connection

  • RTCPeerConnection is the heart of WebRTC. One object represents the link to one remote peer. It creates offers and answers, gathers ICE candidates, owns the tracks and channels and reports state.
  • RTCRtpTransceiver pairs a sender and a receiver that share one media section of the SDP. pc.addTrack() creates one for you.
  • RTCRtpSender controls how a track is sent (bitrate, simulcast layers, replacing the track). RTCRtpReceiver exposes the incoming track.
  • RTCDataChannel sends text or binary messages.

Transports

Under a peer connection are objects you rarely touch but often read: RTCIceTransport (the chosen network path), RTCDtlsTransport (encryption keys) and RTCSctpTransport (the pipe carrying data channels). Their states feed pc.iceConnectionState and pc.connectionState.

Descriptions and candidates

  • RTCSessionDescription holds type (offer, answer, pranswer or rollback) and sdp text.
  • RTCIceCandidate describes one possible address and port.

Statistics

pc.getStats() returns an RTCStatsReport: a map of counters and gauges (packets lost, round-trip time, frames decoded, selected candidate pair, and more). It is the foundation of every WebRTC debugging tool, covered in Chapter 7.

The protocol stack

Different layers of the network stack do different jobs. You do not program them directly, but knowing the names makes documentation and error messages readable.

Layer Protocol Job
Discovery STUN Learn your public address
Relay TURN Relay packets when no direct path works
Path selection ICE Gather, pair and test candidate addresses
Encryption DTLS Handshake that provides keys (like TLS for UDP)
Media RTP / SRTP Timestamped, encrypted audio and video packets
Feedback RTCP Loss reports, key frame requests, bandwidth hints
Data SCTP over DTLS Messages for data channels
Codecs Opus, VP8, VP9, H.264, AV1 Compress audio and video

All of this is multiplexed onto one UDP port thanks to BUNDLE, so a call usually needs a single hole in the firewall.

Events you will use all the time

Event Fired when
icecandidate A new local candidate is ready to send to the peer
track A remote track arrived
datachannel The remote peer opened a channel
negotiationneeded Something changed and a new offer is needed
connectionstatechange The overall state changed
iceconnectionstatechange The ICE path state changed
signalingstatechange The offer/answer state machine moved

You can inspect the surface of the API in your own browser. This example lists what a fresh connection exposes without calling any network feature.

Explore a peer connection

Notice that localDescription is null until you set one, and sctp is null until a data channel has been negotiated. Many "undefined" bugs in beginner code come from reading these too early.

How the pieces cooperate: a call in one picture

When you add a camera track and call the other person, this happens:

  1. getUserMedia produces a MediaStream with a video track.
  2. pc.addTrack(track, stream) creates a transceiver and fires negotiationneeded.
  3. You create an offer, apply it, and send it through signalling.
  4. ICE gathers candidates and finds a working pair; DTLS completes the handshake.
  5. The sender packetizes encoded video into SRTP; the receiver decodes it and fires track with a stream you attach to a <video> element.
  6. RTCP feedback adjusts the bitrate while the call runs.

Here is the receiving half using a synthetic video source, since the preview has no camera. A canvas stands in for the camera (more in capturing from canvas and audio).

A track crossing a connection

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which object represents the link to ONE remote peer?

    An RTCPeerConnection owns the tracks, channels and transports for a single remote peer. A group call usually uses several.
  2. 2. What does a MediaStreamTrack represent?

    A track is a single audio or video source. A MediaStream groups tracks that belong together.
  3. 3. Which protocol encrypts data channels and provides keys for media?

    DTLS is TLS adapted to datagrams. It secures SCTP (data channels) and supplies keys for SRTP (media).
  4. 4. Which method gives you counters such as packets lost and round-trip time?

    getStats() returns an RTCStatsReport with detailed metrics used for monitoring and debugging.

Summary

  • Capture gives you MediaStreamTracks; an RTCPeerConnection sends them through senders and receives them through receivers.
  • RTCDataChannel carries arbitrary messages; getStats() exposes metrics.
  • ICE finds the path, DTLS encrypts, SRTP carries media, SCTP carries data, and everything shares one UDP port through BUNDLE.
  • The events icecandidate, track, datachannel and negotiationneeded drive most application code.

Next: Environment, Secure Contexts and Permissions