Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
chore: merge main into feat/sfu-udp-exact-room
AAA12d4b4e4aa8d
diff --cc docs/project-memory.mdindex a174a37e,57c11cb7..6688b8c6--- a/docs/project-memory.md+++ b/docs/project-memory.md@@@ -16,17 -17,17 +17,17 @@@ Last updated: 2026-08-1## Current Recommendation- Keep desktop Chrome/Edge and the responsive Web viewer as the baseline. Validate Android Chrome and iOS Safari as leaves.-- Use direct host P2P for one or two viewers. Keep ADR-0004 off broadly; use an exact-room canary until resource, quality, recovery, SFU/UDP, optional-TURN, and browser/mobile gates pass.+- Use direct host P2P for one or two viewers. Keep ADR-0004 off broadly; use an isolated exact-room candidate until resource, quality, recovery, SFU/UDP, bounded-failure, and browser/mobile gates pass.- Browser relays resend remote `MediaStreamTrack` values and re-encode at each hop; WebRTC does not guarantee a shared encoder across peer connections, so measure the cost.- - Keep browser experiments bounded; spike native RTP relay, encoded-object striping, SVC, and FEC separately.- - ADR-0006 retains a fixed-`HIGH` native canary boundary, but its sole product-wiring run reached only host setup and one encoder output before the first-viewer decoded/rendered gate timed out. Downstream checkpoints were not retained, so the result is no-go-unclassified, not a diagnosed product bug. No native product code is accepted; revisit only through the staged evidence gate.- - ADR-0005 accepts SFU roots as the primary central fallback after direct/peer UDP, never default whole-room fanout. The repository candidate has no TURN consumer or credential wire; a future exceptional assigned edge requires a complete generation-bound grant change. PR #12 is superseded.- - Keep the current failure-only controller default-off until the isolated STUN/SFU migration and exact-room gates pass. Preserve break-before-make, sticky healthy subtrees, mobile leaves, and PR #20 prewarm; public transport/load remains open.+ - Keep experiments bounded: the standard representation sequence is below; native RTP relay, encoded-object striping, and FEC remain separate.+ - ADR-0006's fixed-`HIGH` canary reached host setup and one encoder output but retained no downstream checkpoint before the first-viewer timeout. It is no-go-unclassified; no native product code is accepted, and any revisit starts at its staged evidence gate.-- ADR-0005 accepts SFU roots as the primary central fallback after direct/peer UDP, never default whole-room fanout. Optional TURN is issued only to an exceptional assigned edge; PR #12 is superseded.-- Keep the current failure-only controller default-off until config migration and exact-room gates pass. Preserve break-before-make, sticky healthy subtrees, mobile leaves, and PR #20 prewarm; public transport/load remains open.++- ADR-0005 accepts SFU roots as the primary central fallback after direct/peer UDP. The candidate has no TURN consumer or credential wire; any future exceptional-edge grant is a complete separate change. PR #12 is superseded.++- Keep the failure-only controller default-off until the isolated STUN/SFU exact-room gates pass. Preserve break-before-make, sticky healthy subtrees, mobile leaves, and PR #20 prewarm; public transport/load remains open.- Local reparenting is a later candidate: start with unassigned relay admission rescue; do not block current work.- - Flagship media is UDP; HTTPS/WSS stays TLS/TCP. Old production retains coturn TURN for rollback. The candidate uses self-hosted coturn STUN-only for ordinary ICE and separate LiveKit SFU/UDP, with no TURN/media-TCP config or wire. Future selected-edge TURN requires measured design and a complete consumer.- - Treat video settings as ceilings and degradation as unclassified. Local host A+B now covers same-tick capture/outbound identity, windows, deltas, remote linkage, path, and nullable negotiated codec/profile token/allowlisted parameters/current stream `scalabilityMode`. Use it first to reproduce the reported Host-only recovery, then add minimal authenticated C and test standard simulcast/LiveKit/SVC before custom `LOW`; this need not wait for ADR-0006. Never use UA or a composite score.- - Reported poor movie/video audio is unclassified. After video A+B, separately diagnose audio A/B/C and A/V sync across capture settings, codec/fmtp, actual bitrate, loss, jitter, concealment, and jitter buffer. `maxBitrate` is not quality-up; do not expand runtime before evidence. See `docs/research/browser-screen-audio-quality.md`.- - Do not add custom scene detection or dynamic-FPS control until WebRTC statistics and host resource measurements prove a material gap. Keep browser codec order until target hardware proves a more efficient common codec.-- Flagship media defaults to UDP; HTTPS/WSS remains TLS/TCP. Current production still requires coturn UDP/TCP. Future TURN absence is normal, partial config fails, and any media-TCP/port compatibility mode is chosen only by canary.++- Flagship media is UDP; HTTPS/WSS stays TLS/TCP. Old production retains coturn TURN for rollback. The candidate uses self-hosted STUN-only ordinary ICE and separate LiveKit SFU/UDP, with no TURN/media-TCP wire.+ - Treat settings as ceilings and deployed degradation as unclassified. Use correlated Host A+B/Viewer C to compare exact `769de201f7cc` against current `main` for Host-only recovery, game FPS/load, preview cost, actual codec/encoder and one-variable rebuilds; then test standard simulcast/LiveKit/SVC before custom `LOW`. Never use UA or a composite score.+ - Production reports poor film audio and self-echo when system capture includes voice software. Diagnose audio A/B/C and sync; Web cannot isolate arbitrary processes and `maxBitrate` is not quality-up. A Windows 11 native candidate defaults to game-process-tree audio and never widens silently; Windows 10 remains unresolved/unsupported. See `docs/research/browser-screen-audio-quality.md`.+ - Do not add scene detection, dynamic-FPS control, or forced AV1 until stats and target hardware prove the need. Codec acceptance requires actual negotiation, power-efficient candidate evidence, interval encode cost, game FPS, CPU/GPU and sender count; Discord's native capture/hardware tuning is comparison evidence, not proof of server re-encoding or a reusable preset.- Keep room policy deployment-driven: public/password-only rooms are random and temporary; password plus SQLite enables sequential persistent rooms and reusable stopped links.- Deferred architecture audit: `docs/maintenance.md`.diff --cc docs/status.mdindex 8581aa38,45c3eb4b..2ff3b0d1--- a/docs/status.md+++ b/docs/status.md@@@ -32,35 -32,31 +32,33 @@@ unconfigured, so production remains on## Unverified Boundaries- - Full-resolution 30-minute runs, relay CPU/GPU, generational quality, controlled loss/RTT, depth latency, and game capture are unverified.+ - Full-resolution 30-minute runs, relay CPU/GPU, controlled loss/RTT, and depth latency are unverified. Production `769de201f7cc` game sharing is reported low-FPS/high-load; latest `main`, preview cost, codec, and hardware encoding are not yet compared.- Android Chrome/iOS Safari leaves are unverified; runtime conservatively marks detected mobile/iPad clients as leaves.- Silent partitions can wait 30 to 60 seconds for heartbeat detection before the default 5-second grace; this remains unverified.- - Real audio, heterogeneous clients, mobile lifecycle, quality/pause, room `1` republish, and sustained profiles are unverified. Poor movie/video audio is user-reported but unclassified; after video A+B, diagnose capture settings, codec/fmtp, actual bitrate, loss, jitter, concealment, jitter buffer, and A/V sync.+ - Real audio and heterogeneous clients remain unverified. Production reports poor film audio and voice-call self-echo under system capture; there is no app audio ceiling or Web process isolation. Diagnose A/B/C and sync, then gate Windows 11 game-process audio; Windows 10 stays unresolved without system fallback.- Production `769de201f7cc` reportedly sustains native `qualityLimitationReason=bandwidth` and severe blur with one capable LAN/direct viewer; only Host refresh restores quality. Within the five-second grace, stable-clientId Viewer refresh retains its `peerId`/`HostPeer`, while Host refresh rebuilds peers/capture; churn persistence is also reported. This prioritizes but does not prove sender/PC/GCC/capture generation over network or lifecycle causes.- - ADR-0007 remains incomplete. Host A+B codec fields exist, but browser support and the reported case are unverified; authenticated C, the controller, and `LOW` are absent. Weak paths must share one `LOW`; fail closed protects `HIGH` only exceptionally, and an unreliable supported cohort fails acceptance.+ - ADR-0007 remains incomplete. A+B/C browser support and the reported case are unverified; the controller, `LOW`, and an authenticated SFU last-hop C generation are absent. Weak paths must share one `LOW`; fail closed protects `HIGH` only exceptionally, and an unreliable supported cohort fails acceptance.- Browser relays re-encode. ADR-0006 is no-go-unclassified: downstream checkpoints and two-edge/FIFO/TURN gates are absent. Spikes prove one WebCodecs object, not hardware; GCC+RTX is no-go and no-RTX weakens stats.- Browser fanout is host two/viewer one; any accepted endpoint relay stays capped at two downstream edges.-- ADR-0005 accepts SFU-root fallback, but code is failure-only/TURN-required; UDP-first config, edge grants, bounded failure, cost/trust, and public canary are absent.+- ADR-0005's candidate is process-wide STUN-only ordinary ICE plus separate LiveKit SFU/UDP and bounded failure, with no all-room TURN wire. It is default-off and lacks public gates; the old release is rollback.- Pinned LiveKit 1.13.5 Dynacast enables all qualities at or below the room's maximum request, so a `HIGH` root is expected to keep `LOW` enabled. It remains a bounded rejection/verification spike, not evidence that on-demand `LOW` can stop.- The corrected standby smoke is localhost/headless/video-only; public DNS/TLS reuse, transport, audio, shaping, load, mobile, endurance, and sub-25 ms overlap remain open.## Next Milestone- Use the completed local host A+B diagnostics to reproduce the same-LAN/direct- case. First rebuild one affected `HostPeer`/`connectionId` while retaining- capture and healthy peers; separately compare capture-only and full Host rebuilds with- A+B/C evidence and opaque generations. The affected viewer must recover without- moving healthy peers or breaking the host-edge cap. Only proven stuck- generations justify guarded/cooldown recovery; never reconnect periodically or- raise ceilings blindly.-- After video A+B, run the audio A/B/C and sync diagnosis; `maxBitrate` is not a- quality fix. Then add authenticated video C and test standard- simulcast/LiveKit/SVC before custom `LOW`, independently of ADR-0006. The app- owns only the two-state policy; WebRTC/LiveKit owns congestion/layers. Later one- isolated exact-room candidate must pass peer/SFU UDP and bounded-failure gates- before replacing the old release. Optional selected-edge TURN, if evidence later- requires it, is a separate complete change rather than part of this canary.+ Use correlated Host A+B/Viewer C to compare exact production and current `main` on one wired/direct+ game fixture. Record actual codec/encoder, game FPS, CPU/GPU, preview on/off and+ A+B while separately rebuilding one `HostPeer`, replacing capture, and fully+ refreshing Host. Only a proven stuck generation justifies guarded recovery; never+ reconnect periodically, force AV1, or raise ceilings blindly.++ After that reproduction, test simulcast/LiveKit/SVC in order and stop at the+ first fit before custom `LOW`, independently of ADR-0006. Diagnose audio A/B/C,+ sync, and voice-source leakage in parallel when it does not displace that P0;+ `maxBitrate` is not a quality fix. WebRTC/LiveKit owns congestion/layers; the app-owns two-state policy. An exact room later gates peer/SFU UDP and coturn changes.++owns two-state policy. An isolated exact room later gates peer/SFU UDP and++bounded failure before replacing the old release. Selected-edge TURN, if later++justified, is a separate complete change rather than part of this canary.ADR-0004 still requires a full-resolution 30-minute `1/3/5/8` network,resource, quality, latency, recovery, and browser/mobile-leaf matrix.diff --cc "docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index fb72a8e0,07ab00c9..5af8531a--- "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"@@@ -172,47 -179,27 +178,47 @@@ SVC 是 simulcast 与 LiveKit/Dynacast质量控制不放宽媒体拓扑预算:host 仍最多两条下游媒体边;native relay 只转发选定表示的编码包,不解码重编码。后续双树或条带化可把 host 上传从约两份完整码率推向一份加必要冗余,但不阻塞按需双表示的实现。- 标准表示能力排在完整 A+B/C 证据之后、任何自定义双表示媒体实现之前,并可与 ADR-0006 native sender 复核并行:依次做同 sender simulcast、最多两个 LiveKit root 的 Dynacast 验证/否决和 SVC spike。具体语义与资源门槛由 ADR-0007 和[实时质量调研](./research/realtime-quality-adaptation.md)持有,任何方案都不得复用 PR #28 的 minimum-of-two 或绕过 stock WebRTC congestion control。+ 标准表示能力排在完整 A+B/C 证据之后、任何自定义双表示媒体实现之前,并可与 ADR-0006 native sender 复核并行:依次做同 sender simulcast、最多两个 LiveKit root 的 Dynacast 验证/否决和 SVC spike,首个满足语义与资源门槛的路径立即结束序列。具体门槛由 ADR-0007 和[实时质量调研](./research/realtime-quality-adaptation.md)持有,任何方案都不得复用 PR #28 的 minimum-of-two 或绕过 stock WebRTC congestion control。-## 媒体传输配置与可选 TURN--当前已部署版本仍在房间鉴权后生成 coturn REST 凭据:--```text-expiry = floor(unix_seconds) + ttl-username = expiry + ":" + opaque_room_and_peer_subject-credential = base64(HMAC-SHA1(shared_secret, username))-```--`TURN_SHARED_SECRET` 只存在于应用服务和 coturn。浏览器只收到短期 username/credential、STUN/TURN URLs 和 `expiresAt`。这是 release `769de201f7cc` 的现行实现和部署契约:生产缺少 STUN、TURN secret、显式 TURN/UDP URL 或显式 TURN/TCP URL 时启动失败。在新的传输策略代码和 exact-room canary 合入前,部署人员不得仅依据目标文档删除这些变量。--已接受的旗舰目标把 STUN 和 SFU/UDP 作为基线,把 TURN 改为默认未配置的极端网络兼容层。完整 TURN 配置缺失表示正常禁用且不显示提醒;任一部分存在但不完整必须启动即失败。ordinary Host-to-root 或 root-to-viewer 例外需要新 coturn per-edge grant/wire,短期凭据绑定 assignment/connection generation,不能在房间鉴权时广播给普通 peer edges。LiveKit publisher/subscriber 到 SFU 属于另一 ICE 域;pinned 1.13.5 embedded/external TURN 当前向 LiveKit participant 广告,不是 Screener selected-edge grant,也不能在 SFU 宕机时恢复媒体。它仅是 canary candidate,若不能隔离/扩展到 accepted exceptional-edge scope 就拒绝。两条兼容路径必须分开配置、鉴权和 canary,不能把 embedded TURN 写成 ordinary peer coturn 的替代。--目标媒体梯级是 `direct/peer UDP -> SFU ICE/UDP -> optional selected-edge compatibility transport -> failure`。媒体 TCP 默认不启用;具体 ICE/TCP、TURN/UDP、TURN/TCP 或 TURN/TLS 组合只能由目标网络 canary 选择。HTTPS/WSS 始终使用 TLS/TCP,不属于媒体 TCP。clarity/balanced/fluid 只改变编码策略,不能选择 UDP/TCP;TCP 队头阻塞可能放大实时视频 RTT、冻结和 GCC 带宽限制,因此不得把媒体 TCP 描述为高清路径。当前 tracked LiveKit 样例仍配置 ICE/TCP 7881 且 pinned 1.13.5 允许 TCP fallback;在迁移 PR 前这仍是未验收的现行候选,不是假装已经关闭。--候选由 ICE 按优先级和连通性检查选择。界面只报告实际 selected candidate type、ICE protocol,以及本地为 relay 时的 TURN protocol,不推测 NAT 类型或回退步骤。TURN 是单条 ICE 边的 transport,peer-assisted 与 SFU 才是拓扑;一个 selected relay pair 不改变其他边的父子关系。普通 TURN 保留 WebRTC endpoints 间的 DTLS-SRTP,而普通 SFU 终止两侧 DTLS-SRTP;没有应用层 E2EE 时 operator 可接触 SFU 媒体,这一产品取舍必须保持可见。--SFU 是主要中央兜底,但正常只作为 virtual parent 向一至两个必要 roots 发布;每个可靠 root 收到媒体后继续服务既有 sticky descendants。host/native root 最多两条下游媒体边,browser root/relay 最多一个 child。无法挂到健康 root 的多个极端 viewers 只能通过独立 `E`/central-egress cap 准入,不能藏进 normal-root 预算。host→SFU publisher 是独立 ICE 连接,所有 TURN/SFU/endpoint 物理 hop 都按[低服务器成本媒体路由](./research/low-server-media-routes.md)逐项计量。当前控制器仍是 default-off、failure-only;新的 UDP-first 梯级必须先通过 ADR-0005 exact-room canary,不能直接翻转生产开关。+## 媒体传输配置++当前仓库候选已经删除旧全房 TURN contract。`ServerConfig` 只接受+`STUN_URLS`;生产缺失 STUN 启动即失败。`authenticated.iceConfig` 是静态+STUN snapshot,只含 `iceServers`,不含 TURN URL、username、credential、+expiry 或 `relayAvailable`。信令协议也不再接受 `refresh-ice` 或发送+`ice-config`;WebSocket 重连后的新 `authenticated` 自然取得当前 snapshot。++普通 direct/peer `RTCPeerConnection` 与 LiveKit participant 是两个明确的+ICE 域。普通边只消费 `authenticated.iceConfig`;SFU publisher/subscriber+只消费 revision-bound `sfu-config {url, token}`,再由 LiveKit SDK 与服务端+协商自己的 candidates。tracked LiveKit 配置只开放 UDP mux,不配置+`rtc.tcp_port`、external TURN 或 embedded TURN。Node 应用不能替代部署+验证来证明该 UDP listener 从公网可达。++当前可执行梯级是 `direct/peer UDP -> SFU ICE/UDP -> failure`。Viewer 的+现有两次有界 ICE restart/rebuild 后报告 route failure;router 先尝试局部+reparent,再在 root budget 内准备 SFU,最终没有可行 route 时返回明确的+`PEER_NOT_FOUND`,不长时间维持伪连接。HTTPS/WSS 始终使用 TLS/TCP,不+属于媒体 TCP;clarity/balanced/fluid 只改变编码策略。++旧 production release `769de201f7cc` 仍需要 coturn TURN/UDP+TCP。它作为+独立旧实例保留到新 candidate canary 通过;新代码不根据 room allowlist+保留 legacy TURN 分支。`PEER_ASSISTED_ROOM_IDS` 只灰度 topology/SFU route+wire,进程内所有房间的 ordinary ICE 都是 STUN-only。因此验证与回滚必须+使用隔离 candidate/旧实例,不能假设同进程未命中房间仍有旧 transport。++optional selected-edge TURN 仍是未来候选,不是当前能力。只有真实受限网络+证据证明需要时,才以单独 PR 一次性加入配置校验、短期鉴权、assignment/+connection generation grant、限频、客户端消费、部署和负向测试。该 PR+不得恢复房间鉴权时广播的全房 credentials。LiveKit participant-wide TURN+也不能冒充这项 edge grant。++SFU 正常只作为 virtual parent 向一至两个必要 roots 发布;可靠 root 收到+媒体后继续服务 sticky descendants。host/native root 最多两条下游媒体边,+browser root/relay 最多一个 child。无法挂到健康 root 的极端 viewers 只能+通过独立 `E`/central-egress cap 准入。普通 SFU 终止两侧 DTLS-SRTP;没有+应用层 E2EE 时 operator 可接触媒体,这一产品取舍必须保持可见。所有物理+hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)逐项计量。## 可观测性@@@ -275,8 -262,8 +281,8 @@@- 同机双标签页与同 LAN direct;- 真实跨网络、同房间 direct/peer UDP + SFU/UDP root;- - CGNAT、双 NAT、移动热点和普通家宽下使用隔离 candidate,LiveKit 不配置 `rtc.tcp_port` 或任何 TURN,验证 host 与 roots 使用 SFU/UDP;人为封锁 UDP 时必须有界明确失败。旧 production release 留在独立实例作为回滚,不在同进程保留 legacy transport;- - Windows Chrome/Edge 的音轨有/无;-- CGNAT、双 NAT、移动热点和普通家宽下使用临时 canary 配置移除 `rtc.tcp_port`、关闭公网 7881 且不配置 TURN/TCP/TLS,验证 host 与 roots 使用 SFU/UDP;人为封锁 UDP 时必须有界明确失败。只在部署选择兼容层时另测 LiveKit participant TURN 或 ordinary peer coturn;++- CGNAT、双 NAT、移动热点和普通家宽下使用隔离 candidate,LiveKit 显式关闭 TCP fallback 且不配置 TURN,验证 host 与 roots 使用 SFU/UDP;人为封锁 UDP 时必须有界明确失败。旧 production release 留在独立实例作为回滚,不在同进程保留 legacy transport;+ - Windows Chrome/Edge 的 tab/window/monitor 音轨有/无、同时语音通话和 video-only;Windows 11 原生候选另测 game process tree、通知、无渲染流与进程重启,Windows 10 记录明确不支持/未解决;- Android Chrome 与 iOS Safari 的播放手势、旋转、前后台和网络切换;- 一名分享者、八名异构观看者连续 30 分钟,同时记录较低人数基线、实际上行、编码负载和首帧时间。真实 1:8 未完成前不得把默认上限写成性能承诺。- 真实桌面 Chrome 对 balanced 与 clarity 做控制传播和连接身份 smoke;该项只证明直播中应用与不重建,不代替清晰度、负载或公网矩阵。diff --cc "docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index 3663e89a,78426b22..71c2a8c2--- "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,9 -20,9 +20,9 @@@- [ ] 一对多观看:一名分享者可向配置允许的多名观看者发送画面;默认上限为 8,可配置范围为 1 至 16。当前 PoC 的逐观看者连接是测量基线,不再是超过两名观看者时的目标拓扑。- [ ] 端点 fanout 硬上限:任一非服务器端点任何时刻最多维护两条 active downstream media edges,包括加入、断线、换父和恢复过程;上游接收不计入这项上传预算。当前 browser relay 因逐跳重编码仍保守限制为一个 child,只有资源矩阵通过后才可升到二。第三名及后续观看者由系统自动分配给通过验收的 peer-assisted 拓扑,不能隐藏地回退为 Host 第三条连接。没有可行 peer path 时,SFU 作为主要中央兜底 virtual parent 正常向一至两个必要 roots 送流;媒体到达 root 后其余可行观看者仍优先沿受限 peer descendants 扩散。多个无法挂到健康 root 的极端 viewer 可成为额外 server-fed 例外,但必须受显式中央 egress/admission 上限约束,不能无界整房 fanout。TURN 只作为可选的极端网络 transport 兼容层,不定义房间拓扑。- [ ] P2P 优先:每条逻辑媒体边的 ICE 必须先尝试直接 UDP 路径,服务器不得默认中转可直连的媒体。一个或两个观看者优先直接连接分享端;更多观看者的 peer-assisted 行为须先通过 ADR-0004 的实验门槛。-- [ ] NAT 与传输兜底:STUN 必须可用。普通 direct/peer 边默认只使用 ICE/UDP;其路径不可用时改由 SFU virtual parent 承担必要 root,而不是给每条 peer edge 常驻 TURN candidates。旗舰默认媒体路径为 `direct/peer UDP -> SFU ICE/UDP -> 明确失败`。部署者可为已验证的受限网络额外启用短期鉴权 TURN。普通 Host 到 peer root 或 root 到 viewer 的异常边需要新增、绑定当前 assignment/connection generation 的独立 coturn grant/wire;一个 TURN seed root 收到媒体后仍优先服务 bounded peer descendants。LiveKit publisher/subscriber 到 SFU 是另一 ICE 域,pinned 1.13.5 的 embedded/external TURN 当前按 LiveKit participant 广告,不是 Screener selected-edge grant。两者必须分开配置、鉴权和验收。媒体 ICE/TCP、TURN/TCP 和 TURN/TLS 不是默认质量路径。HTTPS/WSS 仍使用 TLS/TCP。全部可选 TURN 配置缺失表示正常禁用且不提示,部分配置必须启动即失败。+- [ ] NAT 与传输兜底:STUN 必须可用。普通 direct/peer 边只接收 STUN ICE servers;其路径不可用时改由 SFU virtual parent 承担必要 root,而不是给每条 peer edge 常驻 TURN candidates。当前可执行梯级为 `direct/peer UDP -> SFU ICE/UDP -> 明确失败`。应用配置、信令协议和客户端不得保留无消费者的全房 TURN URL、credential 或续期 wire。未来只有经受限网络证据证明必要时,才可由独立 PR 新增绑定当前 assignment/connection generation 的 selected-edge coturn grant;一个 TURN seed root 收到媒体后仍优先服务 bounded peer descendants。LiveKit publisher/subscriber 到 SFU 是另一 ICE 域,pinned 1.13.5 的 embedded/external TURN 当前按 LiveKit participant 广告,不是 Screener selected-edge grant。两者必须分开配置、鉴权和验收。当前候选不配置 LiveKit TURN、媒体 ICE/TCP、TURN/TCP 或 TURN/TLS;HTTPS/WSS 仍使用 TLS/TCP。- [ ] 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,默认采用清晰优先;分享期间可直接换档或应用有界高级设置,不重新选择来源或重建健康连接。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,必须读回实际 sender 参数并显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。- - [ ] 按需双表示:健康房间只运行一套 active `HIGH` representation;第一条观看路径被同一时段的 sender 与 viewer 统计持续证明无法承受时,系统必须启动唯一一套由全部弱路径共用的 `LOW` 并迁移弱路径。健康路径继续使用 `HIGH`,全部弱路径稳定恢复后关闭 `LOW`。active representation 硬上限为二,禁止按观看者增长为 N 套,也禁止把最差路径的目标应用到整个房间。标准浏览器不保证跨 PeerConnection 共用一个物理编码器,inactive 层也不保证释放 GPU;物理 encoder instance、CPU/GPU 和释放行为必须实测。没有合格 hardware/power-efficient 路径或启动 `LOW` 造成不可接受负载时,当次必须 fail closed:保护 `HIGH` 并明确显示弱路径降级或不可用;这只是异常止损,supported sender cohort 若不能可靠按需启动 `LOW`,则自动质量控制验收失败,必须优化编码路径或明确标记不支持。+ - [ ] 按需双表示:健康房间只运行一套 active `HIGH` representation;第一条观看路径被同一时段的 sender 与 viewer 统计持续证明无法承受时,系统必须启动唯一一套由全部弱路径共用的 `LOW` 并迁移弱路径。健康路径继续使用 `HIGH`,全部弱路径稳定恢复后关闭 `LOW`。active representation 硬上限为二,禁止按观看者增长为 N 套,也禁止把最差路径的目标应用到整个房间。实现必须依次验证标准 WebRTC simulcast、LiveKit layer selection/Dynacast 和 SVC;任一方案满足按需停启、独立选层与资源门槛即停止,不继续自研媒体层。标准浏览器不保证跨 PeerConnection 共用一个物理编码器,inactive 层也不保证释放 GPU;物理 encoder instance、CPU/GPU 和释放行为必须实测。没有合格 hardware/power-efficient 路径或启动 `LOW` 造成不可接受负载时,当次必须 fail closed:保护 `HIGH` 并明确显示弱路径降级或不可用;这只是异常止损,supported sender cohort 若不能可靠按需启动 `LOW`,则自动质量控制验收失败,必须优化编码路径或明确标记不支持。- [ ] 路径级质量状态:每条观看路径只使用 `HIGH` 与 `FALLBACK` 两态。进入 `FALLBACK` 需要多个连续窗口的带宽不足、冻结或解码跟不上证据,回到 `HIGH` 需要更长的稳定窗口;进入与退出使用不同门槛且不计算综合分数。Viewer 的低档请求必须经当前会话鉴权、限频和去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、派生后的实际协商视频 codec/profile/parameters(适用时含 `scalabilityMode`)与 viewer 的实际解码、丢帧、冻结证据交叉验证,不能仅凭自报生效;上报不得包含 raw SDP、candidate 地址或原始设备/网络标识,鉴权与关联只使用服务端签发的不透明路径/连接代次 ID。- [ ] 断线恢复:临时网络变化时尝试 ICE restart 和重连,并向用户显示当前连接状态。- [ ] 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、丢包、抖动、码率、帧率、编码耗时和受限原因。候选与错误仅使用[低服务器成本媒体路由](./research/low-server-media-routes.md)的脱敏字段和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText` 或网络标识。@@@ -43,10 -43,10 +43,10 @@@- [ ] 分包/分层多树实验:把编码包、对象或可独立解码层拆到多个 peer 路径以分散上传,只能在独立 spike 中验证。必须保持亚秒级,处理多父重组、排序、丢包恢复、关键帧、同步和节点退出;未通过门槛前不进入产品路由控制器。- [ ] SFU-root 中央兜底:产品部署目标必须提供经 canary 验收的单节点 SFU 资源;系统在 direct/peer UDP 不可用或明确拓扑预算无法接纳时自动把它作为主要中央兜底,不要求用户选模式。它只向总计一至两个必要 roots 出口;root 优先承担受限 peer descendants,没有可靠 relay root 时必要 viewer 只作为同一总上限内的零 descendants root。已关闭 PR #12 的显式整房 SFU 模式已被取代。当前 PR #17 实现仍是 default-off、failure-only 且生产未配置;按 ADR-0005 的 exact-room canary 验收并修改配置契约后,才能启用新的默认梯级。- [ ] 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。- - [ ] Windows 应用音频:仅捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享。+ - [ ] Windows 应用音频:Windows 11 原生候选默认仅捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。-- [ ] 连接自检:在开始分享前验证信令、STUN、SFU ICE/UDP 及部署实际启用的可选 TURN 或媒体 TCP 可达性,并给出不暴露凭据的诊断结果。未配置可选兼容层不是告警。+- [ ] 连接自检:在开始分享前验证信令、STUN 和 SFU ICE/UDP 可达性,并给出不暴露地址或凭据的诊断结果。当前没有 selected-edge TURN 或媒体 TCP 配置面;未来兼容层只有在完整实现后才加入自检。- [ ] 受限网络增强:部署者仅在明确选择覆盖 UDP 受限网络且 canary 证明收益时,才可启用短期鉴权 TURN 或媒体 TCP;它只能用于控制器选中的异常 transport,不能成为所有普通 peer 边的默认候选,也不能被描述为更高清的传输方式。- - [ ] 运行时编解码选择:根据端点能力和统计数据选择实际硬件编码的 H.264、VP8、VP9 或 AV1,并始终保留兼容回退。+ - [ ] 运行时编解码选择:先保留浏览器默认协商;只有端点能力相交、Media Capabilities 对目标分辨率/FPS/码率报告 supported/smooth/power-efficient,且实际 outbound codec、区间 encode time、游戏 FPS、CPU/GPU 与 sender 数量共同通过时,才调整 H.264、VP8、VP9 或 AV1 优先级。AV1 不得因压缩率推断而默认启用,任何候选都不得静默落入高负载软件编码。- [ ] 诊断页面:用户可导出不含敏感地址和凭据的连接诊断信息。### P2 - 可选功能diff --cc src/client/pages/HostPage.tsxindex 92576974,71503901..f05886de--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@@ -297,8 -321,16 +320,15 @@@ export function HostPage({ onAuthorizatpeerAssistedRef.current = false;setStream(null);setDetails(null);- setRelayAvailable(false);setMaxViewers(null);setPeerSnapshots(new Map());+ viewerQualityEvidenceTimersRef.current.forEach((timer) =>+ window.clearTimeout(timer),+ );+ viewerQualityEvidenceTimersRef.current.clear();+ viewerQualityEvidenceRef.current = new Map();+ setViewerQualityEvidence(new Map());+ activeRouteRevisionRef.current = 0;setSignalStatus("offline");setSwitchingSource(false);setChangingQuality(false);diff --cc src/shared/protocol.tsindex 5179ad5c,15c94ff9..ead74dee--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@@ -5,7 -7,9 +7,10 @@@ export const MAX_SIGNAL_BYTES = 64 * 10export const ROOM_CODE_LENGTH = 12;export const MAX_MEDIA_ROUTE_REVISION = Number.MAX_SAFE_INTEGER;export const MAX_SFU_TOKEN_LENGTH = 8 * 1024;+export const MAX_ICE_SERVER_URLS = 8;+ export const MAX_VIEWER_QUALITY_EVIDENCE_BYTES = 2 * 1024;+ export const VIEWER_QUALITY_EVIDENCE_INTERVAL_MS = 2_000;+ export const VIEWER_QUALITY_EVIDENCE_EXPIRY_MS = 5_000;const opaqueIdSchema = z.string()@@@ -365,7 -457,25 +459,19 @@@ export const serverMessageSchema = z.un.strict(),z.object({- type: z.literal("host-status"),+ type: z.literal("viewer-quality-evidence"),+ viewerPeerId: opaqueIdSchema,+ parentPeerId: opaqueIdSchema,+ guard: viewerQualityEvidenceGuardSchema,+ ...viewerQualityEvidenceWindowShape,+ })+ .strict()- .refine(freezeFitsEvidenceWindow, {- message: "Viewer freeze duration exceeds its evidence window",- }),- z- .object({- type: z.literal("ice-config"),- iceConfig: iceConfigSchema,- })- .strict(),- z- .object({- type: z.literal("host-status"),++ .refine(freezeFitsEvidenceWindow, {++ message: "Viewer freeze duration exceeds its evidence window",++ }),++ z++ .object({++ type: z.literal("host-status"),online: z.boolean(),}).strict(),diff --cc tests/protocol.test.tsindex 97862194,e262ba23..837f9b73--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@@ -19,13 -20,35 +20,41 @@@ const qualitySettings =degradationPreference: "maintain-resolution",} as const;+ const qualityEvidence = {+ type: "viewer-quality-evidence",+ guard: {+ connectionId: "connection_12345678",+ routeRevision: 0,+ },+ sequence: 0,+ windowMs: 2_000,+ metrics: {+ width: 1_920,+ height: 1_080,+ framesPerSecond: 59.8,+ bitrateKbps: 7_500,+ packetsReceivedDelta: 1_500,+ packetsLostDelta: 2,+ jitterMs: 3.5,+ framesDecodedDelta: 120,+ framesDroppedDelta: 1,+ decodeMsPerFrame: 2.4,+ freezeCountDelta: 0,+ freezeDurationMsDelta: 0,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters:+ "packetization-mode=1; level-asymmetry-allowed=1",+ },+ } as const;+describe("client signaling protocol", () => {+ it("rejects the removed all-room ICE refresh request", () => {+ expect(clientMessageSchema.safeParse({ type: "refresh-ice" }).success).toBe(+ false,+ );+ });+it("accepts a bounded authentication message", () => {expect(decodeClientMessage(diff --cc tests/server-signal.test.tsindex 8cea02f1,24c77439..61a56bec--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@@ -159,7 -162,7 +160,8 @@@ async function startHarnesspersistent?: boolean;peerAssistedMedia?: boolean;peerAssistedPrimaryRoomOnly?: boolean;+ stunUrls?: readonly string[];+ now?: () => number;} = {},): Promise<SignalHarness> {const config = testConfig();