docs: document Lingbot-World WebRTC media-path network requirements

[mvanhorn]

Summary

Lingbot-World users on cloud GPU instances can now tell before launch whether their setup supports the WebRTC video path. This adds a "Network requirements (WebRTC)" section to docs/source/models/lingbot_world.rst explaining that reaching the HTTP /request_session page is necessary but not sufficient, that WebRTC needs a working media path (typically UDP) for ICE/DTLS/SRTP, and which remote options work (direct network access, UDP forwarding/VPN, or a TURN/STUN relay).

Why this matters

Issue #270 (#270) describes the "viewer loads but video never appears" symptom: with SSH/TCP-only port forwarding the HTTP viewer page loads while the WebRTC peer connection silently fails. The new section ends with a short troubleshooting note pointing at the media path so users know what to check. Claims stay tied to standard WebRTC behavior; no specific port numbers or a bundled TURN server are asserted since none appear in the repo.

Testing

Docs-only change covered by the doc.yml Sphinx build: the new section renders with no RST syntax or duplicate-label warnings, and the page already in the models toctree continues to build. The file already carries its SPDX header, so reuse-lint stays green. Full build runs in CI.

Fixes #270

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[jarcherNV]

Review with Codex GPT 5.5 for PR #287 -> Issue #270
Mostly addresses it, but needs one wording fix before closing #270.

Thanks for putting this together. The new WebRTC network section is the right shape for #270: it makes clear that /request_session only proves the HTTP/signaling path, calls out the SSH -L / TCP-only forwarding limitation, and gives users a concrete “viewer loads but video never appears” thing to check.

Before we merge, could you tighten the STUN/TURN wording so it matches what the current LingBot viewer actually supports? The client creates RTCPeerConnection() with default config, and the server path does not expose a user-facing ICE server / TURN configuration. STUN also is not a relay when direct media connectivity is blocked. I’d either frame TURN/STUN as requiring additional implementation/configuration not currently exposed, or limit the supported setup guidance to direct network access, UDP-capable forwarding, or VPN for this PR.

[greptile-apps]

Greptile Summary

This docs-only PR adds a "Network requirements (WebRTC)" section to docs/source/models/lingbot_world.rst explaining that the HTTP /request_session path and the WebRTC media path (ICE/DTLS/SRTP over UDP) are independent, and that SSH TCP port-forwarding only covers the former. The existing SSH-forwarding note is updated to point readers at the new section, and a short troubleshooting cue is appended.

• New section (lines 56–88): Describes the two-phase connection (HTTP signaling + WebRTC media), names three viable remote-access patterns (direct network access, UDP-capable VPN/forward, configured TURN relay), and ends with a first-step troubleshooting hint for the "page loads, no video" symptom.
• Updated note (lines 224–242): Adds a forward reference to the new requirements and appends a one-line caveat that the shown SSH commands cover HTTP only.

Confidence Score: 5/5

Documentation-only change with no code or configuration modifications; safe to merge.

The change is limited to a single RST file, adds technically accurate prose about WebRTC's two-phase connection model, and makes no code or config changes. RST section levels are consistent, there are no duplicate labels, and the new section's claims match standard WebRTC behavior.

No files require special attention.

Important Files Changed

Filename	Overview
docs/source/models/lingbot_world.rst	Adds a "Network requirements (WebRTC)" section explaining HTTP vs. media-path separation, and updates the existing SSH-forwarding note to cross-reference it; RST structure and section levels are consistent with the rest of the file.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant Server as LingBot-World Server (HTTP :8089)
    participant ICE as ICE / WebRTC Media Path (UDP)

    Browser->>Server: GET /request_session (HTTP)
    Server-->>Browser: Viewer page (HTML/JS)
    Browser->>Server: POST /api/webrtc/offer (HTTP signaling)
    Server-->>Browser: SDP answer
    Browser->>ICE: ICE candidate exchange (STUN)
    Note over Browser,ICE: Requires UDP reachability — TCP-only SSH forwarding does not carry this path
    ICE-->>Browser: ICE connected
    Browser->>ICE: DTLS handshake → SRTP/SCTP session
    ICE-->>Browser: Live video stream (SRTP)

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into fix/270-lingbot..." | Re-trigger Greptile}

[greptile-apps]

STUN and TURN serve different purposes: STUN only assists with NAT traversal by discovering a client's public IP/port, but it does not relay any media traffic. When "direct peer-to-peer connectivity is blocked" (e.g., by a strict firewall or symmetric NAT), a STUN server alone will not establish the media path — only a TURN relay will. Bundling them under "STUN/TURN" in this condition is misleading, since STUN provides no benefit in that exact scenario.

Suggested change

	- A configured STUN/TURN deployment when direct peer-to-peer connectivity
	is blocked. LingBot-World does not configure a bundled TURN relay by
	default, so provide and configure relay infrastructure if your
	environment requires it.
	- A configured TURN relay deployment when direct peer-to-peer connectivity
	is blocked. LingBot-World does not configure a bundled TURN relay by
	default, so provide and configure relay infrastructure if your
	environment requires it. A STUN-only server assists with NAT traversal
	but does not relay media — a TURN server is required when p2p is fully
	blocked.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[jmccaffrey-nv]

/ok to test 54c89ad

[liruilong940607]

Thanks for adding this instruction!

This feels more like a "potential issue and solution" instead of a general instruction that every user need to read. And if we keep adding things like this the doc page will grow very fast in length.

I would suggest we move this into a "potential issue and solution" section and fold it by default.

[liruilong940607]

I just saw this other PR about trouble shooting -- I think this belongs perfectly to the troubleshoting page. And this is a shared troubleshoting between both lingbot and omnidreams [and in the future more models] for webrtc demo