scenario-video-assembly

场景视频组装

概述

Scenario 的 MCP 接口没有编辑工具。每个合成、拼接、修剪和字幕处理操作都是通过 model_run 运行的确定性模型。合成、拼接和修剪模型的 ID 是固定的，列于下文；Scenario 提供两种字幕处理模型，因此需通过 recommend 发现其中一个。连接方式和核心循环：参见 scenario 技能；视频片段本身：参见 scenario-video。如果你可用的技能中缺少这里提到的某个关联技能，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；若无人在场，则根据工具架构继续操作，并标明这一缺失。

快速参考：先选择后端

需求	模型
端到端拼接视频片段，可选转场	model_scenario-video-concat
任何需要重叠的内容：叠加、背景音轨、标题	model_scenario-compose-video
静态布局（缩略图、拼图、主视觉）	model_scenario-compose-image

这些 ID 是常量：每个都是 Scenario 针对相应操作提供的唯一确定性工具，因此发现过程只会重新推导出它。

拼接是顺序进行的：videos 接收 2 到 50 个文件（不能是 1 个），preserveAudio（默认值为 true）会将每个片段自带的音轨保留在剪辑中；可选的 transitions 数组长度必须等于视频数量减 1。每个数组项都是 {type, duration} 对象，而不是单独的字符串：type 是从架构中读取的 18 个名称之一（默认值 fade 是普通交叉淡化；dissolve 是另一种效果；none 表示硬切），duration 为 0.1 到 5 秒，默认值为 0.5。若全程使用硬切，则省略该数组；当需求没有要求镜头之间流畅衔接时，这始终是正确的做法。

preserveAudio 不保证同步：拼接后的成品曾出现音频与画面逐渐不同步的情况，无论是否使用转场（这是撰写本文时已确认的缺陷）。拼接带有对白或音效的片段后，必须核验，不能只凭信任：对输出调用 asset_get，将 properties.duration 与输入片段时长之和进行比较（每个转场最多会使成品时长缩短 duration 秒）；然后下载成品，检查音频流和视频流是否等长（本地检查下载文件属于检视，而非编辑），并确认某个可见提示（剪辑点、张嘴或撞击）与对应声音同步。若语音必须与画面保持同步，请改用 Video Studio 进行组装：每个片段图层都在其 startTime 携带自己的音轨，因此拼接不会引入不同步，但代价是只能使用硬切或逐图层淡入淡出，而不能使用转场组。拼接仍适用于无声片段，以及之后再添加背景音轨的剪辑。

Video Studio 使用绝对时间轴：layers 包含 1 到 50 个图像、视频或音频源，通过 startTime 放置，并通过 zIndex 排列层级（数值越高越靠前）；它提供逐图层的 fadeIn/fadeOut，而非片段间转场数组，因此两个片段之间的交叉淡化应使用拼接。至少有一个图层必须是视频，因此在静态图像上叠加音乐会被拒绝。

Video Studio 契约

每个图层都有三种名称容易混淆的时间概念：

• startTime 和 endTime 用于设定图层在时间线上的位置。
• trimStart 和 trimEnd 表示从源素材开头和末尾裁掉的时长，而不是入点和出点：若要播放一段 90 秒音轨的前 20 秒，请设置 trimEnd: 70。
• duration 用于覆盖图层的时长。顶层的 duration 是另一个字段，用于设定整个合成的时长，且仅在 durationMode 为 "custom" 时生效。

所有时间单位均为秒，精度为 step: 0.1，因此不要承诺帧级精准剪辑。x 和 y 是字符串，可以使用像素、百分比或方位词；anchor 用于指定图层上的哪个点作为定位点：top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right（中间的值直接写作 center），默认值为 "top-left"。将右下角的徽标贴边放置时，可设置 x: "right"、y: "bottom"、anchor: "bottom-right"；若要留出边距，可使用百分比。

canvasMode 和 durationMode 的默认值均为 "auto"，会根据图层计算得出：自定义画布需设置 canvasMode: "custom"，并提供数值类型的 canvasWidth 和 canvasHeight（没有顶层的 width/height，而且不同于图层中字符串类型的 width/height，这里的值是数字）；自定义时长需设置 durationMode: "custom"，并提供顶层的 duration。fit 仅对同时设置了图层自身 width 和 height 的图层生效，它们与 x 和 y 一样是字符串：若要调整视频片段的画面比例，请将两者都设为画布大小，并使用不带单位的像素数字字符串（width: "1920"、height: "1080"，这是架构中 "0" 默认值的格式；百分比字符串也可用），然后传入 "cover"（裁剪）或 "contain"（加黑边），因为默认的 "fill" 会拉伸画面。即使覆盖层的尺寸与原始尺寸相同，也请显式设置其 width 和 height：文档称留空会保留原尺寸，但实际结果并不可靠；例如，在 1920x1080 的画布上，一个 560x80 的条带最终变成了 1792x256。此处的输出字段是 videoOutputFormat；在 Image Studio 中是 imageOutputFormat，在 concat 和 trim 工具中则是 outputFormat。

图层的 type（image、video、audio 或 mask）为可选项，否则会根据 source 推断。这里没有文本图层，因此标题、下三分之一字幕和片尾卡片会以渲染后的 PNG 形式作为 image 图层合成；scenario-text-overlay 可将文本渲染得精准无误。

示例：三个片段、一段背景音乐和字幕

1. 对每个源素材调用 asset_get 并读取 properties：实际的 duration（音频也带有此属性）、视频的 frameRate，以及视频和图片的 width／height。即使要求模型生成八秒，返回内容也不一定恰好是八秒。
2. 将时长相加，得到每个片段的 startTime，然后对 model_scenario-compose-video 调用 model_schema_get。
3. 调用 model_run，让 layers 包含三个片段及其计算出的 startTime（zIndex: 0）、一个通过 x／y／anchor 固定位置且 zIndex: 1 的 Logo PNG，以及一条音频层形式的音乐，并用 trimEnd 将音乐裁剪至所有片段的总时长，因为自动 durationMode 会根据每一层计算时长，音乐也包括在内。volume（0 到 2）和 mute 是逐层设置的，也适用于视频层，因此可以从任一侧调整背景音乐音量。设置 canvasMode: "custom"，并指定 canvasWidth 和 canvasHeight；fps 默认值为 30，接受 1 到 120 的整数，因此若各片段的帧率一致（四舍五入后），就将其设为测得的 frameRate——这正是第 1 步读取它的原因。
4. 调用 jobs_wait，然后为剪辑成片添加字幕，而不是逐个片段添加：model_scenario-caption-studio（在创作时选择，因为 Scenario 提供两种字幕工具；请通过 recommend 重新发现）将成片作为 video，并转写母版实际包含的音频，因此应降低背景音乐的 volume，而不是静音对白。对于 Caption Studio，请遵循 scenario-caption-studio 中关于输入修正后的 SRT 和验证渲染字幕的说明，不要根据文件类型的 schema 推断上传方式：公开的 upload_asset 类型不包含文本。它默认会烧录字幕；当 outputSrt 为 true 时会返回旁路文件；并通过 textPosition（top、middle 或 bottom，默认值为 bottom，因此应将字幕移离底边叠加层）设置字幕位置。其他字幕工具则各有其当前的输入规范。
5. 调用 asset_display 检查，然后调用 asset_download 获取文件，format 保持未设置（它是图片转换目标）。

为便于移交修订，请保留无字幕母版、源素材、实际提交的图层载荷、测得的时长、旁白文本和语音设置、带可编辑版式设置的标题 PNG，以及任何修正后的 SRT 和返回的字幕主题。让输出 ID 与制作配置保持关联。只修改需要调整的图层，并从无字幕母版重新生成字幕；不要在已烧录字幕的导出文件上叠加新字幕。这些记录可用于重建，但不保证能生成原生编辑器项目，也不保证能在新环境中成功复现。

裁剪、拆分和调整大小各有自己的工具模型。注意，model_scenario-video-cut 的 startTime／endTime 表示源素材的入点和出点，而非时间线上的位置。

常见错误

• 使用 video_compose 之类的 MCP 工具，或用本地 ffmpeg 直接完成编辑。编辑接口是对工具模型调用 model_run；探测下载内容没有问题。
• 只给拼接工具一个片段，或每个片段都指定一个转场：至少需要 2 个视频，转场数量比片段少一个。
• 将此处的 dry_run 当作验证手段：它只会返回成本估算，而目录中的组装载荷在结构上最为复杂。
• 未检查同步情况就为拼接后的母版添加字幕：字幕工具会根据听到的音频为字幕行计时，因此音频有偏移时，字幕也会带着偏移一起输出。