§ 6.4  Module 6 — Surviving the Network: Loss, Congestion, and Jitter

Reading the Instruments: getStats()

When you can measure what you are speaking about, and express it in numbers, you know something about it.— William Thomson, Lord Kelvin, 1883

6.4.1The report is a graph, not a list

Call await pc.getStats() and you receive an RTCStatsReport: a maplike collection of small dictionaries, each carrying three universal members — a unique id string, a timestamp, and a type that names which dictionary shape you are holding. The types you will read daily: outbound-rtp, one per RTP stream you send (so three of them under simulcast, one per layer); inbound-rtp, one per stream you receive; remote-inbound-rtp and remote-outbound-rtp, your reflection in the far peer's mirror, distilled locally from the RTCP reports it sends back; media-source, the track before the encoder touches it; codec, the negotiated payload formats; transport, the DTLS/ICE bundle underneath everything; and candidate-pair, local-candidate, remote-candidate, the connectivity lattice from Module 3.

What makes the report navigable is that these dictionaries reference each other by id. An outbound-rtp entry carries a mediaSourceId, a codecId, a transportId, and a remoteId naming its remote-inbound-rtp twin; the transport carries a selectedCandidatePairId; the pair carries localCandidateId and remoteCandidateId. The report is a relational database serialized as a Map, and every question you will ever ask of it is a join: report.get(stat.someId). Nothing is nested; everything is flat and keyed. Learn the graph once — Figure 6.4.1 draws the sender's half — and any statistic is three hops away.

6.4.2The delta discipline

Here is the trap that has broken more dashboards than any other: almost nothing in the report is a rate. bytesSent, packetsSent, framesEncoded, packetsLost, nackCount — all cumulative counters, monotonically climbing since the stream began. The design is deliberate and it is the right one: a counter survives a missed poll (you lose resolution, never information), it cannot double-count, and any consumer can derive a rate over whatever window it likes. But it means the raw number is nearly meaningless on its own. A bytesSent of 52,911,437 tells you the call has been running a while; it says nothing about whether video is flowing now.

The discipline: keep the previous sample, subtract, and divide by the delta of the report's own timestamp field — a DOMHighResTimeStamp in milliseconds. Never divide by your polling interval. You asked setInterval for 1,000 ms; the event loop delivered 1,007, or 1,340 under load, and the report itself was composed at some instant you do not control. The timestamp member records when the counters were actually read, and it is the only denominator that makes the arithmetic honest:

const prev = new Map();                      // ssrc → last sample
async function sample(pc) {
  const report = await pc.getStats();
  for (const s of report.values()) {
    if (s.type !== 'outbound-rtp' || s.kind !== 'video') continue;
    const p = prev.get(s.ssrc);
    if (p) {
      const dt   = (s.timestamp - p.timestamp) / 1000;      // ms → s
      const kbps = (s.bytesSent - p.bytesSent) * 8 / dt / 1000;
      const fps  = (s.framesEncoded - p.framesEncoded) / dt;
      render(s.ssrc, kbps, fps);
    }
    prev.set(s.ssrc, s);
  }
}
setInterval(() => sample(pc), 1000);

Listing 6.4.1 — the delta discipline. Rates come from consecutive-sample subtraction over the report's own timestamps, never from the counters or the intended polling interval.

The same discipline yields packet rate from packetsSent, loss rate from packetsLost against packetsReceived, and encoder framerate from framesEncoded. Comparing joined entries across one report is equally revealing without any deltas at all: when media-source says the camera delivers 1280 × 720 at 30 fps and outbound-rtp says frameWidth 640, frameHeight 360, the gap between them is adaptation, measured — the encoder is shedding load, and § 6.4.4 tells you why.

Predict before you compute — both questions below are one subtraction away.

6.4.3Two round-trip times and one jitter

Ask "what is the RTT?" and the report answers twice, from two different instruments. The first lives in remote-inbound-rtp.roundTripTime and is measured by RTCP: your sender stamps a Sender Report, the far end's Receiver Report echoes when it last saw one (LSR) and how long it sat on it (DLSR), and arrival time minus both is the round trip (RFC 3550 §6.4.1). This is the RTT of the media path for that specific stream, refreshed at RTCP cadence — roughly once a second. The second lives in candidate-pair.currentRoundTripTime and is measured a layer down, by the STUN connectivity checks that ICE keeps sending as keepalives and consent probes (RFC 7675): the transport's RTT, per candidate pair, independent of any media. They usually agree; when they diverge, the divergence is itself a symptom — RTCP RTT climbing while STUN RTT holds steady points at remote endpoint distress rather than the network. Both are reported in seconds, and both come with averaging companions (totalRoundTripTime ÷ roundTripTimeMeasurements and responsesReceived) when a single reading is too noisy.

Jitter is worse, because it changes units between the wire and the API. On the wire, the interarrival jitter carried in RTCP reports is expressed in RTP timestamp ticks — the media clock, 90 kHz for video, 48 kHz for Opus. The jitter member of inbound-rtp (and of remote-inbound-rtp) is that same quantity divided by the codec's clock rate: seconds. A reading of 0.045 is 45 milliseconds of interarrival variation — enough that the jitter buffer of § 6.3 is holding a deep cushion and NetEQ is time-stretching to hide it. Read it as milliseconds and you will conclude the network is pristine while your users hear soup.

6.4.4qualityLimitationReason and the adaptation ladder

Module 6 has argued that the encoder's bitrate is not its own: the congestion controller hands down a target, and the encoder obeys. outbound-rtp is where that obedience becomes visible. The qualityLimitationReason member says, in one word, why the encoder is not producing the quality the track could support: 'none' (it is), 'bandwidth' (the target bitrate is the ceiling), 'cpu' (the machine cannot encode fast enough), or 'other'. Its companion qualityLimitationDurations is a map of seconds spent in each state — the call's whole history of struggle in four numbers — and qualityLimitationResolutionChanges counts how many times the encoder actually moved a rung. The word choice matters for remediation: 'bandwidth' indicts the network or a configured cap, and the fix is congestion-side; 'cpu' indicts the endpoint — a laptop on battery, a browser encoding three simulcast layers in software — and no amount of bandwidth will help it.

The surrounding counters tell you what the struggle is costing. retransmittedPacketsSent is the RTX tax paid to repair loss; nackCount and pliCount on outbound-rtp count the NACK and PLI messages of the RTCP feedback machinery this sender has received — the direction reads backwards until you internalize that feedback about your sending arrives inbound. On the receive side, inbound-rtp.framesDropped counts frames that arrived but were discarded before display, typically for arriving too late to render — loss the network never saw. A rising pliCount with a rising retransmittedPacketsSent is a lossy path; a rising framesDropped with clean packet counts is a late path, and § 6.3's buffer is where the lateness is being paid.

When the encoder must shed load, what it sacrifices is a policy you control. The degradationPreference member of the sender's parameters (set through setParameters) chooses the ladder: 'maintain-framerate' walks resolution down and keeps motion smooth; 'maintain-resolution' walks framerate down and keeps pixels sharp; 'balanced', the default, alternates. The track-level contentHint property declares what the pixels are — 'motion', 'detail', or 'text' for video — so the pipeline can choose codecs, tools, and ladders to match; Chrome treats screen-capture tracks and tracks hinted 'detail' or 'text' as resolution-precious. The stakes are concrete for the screen-share case: § 5.3 showed how 4:2:0 chroma subsampling already bleeds red text at full resolution; let the adaptation ladder halve the resolution under congestion and the glyphs dissolve entirely. A code review over a congested link wants contentHint = 'text' and 'maintain-resolution': fifteen sharp frames per second beat thirty blurred ones when the content is a diff.

6.4.5Finding the pair that carries the call

The last join is the one most often botched. A live report contains many candidate-pair entries — every pairing ICE ever checked, frozen at various states — and exactly one of them is carrying your media. The tempting heuristics are all wrong. Picking the pair with the most bytesSent fails after a network change: the stale pair keeps its byte totals forever, and the fresh pair — perhaps a TURN relay pair adopted when WiFi dropped — starts from zero. Filtering on nominated === true fails too, because nomination is sticky history, not present tense: after an ICE restart or renomination, several succeeded pairs can carry the flag. The authoritative answer is the transport's own declaration: find the transport entry — the same dictionary that reports the DTLS handshake state — and resolve its selectedCandidatePairId. One join, no guessing.

Once you hold the right pair, it is the richest dictionary in the report: currentRoundTripTime from § 6.4.3, availableOutgoingBitrate straight from the bandwidth estimator, request/response counters for the STUN conversation, and the two candidate ids that tell you — via one more join — whether this call is host-to-host on a LAN or relayed through a TURN server two countries away. That, plus the delta discipline, plus the graph, is the whole craft. A word of calibration before the problems: connectionState === 'connected' tells you the transport is up, and nothing more; whether video is actually flowing is a question only inbound-rtp's climbing counters can answer. The person others call when "the video is bad" is simply the person who knows which dictionary to open, which counter to subtract, and which of two RTTs to believe.

Problems for § 6.4Check your understanding

Two items: build the poller every production WebRTC service contains, then prove you know where the numbers live and what units they wear.

¶Field quirks

What the specifications say, and what the browsers actually do, are two different documents. These are the divergences that cost production teams their weekends.