Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

docs: align active requirements and design

AAA39dc7061b238
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 01504ff9..eaaac5a8 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"
@@ -2,11 +2,11 @@
## 2026-08-18 14:45
-状态:首个 PoC 基线及其已接受扩展的当前设计。Production 仍使用 STUN-only ordinary ICE;旗舰进程以 `PEER_ASSISTED_MEDIA=true` 对所有正常房间启用 peer-assisted 与 LiveKit SFU/UDP,room `1` 仅是历史 smoke。默认关闭的 built-in Peer ICE TURN canary 已失败并回滚,不再是产品方向;下一候选只能在 SFU/UDP 后由 controller 选择单条异常 edge。旧 release 与 coturn relay 仅保留为隔离回滚路径,不是同进程兼容分支。
+状态:首个 PoC 基线及其已接受扩展的当前设计。Production 仍使用 STUN-only ordinary ICE;旗舰进程以 `PEER_ASSISTED_MEDIA=true` 对所有正常房间启用 peer-assisted 与 LiveKit SFU/UDP,room `1` 仅是历史 smoke。built-in Peer ICE TURN canary 已失败并回滚,不再是产品方向;production 已配置仅由 controller 向单条异常 edge 发放的 selected-edge TURN,但真实中继媒体仍未验收。旧 release 与 coturn relay 仅保留为隔离回滚路径,不是同进程兼容分支。
## 目标与边界
-产品面向一名分享者和小范围可信朋友的低延迟游戏画面分享。观看端使用普通桌面或手机浏览器;每条媒体边独立 ICE。当前 production 的普通边只接收自托管 STUN;room `1` 在 peer 恢复耗尽后可由 LiveKit ICE/UDP virtual parent 服务一至两个必要 roots,再失败则有界明确结束。当前房间默认最多八名观看者、可配置范围为 1 至 16;自动分布式拓扑通过 20 人门禁后,目标 release 才把默认值和上限原子改为 20。容量配置只是接入边界,不是性能声明。
+产品面向一名分享者和小范围可信朋友的低延迟游戏画面分享。观看端使用普通桌面或手机浏览器;每条媒体边独立 ICE。当前 production 的普通边只接收自托管 STUN;所有正常房间在 peer 恢复耗尽后均可由 LiveKit ICE/UDP virtual parent 服务一至两个必要 roots,再失败时仅可为 controller 选中的异常 edge 尝试一次短期 TURN,随后有界明确结束。当前房间默认最多八名观看者、可配置范围为 1 至 16;自动分布式拓扑通过 20 人门禁后,目标 release 才把默认值和上限原子改为 20。容量配置只是接入边界,不是性能声明。
本阶段必须形成完整的最小纵向链路:
@@ -160,7 +160,7 @@ PoC 不强制 codec,也不做 SDP munging。先通过 stats 记录实际协商
`audio: true` 只是请求。若 `getAudioTracks()` 为空,分享者界面必须显示“当前来源没有可共享音频”。`systemAudio`、`windowAudio` 和 `audioSelection` 只影响选源器偏好,浏览器可以忽略且没有对应的标准音频来源类型读回,因此不能显示为系统、窗口或所选游戏音频保证。纯 Web 首版接受浏览器实际提供的标签页或系统音频,不承诺仅捕获某个游戏进程;系统音频可能把语音软件中观众自己的声音再次采入,这属于源内容泄漏而非 Host 页面回放,AEC 或 Web Audio 无法从已混合 track 恢复进程身份。Web 端必须保留 video-only 选择并明确风险,不能声称已隔离语音。
-后续 Windows sender 以所选游戏 PID 为本地边界,优先使用 WASAPI process loopback 的 include-target-process-tree 捕获游戏及其子进程;“全部系统声音”仅为显式选择。目标进程无渲染流、退出或捕获失败时显示无声/未知,不回退为整机音频,也不上传 PID、路径、窗口标题、设备标识或原始音频。该 API 的最低 build 20348 不存在于普通 Windows 10 22H2(19045)产品矩阵,因此当前候选只覆盖 Windows 11;Windows 10 game-only 音频保持未解决或明确不支持,直到独立候选通过。
+当前 Windows Native sender 以所选游戏 PID 与进程创建时间为本地边界,使用 WASAPI process loopback 的 include-target-process-tree 捕获游戏及其子进程。目标进程无渲染流、退出或捕获失败时显示无声/未知,不回退为整机音频,也不上传 PID、路径、窗口标题、设备标识或原始音频。该 source-only 路径当前只支持 Windows 11;Windows 10 game-only 音频保持明确不支持,打包与其他媒体 route 仍待完成。
直播中切换来源仍由明确的按钮手势重新调用 `getDisplayMedia()`,不改变房间、host generation 或媒体拓扑。选源取消或失败时继续发送旧流;成功后为每个现有 sender 调用 `replaceTrack()`,健康连接不重新协商。初始 offer 预留 send-only audio transceiver,使音频可以在 `null -> track -> null` 间切换。若某个 peer 的替换或回滚失败,只重建该 peer;新流提交后才停止旧流,并以当前 stream 身份保护旧 track 的迟到 `ended` 事件。统计码率累加器在换源后重置,避免把不同 track 的计数器混算。
@@ -235,10 +235,10 @@ fixed-`HIGH` -> 现有 WebRTC/一至两名 Web Viewer 的 P2 窄实验。硬件
当前仓库已经删除旧全房 TURN contract 和被拒绝的 participant-wide built-in
config、issuer、capability、`refresh-ice`/`ice-config` wire 与客户端传播。
Production `ServerConfig` 必须配置 `STUN_URLS`;旧 `PEER_ICE_TURN_*` 即使为空也
-启动失败,且绝不是 selected-edge tuple 的 alias。Source candidate 已在同一 coherent
-change 中加入完整 default-off `SELECTED_EDGE_TURN_*` tuple、controller consumer 与
+启动失败,且绝不是 selected-edge tuple 的 alias。当前 source 已加入完整可选的
+`SELECTED_EDGE_TURN_*` tuple、controller consumer 与
Host/ViewerRelay/Viewer rebuild;部分配置、非法 UDP TURN URI、弱或复用 secret、越界
-TTL 都启动失败。该 candidate 尚未部署或通过真实 relay-media 验收。
+TTL 都启动失败。Production 已配置该 tuple,但尚未通过真实 relay-media 验收。
旧 `TURN_URLS`、`TURN_SHARED_SECRET`、`TURN_CREDENTIAL_TTL_SECONDS` 继续
fail-fast,绝不作为 alias。
@@ -266,8 +266,8 @@ external TURN 或 embedded TURN。Node 应用不能替代部署验证来证明
从公网可达;自托管 `stun_servers` 也避免 pinned LiveKit 1.13.5 继承默认公共
Google STUN。
-Source candidate 的可执行梯级是 `direct/peer UDP -> SFU ICE/UDP -> selected-edge
-TURN -> failure`,production 仍停在 SFU 后的 bounded failback。Viewer 的
+当前可执行梯级是 `direct/peer UDP -> SFU ICE/UDP -> selected-edge TURN -> failure`。
+Production 已配置整条梯级,但仍缺真实 SFU/TURN 媒体验收。Viewer 的
现有两次有界 ICE restart/rebuild 后报告 route failure;router 先尝试局部
reparent,再在 root budget 内准备 SFU,最终没有可行 route 时返回明确的
`PEER_NOT_FOUND`,不长时间维持伪连接。HTTPS/WSS 始终使用 TLS/TCP,不
@@ -306,7 +306,7 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)
- `connectionState` / `iceConnectionState`;
- 选中候选对的 local/remote candidate type 与 ICE `protocol`,任一端为 `relay` 即标记中继;
- 本地 relay candidate 的 `relayProtocol`;规范禁止远端 candidate 暴露该字段,因此不推断远端使用 TURN/UDP、TCP 还是 TLS;
-- 后续 exact-room SFU/UDP 与可选兼容 transport 只按[低服务器成本媒体路由](./research/low-server-media-routes.md)的 generation-baselined、privacy-safe ICE manifest 记录;先以本地脱敏 `webrtc-internals` 建立 ground truth,不新增后台遥测;
+- SFU/UDP 与可选兼容 transport 只按[低服务器成本媒体路由](./research/low-server-media-routes.md)的 generation-baselined、privacy-safe ICE manifest 记录;先以本地脱敏 `webrtc-internals` 建立 ground truth,不新增后台遥测;
- `currentRoundTripTime`、发送码率和 `availableOutgoingBitrate`;
- 实际帧率、分辨率和相邻有效采样窗的 RTP 丢包率;
- codec、编码实现、最近采样区间内的每帧编解码耗时和 `qualityLimitationReason`;同一连接不并发采样,首个样本、无新帧、统计对象换代或计数器重置时显示未知并重新建立基线,不用连接生命周期均值掩盖后续过载。
@@ -376,7 +376,7 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)
3. 完成屏幕捕获、逐观看者 PeerConnection、观看播放和手动质量档。
4. 完成连接恢复和 stats 面板;随后以 STUN-only snapshot 替换旧全房 TURN credential/refresh wire。
5. 完成 automatic peer/SFU controller,并让 room `1` 仅作为历史 smoke fixture。
-6. 默认关闭的 selected-edge TURN tuple、revision-bound one-use grant 与 parent/child rebuild 已在 source candidate 闭环;其后再用有界网络矩阵验收 ordinary STUN-only、SFU/UDP、单条 forced relay、资源成本和明确失败,coturn/production rollout 保持独立验收边界。保留现有 benchmark,但统一性能对比不是功能落地前置。
+6. 可选 selected-edge TURN tuple、revision-bound one-use grant 与 parent/child rebuild 已在 source 和 production 配置闭环;下一功能验收只需一条 forced relay 媒体 smoke,完整网络/资源 benchmark 后置。ordinary STUN-only、SFU/UDP、coturn rollout 仍保持独立边界。
7. 在媒体主线阶段验收后,用一个原子 PR 迁移 Host admission、`screener-v2`、room-scoped Viewer grant 和 SQLite v2;同一部署切换客户端/服务端/环境和数据库备份,随后删除 v1 配置、wire 与测试。用户名/roster 保持独立。
8. P1 继续完成 Windows native fixed-`HIGH` staged gate 与 deployment;移动 Host 不阻断或先于它。
9. P2 只在上述门槛后运行 Android 14/API 34+ fixed-`HIGH` 原生 sender spike;失败即停,不扩展为跨平台 framework。
@@ -397,7 +397,7 @@ bounded controller,且 room `1` 曾作为 exact smoke;下列内容保留为
STUN-only;只有 controller-selected edge 可接收一次短期 grant。该边界不增加 UI、
用户选择或百分比框架。
-产品硬目标是任一非服务器节点任何时刻最多两条下游媒体边。系统按一个或两个观看者直接 P2P、更多观看者 peer-assisted、部署 SFU 中央兜底、最后 selected-edge TURN 的顺序自动分配和恢复,分享者与观看者不选择拓扑。默认媒体 transport 只使用 UDP;SFU 作为 virtual parent 正常只送一至两个 roots,roots 之后仍优先沿受限 peer descendants 扩散;多个无法挂到健康 root 的极端 viewers 只可使用另设上限的中央 edge。Production 已把普通 ICE 收敛为 STUN-only、删除旧全房 TURN wire;source 对所有启用的房间使用同一 failure-only controller,旧 `PEER_ICE_TURN_*` 配置启动失败,replacement selected-edge 已完成 source candidate 但尚未部署。公网 SFU media、selected relay 与资源仍未验收,旧 release/coturn 仅作回滚。ADR-0004/0005 的媒体验收尚未完成。
+产品硬目标是任一非服务器节点任何时刻最多两条下游媒体边。系统按一个或两个观看者直接 P2P、更多观看者 peer-assisted、部署 SFU 中央兜底、最后 selected-edge TURN 的顺序自动分配和恢复,分享者与观看者不选择拓扑。默认媒体 transport 只使用 UDP;SFU 作为 virtual parent 正常只送一至两个 roots,roots 之后仍优先沿受限 peer descendants 扩散;多个无法挂到健康 root 的极端 viewers 只可使用另设上限的中央 edge。Production 已把普通 ICE 收敛为 STUN-only、删除旧全房 TURN wire,并为所有正常房间配置同一 controller 和 replacement selected-edge tuple;旧 `PEER_ICE_TURN_*` 配置启动失败。公网 SFU media、selected relay 与资源仍未验收,旧 release/coturn 仅作回滚。ADR-0004/0005 的媒体验收尚未完成。
恢复目标按证据和成本逐级升级:短暂 `disconnected` 先观察同代 bytes/stats,`failed` 才执行一次 ICE restart;仍失败时重建一次相同 parent,再尝试不同的合格 peer parent,peer 候选耗尽后才申请 SFU。每个动作最多一次且成功即停,不实现“三次相同重试”。初始 `connecting`/`checking` 的软提示和硬窗口尚未实现;硬窗口必须先用移动网络实测确定,不能直接复用现有 3 秒恢复常量。Viewer SFU root 只刷新一次短期 grant,随后至多重建一次原 failed parent selected edge;Host publisher/global SFU failure 维持 bounded peer failback。Host 只保留当前 route revision 的 `connect | source | video-publish | sender-config | audio-publish | transport` 枚举阶段作为本地事件提示,不上传原始错误、URL、token、candidate 或地址。
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 5b44aaee..887a19bc 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 @@
### P0 - 必须实现
- [ ] 首屏双入口:分享入口通过 Host admission 后,主工作区必须同等突出“开始分享”和“加入房间”两个主要动作,并用清楚的视觉分隔表达发送与接收;观看者不需要知道 Host admission 密码。点击后直接进入现有分享或房间加入流程,不增加营销首页、模式向导或拓扑选择。浏览器标签页使用与现有 `MonitorUp` 品牌语言一致的 favicon。
-- [ ] 简单房间:分享者获得纯数字房间码。房间默认是私密模式,现有 `/r/{code}#v={grant}` 邀请继续直接进入;Host 也可给该房间设置低门槛观看密码,使仅有 `/r/{code}` 或 `/join` 房间码的 Viewer 在中性页面输入密码后进入。Host 可显式选择 public-watch,使纯房间码直接观看。当前源码候选已实现密码入口,但线上版本尚未部署。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。
+- [ ] 简单房间:分享者获得纯数字房间码。房间默认是私密模式,现有 `/r/{code}#v={grant}` 邀请继续直接进入;Host 也可给该房间设置低门槛观看密码,使仅有 `/r/{code}` 或 `/join` 房间码的 Viewer 在中性页面输入密码后进入。Host 可显式选择 public-watch,使纯房间码直接观看。房间密码入口已部署。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。
- [ ] 免安装观看:桌面和手机观看者可直接通过浏览器链接进入、授权并播放,不依赖与分享端相同的桌面客户端。
- [ ] 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时暂停画面和切换分享来源。Host 本地预览必须直接使用 capture stream,不得为预览建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。
- [ ] 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。
@@ -39,7 +39,7 @@
### P1 - 重要功能
-- [ ] 私密房间双入口:在不引入账号、密码找回或通用服务端 session 的前提下,private room 同时接受“房间号 + 该房间观看密码”和现有 `/r/{code}#v={grant}` 私密邀请;有效 grant 直接进入目标房间,没有 grant 的 `/join` 或 `/r/{code}` 只显示中性的房间密码输入。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符,不要求字符组合复杂度;服务端先以固定保守参数的 Node 异步 scrypt 落地,全局最多执行 2 个、等待 16 个派生,取槽后跳过 stale session,目标 1 GiB 部署机的参数 benchmark 与优化在功能部署后进行。房间密码、grant 与 verifier 的权限都只能是该房间 Viewer;明文密码不得进入 URL/query/cookie、`localStorage`、`sessionStorage`、日志或 SQLite,也不能取得 Host admission、建房、发布或跨房权限。不存在、错误密码、队满和正确密码后的满房都返回通用结果。当前源码候选已实现该最小闭环,线上仍未部署。
+- [ ] 私密房间双入口:在不引入账号、密码找回或通用服务端 session 的前提下,private room 同时接受“房间号 + 该房间观看密码”和现有 `/r/{code}#v={grant}` 私密邀请;有效 grant 直接进入目标房间,没有 grant 的 `/join` 或 `/r/{code}` 只显示中性的房间密码输入。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符,不要求字符组合复杂度;服务端先以固定保守参数的 Node 异步 scrypt 落地,全局最多执行 2 个、等待 16 个派生,取槽后跳过 stale session,目标 1 GiB 部署机的参数 benchmark 与优化在功能部署后进行。房间密码、grant 与 verifier 的权限都只能是该房间 Viewer;明文密码不得进入 URL/query/cookie、`localStorage`、`sessionStorage`、日志或 SQLite,也不能取得 Host admission、建房、发布或跨房权限。不存在、错误密码、队满和正确密码后的满房都返回通用结果。该最小闭环已部署。
- [ ] 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,所有正常房间都进入同一个 direct/peer -> SFU -> selected-edge controller;每个房间独立保存 assignment/session/revision/connection generation 和容量状态。`PEER_ASSISTED_ROOM_IDS` 已退役,room `1` 只作为历史 smoke fixture,不能作为功能开关。未启用总开关的开发/轻量部署仍可保留 ordinary P2P;普通 peer 始终 STUN-only。selected-edge TURN 只能复用当前 controller 选中的异常 edge,不能向普通 peer edge 预发 candidates。该能力不增加 UI、用户选择、百分比发布或第二套路由器。