| name | webrtc-connection-diagnostics |
| description | Diagnose ovstream WebRTC/native connection failures from logs. Use when a client can't connect, the stream is black, a connection times out, or you need to reason about STUN/TURN/ICE/NAT/firewall/container/cloud topology, signaling timeouts, or "what does this StreamSDK error code mean". |
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,
)
Source: snippet
