scenario-video-assembly

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scenario Video Assembly

Scenario 视频组装

Overview

概述

Scenario has no editing tools on the MCP surface. Every compositor, concatenator, trimmer and captioner is a deterministic model run through

model_run

. The compositor, concatenator and trimmer ids are fixed and named below; Scenario ships two captioners, so that one is discovered with

recommend

. Connection and the core loop: see the

scenario

skill; the clips themselves: see

scenario-video

. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

Scenario在MCP表层没有编辑工具。所有合成器、拼接器、修剪器和字幕生成器都是通过

model_run

运行的确定性模型。合成器、拼接器和修剪器的ID是固定的，如下所列；Scenario自带两个字幕生成器，因此需要通过

recommend

来发现可用的那一个。连接方式与核心循环请参考

scenario

skill；片段本身的相关内容请参考

scenario-video

。如果你的可用技能中缺少此处提到的兄弟技能，请让用户安装它（命令：

npx skills add scenario-labs/skills --skill <name>

）；在无人值守的情况下，请根据工具schema继续操作并标记缺失的技能。

Quick reference: pick the backend first

快速参考：先选择后端模型

Need	Model
Clips end to end, optional transitions	`model_scenario-video-concat`
Anything overlapping: overlay, bed, titles	`model_scenario-compose-video`
Still layout (thumbnails, sheets, key art)	`model_scenario-compose-image`

These ids are constants: each is Scenario's single deterministic tool for its operation, so discovery would only re-derive it.

Concat is sequential:

videos

takes 2 to 50 files (never 1),

preserveAudio

(default true) carries each clip's own track into the cut, and the optional

transitions

array's "length must be number of videos - 1". Each entry is an object

{type, duration}

, never a bare string:

type

is one of 18 names read off the schema (

fade

, the default, is the plain crossfade;

dissolve

is a different effect;

none

a hard cut) and

duration

runs 0.1 to 5 seconds, default 0.5. Omit the array for hard cuts throughout, the right call whenever the brief does not ask one shot to flow into the next.

preserveAudio

is not a guarantee of sync: a concatenated cut has come back with its audio drifting against the picture, with and without transitions (a confirmed defect at authoring time). A concat of clips carrying dialogue or effects is verified, never trusted:

asset_get

the output and compare

properties.duration

with the inputs' sum (each transition shortens the cut by up to its

duration

), then download it and check that the audio and video streams run the same length (a local probe of the download is inspection, not editing) and that a visible cue (a cut, a mouth opening, an impact) lands on its sound. When speech must stay locked to the picture, assemble in Video Studio instead: each clip layer carries its own track at its

startTime

, so a drift introduced by joining has nowhere to arise, at the price of hard cuts or per-layer fades in place of the transition set. Concat stays the tool for silent clips and for cuts whose bed is laid afterwards.

Video Studio is an absolute timeline:

layers

holds 1 to 50 image, video or audio sources placed by

startTime

and stacked by

zIndex

(higher in front), with per-layer

fadeIn

fadeOut

rather than a between-clip array, so a cross-fade between two clips belongs in concat. At least one layer must be a video, so a music bed over a still is rejected.

需求	模型
片段首尾拼接，可选转场效果	`model_scenario-video-concat`
任何重叠内容：叠加、背景音、标题	`model_scenario-compose-video`
静态布局（缩略图、图集、主视觉）	`model_scenario-compose-image`

这些ID是常量：每个ID对应Scenario用于该操作的唯一确定性工具，因此执行发现操作也只会得到相同的结果。

拼接（Concat）是顺序执行的：

videos

参数接受2到50个文件（不能是1个），

preserveAudio

（默认值为true）会将每个片段的音轨保留到剪辑中，可选的

transitions

数组的“长度必须等于视频数量减1”。每个数组项都是一个

{type, duration}

对象，不能是纯字符串：

type

是schema中列出的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

，而非片段间的转场数组，因此两个片段之间的交叉淡入淡出应使用拼接工具实现。至少必须有一个图层是视频，因此不支持在静态图片上添加背景音乐。

The Video Studio contract

Video Studio 使用约定

Per layer, three timing ideas have confusable names:

```
startTime
```
and
```
endTime
```
place the layer on the timeline.
```
trimStart
```
and
```
trimEnd
```
are amounts shaved off the head and tail of the source, not in and out points: to play the first 20 seconds of a 90-second track, set
```
trimEnd: 70
```
.
```
duration
```
overrides the layer's length. The top-level
```
duration
```
is a different field, setting the whole composition, and applies only when
```
durationMode
```
is
```
"custom"
```
.

Everything is in seconds at

step: 0.1

, so do not promise frame-accurate cuts.

and

are strings taking pixels, percentages or words, and

anchor

says which point of the layer they address:

top-left

top-center

top-right

center-left

center

center-right

bottom-left

bottom-center

bottom-right

(the middle one is bare

center

), defaulting to

"top-left"

. A bottom-right logo is

x: "right"

y: "bottom"

anchor: "bottom-right"

, flush to the edge unless you inset it with a percentage.

canvasMode

and

durationMode

both default to

"auto"

, computed from the layers: a custom frame is

canvasMode: "custom"

plus numeric

canvasWidth

and

canvasHeight

(there are no top-level

width

height

, and unlike the layers' string

width

height

these are numbers), and a custom length is

durationMode: "custom"

plus the top-level

duration

fit

only acts on a layer that also sets the layer's own

width

and

height

, strings like

and

: to reframe a clip, set both to the canvas size as bare pixel numbers in strings (

width: "1920"

height: "1080"

, the form of the schema's own

"0"

default; a percent string also works) and pass

"cover"

(crops) or

"contain"

(letterboxes), since the default

"fill"

stretches. Give an overlay layer an explicit

width

and

height

even at its native size: leaving them empty is documented as preserving the original but does not reliably, and a 560x80 strip came back at 1792x256 on a 1920x1080 canvas. The output field is

videoOutputFormat

here,

imageOutputFormat

in Image Studio, and

outputFormat

in concat and the trim utilities.

A layer's

type

(image, video, audio, or mask) is optional and otherwise inferred from

source

. There is no text layer, so titles, lower thirds and end cards arrive as rendered PNGs composited as image layers;

scenario-text-overlay

renders them letter-perfect.

每个图层有三个容易混淆的时间相关概念：

```
startTime
```
和
```
endTime
```
用于在时间线上定位图层。
```
trimStart
```
和
```
trimEnd
```
是从源文件开头和结尾裁剪掉的时长，而非入点和出点：例如要播放一段90秒音轨的前20秒，需设置
```
trimEnd: 70
```
。
```
duration
```
会覆盖图层的时长。顶层的
```
duration
```
是另一个字段，用于设置整个合成作品的时长，仅当
```
durationMode
```
为
```
"custom"
```
时生效。

所有时间单位均为秒，精度为

step: 0.1

，因此不要承诺帧精确的剪辑。

和

是字符串类型，支持像素、百分比或关键词值，

anchor

指定坐标对应图层的哪个锚点：

top-left

、

top-center

、

top-right

、

center-left

、

center

、

center-right

、

bottom-left

、

bottom-center

、

bottom-right

（正中间是

center

），默认值为

"top-left"

。要放置右下角的Logo，可设置

x: "right"

、

y: "bottom"

、

anchor: "bottom-right"

，这样会紧贴边缘，除非用百分比值设置内边距。

canvasMode

和

durationMode

的默认值都是

"auto"

，由图层自动计算得出：自定义画幅需要设置

canvasMode: "custom"

以及数值类型的

canvasWidth

和

canvasHeight

（没有顶层的

width

height

字段，且与图层的字符串类型

width

height

不同，这两个字段是数值类型）；自定义时长需要设置

durationMode: "custom"

以及顶层的

duration

。

fit

仅对同时设置了自身

width

和

height

的图层生效，这两个字段和

、

一样是字符串类型：要重新调整片段的画幅，需将宽高都设置为画布尺寸的像素数值字符串（例如

width: "1920"

、

height: "1080"

，也就是schema默认值

"0"

的格式；百分比字符串也可以），并传入

"cover"

（裁剪）或

"contain"

（信箱模式），因为默认值

"fill"

会拉伸画面。即使叠加图层使用原始尺寸，也要显式设置

width

和

height

：文档中说留空会保留原始尺寸，但这并不可靠，曾出现过560x80的长条在1920x1080画布上变成1792x256的情况。此处的输出字段是

videoOutputFormat

，Image Studio中是

imageOutputFormat

，拼接和修剪工具中是

outputFormat

。

图层的

type

（image、video、audio或mask）是可选的，未设置时会从

source

推断。没有文本图层，因此标题、下方三分之一字幕条和片尾卡需要先渲染为PNG文件，再作为图像图层合成；

scenario-text-overlay

可以完美渲染这些文字内容。

Worked example: three clips, a music bed, and captions

实操示例：三个片段、背景音乐加字幕

For every source,
```
asset_get
```
and read
```
properties
```
: the real
```
duration
```
(audio carries it too),
```
frameRate
```
on video, and
```
width
```
/
```
height
```
on video and images alike. A model asked for eight seconds does not always return exactly eight.

Add them up to get each clip's

startTime

, then

model_schema_get

model_scenario-compose-video

```
model_run
```
it with
```
layers
```
holding the three clips at their computed
```
startTime
```
s (
```
zIndex: 0
```
), a logo PNG pinned by
```
x
```
/
```
y
```
/
```
anchor
```
at
```
zIndex: 1
```
, and the music as an audio layer trimmed to the clips' total with
```
trimEnd
```
, since auto
```
durationMode
```
computes from every layer, the bed included.
```
volume
```
(0 to 2) and
```
mute
```
are per-layer and apply to video layers too, so balance the bed from either side. Set
```
canvasMode: "custom"
```
with
```
canvasWidth
```
and
```
canvasHeight
```
;
```
fps
```
defaults to 30 and takes whole numbers from 1 to 120, so set it to the clips' measured
```
frameRate
```
when they agree (rounded), which is what step 1 read it for.
```
jobs_wait
```
, then caption the finished cut rather than each clip:
```
model_scenario-caption-studio
```
(an authoring-time pick, since Scenario ships two captioners: re-discover with
```
recommend
```
) takes it as
```
video
```
and transcribes whatever audio the master actually carries, so lower the bed's
```
volume
```
rather than muting the dialogue. It burns captions in by default, takes an existing
```
.srt
```
as
```
subtitles
```
, a file input needing
```
upload_asset
```
first, returns a sidecar when
```
outputSrt
```
is true, and positions them with
```
textPosition
```
(
```
top
```
,
```
middle
```
or
```
bottom
```
, default
```
bottom
```
, so move it off a bottom-edge overlay).
```
asset_display
```
to review, then
```
asset_download
```
with
```
format
```
left unset (it is an image conversion target) for the file.

Trim, split and resize have their own tool models. Note

model_scenario-video-cut

startTime

endTime

are source in and out points, not timeline placement.

对每个源文件，调用
```
asset_get
```
并读取
```
properties
```
：真实的
```
duration
```
（音频也有该字段）、视频的
```
frameRate
```
，以及视频和图片的
```
width
```
/
```
height
```
。模型生成的8秒内容不一定刚好是8秒。
将时长相加得到每个片段的
```
startTime
```
，然后调用
```
model_schema_get
```
获取
```
model_scenario-compose-video
```
的schema。
调用
```
model_run
```
运行该模型，
```
layers
```
中包含：三个片段按计算出的
```
startTime
```
放置（
```
zIndex: 0
```
），一个Logo PNG通过
```
x
```
/
```
y
```
/
```
anchor
```
固定在
```
zIndex: 1
```
的位置，音乐作为音频图层通过
```
trimEnd
```
裁剪到与片段总时长一致——因为自动
```
durationMode
```
会根据所有图层（包括背景音）计算时长。
```
volume
```
（0到2）和
```
mute
```
是逐层设置的，也适用于视频图层，因此可以从任意一侧调整背景音的平衡。设置
```
canvasMode: "custom"
```
并指定
```
canvasWidth
```
和
```
canvasHeight
```
；
```
fps
```
默认值为30，支持1到120的整数，因此当所有片段的
```
frameRate
```
一致时（取整后），将其设置为该值，这也是步骤1读取帧率的目的。
调用
```
jobs_wait
```
等待任务完成，然后给成品剪辑添加字幕（而非逐个片段添加）：
```
model_scenario-caption-studio
```
（这是编写本文时的选择，因为Scenario自带两个字幕生成器，可通过
```
recommend
```
重新发现可用版本）将视频作为
```
video
```
参数传入，会转录母版实际携带的所有音频，因此只需降低背景音的
```
volume
```
，而不要静音对话。该模型默认烧录字幕，支持传入现有
```
.srt
```
文件作为
```
subtitles
```
（文件输入需要先调用
```
upload_asset
```
上传），当
```
outputSrt
```
为true时会返回侧载字幕文件，并通过
```
textPosition
```
设置字幕位置（
```
top
```
、
```
middle
```
或
```
bottom
```
，默认
```
bottom
```
，因此如果底部有叠加层，需要调整字幕位置）。
调用
```
asset_display
```
进行审核，然后调用
```
asset_download
```
下载文件，无需设置
```
format
```
参数（该参数用于图片格式转换）。

修剪、分割和调整大小有各自的工具模型。注意

model_scenario-video-cut

的

startTime

endTime

是源文件的入点和出点，而非时间线上的位置。

Common mistakes

常见错误

Reaching for an MCP tool like
```
video_compose
```
, or for local ffmpeg to do the edit itself. The editing surface is
```
model_run
```
on tool models; probing a download is fine.
Handing concat one clip, or one transition per clip: the minimum is 2 videos, and transitions run one fewer.
Trusting
```
dry_run
```
here as validation: it returns a cost estimate only, and assembly payloads are the most structurally complex in the catalog.
Captioning a concatenated master before checking its sync: the captioner times its lines to the audio it hears, so drifted audio ships drifted captions on top of it.

试图使用
```
video_compose
```
之类的MCP工具，或者用本地ffmpeg进行编辑。编辑操作的入口是对工具模型调用
```
model_run
```
；对下载文件进行检测是可以的。
给拼接工具传入1个片段，或者转场数量和片段数量相同：最少需要2个视频，转场数量比视频数量少1。
信任
```
dry_run
```
的验证结果：它仅返回成本估算，而组装请求的payload是所有工具中结构最复杂的。
在检查拼接母版的音画同步之前就添加字幕：字幕生成器会根据听到的音频来计时字幕行，因此漂移的音频会导致字幕也跟着错位。