执行摘要

• 一句话：新增实时 WebUI 播放控制器，优化帧节奏与缓冲
• 推荐动作：该 PR 值得精读，特别是 RealtimePlaybackController 的缓冲设计和事件切换逻辑。review 中关于 transfer 策略的讨论反映了实时流媒体中常见的权衡，值得关注。建议合并前确认除零修复已包含，并考虑增加集成测试。

功能与动机

改善实时 WebUI 的播放体验，减少抖动和缓冲，提供更流畅的预览，同时优化后台输出节奏和帧处理性能。

实现拆解

1. 新增客户端播放控制器：在 playback_controller.js 中创建 RealtimePlaybackController 类，管理帧队列、源帧率估计、缓冲水位线、丢帧策略和事件切换宽限期。控制器通过 enqueueDecodedFrames 和 render 方法驱动。

2. 集成控制器到主逻辑：在 app.js 中集成控制器，替换原有的简单缓冲逻辑，新增 requestedInputFps、previewPlaybackTargetFps 等变量，调整预览质量常量（如 MAX_WEBP_PREVIEW_OUTPUT_QUALITY=80），并添加帧录制功能。

3. 后台输出节奏：在 realtime_video_api.py 中新增 _output_pacing_fps 计算目标输出帧率，_wait_for_realtime_output_slot 函数在发送前等待合适时机，避免发送过快。

4. 预览图像尺寸限制：在 realtime_output_adapter.py 中新增 _preview_dimensions 和 _resize_preview_image 函数，支持 preview_max_width 参数，在编码 WebP/JPEG 前按比例缩小图像，降低传输量。

5. 批量 RIFE 插值：在 rife_interpolator.py 中添加 _interpolate_2x_batched 方法，将相邻帧分批送入 RIFE 模型，通过 _MAX_RIFE_BATCH_PAIRS=16 控制批量大小，减少 PyTorch 调用开销。

关键文件：

• python/sglang/multimodal_gen/apps/realtime_webui/playback_controller.js（模块 播放控制；类别 source；类型 entrypoint；符号 RealtimePlaybackController, clamp, finitePositive, error）: 新增客户端播放控制器，实现帧缓冲、节奏和丢帧管理，是 PR 核心变更。
• python/sglang/multimodal_gen/apps/realtime_webui/app.js（模块 实时界面；类别 source；类型 core-logic；符号 updateStats, requestedInputFps, frameInterpolationMultiplier, previewPlaybackTargetFps）: 主应用逻辑，集成播放控制器、调整预览质量和传输策略、添加录制功能。
• python/sglang/multimodal_gen/apps/realtime_webui/playback_controller_test.js（模块 播放控制；类别 test；类型 test-coverage；符号 frames, enqueueChunk, renderFor, stableSourceDoesNotDrop）: 新增播放控制器单元测试，验证稳定源不丢帧、慢服务器限制渲染帧率、积压丢帧和事件切换行为。
• python/sglang/multimodal_gen/runtime/entrypoints/openai/realtime/realtime_output_adapter.py（模块 输出适配；类别 source；类型 core-logic；符号 _preview_dimensions, _resize_preview_image, _build_encoded_preview_payload）: 添加预览图像尺寸限制和编码质量调整支持。
• python/sglang/multimodal_gen/runtime/entrypoints/openai/realtime/realtime_video_api.py（模块 输出节奏；类别 source；类型 entrypoint；符号 _result_num_frames, _output_pacing_fps, _wait_for_realtime_output_slot）: 添加输出节奏控制 pacing 和相关统计。
• python/sglang/multimodal_gen/runtime/postprocess/rife_interpolator.py（模块 帧插值；类别 source；类型 core-logic；符号 _frames_to_tensor, _tensor_to_frames, _interpolate_2x_batched）: 批量 RIFE 插值优化，提升插值效率。

关键符号：RealtimePlaybackController, clamp, finitePositive, updateStats, requestedInputFps, frameInterpolationMultiplier, previewPlaybackTargetFps, syncPlaybackTargetFps, clearFrameQueue, closeFrames, recordingFileName, _preview_dimensions, _resize_preview_image, _build_encoded_preview_payload, _output_pacing_fps, _wait_for_realtime_output_slot, _interpolate_2x_batched, _frames_to_tensor, _tensor_to_frames

评论区精华

gemini-code-assist[bot] 指出将压缩预览 payload 传输到 workder 会丧失主线程回退解码能力，建议仅对原始未压缩内容使用 useTransfer=true。此外，在 _preview_dimensions 中 width 可能为零导致 ZeroDivisionError，需添加 width <= 0 的边界检查。

• 压缩预览帧传输策略 (design): 建议使用 isEncodedPreviewContentType(header.content_type) 条件避免 transfer 压缩帧。
• 预览尺寸计算中的除零风险 (correctness): 建议添加 width <= 0 检查。

风险与影响

• 风险：
  • 播放控制器状态管理：新控制器涉及复杂的缓冲和丢帧逻辑，可能在某些边缘情况（如极端延迟或丢包）下表现异常，需充分测试。
  • 除零错误：_preview_dimensions 中若 width 为零会触发 ZeroDivisionError，即使 review 已建议修复，但尚未确认是否合并。
  • 传输策略影响回退解码：将压缩预览帧标记为 transfer 会剥夺主线程回退解码能力，若 worker 解码失败可能导致黑屏。
  • 测试覆盖不足：仅包含 Node.js 单元测试，缺少与后端集成的端到端测试，无法验证整体流程。
• 影响：
  • 用户影响：实时 WebUI 用户将体验到更平滑的播放，减少卡顿和延迟。预览质量可能因新的质量限制（默认 80 vs 原来 95）而略有下降，但响应性提升。
  • 系统影响：后台增加输出节奏控制，可能降低发送带宽；批量 RIFE 插值减少模型调用次数，提升 GPU 利用率。
  • 团队影响：新增播放控制器需维护其状态机逻辑，后续扩展需理解其缓冲策略。
  • 风险标记：除零错误风险, 传输策略可能影响解码回退, 测试覆盖不足

关联脉络

• PR #27068 [diffusion] Polish realtime WebUI waiting state: 直接关联，修改了相同的实时 WebUI 文件 app.js，持续优化实时体验。
• PR #23755 [SGLang Tracing] Add pd disaggregation mooncake backend tracing: 相关，本 PR 修改了 trace_wrapper.py，与追踪初始化相关，PR#23755 建立了追踪框架。