Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs: record relay profile synchronization
AAAc6bea3eb42c1
diff --git a/docs/adr/0004-peer-assisted-media-experiment.md b/docs/adr/0004-peer-assisted-media-experiment.mdindex 39c5d62f..9b8a1c93 100644--- a/docs/adr/0004-peer-assisted-media-experiment.md+++ b/docs/adr/0004-peer-assisted-media-experiment.md@@ -63,6 +63,18 @@ downstream `RTCPeerConnection`. The browser therefore decodes and re-encodes atevery relay hop. Existing audio follows the same stream when capture providesit; the experiment does not invent a separate audio protocol.+The peer-assisted wire accepts exactly `1080p60`, `1080p30`, and `720p30` as+room quality profile IDs. The signaling server holds the current ID in bounded,+per-room memory only; it is not persisted. An authenticated peer-assisted+snapshot includes the current value, the host reasserts its local choice before+reconciling assigned children, and live changes are sent to all online viewers.+The viewer relay keeps one desired profile for its current and future child.+Sender setup, stream replacement, and profile changes are serialized inside+each `HostPeer`, with the latest desired value winning. The ordinary P2P+authenticated wire remains unchanged and profile-control messages are forbidden+in that mode. This coordinates sender targets; it does not prove achieved+resolution, bitrate, frame rate, or resource cost.+Encoded Transform, DataChannel media, WebCodecs rendering, dummy-sender bytereplacement, custom congestion control, codec ladders, multiple trees, mobilebackground relay, and automatic SFU migration are excluded. They are not rescue@@ -75,19 +87,22 @@ connections because browsers do not guarantee cross-connection encoder reuse.Each viewer relay also performs one downstream encode. This is tolerated onlyfor the experiment and must be measured honestly.-A production peer-assisted design must eventually use a packaged/native sender-whose custom libwebrtc encoder proxies share one encoded output while retaining-independent standard WebRTC packetizers for the host's edges. That native work-requires a separate ADR and measurements. It is not implemented or abstracted-in advance by this spike. Standard browser viewing remains required.+A separate planned packaged/native sender must use custom libwebrtc encoder+proxies that share one encoded output while retaining independent standard+WebRTC packetizers for the host's edges. That work requires its own ADR and+measurements regardless of this browser relay experiment's result. It reduces+host encoding work but does not remove the upload copy for each outgoing edge.+It is not implemented or abstracted in advance by this spike. Standard browser+viewing remains required.## Acceptance Gate-Test 1, 3, 5, and 8 viewers for 30 minutes at 720p60 with controlled per-edge-RTT at or below 40 ms and loss at or below 1%. Current desktop Chrome and Edge-form the relay cohort; current Android Chrome and iOS Safari join last as leaf-checks. The protocol has no relay-capability bit, so controlled join order is-the only enforcement and this spike is not safe for arbitrary-user deployment.+Test 1, 3, 5, and 8 viewers for 30 minutes across the 1080p60, 1080p30, and+720p30 profiles with controlled per-edge RTT at or below 40 ms and loss at or+below 1%. Current desktop Chrome and Edge form the relay cohort; current Android+Chrome and iOS Safari join last as leaf checks. The protocol has no+relay-capability bit, so controlled join order is the only enforcement and this+spike is not safe for arbitrary-user deployment.The proposal advances only if every condition holds:@@ -100,6 +115,8 @@ The proposal advances only if every condition holds:zero-copy forwarding;- excluding explicit TURN paths, the application server carries no media;- host and relay upload remain within 20% of `childCount * observedBitrate`;+- authentication and live profile changes leave every current and future child+ sender targeting the same latest room profile without altering the P2P wire;- first picture is at most 3 seconds, a 60 fps run does not remain below 50decoded fps for more than 5 seconds, and depth-four p95 glass-to-glasslatency is at most 350 ms;@@ -120,16 +137,17 @@ Fixing an ordinary implementation bug inside the bounded spike is allowed. Ifmeeting a gate requires Encoded Transform/DataChannel/WebCodecs media, customcongestion control, FEC/RTX changes, multiple trees, relay scoring, transcoding,a codec ladder, relaxed host fanout, or a browser-specific RTP injection hack,-stop. Change this ADR to Rejected and delete the experimental runtime path and-dependencies. Only when every non-encoding gate passes and relay re-encoding is-the sole failure may a separate ADR propose a native shared-encode host with-opt-in native volunteer encoded-RTP relays. Any other failure closes peer-assistance and keeps standard P2P plus explicit user-operated or central SFU-fallbacks.+stop. Change this ADR to Rejected and delete the experimental browser-relay+runtime path and dependencies. That result keeps standard P2P plus explicit+user-operated or central SFU fallbacks. It does not cancel the separate planned+native shared-encode sender, and that sender cannot be used to mark an otherwise+failed browser-relay topology as passing.Passing the gate does not change this ADR to Accepted. It permits a separate ADRto propose a production design, including broader game-audio/A-V verification,-voluntary relay policy, privacy disclosure, and the native shared-encode sender.+voluntary relay policy, and privacy disclosure. The native shared-encode sender+is the independent planned work described above, not a reward for passing this+gate.## Consequences If The Spike Proceedsdiff --git a/docs/project-memory.md b/docs/project-memory.mdindex abc2890e..d1fba36f 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -5,7 +5,7 @@ Last updated: 2026-08-19## Confirmed Intent- Build Discord/KOOK/Oopz/TeamSpeak-like low-latency game screen sharing for one broadcaster and a small trusted friend group. Public or large broadcasts belong on OBS/Twitch-class services.-- Viewers should join from a normal desktop or mobile browser. A packaged sender is acceptable later when measurements justify native capture, audio, or shared encoding.+- Viewers should join from a normal desktop or mobile browser. A packaged/native sender is a planned later stage for shared encoding and may also improve capture and audio without changing the Web viewer requirement.- Use a Photon-style central rendezvous service for access, rooms, signaling, deterministic topology, STUN, TURN fallback, and observability while clients carry media whenever practical.- Server bandwidth cost is a primary constraint. The media priority is direct P2P, then measured peer assistance, then an explicit user-operated or central SFU fallback. Never migrate topology silently.- The broadcaster has a hard target of at most two downstream media edges. Every assigned edge independently uses ICE and authenticated TURN/UDP or TURN/TCP when direct connectivity fails; P2P-first never means direct-only.@@ -19,7 +19,7 @@ Last updated: 2026-08-19- Use direct host P2P for one or two viewers. Draft ADR-0004 and Draft PR #13 own the default-off experiment for later viewers: two sticky deterministic chains, host capacity two, viewer capacity one, no proactive rebalance or composite score, and no more than eight viewers when `PEER_ASSISTED_MEDIA=true`.- Standard browser relays resend remote `MediaStreamTrack` values and therefore decode and re-encode at every hop. Browser WebRTC does not guarantee one shared encoder across peer connections; measure this cost rather than hiding it.- Reject the browser experiment if it needs Encoded Transform/DataChannel/WebCodecs media, custom congestion or RTP recovery, multiple trees, relay scoring, transcoding, codec ladders, browser RTP injection, or more than two host edges.-- Only if every non-encoding gate passes and re-encoding is the sole failure may a separate ADR propose a native shared-encode host plus opt-in native volunteer encoded-RTP relays. Any other failure closes peer assistance.+- Plan a separate native-sender ADR for TeamSpeak-style shared encoding regardless of the browser relay result. One compatible encoded output may feed at most two standard WebRTC packetizers to reduce host encode work, but each edge still consumes upload bandwidth. This work is not part of the current Draft and cannot rescue another failed browser-relay gate.- Keep user-operated mini-SFU deployment and central single-node SFU Draft PR #12 as explicit fallbacks. They transfer fanout egress to their operator and do not justify automatic switching, Redis, or multi-node infrastructure.- Prefer direct UDP, then TURN/UDP, with TURN/TCP as the required non-UDP fallback. Optional TURN/TLS uses TCP 5349 by default; TCP 443 needs a dedicated address or validated L4/SNI routing.- Treat 1080p60 at 8 Mbps as a best-effort ceiling. Keep the deployed 1080p60 at 8 Mbps, 1080p30 at 5 Mbps, and 720p30 at 3 Mbps profiles switchable during sharing. `balanced` does not guarantee resolution-first behavior; measure actual browser tradeoffs.@@ -34,12 +34,12 @@ Last updated: 2026-08-19- Access remains deliberately small: optional site-wide `ACCESS_PASSWORD`, a 12-hour stateless HMAC HttpOnly `SameSite=Strict` cookie, internal host token, role-bound signaling, Origin/payload checks, and no accounts, JWTs, session map, or logout flow.- With `ROOM_DATABASE_PATH` and the site password, built-in SQLite stores only auto-incremented room ID and host-token digest. Links persist and stopping sharing leaves viewers waiting. Production room ID `1` survived the `5b2fb005f6f7` deployment restart. Without the path, rooms remain random and temporary; public mode cannot use sequential rooms.- Production runs behind nginx with Node.js 24.19.0. Authenticated coturn 4.17.2 at `turn.bonfire.icu:3478` has verified public STUN, TURN/UDP, TURN/TCP, and relay-only traffic. TURN/TLS is intentionally disabled.-- Draft PR #13 contains deterministic server/client peer-assisted assignment and standard remote-track relay. It defaults off, is capped at eight viewers, re-encodes at every relay, and is neither merged nor deployed. Native shared encoding and custom encoded browser transport are not implemented.+- Draft PR #13 contains deterministic server/client peer-assisted assignment, standard remote-track relay, and synchronized 1080p60/1080p30/720p30 room profiles. It defaults off, is capped at eight viewers, re-encodes at every relay, and is neither merged nor deployed. Native shared encoding and custom encoded browser transport are not implemented.- Chromium 151 demonstrated the intended three-viewer shape: exactly two connected host outbound peers; viewer 1 with one inbound plus one outbound forwarding to viewer 3; viewer 2 direct from the host; and decoded frames at all three viewers.- A Chromium 151 one-to-eight synthetic functional smoke formed two depth-four chains: two connected host outbound peers, one inbound plus one outbound at viewers 1 through 6, inbound-only viewers 7 and 8, and decoded frames everywhere. This proves topology only, not profile quality, resource cost, latency, or endurance.- Closing the first-level relay reattached its branch and resumed decoding in about 5.3 seconds while host active connected outbound edges peaked at two. A silent partition instead waits for the 30-second heartbeat, so detection can take 30 to 60 seconds before the default 5-second viewer grace; that path is unverified.-- Relay outbound stats are observable, but relay senders still use a fixed `1080p60`/8 Mbps envelope rather than the host-selected profile. Profile propagation blocks valid comparative quality and resource measurements.-- The recorded peer-assisted full check passes type checking, 12 Vitest files with 135 tests, and both client and server production builds. Production release `5b2fb005f6f7` separately passed 108 Vitest tests, both builds, loopback and public HTTPS/access-gate checks, and a clean activation without disturbing nginx, coturn, or the blog.+- The peer-assisted authenticated snapshot and host-only update synchronize one bounded, non-persistent room profile. Online viewers receive changes; `ViewerRelay` uses the latest desired profile for current and future children, while `HostPeer` serializes sender setup, stream replacement, and last-wins profile updates. The ordinary P2P wire is unchanged. Real 1/3/5/8 quality, resource, and latency measurements remain pending.+- The recorded peer-assisted full check passes type checking, 12 Vitest files with 141 tests, and both client and server production builds. Production release `5b2fb005f6f7` separately passed 108 Vitest tests, both builds, loopback and public HTTPS/access-gate checks, and a clean activation without disturbing nginx, coturn, or the blog.- Draft SFU PR #12 and ADR-0003 remain unmerged, undeployed, and independently reversible. There is no infrastructure blocker for the deployed Web baseline or bounded peer-assisted experiment.## Provisional Quality Targetsdiff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.mdindex 64bb0141..e6bd9d42 100644--- a/docs/research/low-server-media-routes.md+++ b/docs/research/low-server-media-routes.md@@ -14,17 +14,19 @@ The smallest current plan is:2. For later viewers, test the fixed two-chain browser relay in ADR-0004. It isdisabled by default with `PEER_ASSISTED_MEDIA=false`, is limited to at mosteight viewers, and decodes and re-encodes at every relay.-3. Only if that spike passes every topology, churn, connectivity, compatibility,- and latency gate but fails solely because of relay re-encoding may a separate- experiment combine a native shared-encode host with opt-in native volunteer- encoded-RTP relays.-4. Keep a user-operated mini-SFU and a centrally operated single-node SFU as+3. Plan a separate native shared-encode sender regardless of the browser relay+ result. It reduces duplicate host encoding while retaining at most two+ standard WebRTC edges, so it does not remove their upload cost.+4. Only if browser relay re-encoding is the isolated failure should another+ experiment add opt-in native volunteer encoded-RTP relays.+5. Keep a user-operated mini-SFU and a centrally operated single-node SFU asexplicit fallbacks. They transfer fanout bandwidth to their operator; they donot make it disappear.-Any browser-spike failure other than the isolated re-encoding cost closes the-peer-assisted route. Draft SFU PR #12 remains unmerged and undeployed. There is-no automatic topology migration in this plan.+Any browser-spike failure other than isolated relay re-encoding closes that+browser-relay route. It does not cancel the separate native sender plan. Draft+SFU PR #12 remains unmerged and undeployed. There is no automatic topology+migration in this plan.## Traffic Conservation And The Impossible Triangle@@ -56,7 +58,8 @@ lost.| --- | --- | --- | --- || Direct host P2P | Host emits one copy per viewer | Host upload and sender pipelines grow with viewers | Keep for one or two viewers || Fixed two-chain browser relay | Host emits at most two copies; each relay emits at most one | Ordinary browser, but every relay decodes and re-encodes and adds a hop | Current default-off, maximum-eight-viewer spike |-| Native shared host plus native volunteer encoded-RTP relay | Host encodes once for up to two edges; each volunteer forwards one encoded copy | Native install, RTP/RTCP forwarding, packaging, and opt-in relay policy | Conditional next experiment only if re-encoding is the sole browser-spike failure |+| Native shared-encode host | Host encodes once for at most two standard WebRTC edges | Native sender packaging and custom libwebrtc encoder fanout | Planned separate sender phase; still pays per-edge upload |+| Native volunteer encoded-RTP relay | Each volunteer forwards one encoded copy | Native install, RTP/RTCP forwarding, packaging, and opt-in relay policy | Conditional experiment only if relay re-encoding is the sole browser-spike failure || User-operated mini-SFU | User's SFU emits viewer copies | Separate deployment and its egress bill; running it on the host does not reduce that host's uplink | Explicit fallback || Central single-node SFU | Service SFU emits viewer copies | Lowest endpoint relay burden; service pays approximately `N * B` egress | Explicit fallback; Draft PR #12 only || SVC plus multiple trees | Peers emit striped layer copies across several trees | Layer scheduling, reassembly, redundancy, and more churn state | Reject for the current product |@@ -65,7 +68,7 @@ lost.| Peer-assisted CDN | Peers cache or upload segments/objects | Discovery, locality, scheduling, incentives, abuse, and privacy systems | Reject for this trusted group || IP multicast | Multicast routers replicate packets | Requires multicast-enabled hosts and routed networks unavailable to ordinary Internet browsers | Reject outside managed networks |-## Conditional Native Encoded-RTP Route+## Planned Native Sender And Conditional Encoded-RTP RelayPion exposes the necessary native building blocks: `TrackRemote.ReadRTP()` readsencoded RTP, `TrackLocalStaticRTP.WriteRTP()` writes pre-packetized RTP into@@ -82,9 +85,11 @@ also needs a separate native shared encoder so its two WebRTC packetizers consumone encoded result. Pion's broadcast example demonstrates server-side RTPfanout, but it does not supply this end-user topology or product behavior.-This route is permitted only after measurements isolate re-encoding as the sole-failure. It must not rescue failures in deterministic assignment, host fanout,-relay loss recovery, ICE/TURN connectivity, mobile leaves, or end-to-end latency.+The native shared-encode sender is a planned independent phase. Native volunteer+relays remain conditional on measurements isolating relay re-encoding as the+sole browser-spike failure. They must not rescue failures in deterministic+assignment, host fanout, relay loss recovery, ICE/TURN connectivity, mobile+leaves, or end-to-end latency.## Rejected For The Current Implementationdiff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.mdindex 0f5061e7..b1da0d59 100644--- a/docs/research/peer-assisted-media.md+++ b/docs/research/peer-assisted-media.md@@ -113,9 +113,9 @@ application messages no larger than 16 KB when interleaving is unavailable.This is a custom media plane over a proven transport, not a custom UDP stack.It remains materially more complex than standard WebRTC media and is rejected-for the first spike. It cannot rescue a failed gate; only when re-encoding is-the sole failure may the separate native encoded-RTP route described in-`low-server-media-routes.md` be proposed.+for the first spike. It cannot rescue a failed browser-relay gate. The separate+native shared-encode sender described in `low-server-media-routes.md` is planned+independently and requires its own ADR and measurements.Sources:@@ -129,7 +129,7 @@ sending the result directly to viewers. This removes repeated encoding andmemory cost, but it does not remove one network copy per viewer. It thereforedoes not satisfy a hard host fanout of two by itself.-A future native Screener sender can preserve standard browser receivers without+A planned native Screener sender can preserve standard browser receivers withoutwriting a new transport. libwebrtc accepts an application-supplied`VideoEncoderFactory`; a factory can return per-send-stream proxy encodersbacked by one shared hardware encoder and fan the resulting `EncodedImage` into@@ -181,6 +181,33 @@ Per-edge ICE remains independent. An edge may be direct or may use authenticatedTURN, so peer assistance reduces normal server media traffic but cannot promisezero server traffic in restrictive networks.+## Implemented Quality Profile Coordination++The current Draft implementation coordinates one room profile across the+peer-assisted tree without adding adaptation logic. Its strict ID set is+`1080p60`, `1080p30`, and `720p30`, matching the existing capture and sender+profiles. The signaling server stores the current ID in a room-count-bounded+in-memory map, defaults to `1080p60`, includes it in peer-assisted authenticated+snapshots, and broadcasts host changes to online viewers. The value is retained+when sharing stops, removed when the room is abandoned or expires, and is not+written to SQLite. The standard P2P authenticated variant is unchanged and+profile-control messages are forbidden in that mode.++After peer-assisted authentication, the host reasserts its local selection+before reconciling assigned children. A viewer records the snapshot or update+before applying its assignment. `ViewerRelay` keeps a synchronously updated+desired profile and serializes profile changes with stream replacement, so both+an existing child and a later replacement start from the latest target. Inside+`HostPeer`, initial sender configuration, stream replacement, and profile+updates share one mutation queue; operations read the latest desired profile at+execution time, giving rapid changes last-wins behavior without versions or+acknowledgements.++This only removes the previous fixed-1080p60 relay envelope. Browser constraints+and RTP sender parameters remain targets, so achieved bitrate, frame rate,+resolution, encode work, and cross-hop quality still require the measurement+matrix below. It does not add or imply shared encoding.+Peer multicast research such as SplitStream demonstrates why load-balanced,failure-tolerant overlays normally introduce multiple trees and contentstriping. Those mechanisms are intentionally excluded: needing them is a reason@@ -239,12 +266,12 @@ existing screen-audio track when the browser provides one. SVC/simulcast,custom encoded transport, FEC changes, multi-tree striping, transcoding,background mobile relay, and automatic SFU migration are excluded.-Run 1, 3, 5, and 8 viewers for 30 minutes at 720p60 under controlled per-edge-RTT at or below 40 ms and loss at or below 1%. Record topology generation and-depth, selected candidate type, host and relay upload, packets lost, jitter,-frames encoded/decoded/dropped, total encode/decode time, decoded FPS,-`qualityLimitationReason`, first picture, reparent time, CPU, GPU, and-glass-to-glass latency.+Run 1, 3, 5, and 8 viewers for 30 minutes across the 1080p60, 1080p30, and+720p30 profiles under controlled per-edge RTT at or below 40 ms and loss at or+below 1%. Record topology generation and depth, selected candidate type, host+and relay upload, packets lost, jitter, frames encoded/decoded/dropped, total+encode/decode time, decoded FPS, `qualityLimitationReason`, first picture,+reparent time, CPU, GPU, and glass-to-glass latency.All hard gates must pass:@@ -276,15 +303,17 @@ requires an encoded DataChannel/WebCodecs media plane, custom congestioncontrol, FEC/RTX changes, multiple distribution trees, relay scoring,transcoding, a codec ladder, or relaxed host fanout, abandon this browserarchitecture. Mark ADR-0004 rejected, remove its experimental runtime code and-dependencies, and retain this research. Only if relay re-encoding is the sole-failed gate may a separate ADR propose the native shared-encode/encoded-RTP-route; every other failure keeps standard P2P plus explicit user-operated or-central SFU fallbacks.+dependencies, and retain this research. The separate planned native+shared-encode sender still requires its own ADR, lowers encode work rather than+per-edge upload, and cannot rescue other failed browser-relay gates. A rejected+relay experiment keeps standard P2P plus explicit user-operated or central SFU+fallbacks.Passing these gates proves only that a second design phase is justified. Itdoes not accept peer-assisted media for production. Production adoption would-need a new ADR, voluntary relay policy, broader audio/A-V verification, and the-native host shared-encode design.+need a new ADR, voluntary relay policy, and broader audio/A-V verification. The+native host shared-encode sender is a separate planned phase regardless of this+experiment's result and is not implemented here.The recovery gate above does not cover silent network partitions. With thedefault 30-second heartbeat, server detection can take 30 to 60 seconds beforediff --git a/docs/status.md b/docs/status.mdindex 2899d680..2605f7be 100644--- a/docs/status.md+++ b/docs/status.md@@ -13,9 +13,11 @@ IDs, reusable links, and a waiting state after sharing stops. Production room IDProduction still uses one host `RTCPeerConnection` per viewer. Draft PR #13 addsa default-off, standard-WebRTC peer-assisted experiment for later viewers: twosticky chains with host capacity two, viewer capacity one, and decode/re-encode-at every browser relay hop. `PEER_ASSISTED_MEDIA=false` remains the default, the-mode cannot be enabled above eight viewers, and it is neither merged, deployed,-nor production-validated. Draft SFU PR #12 is also unmerged and undeployed.+at every browser relay hop. The Draft now also propagates the host-selected+1080p60/1080p30/720p30 room profile to current and future relay senders.+`PEER_ASSISTED_MEDIA=false` remains the default, the mode cannot be enabled above+eight viewers, and it is neither merged, deployed, nor production-validated.+Draft SFU PR #12 is also unmerged and undeployed.## Current Snapshot@@ -26,12 +28,13 @@ nor production-validated. Draft SFU PR #12 is also unmerged and undeployed.- Without `ROOM_DATABASE_PATH`, rooms are random and temporary. With both the database path and site password, room IDs start at `1`, links persist, and stopping a share leaves viewers waiting. SQLite stores only room ID and host-token digest.- Direct ICE is preferred independently per media edge. Authenticated TURN/UDP and TURN/TCP are required production fallbacks; TURN/TLS is optional.- The media priority is direct P2P for one or two viewers, peer assistance only after every ADR-0004 gate passes, then user-operated or central single-node SFU as an explicit fallback. There is no automatic migration.+- Peer-assisted profile state is bounded, server-memory-only, and absent from the ordinary P2P wire. The host reasserts its choice after authentication; online viewers receive changes, and each relay applies the latest desired profile to its current or future child through serialized sender mutations.## Verified Evidence- Production release `5b2fb005f6f7` passed type checking, 108 Vitest tests, both production builds, loopback smoke, public HTTPS/access-gate checks, and clean activation under `/opt/screener/current`. The new 1080p30 asset loaded, Screener had zero automatic restarts, and nginx, coturn, and the existing blog remained healthy.- The protected production database and permissions survived restart, and room ID `1` remained present. Stop-and-republish and link reuse still require a browser cycle.-- The recorded peer-assisted full check passes type checking, 12 Vitest files with 135 tests, and both client and server production builds.+- The recorded peer-assisted full check passes type checking, 12 Vitest files with 141 tests, and both client and server production builds.- Chromium 151 one-to-three evidence held exactly two connected host outbound peers. Viewer 1 held one inbound plus one outbound peer and forwarded to viewer 3; viewer 2 stayed direct; all three decoded frames.- A Chromium 151 one-to-eight synthetic functional smoke formed two depth-four chains. The host held two outbound peers; viewers 1 through 6 each held one inbound plus one outbound; viewers 7 and 8 were leaves; all decoded frames. This proves topology only, not quality, resource cost, latency, or endurance.- Closing the first-level relay caused its branch to reattach and decode again after about 5.3 seconds while host active connected outbound edges peaked at two.@@ -40,7 +43,7 @@ nor production-validated. Draft SFU PR #12 is also unmerged and undeployed.## Unverified Boundaries-- Relay senders still use a fixed `1080p60`/8 Mbps envelope instead of the host-selected room profile. Profile propagation blocks valid peer-assisted quality and resource comparisons.+- Room profile propagation is implemented, replacing the fixed relay `1080p60` envelope. Actual cross-hop resolution, bitrate, frame rate, encode cost, and generational quality under each profile remain unverified.- Peer assistance has not completed 1/3/5/8-viewer 30-minute runs, relay CPU/GPU and generational-quality measurements, controlled loss/RTT tests, or depth-four latency gates.- Android Chrome and iOS Safari remain required leaves but are not verified for this topology. There is no runtime relay-capability bit; controlled join order is the only mobile-leaf enforcement, so arbitrary-user deployment is excluded.- The observed recovery starts from a page close immediately seen by the server. A silent partition can wait 30 to 60 seconds for heartbeat detection before the default 5-second grace; it remains unverified.@@ -52,7 +55,7 @@ nor production-validated. Draft SFU PR #12 is also unmerged and undeployed.Complete only the bounded ADR-0004 experiment, with distribution work ahead ofUI polish:-- propagate one room quality profile to host and relay senders before comparative media measurements;+- validate authentication, live switching, stream replacement, and child rebuild against the latest room profile in real browsers;- preserve host fanout at two and viewer fanout at one across joins, reconnects, grace expiry, and reparenting;- run reproducible 1/3/5/8-viewer measurements using the deployed profiles, recording topology depth, selected ICE path, host/relay upload, encode/decode work, first picture, decoded FPS, quality limitation, and glass-to-glass latency;- repeat first-level relay loss with a server-observed close and separately measure silent heartbeat-detected partition recovery; and@@ -64,13 +67,16 @@ picture, about 8 seconds total. Silent partitions include their detection delay.All gates fail closed. If success requires a custom browser media plane, changedRTP recovery, multiple trees, scoring, transcoding, a codec ladder, or more than-two host edges, remove the experiment. Only an isolated re-encoding failure may-advance to a separate native shared-encode and volunteer encoded-RTP proposal.+two host edges, remove the browser-relay experiment. A separate native+shared-encode sender remains planned regardless of that result; it lowers host+encode work, does not remove per-edge upload, and cannot rescue another failed+topology gate.## Blockers And DecisionsNo infrastructure blocker remains. Production adoption of peer assistance is-blocked on profile propagation and the measurement matrix above.+blocked on the measurement matrix and ADR-0004 gates above. Native shared encode+requires its own later ADR and is not part of Draft PR #13.- Whole-system versus selected-game audio for the first release.- Initial deployment region and network cohort.diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index 7cf1d8b3..91d19431 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -247,9 +247,13 @@ TURN/TLS 是可选能力,不是生产启动门槛。启用时默认使用 RFC所有边都继续使用标准 WebRTC。每名 viewer 播放收到的 remote `MediaStream`,并把其中的 remote tracks 加入给唯一 child 的新 `RTCPeerConnection`。该路径会逐跳解码和重编码;实验必须记录每层 encode time、CPU/GPU、`qualityLimitationReason`、帧率、分辨率和延迟,不能称为 zero-copy 或 shared encode。+Peer-assisted 信令只接受 `1080p60`、`1080p30`、`720p30` 三个 `qualityProfileId`。服务端用受房间容量限制的内存 Map 保存当前值,默认 `1080p60`,不写入 SQLite;停止分享时保留,房间被放弃或过期时删除。peer-assisted 鉴权快照携带当前值,host 鉴权后先重报本地选择再创建已分配的 child,直播中换档时通知所有在线 viewers,后加入者直接取得最新快照。普通 P2P 的严格鉴权 wire 保持原样,host 或 viewer 在该模式发送档位同步消息都会被拒绝。++Viewer 在处理 peer-assisted 鉴权快照时先更新 `ViewerRelay` 的 desired profile,再应用拓扑分配;同一个串行队列协调 remote stream、当前 child 更新和以后重建的 child,因此它们读取同一最新目标。每个 `HostPeer` 也把初始 sender 配置、`replaceStream()` 和 `updateProfile()` 放进同一 sender-mutation queue;`desiredProfile` 在入队前同步更新,已排队操作执行时读取最新值,使快速连续换档保持 last-wins,而不增加版本号或确认协议。这里同步的是浏览器 sender 的目标上限,不是实际分辨率、帧率、码率或 shared encoding 的性能保证。+spike 复用现有 screen stream 和浏览器 codec 协商,覆盖当前桌面 Chrome/Edge relay、按测试顺序位于链尾的当前 Android Chrome 与 iOS Safari leaf、最多八名 viewer;捕获存在时沿同一标准 WebRTC 路径带上音频。Encoded Transform/DataChannel/WebCodecs 媒体、SVC/simulcast、多树、转码、codec ladder、综合评分、移动端后台 relay 和自动 SFU 迁移均不实现。验收与失败即放弃条件以 ADR-0004 为准;成功也只能触发新的生产 ADR。-浏览器不保证多个 `RTCPeerConnection` 共享一次编码。实验允许 host 对一至两个 seed 各自编码;若未来正式采用,原生分享端必须用 shared encoder 将一份编码结果交给最多两套标准 WebRTC packetizer。该长期实现不在本 spike 中提前抽象。+浏览器不保证多个 `RTCPeerConnection` 共享一次编码。实验允许 host 对一至两个 seed 各自编码。后续独立的 native sender 阶段必须用 shared encoder 将一份编码结果交给最多两套标准 WebRTC packetizer,并由新的 ADR 约束;它降低 host 编码负载,但两条出边仍各自消耗上传带宽。该计划不依赖本次浏览器 relay 实验成败,也不在本 spike 中提前抽象或实现。详细证据见 `docs/research/peer-assisted-media.md`,提案见 `docs/adr/0004-peer-assisted-media-experiment.md`。diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index 4f0904b8..0826574e 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -20,7 +20,7 @@- [ ] 分享端 fanout 硬上限:分享端任何时刻最多维护两条下游媒体边,包括加入、断线、换父和恢复过程。第三名及后续观看者只能由通过验收的 peer-assisted 拓扑、部署者显式选择的可选 SFU 承载,或被明确拒绝;不能隐藏地回退为分享端第三条连接。- [ ] P2P 优先:每条逻辑媒体边的 ICE 必须先尝试直接 UDP 路径,服务器不得默认中转可直连的媒体。一个或两个观看者优先直接连接分享端;更多观看者的 peer-assisted 行为须先通过 ADR-0004 的实验门槛。- [ ] NAT 兜底:每条 parent-child 边独立进行 ICE;生产环境必须提供 STUN、TURN/UDP 与 TURN/TCP candidates,通过优先级偏好直连和 UDP,同时允许无法使用 UDP 的网络选择 TCP,不能因为某条边的网络与其他边不同而静默失败。-- [ ] 质量档位:提供 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档上限;分享期间可直接换档而不重新选择来源或重建健康连接。保留 `contentHint = "motion"` 并显式设置 `degradationPreference = "balanced"`;该偏好允许浏览器在帧率和分辨率之间权衡,不保证清晰度优先,具体行为必须实测。自定义动态 FPS 或画面检测策略必须在统计证明有必要后再实现。+- [ ] 质量档位:提供 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档上限;分享期间可直接换档而不重新选择来源或重建健康连接。Peer-assisted 房间只允许这三个档位 ID,并把分享者当前选择同步给现有和后续 relay sender;普通 P2P 信令结构保持不变。保留 `contentHint = "motion"` 并显式设置 `degradationPreference = "balanced"`;该偏好允许浏览器在帧率和分辨率之间权衡,不保证清晰度优先,具体行为必须实测。自定义动态 FPS 或画面检测策略必须在统计证明有必要后再实现。- [ ] 断线恢复:临时网络变化时尝试 ICE restart 和重连,并向用户显示当前连接状态。- [ ] 可观测性:采集候选类型、RTT、丢包、抖动、实际码率、帧率、编码耗时和质量受限原因。- [ ] 访问控制:部署者可配置一个全站 `ACCESS_PASSWORD`;为空时网站公开,非空值必须为 1 至 128 个可见 ASCII 字符。配置时分享者和观看者都必须先登录。登录成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` cookie,建房 HTTP 和 WebSocket 都只使用该 cookie,不提供建房 Bearer 旁路;不引入账号、JWT、服务端 session Map 或 logout。@@ -28,8 +28,8 @@### P1 - 重要功能-- [ ] Peer-assisted 媒体实验:分享端最多两个 child、每名 viewer 最多一个 child;信令服务只按深度和服务端加入序号确定性地形成两条 sticky 平衡链,不加入综合评分或主动重平衡。每个 viewer 将收到的标准 remote track 通过新的 `RTCPeerConnection` 转发,因此会逐跳解码和重编码;必须测量而不能称为 shared encode。该功能在 ADR-0004 的实验门槛通过并由后续 ADR 正式接受前不得成为产品路径。-- [ ] 原生 shared encode 分享端:长期产品若采用 peer-assisted,Electron/原生分享端必须保证一份兼容编码输出扇出到最多两套独立 WebRTC packetizer;浏览器不保证跨 `RTCPeerConnection` 复用编码器,因此纯 Web 分享端只能作为实验或便利回退,不能宣称满足 shared encode 保证。+- [ ] Peer-assisted 媒体实验:分享端最多两个 child、每名 viewer 最多一个 child;信令服务只按深度和服务端加入序号确定性地形成两条 sticky 平衡链,不加入综合评分或主动重平衡。每个 viewer 将收到的标准 remote track 通过新的 `RTCPeerConnection` 转发,因此会逐跳解码和重编码;必须测量而不能称为 shared encode。服务端只在受房间数限制的内存状态中保存当前档位,不写入 SQLite;host 鉴权后先重报档位,在线 viewers 接收更新,后加入者从鉴权快照取得当前值。该功能在 ADR-0004 的实验门槛通过并由后续 ADR 正式接受前不得成为产品路径。+- [ ] 原生 shared encode 分享端:后续独立的 Electron/原生分享端阶段必须保证一份兼容编码输出扇出到最多两套独立 WebRTC packetizer,并由单独 ADR 和测量约束。它降低分享端重复编码负载,但不消除每条出边各自的上传带宽。浏览器不保证跨 `RTCPeerConnection` 复用编码器,因此当前 Web spike 不实现、也不能宣称满足 shared encode 保证。- [ ] 可选 SFU:部署者可显式选择单节点 SFU 来降低分享端上传;它保持非默认、可逆,并承担每名观看者的服务器出口成本。Draft PR #12 仍在评审,不能视为已合并、已部署或推荐路径。- [ ] 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。- [ ] Windows 应用音频:仅捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享。@@ -62,7 +62,7 @@- 默认八名观看者和可配置的 1 至 16 范围是接入容量边界,不承诺任意机器、档位或网络都能稳定承载该人数,也不承诺跨洲网络下的固定低延迟。- 浏览器规范要求每次由用户主动选择分享源,权限不能永久保存;纯网页不能保证指定游戏窗口或始终获得系统音频。- 1080p60 是能力目标,实际分辨率、帧率和硬件编码由浏览器、GPU、驱动、画面复杂度及网络共同决定。-- 已部署首版仍是标准 WebRTC P2P。Peer-assisted spike 只复用标准 remote-track WebRTC,不加入 Encoded Transform/DataChannel/WebCodecs 媒体协议,也不自研 UDP、编解码器、拥塞控制、FEC/RTX、多树、转码、codec ladder 或综合评分器;需要其中任一项即放弃实验。SFU 只允许作为单独评审、显式配置的可选模式,不自动切换或双发。+- 已部署首版仍是标准 WebRTC P2P。Peer-assisted spike 只复用标准 remote-track WebRTC,不加入 Encoded Transform/DataChannel/WebCodecs 媒体协议,也不自研 UDP、编解码器、拥塞控制、FEC/RTX、多树、转码、codec ladder 或综合评分器;需要其中任一项即放弃本次浏览器 relay 实验。独立计划中的 native shared encode sender 不在本 spike 实现,也不能挽救其他拓扑门槛失败。SFU 只允许作为单独评审、显式配置的可选模式,不自动切换或双发。- GPL/AGPL 项目在许可证策略确认前仅用于研究,不能直接复制到计划闭源的产品中。## 验收标准@@ -93,8 +93,9 @@- Given 一名分享者和一至两名观看者,When 运行直接 P2P,Then 分享端为每人建立独立媒体边且总 fanout 不超过二。- Given peer-assisted spike 分别运行 1、3、5、8 名观看者,When 用户加入、离开或 relay 失效,Then 服务端使用同一个确定性广度优先规则形成两条 sticky 链,只为新 viewer 或失去 parent 的 subtree root 分配 parent,不主动搬动其他节点;分享端在任何瞬间都不超过两个 child 且每名 viewer 不超过一个,没有可用 parent 时明确等待或拒绝,而不是增加分享端 fanout。- Given 一名分享者和八名观看者,When 在受控网络中运行已记录的质量档位,Then 记录每条边的拓扑深度、候选类型、码率、编码/解码负载、分享端与 relay 上行、首帧和玻璃到玻璃延迟;该条在真实矩阵完成前保持未验收。+- Given peer-assisted host 鉴权或直播中换档,When 其选择三个受限档位之一,Then 当前和以后建立的 relay child sender 都使用最新目标档位,服务端只保留房间级内存状态并通知在线 viewers;普通 P2P 的鉴权 wire 不新增该字段,且不接受档位同步消息。- Given 标准浏览器把收到的 remote track 直接加入下游 `RTCPeerConnection`,When 检查 relay 统计和 libwebrtc 路径,Then 明确记录新的 outbound encoder、编码耗时和 CPU/GPU 限制,不把它当作 encoded forwarding 或 shared encode 成果。-- Given ADR-0004 的任一硬门槛只有在引入 Encoded Transform/DataChannel/WebCodecs 媒体、自定义拥塞控制、FEC/RTX、多树、综合评分、转码、codec ladder、浏览器 RTP 注入 hack 或放宽 host fanout 后才能满足,When 结束 bounded spike,Then 放弃并删除实验运行时代码,保留标准 P2P 和可选 SFU。+- Given ADR-0004 的任一硬门槛只有在引入 Encoded Transform/DataChannel/WebCodecs 媒体、自定义拥塞控制、FEC/RTX、多树、综合评分、转码、codec ladder、浏览器 RTP 注入 hack 或放宽 host fanout 后才能满足,When 结束 bounded spike,Then 放弃并删除浏览器 relay 实验运行时代码,保留标准 P2P 和可选 SFU;后续 native shared encode sender 仍按独立 ADR 推进,但不能据此把失败的 relay 拓扑判为通过。- Given 新观看者会使预计总上行超过安全预算,When 其请求加入,Then 系统自动降低档位、拒绝该档位或建议改用外部直播服务,而不是持续堆积发送队列。### 质量和恢复