WebRTC Debugging and Diagnostics Language

Disconnected is recoverable — failed is not. Handling both states correctly prevents a brief network blip from destroying a call.

ICE connection state lifecycle: new → checking → connected (→ completed) → disconnected → failed (or back to connected if recovery). Disconnected typically happens during brief network changes: switching Wi-Fi networks, going through a tunnel (mobile), or temporary packet loss. WebRTC's ICE agent continues sending keepalives and connectivity checks during disconnected state. If connectivity resumes within ~5 seconds (browser-configurable), the state transitions back to connected — seamless to the user. If not, it transitions to failed. Application strategy: on disconnected, show "Connection unstable — trying to reconnect..."; start a timer; on failed, attempt ICE restart (pc.restartIce()); on timeout, end the call and prompt the user to rejoin.

Key vocabulary:
• disconnected state — transient; ICE lost connectivity but still attempting recovery; may return to connected
• failed state — terminal; all ICE candidates exhausted; requires ICE restart or call teardown
• ICE restart — pc.restartIce(); generates new ICE credentials and triggers fresh candidate gathering to recover from failed state

Packet loss rate = lost / (lost + received) — the denominator is total expected packets. 4.8% is mild-to-moderate: audio survives with Opus FEC; video will show noticeable freezing.

WebRTC quality thresholds (approximate): 0-1% packet loss — excellent; 1-3% — good; 3-5% — degraded video quality, audio acceptable; 5-10% — significant video freezing, audio still intelligible with Opus FEC; 10%+ — video unusable, audio struggles. The getStats() inbound-rtp report also provides framesDecoded, framesDropped, and jitterBufferDelay — together with packetsLost, these give a complete picture of video quality. For the audio track, packetsLost and concealment metrics show how often the jitter buffer had to synthesise audio to cover lost packets. In dashboards, track packet loss rate by candidate pair type — relay paths often have lower packet loss than direct paths in lossy networks.

Key vocabulary:
• packet loss rate — packetsLost / (packetsLost + packetsReceived); key video quality metric
• framesDropped — video frames the decoder dropped due to decode errors or missing reference frames
• jitter buffer — WebRTC's adaptive buffer that absorbs network timing variation; delay vs. smoothness trade-off

chrome://webrtc-internals is the power tool — it captures everything Chrome's WebRTC engine knows, including data not exposed via application APIs.

Critical debugging workflows with chrome://webrtc-internals: (1) codec negotiation debugging — read the full SDP offer and answer side-by-side to see which codecs were negotiated and why; (2) ICE candidate debugging — see ALL gathered candidates (not just the selected pair), which TURN servers were contacted, and which candidate pair is actually in use; (3) quality degradation analysis — getStats() time-series graphs show exactly when packet loss spiked or jitter increased, correlating with user-reported quality issues; (4) DTLS handshake timing — see how long TLS setup took (should be under 100ms; longer suggests TURN relay issues). For non-Chrome browsers, Firefox has about:webrtc and Safari has no equivalent — use getStats() programmatically and log to your own analytics.

Key vocabulary:
• chrome://webrtc-internals — Chrome's internal WebRTC debug page; shows full SDP, all ICE candidates, and stats graphs
• SDP dump — the complete offer/answer SDP content; chrome://webrtc-internals shows this; critical for codec debugging
• active candidate pair — the ICE candidate pair currently being used for media; shown in chrome://webrtc-internals

High RTT compounds packet loss damage for video — each recovery cycle takes longer, extending freeze duration. 850ms RTT means a lost packet can freeze video for nearly 2 seconds (loss detected + NACK sent + retransmission received).

The video freeze/RTT relationship: (1) a packet carrying video frame data is lost; (2) the receiver notices the gap and sends a NACK; (3) with 850ms RTT, the NACK arrives at the sender 425ms after the packet was sent; (4) the sender retransmits; (5) the retransmitted packet arrives another 425ms later — ~850ms of total freeze time for a single lost packet. For comparison, at 50ms RTT (good condition), the same recovery takes ~50ms — imperceptible. Mitigation: if RTT is consistently high, look at TURN relay server geography (the relay may be on the wrong continent), check for bufferbloat on the network path, and consider switching from VP8/VP9 to a lower-latency encoding profile.

Key vocabulary:
• RTT (Round-Trip Time) — total time for a packet to reach the remote peer and the acknowledgement to return; in seconds
• NACK (Negative Acknowledgement) — RTCP message from receiver requesting retransmission of a lost video packet
• bufferbloat — excessive buffering in network equipment causing very high RTT while packet loss remains low

Permanent checking state means ICE is running connectivity checks but none succeed — a classic symptom of NAT traversal failure with a misconfigured or absent TURN server.

Debugging checklist for stuck-in-checking: (1) open chrome://webrtc-internals and check the ICE candidate table — are relay candidates listed? If no relay candidates appear, the TURN server URL is wrong or unreachable; (2) check that ICE candidates from both peers are being received by the other side — if the signaling server has a bug and candidates are dropped, checking will run forever on wrong candidates; (3) test the TURN server directly with a STUN/TURN testing tool (e.g., Trickle ICE online tool); (4) check if TCP TURN (port 443) is configured as a fallback for environments where UDP is blocked; (5) verify the TURN server's authentication credentials (username/password or time-limited token) have not expired.

Key vocabulary:
• checking state — ICE is sending connectivity checks on candidate pairs; waiting for a successful response
• connected state — at least one candidate pair has passed connectivity checks; media can flow
• ICE candidate pair — a combination of local candidate and remote candidate; ICE tests pairs to find a working path