16 Reference

Transport and Streaming

Customer guide · v20.1.8 · October 12, 2026

In this chapter

WebRTC (default)
WebSocket fallback
Capture profile and backpressure
Streaming diagnostics
Remote interaction

BrowserBox uses an ACK-paced, bounded streaming pipeline to deliver remote browser frames to connected clients. Two transport modes are available:

16.1 WebRTC (default) #

By default, BrowserBox negotiates a peer-to-peer data channel between server and client. WebRTC is the initial path. One of every 60 published frames is eligible for a same-frame WebRTC/WebSocket comparison; the client reports the faster path, and native BrowserBox requires two consistent observations before switching so a single jittery sample cannot flap the selection.

16.2 WebSocket fallback #

If WebRTC negotiation fails (firewalled UDP, restricted NAT, or BBX_DISABLE_WEBRTC=true), BrowserBox falls back to WebSocket binary transport. This works through HTTP proxies and load balancers that support WebSocket upgrades and still delivers real-time frames. BrowserBox does not retry WebRTC indefinitely after a bounded failure.

For deployments behind an HTTP proxy or strict corporate firewall where WebRTC is unreliable, forcing WebSocket-only mode improves connection stability:

export BBX_DISABLE_WEBRTC=true
bbx start

To retain WebRTC and WebSocket fallback but disable the sparse comparison and learned switching:

export BBX_DISABLE_WEBRTC_RACING=true
bbx start

16.3 Capture profile and backpressure #

Native v20 intentionally uses the release-readiness profile measured during cutover: JPEG quality 80 and every captured frame. Backpressure remains adaptive even though JPEG quality is fixed:

Each viewer has bounded frame and transport ownership; capacity refusal follows a typed fallback path rather than terminating the service.
When frames back up, newer state can coalesce over stale unsent state so recovery favors the current page rather than replaying an old queue.
Round-trip acknowledgements, credits, mailbox/coalescing counts, selected transport, dimensions, and frame byte length feed the existing streaming diagnostics overlay.
BBX_ADAPTIVE_IMAGERY remains accepted for upgrade compatibility but does not change the native v20 capture profile.

16.4 Streaming diagnostics #

BrowserBox can show a live streaming stats overlay in the client UI with FPS, transport mode, round-trip time, and frame-flow status.

To display it:

export BBX_SHOW_STREAMING_STATS_OVERLAY=true
bbx start

The overlay shows live metrics including:

Metric	Meaning
FPS	Frames per second currently being delivered to the client. This reflects actual browser redraw activity—if the remote page is static, the FPS will naturally be low even on a healthy connection.
Transport	Active transport mode: `WebRTC` or `WebSocket`.
RTT	Round-trip time between server and client, used by the pipeline for pacing decisions.
Backpressure	Whether the pipeline is currently throttling or dropping frames to keep up with network conditions.

Important: a low FPS reading does not necessarily indicate a problem. If the remote page content is not changing, BrowserBox does not generate frames—FPS measures browser redraw activity, not a minimum guaranteed stream rate. A high-resolution page with no animations will show near-zero FPS on a healthy connection.

16.5 Remote interaction #

Double and triple clicks. BrowserBox counts rapid presses the way the local platform does and sends the count to the remote page, so double-click handlers, double-click word selection, and triple-click line selection work. Mouse presses count as a sequence within 500 ms and 4 pixels; touch and pen taps within 400 ms and 24 CSS pixels.
Dropdowns. A single-choice <select> on the remote page opens the user’s own operating-system dropdown, positioned over the remote control, so it looks and behaves natively on desktop and mobile. Multi-select lists and list boxes (size greater than 1) are operated directly on the remote page.