用途
该技能用于诊断 Remotion Studio 播放卡顿(buffering)问题,帮助定位导致播放阻塞的具体层、媒体源和代码位置。当需要回答“哪一层导致了缓冲”、想要揭示造成卡顿的播放块、或验证修复效果时使用。
主要能力
- 缓冲追踪:通过
set_buffering_tracing启用/禁用追踪,记录缓冲事件、句柄堆栈、媒体源和所属位置。 - 资源计数器:读取
get_diagnostics获取计数器基线,包括audioIteratorsCreated、mediabunnySinksOpen、bufferingHandlesCreated、bufferingStatesTriggered等。 - 事件查询:使用
get_buffering_events获取缓冲事件列表(支持 limit 参数),检查事件帧、持续时间、句柄堆栈和 owner 位置。 - 定位揭示:使用
reveal_buffering_handle根据 eventId 和 handleId 暂停播放、切换到记录的合成、跳转到事件起始帧,并在时间线和 Inspector 中选中 owner。 - 播放控制:通过
select_composition、seek_to_frame、play、pause复现报告的卡顿区间。 - 清理与重置:
clear_buffering_events清空已完成历史(保留活动事件);reset_buffering_handles_created重置句柄创建计数。
使用方式
- 确认当前 worktree 的 Studio 正在运行,确认合成和复现范围。不要为了获取追踪而修改合成。
- 启用追踪:调用
set_buffering_tracing传入{"enabled": true},或通过 Settings → Studio → Debug → Show diagnostics、Config.setShowDiagnostics(true)、--show-diagnostics启用;浮动面板挂载期间会自动启用追踪。 - 暂停播放并调用
clear_buffering_events清空历史,读取get_diagnostics获取计数器基线。可选调用reset_buffering_handles_created重置创建计数。 - 使用
select_composition、seek_to_frame、play、pause复现报告区间,尽早开始以包含预挂载和加载过程。 - 调用
get_buffering_events(如{"limit": 20})和get_diagnostics获取事件与计数器。检查记录的帧、持续时间、句柄堆栈、媒体源和 owner 位置(owners 从最近层向上遍历祖先)。 - 使用
reveal_buffering_handle传入返回的 eventId 和 handleId,定位到具体帧和层;通过get_selection和get_playback_state确认。面板的 Reveal 按钮执行相同操作。 - 完成后调用
set_buffering_tracing传入{"enabled": false}关闭追踪(若面板仍打开则追踪保持启用)。报告合成、帧、源位置、媒体 URL、持续时间和原因证据。
这些工具在常规、分离、部署和 Browser Studio 中均可使用。Reveal 需要可选择的合成时间线;如果记录、合成或匹配层已不存在,会报错。
证据解读要点
audioIteratorsCreated是累积值,不是活跃迭代器数量。mediabunnySinksOpen是当前已注册且输入未释放的 sink 数量,不是累积计数。bufferingHandlesCreated统计创建播放块的调用次数;块可被立即清除而不进入缓冲。重置仅影响此计数。bufferingStatesTriggered统计进入内部缓冲状态的转换次数;重叠句柄形成一个 episode;同一 React 批次内添加并移除的句柄不会触发 episode;短 episode 可能不显示加载指示器(默认延迟 300ms)。activeAtStart: true标识 episode 开始时已存在的句柄;其他句柄加入了已缓冲的 episode,可能延长它或由重新同步产生。记录的句柄是播放阻塞的证据,但本身不能证明根本原因。- 事件帧是缓冲进入时的合成帧;句柄帧和 releasedFrame 描述创建与释放时间(performance.now() 毫秒)。
endedAt: null表示进行中;endReason: 'unmounted'表示缓冲提供者消失,而非媒体加载完成。 - 追踪从启用时开始,不回溯;事件开始时仍在阻塞的早期句柄会出现在
omittedHandles中。详细历史最多保留 100 个事件,每个事件最多 50 个句柄;面板显示最新 20 个。将追踪视为完整前应检查droppedEvents和omittedHandles。 - 历史和计数器在页面重载时重置;清空历史保留活动记录且不重置计数器;清空后 ID 不会复用。
- 仅使用
afterId请求更新的事件;要检查现有 episode 的更新或释放,省略它。源堆栈在层卸载后仍可用;Reveal 按身份或捕获的源信息匹配当前层,可能回退到祖先;应检查返回的选择而非假设原始层在编辑或 HMR 后仍存在。
定位原因与验证修复
读取首个阻塞句柄的源和所属 JSX,将媒体等待追溯到底层 fetch、解码、seek 或同步路径。遵循 fix-root-cause 流程,区分初始解码器等待与后续为重新同步创建的音频句柄。
检查相关 Sequence 的 premountFor、实际挂载帧和源媒体属性。预挂载会提前挂载,但不保证所有即将到来的帧都已解码。canvas-ahead-of-time.ts 中的预览队列持有三个提前槽位;当前/预看帧和浏览器解码器缓冲区是分开的,不要将其理解为预挂载期间解码完整一秒。
对于疑似媒体瓶颈,验证分辨率、编解码器、文件大小、比特率和解码时间。在提议替换前确认替代文件包含相同画面。不要抑制缓冲或静默替换视频来隐藏卡顿。
更改后复现相同区间,比较事件数量/持续时间、资源计数器和可见输出。对于 React 渲染回归使用 react-scan。保持追踪有界且本地;总结相关句柄而非返回所有原始堆栈。详细堆栈捕获是可选开启的,诊断工作之外应保持关闭。
适用场景
- 排查 Remotion Studio 中播放卡顿的具体层和媒体源。
- 追踪预挂载与媒体加载对缓冲的影响。
- 验证修复后缓冲事件数量和持续时间的变化。
- 在部署或 Browser Studio 环境中进行诊断。
限制
- 追踪从启用时开始,不回溯历史。
- 详细历史最多保留 100 个事件、每事件 50 个句柄,面板仅显示最新 20 个。
- Reveal 需要可选择的合成时间线,且在记录、合成或匹配层不存在时会报错。
- 历史和计数器在页面重载时重置。
- 详细堆栈捕获需手动开启,默认关闭。