[feat] allocate DeskHub video bandwidth automatically

docs/deskhub.md

@@ -29,7 +29,7 @@
 
 ## 预览与兼容性
 
-自动分辨率模式下，桌面墙发起或接管的会话在能力协商后默认请求最长边不超过 320 像素的画面。点卡片展开后，根据视频显示区域的实际物理像素（包含 HiDPI 缩放）请求分辨率；全屏、退出全屏和调整窗口大小后会重新计算，尺寸稳定 200 毫秒后更新订阅。返回网格、隐藏桌面墙或切换到其他设备后恢复缩略图尺寸。同一会话同时在独立串流窗口显示时，按两个可见视频区域中较大的尺寸请求，避免小预览降低大窗口的清晰度。选择固定或原始分辨率后使用对应上限；恢复自动后重新跟随视图。普通连接页发起且未加入桌面墙管理的会话保留原有分辨率行为。
+自动分辨率模式下，桌面墙发起或接管的会话在能力协商后默认请求最长边不超过 320 像素的画面。点卡片展开后，根据视频显示区域的实际物理像素（包含 HiDPI 缩放）请求分辨率；全屏、退出全屏和调整窗口大小后会重新计算，尺寸稳定 200 毫秒后更新订阅。返回网格或切换到其他设备后恢复缩略图尺寸。不可见设备暂停视频；如果同一设备仍在可见的独立串流窗口显示，则继续传输。同一会话同时在独立串流窗口显示时，按两个可见视频区域中较大的尺寸请求，避免小预览降低大窗口的清晰度。选择固定或原始分辨率后使用对应上限；恢复自动后重新跟随视图。普通连接页发起且未加入桌面墙管理的会话保留原有分辨率行为。
 
 被控端按连接分别在编码前缩放，完整保留桌面比例，不放大超过源画面的尺寸，也不修改被控端屏幕的系统分辨率。请求的宽高是上限，画质和网络自适应仍可降低实际发送尺寸。默认跟随每个会话原有的 30／60 帧设置；指定帧率仅覆盖桌面墙订阅，不修改会话的画质或原有帧率偏好。声音仍需明确开启。
 
@@ -39,15 +39,27 @@
 
 连接旧版被控端时，若仅声明 `supports_deskhub_preview`，控制端发送原有 v1 订阅；若未声明预览能力，则不发送该订阅，沿用其视频策略。旧控制端连接新版被控端时继续使用原分辨率；v1 订阅也会清除此前的尺寸限制。只有同时声明 `supports_deskhub_preview` 与 `supports_deskhub_resolution` 的被控端才会收到 v2 尺寸请求，旧版本不承诺发送端节省资源。
 
+### 视频带宽分配
+
+“设置 → 桌面墙 → 视频总带宽”配置所有支持带宽协商的桌面墙会话共享的视频预算，默认 20 Mbps，可选 2、5、10、20、50、100 Mbps。保存立即应用，取消不生效，重启后保留；恢复默认后需要保存。它是视频的持续目标预算，包含发送端为视频纠错、重传及 RTP 开销预留的份额；音频、文件传输、普通连接及不支持带宽协商的旧版设备不计入，关键帧和切换期间的瞬时速率可能超过预算。
+
+控制端根据请求的分辨率和帧率估算每台设备的需求上限。先为每台可见设备保留至多 100 Kbps 的基础份额（总预算不足时等分），再按权重分配剩余预算：展开画面或可见的独立串流窗口权重为缩略图的 4 倍。相同规格、相同优先级的设备基本均分；达到需求上限的设备让出剩余额度，不强制用满总预算。默认缩略图 320 × 320 上限、30 FPS 的需求预算为 500 Kbps。分配随连接、分页、分组、窗口可见性以及分辨率／帧率变化更新，独立串流窗口和墙内画面使用同一份设备预算。需求和总预算未变化时复用分配结果，不随 UI 刷新重复计算。
+
+翻页、切换分组、隐藏或最小化桌面墙后，没有可见画面的墙内会话发送 `fps=0` 暂停视频，保留连接和主动开启的音频。重新可见后恢复当前需求并请求关键帧。单纯重新分配带宽不会触发所有设备同时发送关键帧，也不会重置 15 FPS 的发送节奏。
+
+预算不代表测速结果。每条连接原有的拥塞控制继续工作，发送端使用网络可用带宽与设备预算中的较小值，并在设备的多个活动显示流之间再分配。视频探测速率受同一设备额度约束，以便网络恢复或画面展开后继续升速；额度下降会取消旧探测，暂停视频时关闭探测和填充包。只有声明 `supports_deskhub_bandwidth` 的对端会收到带宽字段；支持预览但不支持带宽协商的旧版仍能暂停不可见视频，更旧版本保持原行为。
+
 ### 协议与接口
 
 可靠控制通道的 `deskhub_preview` v2 保留 v1 的 `request_id`、`fps`、`quality`、`frame_rate`、`preference`、`audio` 字段，新增必填 `width`、`height` 整数，单位为物理像素。两个值均为 0 表示恢复源尺寸上限，否则两个值均须在 2～16384 之间；非法或缺失的值不应用。`deskhub_preview_status` 回传请求的协议版本、请求 ID 与 `accepted`。请求 ID 跳过 0，支持 32 位回绕，重复或过期请求不会覆盖新设置。断开会话清除订阅和 15 FPS 协商能力，再连接会重新发送当前需求。15 FPS 扩展通过可选能力 `supports_deskhub_fps15` 协商，沿用 v1／v2 的字段结构，使用 `fps=15, frame_rate=30`，在编码前将实际输入限制为 15 FPS。
 
+带宽扩展沿用 v1／v2，增加可选整数 `max_bitrate_bps`（0～100000000，单位 bps），仅向声明 `supports_deskhub_bandwidth` 的对端发送。0 或缺省表示解除额外的视频预算限制；暂停视频仍使用 `fps=0`。非法字段拒绝整个订阅，断开后清除能力，重连重新协商。MiniRTC 的 `UpdateVideoBitrateLimit(peer, remote_id, remote_id_size, max_bitrate_bps)` 为指定连接的所有视频流设置合计预算，不改变音频与数据发送；返回 0 表示已进入拥塞控制队列，-1 表示参数、连接或传输不支持。
+
 MiniRTC 新增 `UpdateVideoResolution(peer, remote_id, remote_id_size, width, height)` 接口，返回 0 表示已接受，-1 表示参数、连接或传输类型不支持。它为指定控制端的所有显示流设置独立尺寸上限，切换时丢弃旧设置尚未发出的编码结果，并请求新关键帧；底层自适应也以这个上限作为有效源尺寸。
 
 `SetVideoSendPaused(peer, remote_id, remote_id_size, paused)` 与 `SetAudioSendPaused(peer, remote_id, remote_id_size, paused)` 分别控制指定连接的所有视频／音频发送通道，`true` 暂停、`false` 恢复。重复设置不产生额外操作；返回 0 表示接受，-1 表示参数、连接或传输类型不支持。视频暂停阻止新帧进入编码，废弃旧编码结果，并在发送队列上清除待发视频／重传／纠错包，停止探测和填充；恢复请求新关键帧。音频暂停阻止 PCM 编码并清理待发音频，恢复时仅发送新音频。已交给网络的包无法撤回。API 保留连接、采集源、码率与画质设置以及其他媒体／数据通道，也不改变其他控制端的发送状态。
 
-桌面墙将 `fps=0` 和 `audio=false` 分别映射到上述 API；应用层仅保留低帧率节流，静音在 MiniRTC 内部执行。接收端仍保留静音门控及播放队列清理，以立即停止播放网络中已在途的音频。旧版 `audio_capture` 命令在支持新 API 的传输中也按连接静音，已有订阅的音频状态优先；不支持 API 的旧／Web 传输沿用采集开关回退。
+桌面墙将 `fps=0` 和 `audio=false` 分别映射到上述 API；应用层仅保留低帧率节流，不再使用 `1 bps` 代替视频暂停或在采集回调中过滤静音音频。接收端仍保留静音门控及播放队列清理，以立即停止播放网络中已在途的音频。旧版 `audio_capture` 命令在支持新 API 的传输中也按连接静音，已有订阅的音频状态优先；不支持 API 的旧／Web 传输沿用采集开关回退。
 
 ## 批量操作