Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs: accept adaptive H264 browser path
AAA186c9f9775c7
diff --git a/docs/adr/0002-memory-resident-protected-rooms.md b/docs/adr/0002-memory-resident-protected-rooms.mdindex 0535c7ed..4c3e1f1b 100644--- a/docs/adr/0002-memory-resident-protected-rooms.md+++ b/docs/adr/0002-memory-resident-protected-rooms.md@@ -68,15 +68,15 @@ raw token in same-origin `localStorage`; the server keeps only its digest in thecurrent room. Clearing local data or changing browser/device loses ownership.The Host browser also keeps one local creation profile containing its display-name, code-entry policy, and optional room password, plus an independent-non-secret preferred room code with a deadline equal to that room's configured-lease duration (24 hours by default). Host sharing renews it every half lease;-normal stop renews it once more. When old ownership no longer works, the next explicit-share requests the still-current preferred code and atomically reapplies the-creation profile. A free code may therefore be reused, but the result always has-a new Host token, Viewer grant, password material, lease, and room incarnation;-an occupied or expired preference falls back to random allocation. The site-access-password is never part of this profile. A Host room password may be stored locally+name, code-entry policy, and optional room password, plus one independent+non-secret preferred room code. The preference has no client-side lease, timer,+or expiry authority. When old ownership no longer works, the next explicit+share always requests that code and atomically reapplies the creation profile.+The server remains the only owner of room expiry and allocates the requested code+only when free; otherwise it selects another free code and the browser remembers+that result. Every allocation creates a new Host token, Viewer grant, password+material, server lease, and room incarnation. The site-access password is never+part of this profile. A Host room password may be stored locallyas a convenience for this private product; the server receives it only over theauthenticated creation or update path, derives the verifier, and never stores orlogs the plaintext.@@ -143,9 +143,8 @@ the generic `SERVER_ERROR`. None of those paths is folded intoinvitations. Active media already disconnects at that boundary; the additionalcost is a new room code and invitation. Same-browser Host preferences arereapplied automatically on the next explicit share.-- A room unused beyond the lease is released. The local code preference is- renewed while sharing and once on normal stop, then expires after the same- configured lease duration.+- A room unused beyond the server lease is released. The local preferred code+ remains only a future allocation hint and never extends or proves that lease.- Recycled code-only bookmarks may eventually identify a different room. A stalegrant remains unusable because the new room has a different digest.- Multi-process room coordination, seamless restart, and horizontal scaling are@@ -167,10 +166,10 @@ the generic `SERVER_ERROR`. None of those paths is folded intovalid for exactly the current room incarnation and has no independent expiry.`open` and `private` code entry, including private rooms with and without apassword, are covered independently from grant rotate/revoke.-- Same-browser recreation reapplies the Host profile and requests a current- preferred code only while it is free; another browser, cleared storage, an- expired preference, or an occupied code uses random allocation. No fingerprint- or server user record participates.+- Same-browser recreation reapplies the Host profile and always requests its+ preferred code; an occupied code uses random allocation and replaces the local+ preference. Another browser or cleared storage has no preference. No+ fingerprint, client clock, or server user record participates.- Raw site passwords, Host tokens, Viewer grants, and room passwords remain outof application/proxy logs and server durable storage.- On the accepted `screener-v12` Browser wire, a well-formed, site-authorizeddiff --git a/docs/adr/0007-path-isolated-representation-quality.md b/docs/adr/0007-path-isolated-representation-quality.mdindex 4c62d866..7bb2ffce 100644--- a/docs/adr/0007-path-isolated-representation-quality.md+++ b/docs/adr/0007-path-isolated-representation-quality.md@@ -1,8 +1,8 @@# ADR-0007: Framework-Owned Media Quality Adaptation-- Status: Accepted, implemented, and deployed+- Status: Accepted; adaptive Browser codec implementation pending- Date: 2026-08-19-- Last reviewed: 2026-08-25+- Last reviewed: 2026-08-26## Context@@ -22,9 +22,13 @@ it does not need a second bitrate, resolution, FPS, or layer-control system.## Decision-1. Browser video uses VP8 across direct, browser-relay, and SFU paths. Codec- selection, backup codecs, runtime codec switching, and codec state in the- room wire are not product features.+1. Browser video makes one internal, source-scoped codec decision. A bounded+ actual-`RTCPeerConnection` preflight measures H.264 encoded progress against+ the same source progress. A proved source prefers H.264 and retains VP8 as+ the native negotiation fallback; an unsupported, inconclusive, slow, or+ failed preflight uses VP8 only. The result is not persisted or inferred from+ UA, GPU, capability advertisement, or `powerEfficientEncoder` alone.+ Codec UI/state/wire and active-edge codec switching are not product features.2. Display video uses the standard `contentHint = "motion"`; display audio uses`contentHint = "music"`. The hint expresses content intent and does notpromise a resolution, frame rate, bitrate, encoder, or hardware path.@@ -35,20 +39,26 @@ it does not need a second bitrate, resolution, FPS, or layer-control system.After accepting an answer, the Host reapplies the current video profile tothe negotiated sender because the browser may replace or rewrite encodingparameters during negotiation.-5. The SFU publisher sets VP8, the selected HIGH ceiling, and degradation+5. Direct and Browser-relay offers with a proved source order H.264 before VP8+ in one standard codec-preference list; both endpoints select their first+ common codec without a parallel media connection. A failed source gate+ offers VP8 only. Existing edges are not renegotiated when a later relay gate+ completes; its result applies to future children.+6. The SFU publisher uses the Host source decision for its one publication,+ disables backup codec, sets the selected HIGH ceiling and degradationpreference, but does not set `screenShareSimulcastLayers`, mutate lowerencodings, or select a subscriber layer. Pinned LiveKit defaults own the- representation set and source-replacement/republish behavior.-6. LiveKit Dynacast and server send-side BWE remain enabled. AdaptiveStream+ selected codec's representation set and source-replacement/republish behavior.+7. LiveKit Dynacast and server send-side BWE remain enabled. AdaptiveStreamremains disabled because a Viewer may relay its received track to peerchildren; local DOM size or visibility cannot represent that downstreamdemand.-7. Quality measurements are diagnostic. Bitrate, resolution, FPS, RTT, jitter,+8. Quality measurements are diagnostic. Bitrate, resolution, FPS, RTT, jitter,loss, freeze counters, codec, and limitation reason do not trigger parentselection, relay abdication, periodic rebalancing, or route changes. Onlyhard connection failure, the existing non-paused decoded-frame stall, parentdeparture, or capacity invalidation can make an active edge unusable.-8. A healthy decoded route remains sticky. Manual media reconnect rebuilds the+9. A healthy decoded route remains sticky. Manual media reconnect rebuilds thecurrent exact P2P parent or current SFU subscription; it does not search fora better parent. If current-route recovery genuinely exhausts, ADR-0005'sexisting controller tries other eligible P2P parents before SFU.@@ -71,10 +81,19 @@ behavior requested for games, not a quality floor. Real-game readability,weaker Hosts, heterogeneous devices, and public-network SFU quality stillrequire physical evidence.+The exact Chrome 151/153 comparison in realtime-quality research established+why this decision is runtime-evidence driven: the cadence-failing AMD H.264 MFT+and the full-cadence NVIDIA H.264 MFT both reported hardware efficiency. Source+versus encoded-frame progress separated them. Chrome 153 then sustained the+same H.264 path with two senders, Browser relay re-encoding, and one pinned+LiveKit HIGH+LOW publication without backup codec.+## Consequences- Screener owns fewer media mechanisms and follows the pinned frameworks'supported control surfaces.+- A capable Browser Host or relay can use H.264 hardware encoding while another+ source remains on VP8 without a user setting or room-protocol branch.- A constrained Viewer may receive a lower LiveKit representation withoutlowering every subscriber, subject to the publisher and network actuallysustaining the framework contract.@@ -88,6 +107,8 @@ require physical evidence.## Stop Lines- No Screener resolution/FPS/bitrate ladder or representation formula.+- No codec selector, GPU/MFT allowlist, persistent codec cache, parallel+ VP8/H.264 route, active-edge codec churn, or LiveKit backup publication.- No manual SFU layer selector, forced single HIGH publication, or per-Viewerencoder.- No quality score, all-pairs probing, periodic rebalancing, or speculativediff --git a/docs/project-memory.md b/docs/project-memory.mdindex 1d318825..1c7bfa01 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -69,9 +69,12 @@ Last updated: 2026-08-26## Media Quality-- Browser video is VP8 only. Display video uses `contentHint = "motion"` and- display audio uses `contentHint = "music"`. Codec UI/state/wire, backup media- codecs, and runtime codec switching do not exist.+- Current source and production still use VP8 only. The accepted next Browser+ contract runs one source-scoped actual-sender preflight: proved sources prefer+ H.264 with native VP8 fallback, while failed/inconclusive sources remain+ VP8-only. Codec UI/state/wire, persistent codec cache, parallel codec media,+ backup publication, and active-edge codec switching remain absent. Display+ video uses `contentHint = "motion"` and display audio uses `contentHint = "music"`.- Windows Chrome 151 uses software VP8 and exposes no Web control for selectingNVENC, AMF, QSV, a GPU, or an MFT. Edge, non-Windows paths, and real-game CPUcontention remain evidence-specific.@@ -123,8 +126,11 @@ Last updated: 2026-08-26## Current Priority-1. Measure Browser VP8 real-game cost, then complete the mobile Viewer lifecycle- matrix and representative real-network route/media acceptance.+1. Implement and verify the accepted adaptive Browser H.264 sender gate without+ changing the deployed VP8 release, then simplify the local preferred-room+ record while retaining the server lease.+2. Complete the mobile Viewer lifecycle matrix and representative real-network+ route/media acceptance.Quality-driven parent selection, Native sender work, distribution packages,whole-product UI/bilingual polish, and repository-wide simplification remaindiff --git a/docs/research/cross-restart-room-recovery.md b/docs/research/cross-restart-room-recovery.mdindex 5531ab10..346ac30d 100644--- a/docs/research/cross-restart-room-recovery.md+++ b/docs/research/cross-restart-room-recovery.md@@ -1,8 +1,9 @@# Cross-Restart Room Recovery-Status: Research evidence for an unresolved product decision. ADR-0002 continues-to own the accepted behavior: application restart loses every room, credential,-lease, invitation, route, and media authority.+Status: Later optional persistence research. ADR-0002 continues to own the+default behavior: application restart loses every room, credential, lease,+invitation, route, and media authority. The owner accepts that default and does+not reopen persistence merely to preserve a preferred room code.## Current Boundary@@ -87,6 +88,15 @@ not a consequence of Host lineage recovery.5. Are application and LiveKit restart targets both bounded rebuild, or isLiveKit high availability a separately funded requirement?+An optional SQLite mode may reopen this decision only as one complete durable+room-authority contract, disabled by default. It would own room lineage, code,+credential digests, authorization generation, policy/password verifier and a+bounded inactive-retention fact atomically; live participants, routes, stats and+SFU resources still rebuild. Unknown future data is not justification for a+generic database. SQLite can make room identity and authorization robust across+an application restart, but it cannot preserve WebSocket, WebRTC or LiveKit+process state without client reconnect and media recommit.+## Primary Sources- [W3C Capability URLs](https://www.w3.org/TR/capability-urls/)diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex 86208920..ba621f97 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -272,14 +272,15 @@ deficit still require multi-device and real-game calibration before product use.For direct peers, native SDP negotiation can order H.264 before VP8 in one offerand choose the first codec supported by both endpoints; it does not require a-VP8 connection and a parallel H.264 connection. A research candidate is one-share-scoped Host sender preflight and one received-source-scoped Browser-relay-preflight: a proved sender prefers H.264 for future edges, otherwise it retains-VP8, and already active edges are not churned. A single SFU publication still-cannot provide per-subscriber H.264 and VP8 without a second encoded publication.-LiveKit backup codec is therefore not accepted, and an H.264 SFU publication-requires a separate decision on the supported Browser decode floor. No VP9,-AV1, H.265, product codec selector, or deployment is accepted by this evidence.+VP8 connection and a parallel H.264 connection. The accepted Browser design is+one share-scoped Host sender preflight and one received-source-scoped+Browser-relay preflight: a proved sender prefers H.264 for future edges,+otherwise it retains VP8, and already active edges are not churned. A single SFU+publication still cannot provide per-subscriber H.264 and VP8 without a second+encoded publication.+LiveKit backup codec is therefore not accepted. The Host source decision owns+that single publication: proved H.264 or VP8 fallback. No VP9, AV1, H.265,+product codec selector, or deployment is accepted by this evidence.HEVC, AV1, custom WebCodecs pipelines, and application packetization do notreplace the browser WebRTC sender without a new capture, RTP/RTCP, feedback,diff --git a/docs/status.md b/docs/status.mdindex ac24f095..0be6f064 100644--- a/docs/status.md+++ b/docs/status.md@@ -56,11 +56,14 @@ This is the current execution index. Git history owns completed timelines;## Current Milestone-1. Measure the current VP8 game-load performance bottleneck on supported Browser- Hosts; the exact Windows Chrome 151 boundary is indexed by realtime-quality- research.-2. Finish the Android Chrome and iOS Safari Viewer lifecycle matrix.-3. Finish representative public-network direct, peer-relay, SFU, recovery,+1. Implement the accepted source-scoped Browser H.264 preflight and VP8 fallback+ across direct, Browser relay, and the Host's single SFU publication. Current+ source and production remain fixed VP8 until that candidate is integrated and+ separately released.+2. Remove the client-side preferred-room expiry/renewal timer while keeping the+ server dormant lease; the explicit replace-room UI follows the codec work.+3. Finish the Android Chrome and iOS Safari Viewer lifecycle matrix.+4. Finish representative public-network direct, peer-relay, SFU, recovery,Pause/Resume, screen-audio, real-game A/V, and all-UDP-blocked acceptancewithout adding another transport or quality controller.diff --git a/docs/todo.md b/docs/todo.mdindex 5686b8a5..0fb8f067 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -7,12 +7,23 @@ later topic is not implementation authority by itself.## Now-1. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari matrices for+1. **Adaptive Browser H.264.** Implement the accepted source-scoped actual-sender+ preflight. Proved Host/relay sources prefer H.264 with native VP8 fallback;+ failed or inconclusive sources use VP8. The Host decision owns its one SFU+ publication with backup codec disabled. Add no codec UI, wire state,+ persistent cache, parallel codec route, or active-edge churn.+2. **Preferred room simplification and replacement.** Keep the server dormant+ lease unchanged, but store the latest preferred code without a client expiry+ or renewal timer. After H.264, add the Host refresh-icon action immediately+ left of copy: retire the old room through the normal lifecycle so its+ credentials, password, invitation and routes become invalid, then allocate a+ new room and update the local preference.+3. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari matrices forautoplay gesture, foreground/background audio, foreground video recovery,lock/page reclamation, rotation, Wi-Fi/cellular migration, and assigned-relaysurvival or controller recovery. Web does not promise background video orrelay execution after OS suspension.-2. **Finish real-network route and media acceptance.** Exercise direct peer,+4. **Finish real-network route and media acceptance.** Exercise direct peer,Browser relay, SFU, relay-ingress recovery with subtree retention,disconnect/capacity drain, Pause/Resume, source replacement, screen-audiocontinuity, and real-game A/V sync across representative IPv4/IPv6,@@ -57,9 +68,8 @@ later topic is not implementation authority by itself.| Item | Decision || --- | --- || Repository and distribution license | Decide before public release or package distribution. GPL/AGPL implementations remain research-only until then. |-| Adaptive Browser codec gate | Decide whether to accept one share/source-scoped H.264 sender preflight plus native H.264-to-VP8 negotiation. Chrome 153 passed direct, dual-sender, Browser-relay, and LiveKit paths on the measured NVIDIA/AMD machine while Chrome 151's selected AMD MFT failed. Probe calibration, real-game/60 fps, heterogeneous endpoints, and the single-SFU-publication codec policy remain unaccepted. |-| Cross-restart room identity and media continuity | Decide whether the target stops at Host lineage/control recovery with a fresh authority epoch or also preserves old invitations. A signed Host capsule can restore lineage but cannot combine stable old grants with strong cross-restart rotate/revoke without a small durable latest-generation truth. Media can be rebuilt with a bounded gap, not promised uninterrupted. |-| Quality-driven route exploration | First repair rendered/pause evidence, long recovered-freeze deltas, and presentation eligibility. Then confirm the freeze SLO, whether one post-commit trial plus one best-effort restore may temporarily worsen playback, how inconclusive probation settles, and whether quality work may prioritize an existing SFU publication. No active route change or relay-wide quality abdication is authorized. |+| Optional SQLite persistence | Default memory rooms remain accepted. Define the complete opt-in durable authority, stored fields, inactive retention, credential/grant rotation and recovery before implementation. It may restore rooms and authorization across restart, but media still reconnects and recommits; unspecified future data is not scope. |+| Quality-driven route exploration | The intended model includes exact-child active reparenting, relay ingress reparent with subtree retention, relay egress abdication/drain, and Host egress convergence onto one SFU publication while SFU-fed Viewers may still relay. Research must first unify their evidence, reservations, probation/restore and recovery under the existing single graph/operation; no active quality route change is authorized yet. |## Evidence Boundariesdiff --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 71d6a6d6..4331dc57 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"@@ -80,7 +80,7 @@ code-only policy 使用单一 `open | private` 状态:`open` 是无房间密房间准入管理统一使用同源 `POST /api/rooms/{roomId}/access`:site-access cookie 与 `Authorization: Bearer {hostToken}` 共同授权一个受 schema 约束的 policy、password、rotate 或 revoke 动作。该控制面在分享活动和休眠期间语义相同,不建立 Host participant/WebSocket/media route,不改变 `sharingActive` 或 dormant lease;rotate/revoke 的现有强撤销副作用保持不变。-Host 的同源 `localStorage` creation profile 保存显示名、code-only policy 和可选房间密码,使进程重启或租约过期后的下一次显式分享可原子应用同一偏好。建房响应同时返回实际 `roomLeaseSeconds`;Host ownership 保存该值,独立的 preferred-room 记录保存上次四位号码和 `preferenceExpiresAt`。Host 鉴权分享时立即写 `now + roomLeaseSeconds`,并以半个租期为 interval 低频续写;正常停播再写一次,资源释放和页面卸载停止 interval。清除失效 ownership 不清除仍有效的号码偏好。该密码只保存在 Host 浏览器;不保存在 Viewer 浏览器、URL/query/fragment、cookie、日志、错误或服务器持久存储。建房/更新请求通过 HTTPS 把明文短暂交给服务端,服务端使用 Node 标准异步 `scrypt` 固定 `N=16384,r=8,p=1`、16-byte 随机 salt 和 32-byte verifier,只在当前房间内存保存 48-byte material。进程级 gate 最多执行 2 个、等待 16 个派生,队满即有界失败;任务开始和提交前都复核当前 Host authority 与 room material。不存在、已回收或已过期房间使用 `ROOM_NOT_FOUND`;现存房间的未配置/错误密码和正确密码后的满房使用 `ROOM_ACCESS_DENIED`。+Host 的同源 `localStorage` creation profile 保存显示名、code-only policy 和可选房间密码,使进程重启或租约过期后的下一次显式分享可原子应用同一偏好。建房响应仍返回实际 `roomLeaseSeconds` 并仅由 Host ownership/服务端房间生命周期使用;独立 preferred-room 记录只保存上次实际分配的四位号码,不保存时间、不运行续写 interval,也不证明或延长服务端租期。旧 ownership 过期/失效后始终请求该号码,服务端只在空闲时采用,否则随机分配并让客户端覆盖本地偏好。该密码只保存在 Host 浏览器;不保存在 Viewer 浏览器、URL/query/fragment、cookie、日志、错误或服务器持久存储。建房/更新请求通过 HTTPS 把明文短暂交给服务端,服务端使用 Node 标准异步 `scrypt` 固定 `N=16384,r=8,p=1`、16-byte 随机 salt 和 32-byte verifier,只在当前房间内存保存 48-byte material。进程级 gate 最多执行 2 个、等待 16 个派生,队满即有界失败;任务开始和提交前都复核当前 Host authority 与 room material。不存在、已回收或已过期房间使用 `ROOM_NOT_FOUND`;现存房间的未配置/错误密码和正确密码后的满房使用 `ROOM_ACCESS_DENIED`。邀请使用 `/r/{roomId}#v={grant}`。RFC 3986 要求 fragment 在 dereference 前由 user agent 分离,因此 HTTP request-target 与反向代理 access log 看不到它;WHATWG WebSocket 还明确拒绝含 fragment 的 URL。客户端只从页面 URL 严格解析一次,把 grant 写入 `screener:viewer-grant:{roomId}` 的 `sessionStorage`,随即以 `history.replaceState` 把地址栏替换为 canonical `/r/{roomId}`;刷新和页面内 WSS 重连继续使用该页面会话的值。Host 建房/rotate 收到的 raw grant 同样只在内存和 room-scoped `sessionStorage` 中保留,用它临时构造复制链接;`localStorage` 的 room ownership 只包含 canonical URL、room ID、Host token 和期限。grant 不进入 cookie、query、WebSocket URL、Referrer、日志或错误。生产继续发送 `Referrer-Policy: no-referrer`;fragment 与该 header 降低传输泄漏,但不能防止原邀请消息、浏览器扩展、截图或用户转发,UI 必须把链接称为访问凭据。@@ -104,7 +104,7 @@ rotate/revoke 是 grant 路径的强撤销:服务端先同步提交新 digest/Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,Viewer 也可显式订阅同一 participant snapshot;Native sender 不在 accepted Browser wire 内并在 authority 前拒绝。两端可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的 Web participant 发送完整 `viewer-presence` snapshot,列表严格来自当前带 sessionId 的在线参与者,不含五秒媒体恢复 grace 成员;条目用 `role` discriminator 区分 Host/Viewer。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”Viewer 总数只取 Viewer 条目数;最多两条本机媒体快照只补充当前以 Host 为 active upstream 的连接指标。-每个 presence 条目包含 `role`、`peerId`、`displayName` 和服务端 active assignment 的精确 `upstream`:Host 为 `none`,Viewer 为 `none | peer(peerId) | sfu`。UI 默认只展示名称;房内出现同名时,仅为同名项追加 peerId 尾部至少六字符短后缀,并只在同名项后缀碰撞时逐字符有界延长至完整 peerId。卡片状态只依据本机连接或当前 Viewer 接收证据显示“已连接”,否则保持中性的“线路分配中”或具体连接状态;active assignment 本身不是连接成功证据。Host 对 direct、Peer 转发和 SFU Viewer 使用完全相同的卡片结构,不生成 SFU 分组或 Host publication 伪 Viewer。连接详情同样等待当前媒体证据,再显示绿色 `P2P` 或黄色 `SFU fallback`;每张卡优先使用该 Viewer 回报的实际接收指标,Host 直连发送快照只在尚无回报时提供同结构回退。一级固定为分辨率、帧率、码率和丢包,二级按方向只渲染当前有值的 RTT、jitter、冻结/丢帧、解码耗时、音频播放质量,或捕获/编码输入、编码耗时、编码器与质量限制。固定 VP8/Opus 不显示;实际 codec 偏离产品合同时在卡片内提示。候选地址、候选对 ID、STUN 计数、RID、fmtp、常规 sender 请求/读回和其他内部标识不渲染。Viewer 接收证据由服务端绑定当前 `viewer/upstream/connection/route revision`:Peer 子边只送达其直接父节点及 Host,SFU 接收只送达 Host;因此 SFU Viewer 继续带 Peer 子节点时,两名 Viewer 的证据仍各自归属,不逐层转发或互相冒充。Host 与 Viewer 都可通过独立拓扑按钮从 authoritative assignment snapshot 展示 Host、实际存在的 SFU 节点及精确上下游;Viewer 默认收起并放在视频下方,没有当前 Host presence 时不生成占位拓扑。拓扑不把计划线路当作连接成功,也不显示 IP 或唯一名称对应的 peerId。peerId 不因此成为授权身份或路由输入;名称、presence 与拓扑视图不改变授权、媒体或路由状态机。+每个 presence 条目包含 `role`、`peerId`、`displayName` 和服务端 active assignment 的精确 `upstream`:Host 为 `none`,Viewer 为 `none | peer(peerId) | sfu`。UI 默认只展示名称;房内出现同名时,仅为同名项追加 peerId 尾部至少六字符短后缀,并只在同名项后缀碰撞时逐字符有界延长至完整 peerId。卡片状态只依据本机连接或当前 Viewer 接收证据显示“已连接”,否则保持中性的“线路分配中”或具体连接状态;active assignment 本身不是连接成功证据。Host 对 direct、Peer 转发和 SFU Viewer 使用完全相同的卡片结构,不生成 SFU 分组或 Host publication 伪 Viewer。连接详情同样等待当前媒体证据,再显示绿色 `P2P` 或黄色 `SFU fallback`;每张卡优先使用该 Viewer 回报的实际接收指标,Host 直连发送快照只在尚无回报时提供同结构回退。一级固定为分辨率、帧率、码率和丢包,二级按方向只渲染当前有值的 RTT、jitter、冻结/丢帧、解码耗时、音频播放质量,或捕获/编码输入、编码耗时、编码器与质量限制。正常协商的 H.264/VP8 与 Opus 不显示;实际 codec 超出 accepted contract 时在卡片内提示。候选地址、候选对 ID、STUN 计数、RID、fmtp、常规 sender 请求/读回和其他内部标识不渲染。Viewer 接收证据由服务端绑定当前 `viewer/upstream/connection/route revision`:Peer 子边只送达其直接父节点及 Host,SFU 接收只送达 Host;因此 SFU Viewer 继续带 Peer 子节点时,两名 Viewer 的证据仍各自归属,不逐层转发或互相冒充。Host 与 Viewer 都可通过独立拓扑按钮从 authoritative assignment snapshot 展示 Host、实际存在的 SFU 节点及精确上下游;Viewer 默认收起并放在视频下方,没有当前 Host presence 时不生成占位拓扑。拓扑不把计划线路当作连接成功,也不显示 IP 或唯一名称对应的 peerId。peerId 不因此成为授权身份或路由输入;名称、presence 与拓扑视图不改变授权、媒体或路由状态机。## 信令协议@@ -137,7 +137,7 @@ accepted 的唯一 wire 是 `screener-v12`,不做版本协商、旧 parser、分享者是唯一 offerer。每名观看者对应一个 `RTCPeerConnection`,以独立 `connectionId` 区分重建代次:1. 分享者在开始按钮的同一用户手势内先成功调用 `getDisplayMedia()`。-2. 只有捕获 track 已存在时才请求创建或续租房间、连接 Host WebSocket 并显示邀请。新建请求携带本地 creation profile 和仍有效的 preferred room,使 code-only policy、可选密码 verifier 与号码分配在房间可见前原子生效;偏好号码已占用时服务端直接随机分配。若用户在响应返回前取消,迟到结果不得覆盖后续分享会话,尚未认领的房间通过内部 `abandon-room` 立即释放号码。已经认领的房间在停止捕获后进入 dormant lease,过期才释放。+2. 只有捕获 track 已存在时才请求创建或续租房间、连接 Host WebSocket 并显示邀请。新建请求携带本地 creation profile 和 preferred room,使 code-only policy、可选密码 verifier 与号码分配在房间可见前原子生效;偏好号码已占用时服务端直接随机分配并返回新的本地偏好。若用户在响应返回前取消,迟到结果不得覆盖后续分享会话,尚未认领的房间通过内部 `abandon-room` 立即释放号码。已经认领的房间在停止捕获后进入服务端 dormant lease,过期才释放;本地 preferred room 不参与该 lease。3. 观看者认证后,服务端向在线分享者发送 `peer-joined`;host 晚上线或重连时收到完整观看者快照。4. 分享者创建连接、加入当前视频 track,并以现有音轨或空 sender 预留 audio transceiver,设置 sender 参数,然后创建 offer。5. 观看者收到 offer 后创建连接、设置 remote description、创建 answer。@@ -162,7 +162,7 @@ accepted 的唯一 wire 是 `screener-v12`,不做版本协商、旧 parser、每次 `setParameters()` 都必须从当次 `getParameters()` 派生更新,然后读回 requested/applied `maxBitrate`、`maxFramerate`、`scaleResolutionDownBy` 和 degradation preference。浏览器负责具体降级,实际结果由 stats 观测;拒绝或浏览器改写必须进入可见状态,不能只写 `console.warn`。-Accepted `screener-v12` Web 视频固定使用 `VP8`。P2P 与 browser relay 在首次 offer 前只保留 VP8 media capabilities 及 RTX/RED/FEC repair capabilities;无法应用该约束时明确失败,不静默协商另一媒体 codec。SFU publication 显式使用 VP8 且关闭 backup codec。所有新 Web peer sender 与 SFU publication 保留 `motion` 和用户选择的分辨率、帧率及码率 ceiling;当 desired degradation preference 允许分辨率下降时,启动阶段的 effective preference 暂为 `maintain-resolution`,当前 sender 累计编码至少五帧后由既有 stats 路径一次性应用 desired preference。该切换使用标准 `setParameters()` 进入或离开 balanced 时的原生 restriction reset,不增加 timer、周期重写、质量评分或应用层调档器。UI、quality state/wire 和分享生命周期均没有 codec 分支;实际 outbound codec/profile、encoder implementation 与 stats 是只读结果真相。应用 SDP 变换边界仍只有 Viewer answer 的 Opus stereo receive preference。+Accepted `screener-v12` Web 视频使用页面内 source-scoped H.264/VP8 决策。初始 Host capture 在取得 room/route authority 前,以一对无 ICE server 的本地标准 `RTCPeerConnection` 运行一个有界 H.264-only sender probe;只用实际协商 codec、同一身份的 media-source/encoded progress 与 bounded completion 判断,不读取 UA/GPU/MFT allowlist,也不单独相信 capability 或 `powerEfficientEncoder`。成功结果让后续 P2P/browser-relay offer 按浏览器原生 H.264 capability 顺序列出 H.264,再列 VP8 与 RTX/RED/FEC repair capabilities;失败或 inconclusive 只列 VP8 与 repair。Relay 收到新 upstream stream 后在后台运行同一 gate,完成前建立的 child 使用 VP8,完成后只影响未来 child。无法应用 codec preferences 或缺少 VP8 时明确失败。SFU publication 使用 Host source 当时的同一 H.264/VP8 决定并关闭 backup codec。所有新 Web peer sender 与 SFU publication 保留 `motion` 和用户选择的分辨率、帧率及码率 ceiling;当 desired degradation preference 允许分辨率下降时,启动阶段的 effective preference 暂为 `maintain-resolution`,当前 sender 累计编码至少五帧后由既有 stats 路径一次性应用 desired preference。该切换使用标准 `setParameters()` 进入或离开 balanced 时的原生 restriction reset,不增加周期重写、质量评分或应用层调档器。UI 和 quality state/wire 没有 codec 字段;gate 结果不持久化、不改写已连接 edge,实际 outbound codec/profile、encoder implementation 与 stats 是只读结果真相。应用 SDP 变换边界仍只有 Viewer answer 的 Opus stereo receive preference。Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`autoGainControl` 和 `voiceIsolation`,并以 `channelCount: { ideal: 2 }` 偏好双声道;这是当前 Chrome/Edge Host 基线的实现契约,用于避开网页 `getDisplayMedia()` 默认的语音处理和单声道 APM 候选,不宣称跨浏览器保证,也不固定采样率。所有值都是非强制 post-selection preference;不使用 `exact`、`min` 或 `advanced`。若 `getAudioTracks()` 为空,分享者界面必须显示“当前来源没有可共享音频”。Web 端同时传入 `windowAudio: "window"` 与 `systemAudio: "include"`:窗口选项请求该窗口/应用音频,整个屏幕选项允许用户勾选系统音频;标签页使用浏览器自身的标签页音频选择。浏览器可以忽略这些约束或 picker hints,且没有对应的标准来源类型读回,因此 UI 不额外推断或标注来源。系统音频由用户显式选择,可能包含语音或通知;video-only 始终可用。@@ -172,11 +172,11 @@ Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`直播中切换来源仍由明确的按钮手势重新调用 `getDisplayMedia()`,不改变房间、host generation 或媒体拓扑。选源取消或失败时继续发送旧流;成功后为每个现有 sender 调用 `replaceTrack()`,健康连接不重新协商。初始 offer 预留 send-only audio transceiver,使音频可以在 `null -> track -> null` 间切换。若某个 peer 的替换或回滚失败,只重建该 peer;新流提交后才停止旧流,并以当前 stream 身份保护旧 track 的迟到 `ended` 事件。统计码率累加器在换源后重置,避免把不同 track 的计数器混算。-直播中切换质量不重新打开选源器:对当前视频 track 调用 `applyConstraints()`,再更新所有现有 sender 的参数;quality mutation 不含 codec,新加入或重建的 Browser sender 仍使用固定 VP8 与最新其他权威设置。失败时保留当前分享并给出状态,不以重建整个房间补偿。临时暂停禁用当前 capture stream 的全部音视频 tracks;Host 通过当前 session 与 `shareGeneration` 发送一个 paused boolean,服务端同步 `host-status`、route pause 与 `authenticated` 快照,Viewer 在舞台显示“分享者已暂停”。Resume 使用同一状态更新并重新启用同一批 tracks,不另设 authorization、source acknowledgement 或 proof。晚加入和信令重连从快照恢复,恢复、停止、新分享或会话替换清除旧状态;不得把 track mute、黑帧或网络停顿推断成主动暂停。房间与连接保持不变。+直播中切换质量不重新打开选源器:对当前视频 track 调用 `applyConstraints()`,再更新所有现有 sender 的参数;quality mutation 不重新运行 codec gate,新加入或重建的 Browser sender 使用当前 source 的内存结果与最新其他权威设置。失败时保留当前分享并给出状态,不以重建整个房间补偿。临时暂停禁用当前 capture stream 的全部音视频 tracks;Host 通过当前 session 与 `shareGeneration` 发送一个 paused boolean,服务端同步 `host-status`、route pause 与 `authenticated` 快照,Viewer 在舞台显示“分享者已暂停”。Resume 使用同一状态更新并重新启用同一批 tracks,不另设 authorization、source acknowledgement 或 proof。晚加入和信令重连从快照恢复,恢复、停止、新分享或会话替换清除旧状态;不得把 track mute、黑帧或网络停顿推断成主动暂停。房间与连接保持不变。Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。后台性能诊断必须把 Host 页面前台/遮挡/最小化、被捕获 source 前台/遮挡/最小化以及 preview 播放/暂停分成独立变量,并关联 document visibility/focus、track mute/readyState 与 capture/outbound/inbound stats。页面 timer、伪活跃和 Screen Wake Lock 都不构成屏幕捕获保活方案;若标准浏览器无法维持目标行为,应记录平台能力边界而不是制造第二套 lifecycle。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。-codec 与 content-hint 依据由研究文档持有。`motion` 会改变 Chromium/libwebrtc 的适配取舍并可能空间降级以保留游戏动态;它是标准内容意图,不是分辨率或帧率保证。产品不再用 unset hint 固定 screen-classified 行为,也不围绕某次测量实现应用缩放器。普通 AMD H.264 MFT 的浏览器码控仍丢帧,而诊断性 Desktop SW BRC 可恢复约 30 fps,说明问题不等于硬件编码器本身的吞吐上限;网页没有启用该浏览器进程开关或选择具体 GPU/MFT 的 API。实际 codec 与 encoder 字段只用于诊断,不触发 codec 切换。VP8 hardware acceleration 需要后续按目标浏览器和真实游戏负载单独取证;本设计不假定其存在,也不增加替代 codec 或自定义编码路径。+codec 与 content-hint 依据由研究文档持有。`motion` 会改变 Chromium/libwebrtc 的适配取舍并可能空间降级以保留游戏动态;它是标准内容意图,不是分辨率或帧率保证。产品不再用 unset hint 固定 screen-classified 行为,也不围绕某次测量实现应用缩放器。Chrome 151 的普通 AMD H.264 MFT 即使报告 hardware efficiency 仍持续丢帧,而 Chrome 153 的 NVIDIA H.264 MFT、双 sender、Browser relay 与 LiveKit publication 均维持源 cadence,证明 capability、实现名称或单一硬件标志都不能替代实际 source/encoded progress。网页不启用浏览器进程开关或选择具体 GPU/MFT;gate 只选择 H.264-first 或 VP8-only 的标准协商输入,不控制实际 encoder。VP8 hardware acceleration 仍是证据特定事实;本设计不增加 VP9/AV1/H.265、自定义编码路径或转码。`track.getSettings()` 中存在的 EC/NS/AGC/voice-isolation、`channelCount` 和 `sampleRate` 只能作为当前捕获观测;缺失字段保持未知,Opus 协商仍是独立事实。每个 Web Host 或浏览器 relay 的实际音频 sender 在首次绑定和换源后通过标准 `RTCRtpSender.setParameters()` 请求并读回当前 96/128/192 kbps ceiling;这只是上限,浏览器 WebRTC 拥塞控制仍可降低实际流量,不新增应用层音频降级器。96 kbps 普通是默认 ceiling;128 kbps 音乐和 192 kbps 保真由用户显式选择,均不是最低码率或质量保证。Peer answer 声明 `stereo=1;maxaveragebitrate=192000`,让同一接收协商覆盖所有三档,实际 sender ceiling 仍由所选档位约束;普通 PC synthetic 不用于标定参数、听感或性能。@@ -188,7 +188,7 @@ Viewer 本地连接详情只从当前 route 的唯一 inbound screen video/audio`frameRate` 约束和 sender 的 `maxFramerate` 都是目标或上限;浏览器仍控制实际捕获、重复帧处理、编码和拥塞降级。静态画面可能由浏览器减少实际编码数据,但标准没有保证每个实现以同一种方式节省采集或 GPU 开销。本 PoC 不添加画面差分、定时改约束或自定义动态 FPS 状态机,先用 `framesEncoded`、实际发送码率、`totalEncodeTime`、质量受限原因和主机资源占用测量真实问题。-质量自适应采用 ADR-0007 的框架所有权,而不是全房间按最差链路降档。Direct/peer 保留每条 PeerConnection 的 stock WebRTC GCC。Browser Host 的唯一 SFU publication 不手写层列表,由锁定的 LiveKit client 默认行为拥有 VP8 screen-share representations、source replacement 与 republish。LiveKit Dynacast 和启用 send-side BWE 的 server stream allocator 独立处理聚合需求与每个 subscriber 的实际下行层,订阅端最高质量请求只是上限。Screener 不实现质量评分、带宽估计、周期调档或应用媒体层 selector。当前任一 Viewer 都可能承担 peer children,因此 subscriber 统一保持 `adaptiveStream: false`,relay ingress 不跟随本地 DOM 可见性。Pinned gate 证明了 LiveKit 原生空间选择和 Dynacast 能力,但具体 representation 参数仍属于 pinned component,而不是 Screener 产品常量。+质量自适应采用 ADR-0007 的框架所有权,而不是全房间按最差链路降档。Direct/peer 保留每条 PeerConnection 的 stock WebRTC GCC。Browser Host 的唯一 SFU publication 不手写层列表,由锁定的 LiveKit client 默认行为拥有所选 H.264 或 VP8 的 screen-share representations、source replacement 与 republish。LiveKit Dynacast 和启用 send-side BWE 的 server stream allocator 独立处理聚合需求与每个 subscriber 的实际下行层,订阅端最高质量请求只是上限。Screener 不实现质量评分、带宽估计、周期调档或应用媒体层 selector。当前任一 Viewer 都可能承担 peer children,因此 subscriber 统一保持 `adaptiveStream: false`,relay ingress 不跟随本地 DOM 可见性。Pinned gate 证明了 LiveKit 原生空间选择和 Dynacast 能力,但具体 representation 参数仍属于 pinned component,而不是 Screener 产品常量。质量证据只用于诊断,不形成全房分数或 parent authority。路由只消费 exact child edge 的 `failed/closed` 和非暂停 decoded-frame stall。prepare/commit/abort 绑定 authenticated sessions、share generation、base/pending revision 与 candidate connection;candidate child 的第一帧新 decoded video 是唯一应用层 media-ready,ICE connected 不能单独提交。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 907190ee..1096f58e 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"@@ -17,7 +17,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap### P0 - 必须实现- 首屏双入口:分享入口通过站点访问后,主工作区必须同等突出“开始分享”和“加入房间”两个主要动作,并用清楚的视觉分隔表达发送与接收;持合法房间 grant 的观看者不需要知道站点访问密码。“加入房间”在当前舞台内就地展开房间码输入并提交,不先跳转到独立页面;直接访问 `/join` 仍提供同一输入能力。不增加营销首页、模式向导或拓扑选择。浏览器标签页使用与现有 `MonitorUp` 品牌语言一致的 favicon。-- 简单房间:分享者从当前空闲池随机获得一个 `1000` 至 `9999` 的四位房间码,房间码只负责定位,不是秘密或永久身份。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作;每个新房默认生成含独立 Viewer grant 的完整邀请链接,Host 的主分享动作复制该链接。房间号入口只有公开和私密两种状态;新房默认公开,允许已通过站点访问的 Viewer 直接用房间号加入且不设房间密码。私密且未设置密码时只有有效邀请可加入;设置密码后才额外允许房间号加密码加入。邀请链接与房间号准入相互独立。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。+- 简单房间:分享者从当前空闲池随机获得一个 `1000` 至 `9999` 的四位房间码,房间码只负责定位,不是秘密或永久身份。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作;Host 的复制按钮左侧保留一个申请新房间号的刷新图标动作。该动作销毁旧房间并走同一回收流程,使旧 Host token、密码 verifier、Viewer grant、授权代次和媒体路由全部失效,再按普通建房流程取得新号码。每个新房默认生成含独立 Viewer grant 的完整邀请链接,Host 的主分享动作复制该链接。房间号入口只有公开和私密两种状态;新房默认公开,允许已通过站点访问的 Viewer 直接用房间号加入且不设房间密码。私密且未设置密码时只有有效邀请可加入;设置密码后才额外允许房间号加密码加入。邀请链接与房间号准入相互独立。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。- 免安装观看:桌面和手机观看者可直接通过浏览器链接进入、授权并播放,不依赖与分享端相同的桌面客户端。- 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时同步暂停音视频和切换分享来源;暂停保留现有连接并禁用当前 capture stream 的全部媒体轨道。服务端按当前分享代次同步这一主动暂停状态,观看端在视频舞台显示“分享者已暂停”,不得从黑帧、track mute 或网络状态推断暂停;晚加入和信令重连使用权威快照,恢复、停止、新分享或会话替换清除旧提示。Host 本地预览必须直接使用 capture stream;页面失焦或隐藏时只暂停本地 video element,并明确提示“本地预览已暂停,分享仍在继续”,恢复焦点后继续预览,不得停止 capture、编码或上行。预览不得建立 viewer/媒体边或消耗 SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。- 游戏声音:Windows Chrome/Edge 的初次分享和切换来源都默认请求可用的标签页、窗口或系统音频;浏览器、系统、所选来源或用户没有返回音轨时必须明确提示,而不是静默无声或阻止 video-only 分享。@@ -27,17 +27,17 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Browser Host 与 Viewer 严格校验该值并用它约束稳态 assignment;并行产生媒体的 candidate 必须持有唯一 `TransitionOverlapSlot`,active+pending 物理 copy 只可达到 `min(C + 1, 3)` 并在 commit/abort 后释放。`C=3` 满载时必须先收到 active bounded-gap retirement 再 prepare,绝不产生第四份 copy。SFU subscriber egress 由独立 server admission 记账。当前不兼容房间合同以单一 release 原子升级;缺失/非法 cap、旧 wire 与 executable sender都在取得room/route authority前fail closed。- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。Host 已满且首次需要 SFU 时,同一 controller 用有限 carrier cursor 建立唯一 publication;carrier 必须能在既有 overlap 上限内完成,不能先切断健康分支。终态归原始等待需求,publication 成功后该需求先取得 SFU 画面,剩余 direct candidate 再在后台收敛;完整事务由 ADR-0005 定义。- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。Browser LiveKit publisher/subscriber PC 必须显式使用空 `iceServers`,保留 LiveKit signaling 交付的授权 SFU UDP candidates,并由标准 ICE 选择 nominated non-relay pair;不得把 ordinary-peer STUN、LiveKit join response 中的 STUN 或默认公共 STUN混入该 PC,也不得把某一种 candidate type 或数量写成成功条件。部署 STUN 仍供 ordinary peers 和 LiveKit server-side 公网地址发现使用。浏览器 ICE connectivity checks 是 direct UDP 可达性的权威;Screener 不合成 remote candidate、不预测端口、不分类 NAT,也不使用 TCP 探测推断 UDP 媒体可达性。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,direct 阶段耗尽后在同一 operation deadline 内进入 SFU/UDP,全部可用路径耗尽后明确等待或失败。已接受的完整顺序只有保持或尝试 direct/STUN peers,再复用或建立 direct-ingress Host publication/SFU subscription。Screener 不配置 TURN、ICE/TCP、media TCP 或 TLS-relayed media;当前 LiveKit 也保持 UDP-only。未来若真实严格防火墙矩阵证明需要另一种传输,必须把它作为 LiveKit 内部能力重新决策,不能增加第三种应用 route candidate。LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target;HTTPS/WSS 继续独立使用 TLS/TCP。-- 质量控制:推荐档位始终只有 720p30(3 Mbps)、1080p30(5 Mbps)、1080p60(8 Mbps)三档,默认选择中档 `1080p30`。高级设置的分辨率选项增加 `480p`(854x480),其 FPS 与码率仍由高级控件独立选择;不增加 `480p` 推荐档、preset ID 或固定的 480p FPS/码率组合。三档与高级设置初始值统一采用中档 `balanced`(均衡),`maintain-resolution`(清晰)、`maintain-framerate`(流畅)保留为显式选择。Browser 视频固定使用 VP8;界面、质量状态和 wire 不提供 codec 选择或切换。分享期间可直接换视频档位和 64/128/192 kbps 音频 sender ceiling,音频默认选择中档 128 kbps,不重新选择来源或重建健康连接。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由 WebRTC/LiveKit 决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。Host 资源不足时由 Host 主动选择较低的现有档位。Screener 不设置自定义 SFU layer list、动态 FPS、综合评分或周期性全房间调档。-- 路径隔离表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 Viewer 反馈合成全房目标。Browser Host 的唯一 SFU publication 不设置 `screenShareSimulcastLayers`,由锁定的 LiveKit client 默认行为拥有 VP8 screen-share representations、source replacement 与 republish;LiveKit Dynacast 和启用 send-side BWE 的 server stream allocator 负责需求聚合与每个 subscriber 的实际下行层。Screener 不实现质量评分、带宽估计、周期调档或应用媒体层 selector。所有当前 Viewer 都可能承担 peer children,因此 subscriber 保持 `adaptiveStream: false`,不得让本地元素尺寸或可见性控制 relay ingress。表示选择不改变拓扑、端点容量或路由失效权威。+- 质量控制:推荐档位始终只有 720p30(3 Mbps)、1080p30(5 Mbps)、1080p60(8 Mbps)三档,默认选择中档 `1080p30`。高级设置的分辨率选项增加 `480p`(854x480),其 FPS 与码率仍由高级控件独立选择;不增加 `480p` 推荐档、preset ID 或固定的 480p FPS/码率组合。三档与高级设置初始值统一采用中档 `balanced`(均衡),`maintain-resolution`(清晰)、`maintain-framerate`(流畅)保留为显式选择。Browser 对每个新分享 source 运行一次有界实际 sender 预检;H.264 源帧与编码帧进度通过时,未来 direct/relay offer 原生排序 H.264 后接 VP8,Host 的唯一 SFU publication 也使用 H.264;不支持、证据不足、超时或表现不达标时只使用 VP8。界面、质量状态和 wire 不提供 codec 选择,结果不持久化,也不切换已连接线路。分享期间可直接换视频档位和 64/128/192 kbps 音频 sender ceiling,音频默认选择中档 128 kbps,不重新选择来源或重建健康连接。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由 WebRTC/LiveKit 决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。Host 资源不足时由 Host 主动选择较低的现有档位。Screener 不设置自定义 SFU layer list、动态 FPS、综合评分或周期性全房间调档。+- 路径隔离表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 Viewer 反馈合成全房目标。Browser Host 的唯一 SFU publication 不设置 `screenShareSimulcastLayers`,由锁定的 LiveKit client 默认行为拥有当前 H.264 或 VP8 source decision 对应的 screen-share representations、source replacement 与 republish;LiveKit Dynacast 和启用 send-side BWE 的 server stream allocator 负责需求聚合与每个 subscriber 的实际下行层。Screener 不实现质量评分、带宽估计、周期调档或应用媒体层 selector。所有当前 Viewer 都可能承担 peer children,因此 subscriber 保持 `adaptiveStream: false`,不得让本地元素尺寸或可见性控制 relay ingress。表示选择不改变拓扑、端点容量或路由失效权威。- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时现有 periodic stats 在统一 deadline 内没有新 decoded frame 时,使自己的 exact edge 失效并唤醒同一个 reconcile。decoded progress 只保存 route-keyed `lastDecodedAt`,route/connection变化或新帧重置、暂停抑制,同一 edge只报告一次,不增加轮询器。Active SFU route 暂时没有 video track、stats report 为空或 stats 读取失败时,现有采样 cadence 仍把该次作为无 decoded progress 推进 deadline;它不得停表、伪造连接指标或立即判定 edge 失效,只有 route 停用或 teardown 才停止该 cadence。该 operation 把失败的 exact direct parent 在当前 fact version 视为已尝试;foreground direct window结束后用SFU取得可用画面,剩余direct candidate只在画面后方收敛,新的外部事实才允许本轮失败tuple重新进入。Track availability、低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer只用于stock WebRTC/LiveKit恢复和诊断。relay自身ingress失效时,它作为child换父并保留subtree;disconnect或effective downstream capacity降低只让direct/overflow children逐个走同一事务。- 断线恢复:临时网络变化先交给 WebRTC/LiveKit 的 ICE、consent、重连和流状态。Direct edge 可在 exact current parent/child sessions 内采用 framework rebuild 的新 connection ID而不改变topology。应用只在上述exact edge失效后运行一次有界reconcile;任一步成功即停止。候选耗尽时hard-invalid、confirmed-departed或overflow edge被退休并进入明确waiting,healthy bootstrap edge保留。所有异步结果受authenticated session、share generation、base/pending route revision与candidate connection identity约束,未受影响分支保持sticky。权威暂停abort未提交candidate、保留active graph、抑制stall,并在resume后重新reconcile。- 每名 child 只有一个有界 operation deadline;foreground direct 预算、SFU 可用性优先和后台 direct 收敛由 ADR-0005 的同一 cursor 模型定义,不配置逐 candidate timeout。Exact direct 的标准WebRTC transport-connected只把当前wake延长到该总deadline,不提交graph;第一解码帧仍是唯一commit证据。20 名 Viewer 同时加入时,单一 room-serial operation 仍可能形成线性排队尾延迟;在接受另一种并发模型前,只测量 queue wait、candidate start、first decoded frame 与 final route 的 p50/p95/max,不用 NAT 猜测、TCP probe 或 magic timeout 绕过排队。- 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选、route decision、队列时序与错误的 wire 和日志使用封闭 schema 和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText`、真实 peer/parent/session/connection identity 或网络标识。Host 与 Viewer 产品 UI 不提供连接诊断文件下载;本地折叠详情只显示当前页面直接观测到的连接事实。现有 Host-only bounded route snapshot 保留给自动验收,不连续推送、不进入产品 UI、也不形成 route authority。只有创建该 `RTCPeerConnection` 的本机可显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。-- 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 对每名 Viewer 使用同一种卡片,不按 direct、Peer 转发或 SFU 分组。卡片只把本机连接或当前 Viewer 接收证据称为“已连接”,其余状态保持中性的“线路分配中”或具体连接状态,不把 active assignment 当作连接成功。展开连接详情也只在当前媒体证据成立后显示绿色 `P2P` 或黄色 `SFU fallback`;一级只保留分辨率、帧率、码率和丢包等一眼可读的实际画面结果,二级只显示当前确有值且能解释网络、编解码或播放质量的指标。固定的 VP8/Opus 不常驻展示,只在实际协商偏离产品合同时提示;候选地址、候选对 ID、STUN 计数、RID、fmtp 和其他浏览器内部标识不进入产品 UI。Host/Peer/SFU 的精确上下游与分支结构只由独立权威拓扑视图表达,不在卡片内重复。远端 Viewer evidence 的详情 shell 在同一 viewer/upstream/connection/route identity 内保持稳定并保留每个字段最后一次真实非空观测;五秒 freshness 只决定 evidence 能否继续证明“已连接”,`connecting`/`disconnected` 立即降为非 fresh,`failed`/`closed`、identity/session/share/route 变化或非单调 sequence 则清空/换代。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限、编码合同偏离或需要用户操作的告警。+- 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 对每名 Viewer 使用同一种卡片,不按 direct、Peer 转发或 SFU 分组。卡片只把本机连接或当前 Viewer 接收证据称为“已连接”,其余状态保持中性的“线路分配中”或具体连接状态,不把 active assignment 当作连接成功。展开连接详情也只在当前媒体证据成立后显示绿色 `P2P` 或黄色 `SFU fallback`;一级只保留分辨率、帧率、码率和丢包等一眼可读的实际画面结果,二级只显示当前确有值且能解释网络、编解码或播放质量的指标。正常协商的 H.264/VP8 与 Opus 不常驻展示,只在实际 codec 超出 accepted H.264/VP8 contract 时提示;候选地址、候选对 ID、STUN 计数、RID、fmtp 和其他浏览器内部标识不进入产品 UI。Host/Peer/SFU 的精确上下游与分支结构只由独立权威拓扑视图表达,不在卡片内重复。远端 Viewer evidence 的详情 shell 在同一 viewer/upstream/connection/route identity 内保持稳定并保留每个字段最后一次真实非空观测;五秒 freshness 只决定 evidence 能否继续证明“已连接”,`connecting`/`disconnected` 立即降为非 fresh,`failed`/`closed`、identity/session/share/route 变化或非单调 sequence 则清空/换代。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限、编码合同偏离或需要用户操作的告警。- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}` 和 `/join` 必须先持有效 site-access cookie,之后才检查房间是否存在与 `open | private` code-only policy。未分配、已回收或已过期的 code 返回 `ROOM_NOT_FOUND`;现存私密房间的无密码、缺失或错误密码及容量拒绝继续使用 `ROOM_ACCESS_DENIED`。建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。- 房间级观看授权:新房间总是生成一个 128-bit 随机、22 字符 base64url、可 rotate/revoke 的 room-scoped Viewer grant;服务端内存只在该 exact room incarnation 保存完整 grant 的 SHA-256 摘要。grant 没有独立到期时间或内嵌 room/expiry 字段,与房间同寿,并在房间回收、进程重启、rotate 或 revoke 时失效;同号新房间使用新摘要,旧链接不能进入。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。code-only 入口独立采用 `open | private`,默认 `open` 且无房间密码;`private` 可不设密码并拒绝全部 code-only 尝试,设置密码后只接受匹配值。所有 code-only 尝试先通过站点访问。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可独立 rotate/revoke grant、改变 code-only policy 或设置/移除密码;授权变化必须先提交新的内存代次,再清除 Viewer grace/路由、终止旧代次信令和媒体并断开受影响 Viewer。- 易失房间状态:服务器只在一个有界内存 RoomStore 中保存房间码、租期、Host token/Viewer grant 摘要、code-only policy、可选 48-byte 房间密码校验材料、参与者和控制状态。`ROOM_LEASE_SECONDS` 默认 `86400`;Host 正在分享时不回收,停止分享或 Host 断开后开始 dormant lease,同一 Host token 在期限内重新分享即续租,Viewer 活动不续租,过期后释放号码。应用进程重启时全部房间、租约、邀请和密码状态直接失效;不使用 SQLite、`ROOM_DATABASE_PATH`、schema migration、账号、用户表或服务器 session 表。-- 本地 Host 偏好:房间所有权继续使用随机 Host token,不使用 IP、UA、硬件信息或浏览器指纹。Host 浏览器在同源 `localStorage` 保存 raw Host token,以及昵称、code-only policy 和可选房间密码组成的创建偏好;另以无秘密记录保存上次分配的四位号码和按该房间实际 `ROOM_LEASE_SECONDS` 计算的截止时间(默认 24 小时)。Host 分享中每半个租期续写一次,正常停播再续写一次;页面关闭或崩溃后不再续写,最多保留一个配置租期。服务器只在当前进程内保存 token 摘要和密码 verifier。旧 ownership 失效后的下一次显式分享仅在偏好仍有效时请求原号码;服务端只在号码空闲时分配,否则随机分配。两种结果都创建全新 room incarnation、Host token 和 Viewer grant,不恢复旧租约、密码材料、成员或路由。换设备、换浏览器或清理站点数据即不恢复。+- 本地 Host 偏好:房间所有权继续使用随机 Host token,不使用 IP、UA、硬件信息或浏览器指纹。Host 浏览器在同源 `localStorage` 保存 raw Host token,以及昵称、code-only policy 和可选房间密码组成的创建偏好;另以无秘密记录只保存上次实际分配的四位号码。该 preferred room 没有本地租期、倒计时或续写 timer,也不证明或延长服务端 `ROOM_LEASE_SECONDS`。服务器只在当前进程内保存 token 摘要和密码 verifier。旧 ownership 过期/失效后的下一次显式分享始终请求原号码;服务端只在号码空闲时分配,否则随机分配并返回新的本地偏好。两种结果都创建全新 room incarnation、Host token 和 Viewer grant,不恢复旧租约、密码材料、成员或路由。换设备、换浏览器或清理站点数据即没有该偏好。### P1 - 重要功能- 公网服务器一键部署包:在用户自有的公网服务器上一键部署当前 Web/信令应用、易失房间状态和所需 STUN/SFU/反向代理组件,复用唯一配置、secret、路由、健康检查和恢复合同。普通 app-only 更新先验证新的不可变 artifact 再原子切换,切换前 application release 只保证保留到有限 health/postflight 完成;之后没有保留合同,也不作为维护中的备份。只有实际改动基础设施、配置、secret、持久或不可逆状态时,才为被触及表面定义恢复并预检。它不是托管服务,不能内置真实凭据或跳过域名、TLS、防火墙、端口、容量和适用的恢复预检。@@ -105,7 +105,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given 已通过 site access 的 well-formed code-only 尝试对应未分配、已回收或已过期房间,When `screener-v12` 首条信令鉴权到达,Then 服务端返回 `ROOM_NOT_FOUND`,UI 显示“房间不存在或已过期”且不提供密码重试。Given code 属于现存房间但缺失/错误密码、满房或其他已知有界 admission refusal,Then 服务端继续返回 `ROOM_ACCESS_DENIED` 并使用共享 authentication-failed close code,UI 可提供现有可选密码重试和 Host 邀请提示。Given grant 无效,Then 继续使用通用 `INVALID_TOKEN`;Host 鉴权保持独立错误,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。Given Viewer 持另一个房间的 grant、缺失 grant 或自行把 role 改为 Host,Then 不能建房、发布、跨房或绕过 Host token。- Given Host rotate/revoke Viewer grant,When 新内存摘要和 authorization generation 提交,Then 服务端清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 返回一次新 grant,revoke 锁定 grant 路径,code-only policy 保持独立。- Given Host 浏览器仍持有现存房间的 ownership,When 分享活动或休眠期间更新邀请、code-only policy 或房间密码,Then 同源 HTTP 管理只接受有效 site access 与该房间精确 Host token;操作不建立 Host 媒体会话、不把房间标为分享中、不申请 route/resource,也不续租 dormant lease。rotate/revoke 继续执行同一强撤销,服务端只在 rotate 成功时返回新的 raw grant。-- Given Host 同源本地偏好保存了 `open | private`、可选房间密码和仍在该房间配置租期窗口内的上次房间号,When 服务器重启后该 Host 下一次显式开始分享,Then 客户端清除失效 ownership、请求该 preferred room 并原子重放创建偏好;号码空闲时分配给新的 room incarnation,已占用时随机分配。两者都生成新的 Host token 和 Viewer grant。Given 偏好过期、换浏览器、换设备或清理站点数据,Then 不请求旧号码或恢复旧所有权。+- Given Host 同源本地偏好保存了 `open | private`、可选房间密码和上次实际分配的房间号,When 服务器报告旧 ownership 已过期/失效或重启后该 Host 下一次显式开始分享,Then 客户端清除失效 ownership、始终请求该 preferred room 并原子重放创建偏好;号码空闲时分配给新的 room incarnation,已占用时随机分配并替换本地偏好。两者都生成新的 Host token 和 Viewer grant。该本地号码没有租期、倒计时或续租 authority;换浏览器、换设备或清理站点数据时没有该偏好。- Given 应用进程重启,When 旧 Host、Viewer 或 code-only 链接再次访问,Then 所有旧房间、租约、摘要、密码 verifier 和参与者均已丢弃并 fail closed;运行时不读取数据库、迁移旧 schema 或恢复旧房间。后续同号分配只能创建凭据完全独立的新 incarnation。- Given 部署切换了不兼容的当前协议,When 仍打开的旧页面连接新服务端,Then 单一 release/protocol mismatch 边界终止该 session、停止自动重连并明确提示刷新;不得通过旧 parser、双写或双协议继续假连接。@@ -161,7 +161,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given 同一时刻采集、host outbound 与 viewer inbound 证据,When 进行根因分类,Then 关联派生后的实际协商视频 codec/profile/parameters、适用时的 `scalabilityMode` 与真实解码表现,依次区分 Capture 低、Capture 高但 outbound 因 CPU 低、Capture 高但 outbound 因 bandwidth 低、outbound 正常但 inbound 低、以及 inbound 正常但肉眼模糊五类;不用 UA 或设备型号代替运行时证据,也不上传 raw SDP。- Given Viewer 上报当前路径质量证据,When 报告未鉴权、过频、重复、过期或没有匹配的 sender/viewer 统计,Then 报告被丢弃;有效报告也只能用于诊断,不能改变 Host 表示或路径状态。- Given 受控 RTT/丢包测试条件,When 连续分享高动态游戏画面 30 分钟,Then 延迟、帧率与丢帧达到上述目标,且没有不可恢复的冻结。-- Given Windows Chrome/Edge Browser Host 开始或继续分享,When 浏览器返回 display video track,Then 应用设置 `contentHint = "motion"`,并按浏览器 stats 如实显示实际 RTP codec 与实现字段。Given 已接受的 `screener-v12` 建立 direct 或 browser-relay sender,Then offer 的唯一视频媒体 codec 是 VP8;RTX/RED/FEC 只可作为修复格式,不能引入另一媒体 codec。若浏览器缺少 VP8 capability、`setCodecPreferences()` 或应用失败,Then 在创建 offer 前明确失败而不是静默协商其他 codec。Given 建立 SFU publication,Then LiveKit 固定使用 VP8、不启用 backup codec,且 Screener 不设置自定义 simulcast layer list。+- Given Windows Chrome/Edge Browser Host 开始或继续分享,When 浏览器返回 display video track,Then 应用设置 `contentHint = "motion"`,并按浏览器 stats 如实显示实际 RTP codec 与实现字段。Given 新 source 的有界 H.264 预检证明实际 `video/H264` sender 的源帧/编码帧进度达标,Then 后续 direct 或 browser-relay offer 按浏览器原生 H.264 capability 顺序列出 H.264,再列 VP8 与修复格式;双方不支持 H.264 时同一次协商选择 VP8。Given 预检不支持、证据不足、超时、失败或不达标,Then offer 只列 VP8 与修复格式。缺少 VP8、`setCodecPreferences()` 或应用失败仍在创建 offer 前明确失败。Given 建立 SFU publication,Then 使用 Host source 的同一 H.264/VP8 决定、禁用 backup codec,且 Screener 不设置自定义 simulcast layer list。- Given 分享过程中切换 Wi-Fi/有线网络,When ICE 连接失败,Then 客户端触发 ICE restart,并在成功或超时后给出明确状态。- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到 exact candidate child 解码出第一帧新画面后才原子提交;ICE `connected` 单独不能触发切换。- Given 候选没有准入资源,或 provisional 路径失败、超时、代次过期、参与者变化、房间停止、权限撤销或 session 被替换,When 本次机会结束,Then 原路径和未受影响 branches 继续工作,临时资源被销毁,重试遵守模型定义的有界策略。@@ -171,7 +171,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given Web Host 或浏览器 relay 建立或替换分享音轨,When 对实际音频 sender 应用发送参数,Then 从当次 `getParameters()` 派生所选 `encodings[0].maxBitrate = 64000 | 128000 | 192000`、调用 `setParameters()` 并立即读回,档位缺失时按 128000 处理;Given Web Viewer 为含唯一有效 audio/Opus payload 的 offer 生成 answer,Then 用结构化 SDP parser 只 upsert 该 payload 的 `stereo=1` 与 `maxaveragebitrate=192000`,并把同一个结果用于 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild 和 relay child 都适用;空 SDP、无/歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp 或 parse/write 异常必须按对象 identity 返回浏览器原 answer 并继续,不能发送部分修改或静默冒充 stereo/实际码率。只有实际 `setLocalDescription()` 失败才进入既有连接错误路径。`sprop-stereo` 与 `usedtx` 不新增,其他 fmtp/FEC/session/media 字段逐项保留。- Given 通过 SFU 发布分享音轨,When 构建 LiveKit 2.22.0 publish options,Then 64 kbps 使用 `AudioPresets.musicStereo`、128 kbps 使用 `AudioPresets.musicHighQualityStereo`、192 kbps 使用同等结构的显式 sender ceiling,三档都设置 `forceStereo = true`、`dtx = false` 与 `red = false`;验收同时核对 SDK 选项、applied ceiling、当前 RTP codec/fmtp 与 stats 实际码率,不能从 preset 名称或 `opus/48000/2` 单独推断实际声道内容。- Given 分享正在直播或暂停且 Host 选择新的 64/128/192 kbps 音频档位,When 当前 profile mutation 串行执行,Then 服务端以 last-wins 保存并广播最新 desired profile,每个当前 Host、relay 与 SFU audio sender 从 fresh `getParameters()` 派生 `setParameters()` 并立即 readback,过期 completion 不得覆盖新值;以后创建的 sender 使用最新 desired profile。单个端点应用失败时保留媒体与其旧 applied 值、显示可见告警并允许后续更新或重建重试,不得谎称全房已收敛。当前 applied readback 保持 endpoint-local;没有显式回执 wire 就不宣称跨端点原子提交。该操作不改变 Opus、route revision、media-binding generation 或 publication generation,也不创建第二个音频控制环。当前 screen-audio Host 基线是 Chrome/Edge;其他浏览器只有实际 sender readback 成功时才算支持。-- Given Host 打开已接受的 `screener-v12` 分享设置或更新房间画质,When 查看 UI 或校验消息,Then 不存在 codec selector、codec quality-state/wire 字段或分享生命周期 codec 分支;Browser direct、browser relay 与 SFU publication 始终使用固定 VP8。实际协商 codec 与 encoder 只作为只读诊断显示。+- Given Host 打开已接受的 `screener-v12` 分享设置或更新房间画质,When 查看 UI 或校验消息,Then 不存在 codec selector 或 codec quality-state/wire 字段。source-scoped H.264 预检只产生当前页面内存中的内部发送偏好;结果不持久化、不重新协商健康 edge,实际协商 codec 与 encoder 只作为只读诊断。- Given 浏览器返回屏幕音轨,When 产品展示音频状态或未来连接详情,Then 只能把存在性、浏览器实际返回的 track settings、实际协商 codec/fmtp 和实际流量分别标为捕获、协商或观测事实;字段缺失必须显示为未知,且不得从 Opus 的 `48000/2` RTP 声明推断源采样率或实际 stereo。- Given Web 或后续 native sender 分享电影/视频音频,When 进行产品验收,Then 必须用独立 A/B/C 证据关联 capture audio track/settings、实际 negotiated codec/fmtp、outbound/inbound 实际码率、loss、jitter、concealment、jitter-buffer 与 A/V sync;P2P、浏览器 relay 与 SFU route switch 保持同一持久 Viewer `MediaStream`/媒体元素和 stereo 协商,不新增独立 audio element 或 Web Audio 时钟边界。native sender 必须通过该音质和同步矩阵,且不得把 audio `maxBitrate` ceiling 当作提质证明。- Given 分享者同时运行语音软件,When 选择仅分享游戏声音,Then supported Windows 11 native sender 只保留目标游戏及其子进程的渲染音频,观众、通知和其他应用声音不得进入分享;浏览器 system audio 无法满足时必须允许 video-only 或明确告知其可能包含语音/通知,不能用 AEC、降噪或来源标签伪称已隔离。