Debug WebRTC Voice Agents: Complete Checklist & Troubleshooting Guide

TL;DR: Debug WebRTC voice agents using this 3-layer diagnostic approach:

Start at the Network layer. If ICE never reaches "connected", nothing else matters. If RTP stats show packet loss >5%, audio quality degrades before it reaches your AI pipeline. Only debug STT/LLM/TTS after verifying network and media are healthy.

Related Guides:

• Voice Agent Troubleshooting Guide — Complete diagnostic checklist for ASR, LLM, TTS, and tool failures
• Voice Agent Incident Response Runbook — 4-Stack framework for production outages
• Voice Agent Observability & Tracing — OpenTelemetry tracing for voice pipelines
• How to Evaluate and Test Voice Agents — 4-Layer QA Framework
• Voice Agent Evaluation Metrics Guide — Metrics library with formulas and benchmarks

Quick Symptom Lookup

Jump to the section that matches your issue:

WebRTC Debugging Fundamentals

Voice agents built on WebRTC require debugging across multiple layers that traditional application monitoring doesn't cover: network traversal (ICE/STUN/TURN), media transport (RTP/jitter/packet loss), and the AI pipeline (STT/LLM/TTS latency). Engineers face limited visibility compared to traditional systems—no standard observability for interruption patterns, ASR drift, or orchestration delays.

This guide provides symptom-to-cause diagnostics, structured logging patterns, and framework-specific debugging for LiveKit and Pipecat implementations.

Browser-Based Debugging with chrome://webrtc-internals

chrome://webrtc-internals is the most comprehensive tool for debugging WebRTC connections in real-time.

How to use it:

1. Open chrome://webrtc-internals in Chrome (v87+) before starting your voice agent session
2. Start the voice agent call—connection data will populate automatically
3. Look for the peer connection entry and expand it to see:
   • ICE candidate pairs and connection state
   • Inbound/outbound RTP statistics (packet loss, jitter, RTT)
   • Audio/video track statistics

Critical: Open webrtc-internals before the call starts. Connection establishment data (ICE gathering, candidate exchange) is only captured if the tab is open before the session begins.

Key sections to check:

Firefox alternative: Use about:webrtc for similar functionality, though with fewer features than Chrome.

Production monitoring: chrome://webrtc-internals is impractical outside development. For production, implement client-side event tracing using the getStats() API to collect RTP statistics programmatically.

Understanding WebRTC Connection Architecture

WebRTC uses the Interactive Connectivity Establishment (ICE) framework to establish peer connections through firewalls:

┌─────────────────────────────────────────────────────────────────┐
│                    ICE Connection Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Client A                                        Client B       │
│     │                                               │           │
│     │  1. Gather ICE candidates                     │           │
│     │     (host, srflx, relay)                      │           │
│     │                                               │           │
│     │  2. Exchange candidates via signaling         │           │
│     │ ─────────────────────────────────────────────>│           │
│     │<─────────────────────────────────────────────│           │
│     │                                               │           │
│     │  3. Connectivity checks (STUN binding)        │           │
│     │<─────────────────────────────────────────────>│           │
│     │                                               │           │
│     │  4. Select best candidate pair                │           │
│     │═══════════════════════════════════════════════│           │
│     │         Media flows directly or via TURN      │           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

ICE candidate types:

STUN (Session Traversal Utilities for NAT): Discovers your public IP address and NAT type. Works for most home/office NATs but fails with Symmetric NAT.

TURN (Traversal Using Relays around NAT): Relays all media through the server. Required when Symmetric NAT blocks direct connections (~20% of cases). Adds 20-50ms latency overhead.

SDP Negotiation and Signaling

Session Description Protocol (SDP) describes the multimedia session: codecs, formats, encryption parameters.

Offer/Answer flow:

1. Caller creates SDP offer with supported codecs
2. Offer sent via signaling channel (WebSocket, HTTP)
3. Callee creates SDP answer, accepting/rejecting codecs
4. Answer sent back via signaling
5. Both sides set local/remote descriptions
6. ICE gathering begins after local description is set

Common SDP negotiation failures:

Signaling state transitions:

stable → have-local-offer → have-remote-answer → stable (caller)
stable → have-remote-offer → have-local-answer → stable (callee)

Monitor signalingState changes—unexpected states indicate negotiation problems.

Network and Connectivity Troubleshooting

ICE Connection Failure Diagnosis

Symptom: ICE connection state stuck on "checking" or transitions to "failed"

Diagnostic steps:

1. Check ICE candidate gathering in webrtc-internals:

   • Look for iceGatheringState → should reach "complete"
   • Check iceCandidates array for all three types (host, srflx, relay)
   • Missing srflx candidates = STUN server unreachable
   • Missing relay candidates = TURN server unreachable or bad credentials

2. Check ICE connection state transitions:

   new → checking → connected → completed  ← Success
   new → checking → failed                  ← Failure

3. Examine candidate pairs:

   • Look for pairs with state "succeeded"
   • If all pairs show "failed", connectivity is blocked

ICE failure causes and fixes:

STUN/TURN Configuration Verification

Verify STUN server connectivity:

// Test STUN binding request
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

pc.onicecandidate = (e) => {
  if (e.candidate) {
    console.log('Candidate type:', e.candidate.type);
    // 'srflx' = STUN working
    // 'host' only = STUN not working
  }
};

pc.createDataChannel('test');
pc.createOffer().then(offer => pc.setLocalDescription(offer));

Verify TURN server connectivity:

const pc = new RTCPeerConnection({
  iceServers: [{
    urls: 'turn:your-turn-server.com:3478',
    username: 'your-username',
    credential: 'your-credential'
  }],
  iceTransportPolicy: 'relay' // Force TURN only
});

pc.onicecandidate = (e) => {
  if (e.candidate && e.candidate.type === 'relay') {
    console.log('TURN working: relay candidate gathered');
  }
};

TURN allocation failure causes:

Wireshark debugging:

# Capture STUN/TURN traffic
wireshark -f "udp port 3478 or udp port 5349 or tcp port 443"

Look for:

• STUN Binding Request → Binding Response (success)
• TURN Allocate Request → Allocate Response (success)
• TURN CreatePermission → CreatePermission Response

Firewall and NAT Traversal Problems

Symptom: Connection works on some networks but fails on others

Corporate firewall diagnosis:

NAT type diagnosis:

Symmetric NAT detection: If srflx candidates gather but ICE connectivity checks fail, suspect Symmetric NAT. Force TURN relay:

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'turn:your-server.com:443?transport=tcp', username: '...', credential: '...' }
  ]
});

RTP Media Quality Analysis

Understanding RTP Statistics

Once ICE connection succeeds, audio flows via RTP. Use getStats() API to monitor quality:

// Collect RTP statistics every 2 seconds
setInterval(async () => {
  const stats = await peerConnection.getStats();
  stats.forEach(report => {
    if (report.type === 'inbound-rtp' && report.kind === 'audio') {
      console.log('Packets received:', report.packetsReceived);
      console.log('Packets lost:', report.packetsLost);
      console.log('Jitter (ms):', report.jitter * 1000);
    }
    if (report.type === 'remote-inbound-rtp' && report.kind === 'audio') {
      console.log('Round trip time (ms):', report.roundTripTime * 1000);
    }
  });
}, 2000);

Key RTP metrics from webrtc-internals:

Voice Quality Thresholds

Production thresholds for voice agents (based on Hamming's analysis of 1M+ calls):

Impact of threshold violations:

Jitter Buffer Analysis

Jitter buffers smooth out packet arrival variations but add latency:

Jitter buffer underrun symptoms:

• Audio plays in bursts with gaps
• Words cut off mid-syllable
• Robotic or stuttering speech

Check jitter buffer health in webrtc-internals:

• Look for jitterBufferDelay and jitterBufferEmittedCount
• Calculate average delay: jitterBufferDelay / jitterBufferEmittedCount * 1000 (ms)

Packet Loss Patterns

Bursty vs. random packet loss:

Check packet loss direction:

• inbound-rtp.packetsLost = packets lost coming TO you
• remote-inbound-rtp.packetsLost = packets lost going FROM you

Asymmetric loss points to one-way network issues (different upload/download paths).

Voice Agent Pipeline Debugging

STT/LLM/TTS Latency Breakdown

Voice agent response latency accumulates across the pipeline:

┌─────────────────────────────────────────────────────────────────────────┐
│        Voice Agent Latency Breakdown (Production Reality)               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  User speaks    Audio      STT         LLM         TTS      Audio      │
│      │         capture   process     inference   synthesis  playback   │
│      │           │          │           │           │          │        │
│      │◄─ 70ms ──►│◄─350ms ─►│◄600-1000ms►│◄─100ms ──►│◄─ ~10ms ►│       │
│      │           │          │           │           │          │        │
│      └───────────┴──────────┴───────────┴───────────┴──────────┘        │
│                                                                         │
│      Total: ~1.2-1.6s + network hops (~10ms each × 10 hops = ~100ms)    │
│      Production metrics: P50 ~1.5s, P95 ~5s (Hamming data from 1M+ calls)│
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Component latency targets (based on Hamming production data from 1M+ calls):

Measuring Component-Level Latency

Track these milestones per turn:

const turnMetrics = {
  // Audio
  userSpeechStart: null,      // VAD detects speech
  userSpeechEnd: null,        // VAD detects silence (endpointing)

  // STT
  sttRequestStart: null,      // Audio sent to STT
  sttFirstPartial: null,      // First partial transcript received
  sttFinalTranscript: null,   // Final transcript received

  // LLM
  llmRequestStart: null,      // Prompt sent to LLM
  llmFirstToken: null,        // First token received
  llmComplete: null,          // Full response received

  // TTS
  ttsRequestStart: null,      // Text sent to TTS
  ttsFirstByte: null,         // First audio byte received
  ttsComplete: null,          // Full audio received

  // Playback
  audioPlaybackStart: null,   // Audio playback begins
};

// Calculate latencies
const sttLatency = turnMetrics.sttFinalTranscript - turnMetrics.userSpeechEnd;
const llmLatency = turnMetrics.llmComplete - turnMetrics.llmRequestStart;
const ttsLatency = turnMetrics.ttsFirstByte - turnMetrics.ttsRequestStart;
const turnAroundTime = turnMetrics.audioPlaybackStart - turnMetrics.userSpeechEnd;

Report P50/P95/P99 for each milestone. A single blended latency number hides variance—your P50 might be 600ms while P95 is 2000ms.

Barge-In and Interruption Handling

Barge-in = user interrupts while agent is speaking. Critical for natural conversation.

Barge-in requirements:

Common barge-in failures:

Debug barge-in:

// Log barge-in events
voiceAgent.on('bargeIn', (event) => {
  console.log({
    detectionLatency: event.detectedAt - event.userSpeechStart,
    agentStopLatency: event.agentStoppedAt - event.detectedAt,
    agentWasSpeaking: event.agentAudioPosition,
    userTranscript: event.interruptingUtterance
  });
});

Turn Detection and Endpointing Issues

Endpointing = determining when the user finished speaking.

Endpointing tradeoffs:

Common endpointing failures:

Debug endpointing:

// Log endpointing decisions
speechRecognizer.on('endOfUtterance', (event) => {
  console.log({
    silenceDuration: event.silenceDurationMs,
    threshold: event.configuredThresholdMs,
    transcriptLength: event.transcript.length,
    confidence: event.confidence,
    wasInterrupted: event.interrupted
  });
});

Audio Quality Failure Modes

One-Way Audio Diagnosis

Symptom: One participant hears audio, the other hears nothing.

Diagnostic checklist:

• Check webrtc-internals for packet counts
  • outbound-rtp.packetsSent > 0? You're sending.
  • inbound-rtp.packetsReceived > 0? You're receiving.
• Zero inbound + non-zero outbound = remote side not sending or packets blocked
• Non-zero inbound + zero outbound = local side not sending or packets blocked

One-way audio causes:

Echo and Feedback Issues

Echo cancellation (AEC3) is critical for voice agents—the agent's TTS audio must not trigger its own VAD.

Echo symptoms:

Debug echo issues:

// Check audio processing settings
const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true
  }
});

// Verify settings applied
const track = stream.getAudioTracks()[0];
console.log(track.getSettings());

Choppy or Robotic Voice

Symptom: Audio plays in bursts, sounds mechanical.

Diagnostic steps:

1. Check packet loss in webrtc-internals

   • 5% packet loss = severe degradation

   • 10% packet loss = nearly unintelligible

2. Check jitter buffer underruns

   • Look for gaps in audio level meter
   • Check jitterBufferDelay trending

3. Check CPU usage

   • High CPU can cause frame drops
   • Check totalProcessingDelay stat

Choppy audio causes and fixes:

Framework-Specific Debugging

LiveKit Voice Agent Debugging

LiveKit provides a real-time framework for production-grade multimodal voice agents with WebRTC media server.

LiveKit-specific debugging tools:

Debug LiveKit agent pipeline:

# Enable verbose logging in LiveKit agent
import logging
logging.basicConfig(level=logging.DEBUG)

from livekit.agents import JobContext, WorkerOptions, cli

async def entrypoint(ctx: JobContext):
    # Log connection state
    ctx.room.on("connection_state_changed", lambda state:
        print(f"Connection state: {state}"))

    # Log participant events
    ctx.room.on("participant_connected", lambda p:
        print(f"Participant connected: {p.identity}"))

    # Log track subscriptions
    ctx.room.on("track_subscribed", lambda track, publication, participant:
        print(f"Track subscribed: {track.kind} from {participant.identity}"))

LiveKit connection issues:

Hamming integration for LiveKit: Hamming offers LiveKit-to-LiveKit WebRTC testing: auto-provisioned rooms, scenario generation from prompts, 50+ quality metrics evaluated in <10 minutes.

Pipecat Pipeline Troubleshooting

Pipecat specializes in real-time voice agent infrastructure with STT/LLM/TTS orchestration.

Pipecat debugging tools:

Common Pipecat issues:

Debug Pipecat pipeline latency:

from pipecat.pipeline import Pipeline
from pipecat.services.deepgram import DeepgramSTT
from pipecat.services.openai import OpenAILLMService
from pipecat.services.cartesia import CartesiaTTS
import time

class LatencyLogger:
    def __init__(self):
        self.timestamps = {}

    async def log_stt_output(self, frame):
        self.timestamps['stt_complete'] = time.time()
        print(f"STT latency: {self.timestamps['stt_complete'] - self.timestamps.get('speech_end', 0):.3f}s")

    async def log_llm_output(self, frame):
        self.timestamps['llm_first_token'] = time.time()
        print(f"LLM TTFT: {self.timestamps['llm_first_token'] - self.timestamps.get('stt_complete', 0):.3f}s")

    async def log_tts_output(self, frame):
        self.timestamps['tts_first_byte'] = time.time()
        print(f"TTS TTFB: {self.timestamps['tts_first_byte'] - self.timestamps.get('llm_complete', 0):.3f}s")

Pipecat VAD tuning for 2-5s delay issue:

from pipecat.vad.silero import SileroVADAnalyzer

vad = SileroVADAnalyzer(
    min_silence_duration_ms=400,  # Reduce from default 700ms
    speech_pad_ms=100,
    threshold=0.5  # Adjust sensitivity
)

Framework-Agnostic Diagnostic Patterns

Universal debugging approaches for any voice agent framework:

1. Component boundary logging:

// Log at every boundary
const logBoundary = (component, direction, data) => {
  console.log({
    timestamp: Date.now(),
    component,
    direction, // 'in' or 'out'
    dataSize: JSON.stringify(data).length,
    requestId: currentRequestId
  });
};

// Audio → STT
logBoundary('stt', 'in', { audioChunkSize, format });
// STT → LLM
logBoundary('stt', 'out', { transcript, confidence });
logBoundary('llm', 'in', { promptTokens });
// LLM → TTS
logBoundary('llm', 'out', { responseTokens, content });
logBoundary('tts', 'in', { textLength });
// TTS → Audio
logBoundary('tts', 'out', { audioBytes, duration });

2. Request ID correlation:

// Generate at call start, propagate everywhere
const requestId = `call_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

// Include in all API calls
sttClient.transcribe(audio, { metadata: { requestId } });
llmClient.complete(prompt, { metadata: { requestId } });
ttsClient.synthesize(text, { metadata: { requestId } });

3. Session replay capability: Store full session data for post-mortem analysis:

• Audio recordings (both directions)
• Full transcripts with timestamps
• LLM prompts and responses
• All component latencies

Structured Logging and Observability

Essential Voice Agent Metrics

Network layer:

Media layer:

Pipeline layer:

Minimal Viable Logging Schema

Session-level:

{
  "session_id": "sess_abc123",
  "start_time": "2026-01-25T10:30:00Z",
  "end_time": "2026-01-25T10:35:00Z",
  "duration_seconds": 300,
  "participant_count": 2,
  "completion_status": "completed",
  "ice_connection_type": "relay",
  "average_rtt_ms": 45,
  "total_packet_loss_percent": 0.3
}

Turn-level:

{
  "session_id": "sess_abc123",
  "turn_index": 5,
  "user_speech_start": "2026-01-25T10:31:15.000Z",
  "user_speech_end": "2026-01-25T10:31:18.500Z",
  "user_transcript": "I need to reschedule my appointment",
  "asr_confidence": 0.94,
  "stt_latency_ms": 180,
  "llm_first_token_ms": 220,
  "llm_complete_ms": 450,
  "tts_first_byte_ms": 85,
  "turn_around_time_ms": 735,
  "agent_response": "I can help you reschedule...",
  "barge_in_occurred": false,
  "tool_calls": [
    {"name": "get_appointments", "success": true, "latency_ms": 45}
  ]
}

Connection-level (sample every 5-10 seconds):

{
  "session_id": "sess_abc123",
  "timestamp": "2026-01-25T10:31:20.000Z",
  "ice_connection_state": "connected",
  "selected_candidate_type": "relay",
  "rtt_ms": 42,
  "jitter_ms": 8,
  "packets_received": 15420,
  "packets_lost": 12,
  "packet_loss_percent": 0.08,
  "audio_level_db": -25.5
}

Trace Correlation Across Components

Implement distributed tracing with OpenTelemetry:

const { trace, context, propagation } = require('@opentelemetry/api');

// Start trace at call initiation
const tracer = trace.getTracer('voice-agent');
const span = tracer.startSpan('voice_agent_call');
const ctx = trace.setSpan(context.active(), span);

// Propagate context to all services
const headers = {};
propagation.inject(ctx, headers);

// STT call
await sttClient.transcribe(audio, { headers });

// LLM call
await llmClient.complete(prompt, { headers });

// TTS call
await ttsClient.synthesize(text, { headers });

span.end();

This enables: "Which component caused the 2s latency spike in session X?"

Symptom-to-Cause Diagnostic Tables

Network Issues Quick Reference

Audio Quality Issues Quick Reference

Voice Pipeline Issues Quick Reference

Tooling Ecosystem Overview

Open Source Debugging Tools

Network Analysis Commands

Test STUN connectivity:

# Using turnutils
turnutils_stunclient stun.l.google.com

Test TURN connectivity:

# Using turnutils
turnutils_uclient -u username -w password turn.server.com

Capture WebRTC traffic with Wireshark:

# Filter for STUN protocol
wireshark -f "udp port 3478 or udp port 5349"

# Filter for RTP
wireshark -f "udp portrange 10000-60000"

Commercial Testing Platforms

Testing and Validation Strategies

Automated Testing Checklist

Before deploying voice agent changes:

• Unit tests: STT/LLM/TTS component mocks
• Integration tests: Full pipeline with real services
• Regression tests: Golden call set (50+ recordings)
• Load tests: Concurrent call capacity
• Network simulation: Packet loss, jitter injection

Synthetic Test Call Patterns

// Test scenarios to cover
const testScenarios = [
  {
    name: 'clean_audio',
    backgroundNoise: null,
    packetLoss: 0,
    jitter: 0
  },
  {
    name: 'noisy_environment',
    backgroundNoise: 'coffee_shop_-20db',
    packetLoss: 0,
    jitter: 0
  },
  {
    name: 'poor_network',
    backgroundNoise: null,
    packetLoss: 3,  // 3%
    jitter: 30      // 30ms
  },
  {
    name: 'barge_in_test',
    interruptAt: 1500,  // ms into agent response
    expectedStopLatency: 200  // ms
  }
];

Regression Detection Alerts

Set alerts for statistical deviations:

Conclusion: Debugging Workflow

Prioritized Debugging Steps

When a voice agent has issues, follow this order:

1. Network layer first

   • Open chrome://webrtc-internals
   • Verify ICE reaches "connected" state
   • Check selected candidate pair type
   • If ICE fails, stop here—fix network first

2. Media layer second

   • Check RTP packet loss (<1% target)
   • Check jitter (<20ms target)
   • Check RTT (<150ms one-way target)
   • If degraded, fix network or adjust jitter buffer

3. Pipeline layer third

   • Measure STT latency (TTFB + final)
   • Measure LLM latency (TTFT + complete)
   • Measure TTS latency (TTFB)
   • Identify which component is slowest

4. Conversation layer fourth

   • Check barge-in detection and response
   • Check endpointing configuration
   • Check turn-taking behavior

Building Observability from Day One

Design for debuggability:

• Implement structured logging at component boundaries
• Generate and propagate request IDs through entire pipeline
• Store session recordings with full transcripts
• Collect RTP statistics via getStats() API
• Track latency percentiles (P50/P95/P99), not just averages
• Implement health checks at each pipeline stage
• Set up alerts for threshold violations

Next Steps

• For LiveKit users: Monitor Pipecat Agents in Production
• For production incidents: Voice Agent Incident Response Runbook
• For comprehensive testing: How to Evaluate and Test Voice Agents
• For metrics deep-dive: Voice Agent Evaluation Metrics Guide

How Hamming Helps with WebRTC Voice Agent Debugging

Hamming provides specialized tooling for debugging and testing WebRTC voice agents:

• LiveKit-to-LiveKit Testing: Auto-provisioned rooms, synthetic test calls, real WebRTC connections
• 50+ Quality Metrics: Latency breakdown, barge-in accuracy, task completion, audio quality
• Session Replay: Full audio playback with transcripts and component traces
• Regression Detection: Automated alerts when metrics deviate from baseline
• Scenario Generation: Auto-generate test cases from prompts, execute in <10 minutes

Instead of manually debugging with chrome://webrtc-internals, get automated visibility into every layer of your voice agent stack.

Debug your voice agents with Hamming →