16 Reference

Transport and Streaming

Customer guide · v19.3.1 · September 29, 2026

In this chapter

WebRTC (default)
WebSocket fallback
Adaptive quality and backpressure
Streaming diagnostics
Remote interaction

BrowserBox uses an adaptive, ACK-paced 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. This delivers the lowest latency and highest frame throughput. The streaming pipeline observes round-trip time and automatically adjusts frame pacing.

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 any HTTP proxy or load balancer and still delivers real-time frames, though with slightly higher latency than WebRTC.

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

16.3 Adaptive quality and backpressure #

The BrowserBox streaming pipeline adapts JPEG quality and frame pacing automatically based on network conditions. Key behaviors:

JPEG quality is adjusted between a minimum and maximum bound in response to downstream capacity.
When the client is consuming frames faster than they are produced, quality is increased.
When frames are backing up (the client is slower than the server), quality is reduced and some frames are dropped to maintain real-time responsiveness.
The pipeline uses round-trip acknowledgements to detect network pressure and adjust pacing.

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.