Troubleshooting Streaming, WebRTC & HLS
This guide covers diagnostic procedures for live playback issues, including WebRTC WHEP negotiation failures, HLS playlist buffering, and browser decoding errors.
1. WebRTC / WHEP: ICE Connection Failed
When a WebRTC player shows a connection failure or infinite loading spinner:
Root Causes & Remediation:
| Cause | Diagnostic Indicator | Solution |
|---|---|---|
Missing public_ip | Client receives private IP candidate (10.x.x.x or 172.x.x.x) | Set webrtc.public_ip: "YOUR_SERVER_PUBLIC_IP" in config.yaml. |
| Firewall UDP Block | Browser console shows ICE connection failed after 5–10 seconds | Open UDP port range 50000-50100 on your host and cloud security groups. |
| Insecure HTTP Origin | Browser rejects WebRTC API (getUserMedia / RTCPeerConnection error) | Browsers enforce HTTPS for WebRTC. Serve the site via TLS or reverse proxy. |
| Symmetric NAT | Connection fails only on certain cellular / corporate Wi-Fi networks | Configure a TURN server under webrtc.turn_servers in config.yaml. |
2. HLS: Infinite Spinner or Black Screen
Cause A: H.265 (HEVC) in Unsupported Browsers
- Symptom: Audio plays, but video is black or shows an unsupported codec error.
- Explanation: Google Chrome and Firefox require hardware decoding support and WebCodecs/MSE for H.265. Safari on macOS/iOS natively supports H.265 in HLS.
- Solution: For universal web browser compatibility, set the camera sub-stream to H.264.
Cause B: Missing SPS / PPS Parameters
- If a client joins mid-stream and the camera hasn't sent an In-band SPS/PPS parameter set yet:
- RUSEON's Ring Buffer caches the active
CodecParamsvia atomic pointers and prepends them to the KeyFrame backfill upon client subscription. - Ensure the camera is streaming keyframes regularly (GOP 1-2 seconds).
3. Audio & Video Desynchronization
If audio drifts ahead or behind video during live playback:
- Timestamp Jitter: Some IP cameras emit irregular audio PTS timestamps under CPU load.
- Inspect Codec Alignment: Verify that audio is encoded in AAC (48kHz or 44.1kHz). Avoid non-standard G.726 codecs.