Webrtc Connection Diagnostics

WebRTC Connection Diagnostics

Overview

ovstream's WebRTC/native backend uses NVIDIA StreamSDK signaling and ICE (not browser-interoperable WebRTC). Most connection failures are network-topology or configuration problems, not SDK bugs. This skill turns captured logs into a diagnosis by matching them against the scenario catalog.

The authoritative reference is docs/WEBRTC_CONNECTIVITY.md — it carries the full scenario matrix, the StreamSDK hex-error table, the key-log-message table, and the multi-machine procedures. The machine-readable catalog is tests/webrtc_net/scenarios.toml (each entry's id, expect_logs, diagnosis, fix). Read both when diagnosing; this skill is the workflow that ties them together.

Step 1 — capture logs at the right level

Connection lifecycle lines (Client connected to WebRTC server) are logged at INFO. The default severity (WARNING) hides them, so raise it on the server side:

ovstream.initialize(
    log_fn=lambda level, channel, message, ts: print(f"[{level.name}][{channel}] {message}"),
    log_min_severity=ovstream.LogLevel.INFO,   # or VERBOSE to chase signaling/ICE
)

Source: examples/python/basic_stream/main.py snippet initialize-sdk

The callback receives ovstream's own logs plus StreamSDK/GStreamer dependency output, so signaling and ICE detail flow through it. Drop to LogLevel.VERBOSE when a connect never completes.

Key fact for diagnosis: client-side signaling timeouts surface in the client's StreamSDK log, not the server's. A server that logs nothing while a client reports a timeout means the client never reached the server — look at reachability (signal port, firewall), not the server.

Step 2 — match the log signature

Find the line(s) you have in the table below (a condensed view of the doc's "Key log messages" + "hex error code" tables) and jump to the named scenario in docs/WEBRTC_CONNECTIVITY.md for the full diagnosis and fix.

For any hex code not above, see the full StreamSDK hex-error table in docs/WEBRTC_CONNECTIVITY.md.

Step 3 — reproduce to confirm (SDK source tree)

If you have the SDK source tree (not just the installed wheel), use the connection probe and harness under tests/webrtc_net/ to reproduce the suspected scenario in isolation:

• Start a server: python tests/webrtc_net/server_harness.py --signal-port 19100 --stream-port 17999 --log-file /tmp/srv.log
• Probe it: ovstream_webrtc_probe --host <ip> --signal-port 19100 --expect connect (add --wait-frame to confirm media decodes; --expect fail to assert a failure path).
• The full topology matrix is driven by pytest tests/webrtc_net/test_connectivity.py -v; scenarios whose capabilities (gpu / coturn / netns / docker) aren't present on the host report skipped, not failed.

The probe runs as a plain process, so to test reachability across a real network, run it from the client machine/namespace/container against the server's address. See tests/webrtc_net/README.md.

Step 4 — topologies you can't simulate locally

For true public-internet / CGNAT, real cloud/Kubernetes ingress, cross-physical-machine, or IPv6/IPv4-stack-mismatch cases, follow the multi-machine manual procedures at the end of docs/WEBRTC_CONNECTIVITY.md.

Common Pitfalls

• Diagnosing from the wrong log. A client-side signaling timeout will not appear in the server log. Capture both ends.
• WARNING-level logging hides the connect line. Raise the server to INFO before concluding "nothing connected".
• "Connected but black" is not a signaling problem. A successful Client connected to WebRTC server rules out signaling/ICE; look at NVENC, the CUDA device, or (for browsers) autoplay/codec.
• Bridge networking drops media silently. Signaling over TCP succeeds while UDP media is unpublished — the connection looks up but never renders.
• Symmetric NAT does not always need TURN. When one peer is public, the hole-punch to it still works through a symmetric NAT. TURN is required only when both peers are NAT/firewall-constrained.
• TURN relay is a browser/WebRTC-client capability. StreamSDK's native ICE stack gathers no relay candidates, so the native ovstream_webrtc_probe cannot use TURN — but a browser client does standard TURN against any server (external ones included). Diagnose relay problems with the browser client.