从 UI 功能到 Agent 工具:用 WebMCP 接入浏览器视频打光与深度转换
在浏览器视频编辑器里,用户可以选中片段、分析场景深度,再调整灯位和光照强度。 但如果让 AI Agent 完成同样的工作,仅仅暴露一个“开始分析”方法还不够。 我们还需要解决: - Agent 如何确定处理的是哪一个片段? - 模型任务运行时,用户修改了素材怎么办? - 分析、渲染和资产提交的状态如何区分? - 参数变化能否先审阅,再应用? - 长任务如何取消,失败后如何重试? - 浏览器工具与本地 CLI 的能力边界在哪里? 最近,我在开源浏览器视频编辑器 **Timeline Studio** 中,将视频打光和深度视频转换接入了 WebMCP 与编辑 Skill,并随 **v1.0.9** 发布。 这篇文章从工程实现的角度,介绍这次接入的设计和验证结果。 ## 一、接入目标:让 Agent 完成可检查的编辑流程 这次接入涉及两项已有的编辑器能力。 **视频打光**:分析场景深度,保留原素材,通过可编辑参数调整局部光照。 **深度视频转换**:将视频转换为表达相对远近的灰度深度视频,生成独立媒体资产。 两项能力共享深度分析基础,但不能使用完全相同的提交逻辑。 打光的交付结果是工程中的一组效果参数;深度转换的交付结果是一段新视频。 因此,整体流程被拆成: ``` 检查工程与目标片段 ↓ 准备并审阅模型任务 ↓ 启动、查询或取消任务 ↓ 分析结果 / 新媒体资产 ↓ 审阅时间线编辑 ↓ 应用、验证、保存与导出 ``` 这种拆分让模型执行与时间线修改各自拥有明确的边界。 ## 二、第一条原则:目标片段必须显式指定 编辑器界面常常围绕“当前选中的片段”组织代码。 如果直接把界面方法暴露给 Agent,可能出现一个问题: 任务启动时选中的是片段 A,用户随后选中了片段 B,而提交结果时又读取了一次当前选择。 长任务的目标就可能发生变化。 这次接入使用检查工具返回的 `clipId`: ``` { "kind": "relight-analysis", "clipId": "", "quality": "balanced" } ``` 任务启动后绑定这个片段,后续选择变化不会重新指定任务目标。 打光分析支持主画面或画中画中的图片、视频片段;深度视频转换要求目标是视频。 素材准备状态和轨道锁也在执行前检查。 ## 三、用异步任务契约处理模型执行 深度分析可能经历模型下载、初始化、取帧和推理。深度视频转换还包含插值、编码与资产提交。 这些过程不适合塞进一次同步编辑调用。 实现复用了现有 AI 任务工具: |工具|职责| |:-:|:-:| |`timeline_ai_capabilities`|读取支持的能力和运行条件| |`timeline_ai_prepare`|校验请求,返回待审阅方案| |`timeline_ai_start`|启动已经准备好的任务| |`timeline_ai_inspect`|查询真实进度、结果或错误| |`timeline_ai_cancel`|请求取消实际任务| ### Prepare 不运行模型 准备阶段检查请求是否合法,并返回目标片段、质量、交付方式以及分析是否可复用等信息。 这一步不下载模型,也不启动推理。 这样,Agent 可以先展示或检查将要执行的工作,再进入有资源开销的阶段。 ### Start 使用独立的重试标识 启动请求示例: ``` { "aiId": "", "requestId": "", "allowModelDownload": true } ``` `aiId` 指向准备好的任务,`requestId` 用于识别同一次启动的重试。 当响应不确定时,调用方复用原来的 `requestId`,避免重复创建任务。 模型下载许可也需要显式提供,不能把一次能力检查理解成下载授权。 ### Inspect 返回实际状态 获得 `jobId` 只代表任务已经创建。 Agent 需要继续查询,直到任务进入成功、失败或取消等终态。成功结果还需要包含对应的分析摘要或资产回执。 这避免了一个常见问题:任务仍在后台运行,Agent 已经告诉用户“处理完成”。 ## 四、复用生产媒体管线,避免逻辑分叉 如果给 Agent 单独实现一套分析和渲染逻辑,短期内可能更容易接通,但长期会形成两套行为: 一套服务于界面,一套服务于工具调用。 它们可能在取帧时间、插值方式、音频处理和取消行为上逐渐产生差异。 这次 WebMCP 接入复用了编辑器已有的: - 深度分析 Worker; - 固定版本的自有模型镜像与缓存; - 源时间映射; - 深度视频渲染与编码; - RIFE 深度帧插值路径。 深度分析采用 **Depth Anything V2 Small Q4F16** 的浏览器 WebGPU 路线。 质量档位如下: |档位|目标深度采样频率| |:-:|:-:| |Fast|8 张/秒| |Standard|16 张/秒| |Fine|24 张/秒| 分析样本上限为 720。长片段达到预算上限后,实际采样密度会降低。 深度视频输出为 24 fps。Fast 和 Standard 复用现有 RIFE 插值路径,Fine 使用现有深度混合路径。 需要区分的是:**模型分析的采样频率与最终视频帧率是两个指标。** 这里的 RIFE 用于深度帧插值,也不能描述成对原始彩色视频进行了生成式增强。 ## 五、源时间映射决定分析是否对得上画面 视频编辑中的时间至少有两种: - 片段在时间线中的时间; - 片段对应的原始素材时间。 经过裁切和变速后,两者不能简单相加。 例如,片段从原视频第 20 秒开始,又应用了速度曲线,那么片段局部第 2 秒对应的原始视频时间,需要通过现有映射计算。 这次接入沿用编辑器的同一条路径: ``` 片段局部时间 ↓ 源时间与速度曲线映射 ↓ 原始视频取帧时间 ↓ 深度分析 ``` 分析签名包含源范围、播放速度、速度曲线和质量等信息。 这些条件变化后,旧分析不能继续被认定为当前片段的有效分析。 否则,即使模型输出本身正确,也可能被用在错误的画面时刻。 ## 六、打光参数走共享命令,支持审阅与撤销 模型分析只准备数据,打光参数修改则进入共享编辑命令层。 新增操作为: ``` clip.set_relight ``` 示例: ``` { "type": "clip.set_relight", "clipId": "", "enabled": true, "quality": "balanced", "light": { "x": -0.2, "y": -0.28, "distance": 2, "strength": 0.35, "range": 0.7, "softness": 0.7, "color": "#ffe5bf" } } ``` 这条操作沿用: ``` inspect → preview → apply → undo ``` 预览阶段展示参数修改前后的语义差异,不改变时间线。应用阶段提交审阅过的方案,并保留正常撤销能力。 参数范围也明确约束: |参数|范围或含义| |:-:|:-:| |`x`|−1~1,方位角为 `x × 180°`| |`y`|−1~1,仰角为 `−y × 90°`| |`distance`|1~4| |`strength`|0~1| |`range`|0.1~1| |`softness`|0~1| |`color`|六位十六进制颜色| 浏览器中启用打光前,需要检查分析是否完整,并且与当前源时间映射和质量匹配。 **分析完成,不会自动开启效果;参数应用,是独立的编辑事务。** ## 七、提交前再次检查,避免覆盖用户的新编辑 长任务运行期间,用户可能删除片段、改变裁切范围、调整变速,或者锁定轨道。 因此,启动前校验只能解决一部分问题。 实现会在提交结果前再次检查源片段,确认它仍然存在,源时间映射没有变化,轨道仍允许处理。 如果条件发生变化,任务会返回相应错误,不把旧结果当作当前素材的结果提交。 分析数据和生成文件也分别处理: 完整分析可以在编码失败或取消后保留,供重试复用。 但“分析仍然可用”不等于“视频资产已经生成”。只有成功生成并提交的资产,才会返回对应回执。 ## 八、深度视频先进入资产库,再审阅插入 对于 Agent,深度转换完成后,结果进入“我的资产”,并返回 `assetIds`。 后续需要: 1. 检查生成资产; 2. 确认插入目标和时间; 3. 预览时间线方案; 4. 应用审阅过的插入操作。 这条路径不会自动替换源片段。 它与手动界面转换的源片段替换行为有明确区别,Skill 和工具文档中也需要说明。 这有助于让 Agent 的副作用保持可见:用户能分别判断生成结果是否可用,以及它应该如何进入工程。 ## 九、Skill 要记录真实执行能力 接通工具之后,我同步更新了仓库编辑 Skill 和网站供 Agent 发现的浏览器 Skill。 文档包括: - 两种任务各自适用的场景; - 质量档位和参数范围; - 准备、启动、查询与取消流程; - 分析完成后的参数应用步骤; - 资产生成后的插入步骤; - 画面与音频验证要求; - 浏览器和本地命令的执行边界。 当前边界是: |执行路径|支持范围| |:-:|:-:| |浏览器 WebMCP|模型分析、深度视频生成、打光参数编辑与浏览器导出| |本地 CLI / STDIO MCP|通过共享命令检查、比较和修改打光设置| |本地无界面渲染子集|尚不渲染这些打光效果,遇到启用的效果会明确拒绝| 不能因为共享命令已经支持某个参数,就声称所有渲染路径都支持对应效果。 明确报错,比静默忽略效果后输出一个文件更容易定位问题。 ## 十、验证结果与限制 本次验证包含接口行为和真实媒体执行。 接口行为覆盖参数边界、轨道锁、分析就绪条件、语义差异、应用与撤销、启动重试去重,以及取消和源片段冲突处理。 真实 Chrome/WebGPU 验证运行了生产模型分析和深度视频生成。 一段 0.6 秒测试素材生成了: - 320×240 深度视频; - 15 个视频帧; - 标称 24 fps; - Opus 音频轨道。 打光前后的渲染采样确认了画面变化,确定性浏览器导出生成了可解码的 H.264/AAC MP4。 另外验证了真实 Worker 取消、生成媒体保存进 `.timeline` 工程、本地 CLI 参数保存,以及不支持的无界面渲染明确报错。 `npm run check` 和 GitHub CI 均通过,保留现有的 79 条 lint 警告。 这些结果证明了本次调用链路和集成行为,不是长视频性能基准,也不能替代复杂素材的视觉质量检查。 快速运动、遮挡、细小轮廓和人物光照,仍需要结合实际画面验证。相对深度也不等于真实世界的度量深度或完整三维重建。 ## 项目与实现 这次接入的核心收获,是把媒体处理中的隐含状态变成了明确契约: **目标是谁、运行到哪里、结果能否提交、编辑能否撤销,都可以被检查。** 这套实现已随 **Timeline Studio v1.0.9** 发布。 **GitHub 仓库:** https://github.com/MartinDelophy/ai-video-editor **Release:** https://github.com/MartinDelophy/ai-video-editor/releases/tag/v1.0.9 **打光与深度视频 Skill 工作流:** https://github.com/MartinDelophy/ai-video-editor/blob/v1.0.9/skills/edit-timeline-studio/references/relighting-and-depth-video.md **WebMCP 接入文档:** https://github.com/MartinDelophy/ai-video-editor/blob/v1.0.9/docs/webmcp.md 如果你也在开发浏览器媒体处理、WebGPU 或 Agent 工具,欢迎查看实现、提交 Issue,或者分享类似的工程实践。