视频编辑器有一个容易被忽略的问题:
用户能在界面里使用某个功能,不代表 Agent 也能可靠地使用它。
一个“视频打光”按钮,对人来说很直观:选中片段,分析场景,调整灯位和光照强度,查看效果。
但对于 Agent,仅仅知道这个按钮存在还不够。它需要知道:
- 应该处理哪一个片段?
- 当前素材是否已经准备好?
- 分析会不会下载模型?
- 长任务如何报告进度和取消?
- 用户在处理中修改了素材,结果还能不能提交?
- 参数修改如何审阅、撤销和保存?
最近,我在开源浏览器视频编辑器 Timeline Studio 中,把视频打光和深度视频转换接入了编辑 Skill 与 WebMCP。
这篇文章介绍的重点,是如何把已有的媒体处理功能变成一套可检查、可执行、可验证的 Agent 工具。
一、先定义两种不同的处理结果
视频打光和深度视频转换都会使用场景深度,但交付方式不同。
视频打光:保留原素材,参数可以继续编辑
打光需要先分析场景深度,再结合灯位、光色、距离、强度和柔和度调整画面。
在这条路径中,分析结果是辅助数据。用户后续仍然可以调整灯光参数,预览和导出使用已有的共享渲染逻辑。
因此,我把它拆成两个步骤:
深度分析 → 审阅并应用打光参数。
分析完成本身不会自动启用打光。
深度视频转换:生成独立的视频资产
深度转换输出的是一段灰度视频,用亮暗表达相对远近。
它需要完成取帧、深度推理、时间插值、视频编码以及源音频处理,最终生成一个新的媒体文件。
对于 Agent,这个结果先进入“我的资产”。是否插入时间线,由后续独立的编辑方案决定。
这样,模型任务完成与时间线编辑就有了清楚的边界。
二、为什么不能直接让 Agent 调用界面按钮?
最直接的实现,是把界面按钮绑定的方法暴露给 Agent。
但这里有一个隐藏问题:界面方法可能依赖当前选中的片段。
假设 Agent 启动分析后,用户又点击了另一个片段。如果后续提交仍然读取“当前选择”,结果就有可能落到错误的对象上。
另一个问题是,界面动作通常包含多个连续行为。例如,手动深度转换完成后,可能直接替换源片段。人通过按钮触发时理解这个行为,但 Agent 的任务契约需要把这些副作用说清楚。
这次接入采用的是显式目标:
{
"kind": "relight-analysis",
"clipId": "<通过检查获取的片段 ID>",
"quality": "balanced"
}
任务绑定被检查过的 clipId,而不是后续不断变化的界面选择。
选择可以变化,正在执行的任务目标不能跟着变化。
三、用同一套任务生命周期承载模型执行
深度分析可能涉及模型下载、初始化、GPU 推理和视频编码,不能把它当成一次立即返回结果的普通编辑操作。
我复用了现有的 WebMCP AI 任务生命周期:
capabilities
↓
prepare
↓
start
↓
inspect / cancel
↓
实际结果
对应的工具包括:
timeline_ai_capabilities
timeline_ai_prepare
timeline_ai_start
timeline_ai_inspect
timeline_ai_cancel
1. Capabilities:先确认当前页面能做什么
Agent 先读取能力信息,了解支持的任务类型、运行条件和质量档位。
模型缓存状态没有检查时,就明确报告未检查,不把它描述成已经就绪。
2. Prepare:准备方案,不执行模型
prepare 检查片段类型、素材准备状态、轨道锁和任务参数,返回可审阅的计划。
这一步不下载模型,也不启动推理。
打光分析可以针对图片或视频;深度视频转换则要求视频片段。
3. Start:启动已经准备好的请求
启动时使用返回的 aiId,同时提供唯一的 requestId 和明确的模型下载许可。
{
"aiId": "<prepare 返回的 ID>",
"requestId": "<本次启动的唯一重试标识>",
"allowModelDownload": true
}
同一次启动重试复用相同的 requestId,避免因为响应不确定而重复创建任务。
4. Inspect:任务 ID 不代表成功
启动返回 jobId 后,Agent 继续查询真实状态。
只有任务进入成功状态,并返回对应结果,才可以报告完成。
深度分析完成、视频编码完成、生成资产提交完成,是不同的阶段,不能混为一谈。
5. Cancel:取消要传到真实任务
取消请求需要进入实际分析与编码管线,触发中止信号和 Worker 收尾。
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 秒,不一定对应原视频的第 22 秒。
如果深度分析、打光预览和导出分别维护时间计算,画面与深度就可能错位。
这次接入沿用编辑器的源时间映射:
片段局部时间
↓
源时间映射
↓
原始视频时间
↓
取帧与深度分析
分析签名同时包含源范围、播放速度、速度曲线、质量等信息。
当用户修改裁切范围或速度曲线后,旧分析就不能被当作当前片段的有效分析继续使用。
六、把打光参数放进共享编辑命令层
模型分析解决的是“准备数据”,打光参数修改解决的是“编辑工程”。
我在共享命令层加入了:
clip.set_relight
示例:
{
"type": "clip.set_relight",
"clipId": "<已检查的片段 ID>",
"enabled": true,
"quality": "balanced",
"light": {
"x": -0.2,
"y": -0.28,
"strength": 0.35,
"softness": 0.7,
"color": "#ffe5bf"
}
}
这条命令进入已有的流程:
检查工程 → 预览语义差异 → 应用 → 撤销。
Agent 可以读取修改前后的参数,用户也可以在编辑器里审阅它。
参数使用严格边界:
| 参数 | 范围或含义 |
|---|---|
x |
−1~1,方位角为 x × 180° |
y |
−1~1,仰角为 −y × 90° |
distance |
1~4 |
strength |
0~1 |
range |
0.1~1 |
softness |
0~1 |
color |
六位十六进制颜色 |
不合法的参数会被拒绝。
在浏览器中启用打光时,还需要确认分析已经完成,并且与当前片段的源时间和所选质量匹配。
七、长任务提交前,再检查一次源片段
模型任务运行期间,用户仍然可能:
- 删除片段;
- 修改源范围;
- 调整变速;
- 锁定轨道;
- 切换到其他素材。
因此,只在启动前检查一次是不够的。
这次实现会在提交分析或生成资产前,再检查源片段是否仍然有效,源时间映射是否发生变化,以及轨道是否允许处理。
如果源片段已经改变,任务不会把旧结果当作新片段的结果提交。
另一方面,完整深度分析与最终视频编码也有不同的生命周期。
编码失败或取消后,已经完成的分析可以保留,供下一次重试复用。但这不能被报告成“深度视频已经生成”。
分析缓存可复用,和媒体资产已交付,是两个不同的事实。
八、Skill 也必须写清楚执行边界
工具接入之后,还需要更新 Agent 使用的 Skill。
否则,Agent 可能知道“有深度能力”,却不知道:
- 打光分析完成后还要单独应用参数;
- 深度视频结果在资产库中;
- 哪些操作需要重新读取工程状态;
- 哪些任务能在本地 CLI 执行;
- 哪些任务必须进入浏览器。
这次同时更新了仓库中的 edit-timeline-studio Skill 和网站供 Agent 发现的浏览器 Skill。
执行边界也明确记录下来:
| 执行路径 | 当前能力 |
|---|---|
| 浏览器 WebMCP | 模型分析、深度视频生成、打光参数编辑与浏览器导出 |
| 本地 CLI / STDIO MCP | 通过共享命令检查、比较和修改打光设置 |
| 本地无界面渲染子集 | 尚不渲染这些打光效果,遇到启用的效果会明确拒绝 |
这种边界很重要。
文档里列出某个功能,并不意味着所有执行路径都已经支持它。不能让 Agent 在缺少渲染能力时,静默忽略效果并交付一个看似成功的文件。
九、这次验证了什么?
验证分为接口行为和真实媒体执行两部分。
接口行为检查覆盖了参数边界、轨道锁、分析就绪条件、语义差异、应用与撤销、重复启动去重,以及取消和源片段冲突处理。
真实浏览器验证使用 Chrome 与 WebGPU,运行了生产模型分析和深度转换。
其中一段 0.6 秒测试素材生成了:
- 320×240 深度视频;
- 15 个视频帧;
- 标称 24 fps;
- Opus 音频轨道。
打光前后的渲染采样确认了画面变化,确定性浏览器导出也生成了可解码的 H.264/AAC MP4。
此外,还验证了真实 Worker 任务取消、生成素材打包进 .timeline 工程、本地 CLI 参数保存,以及不支持的无界面渲染明确报错。
这些属于功能与集成验证,不是长视频性能基准,也不代表所有场景都已经完成视觉质量评估。复杂遮挡、快速运动、人物边缘和光照变化,仍需要按实际素材检查。
本次 npm run check 和 GitHub CI 均通过,保留现有的 79 条 lint 警告。
十、项目与代码
这次工作让我更明确地认识到:媒体编辑器接入 Agent,难点不仅在模型调用。
目标定位、源时间映射、任务状态、提交检查、编辑审阅和结果验证,都需要成为正式契约的一部分。
这些契约清楚之后,Agent 才能在同一个可编辑工程里完成工作,用户也能理解发生了什么,并继续修改结果。
这套实现已经随 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
如果你也在开发浏览器媒体工具、Agent 工具调用或 WebGPU 应用,欢迎查看代码、提交 Issue,或者分享类似的工程实践。