AAA
87883748b6
Checkpoint the accepted Browser v9 product contract before implementation. Current source and production remain v8.
6.0 KiB
ADR-0004: Peer-Assisted Media Experiment
- Status: Historical experiment
- Date: 2026-08-19
- Last updated: 2026-08-22
Context
ADR-0001 accepted browser WebRTC P2P for the MVP. Multi-viewer measurements then showed that sending one Host connection per Viewer does not fit the product's small, bounded upload target. The repository therefore explored whether an ordinary browser Viewer could relay the received screen stream to another Viewer.
This ADR records that experiment and its reusable evidence. It does not set the current endpoint capacity, SFU topology, server-assisted transport, fallback sequence, or resource accounting. ADR-0005 owns current routing invariants.
Experiment
The signaling server assigned a deterministic, bounded directed acyclic graph. Each Viewer had at most one active upstream. Join, capacity release, endpoint departure, and current-edge failure were the only reassignment triggers; healthy unaffected branches remained sticky. The experiment intentionally excluded continuous route scoring, periodic rebalance, multiple simultaneous upstreams, and user-selected topology.
Each browser relay rendered the received MediaStream and added its remote
tracks to a separate downstream RTCPeerConnection. This is standard WebRTC,
not packet forwarding or encoded-frame reuse. The browser decodes and normally
re-encodes at each relay hop, and each downstream connection owns separate
packetization, pacing, congestion control, encryption, and upload traffic.
The experiment shared one strictly validated room quality object across current and future senders. Values were bounded to the existing resolution, frame-rate, bitrate, degradation-preference, codec, and screen-audio choices. Sender mutation was serialized and read back from the browser. Requested settings were treated as ceilings and preferences, never as proof of achieved media quality.
Ordinary peer connections remained STUN-only. In the dated experiment, a TURN candidate would have altered the transport of an authorized edge, not the graph semantics or downstream edge count.
Evidence retained
The experiment established these durable facts:
- standard browser track relay incurs a separate downstream sender and cannot be described as zero-copy or shared encode;
- an upstream receive edge is distinct from downstream upload work;
- endpoint capacity must be enforced by the server and revalidated during reconnect, replacement, and stale-signal handling;
- one active Viewer upstream plus an acyclic committed graph is a tractable safety invariant;
- route replacement must be bound to exact sessions, revision, share generation, assignment generation, and connection identity;
- ICE
connectedis not application readiness; the exact candidate child's first newly decoded frame is required before switching; and - loopback tests can prove graph and signaling invariants but cannot establish real-device encoding cost, target-network latency, or production capacity.
Historical capacity-two and capacity-three runs remain measurement evidence. They do not authorize a current release tier or a browser-specific policy.
Experiment gates
A browser relay path is viable only if representative real-device tests record:
- end-to-end and per-hop latency;
- capture, encode, decode, and render frame rates;
- CPU, GPU, encoder count, and
qualityLimitationReason; - endpoint upload, packet loss, retransmission, and recovery;
- topology depth and the failure radius of a relay departure;
- audio continuity and synchronization when screen audio exists; and
- deterministic bounded recovery without stale edges or unauthorized signals.
The path fails closed if it requires a custom RTP injection layer, a new congestion controller, hidden software encoding, unbounded fanout, or a quality claim unsupported by measurements.
Current interpretation
Peer relay is part of the deployed Browser route owned by ADR-0005. This ADR retains only the experiment evidence used to evaluate that route; its historical policy and gates do not independently authorize current behavior.
The current accepted endpoint rule is one server-authoritative downstream
capacity for every non-server endpoint, default 2 and statically configurable
as 1, 2, or 3; upstream receive is free and role or user agent does not
create an exception. ADR-0005 owns the implemented and deployed Browser route
for direct/SFU publication, subscription, transport, server admission, and
migration overlap. Real heterogeneous-network and resource validation remains
open.
Consequences
Positive:
- the browser path can extend a distributed graph using standard WebRTC;
- exact route generations and media-proven switching are reusable controller invariants; and
- the experiment supplies concrete resource and failure measurements.
Negative:
- every browser relay hop may add decode, encode, latency, and upload cost;
- browser APIs do not guarantee cross-
RTCPeerConnectionshared encoding; and - experimental capacity results cannot substitute for current policy or a real browser and network matrix.
Relationship to other ADRs
- ADR-0001 remains the direct browser P2P baseline.
- ADR-0005 owns current automatic routing and capacity invariants.
- ADR-0007 owns path-quality evidence and representation behavior.
- A future native shared-encode sender or relay requires its own decision and evidence; this experiment does not pre-approve it.
References
Sources were checked on 2026-08-19: