motion-broll

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Motion B-roll

动态图形B-roll

You make motion-graphic clips for a creator's video. Every clip is one shape that never cuts: it morphs its size, corners and colour from state to state while its content swaps with a short blur. A cursor drives the changes with real clicks and drags, and every change lands on a spoken word.

The output is a set of clips the creator drops into their editor. You also give them a preview render of their video with the clips cut in, and two HTML pages: one to step through the clips, one to compare before and after.

Everything you need is in this skill folder:

```
engine/
```
: the motion engine (
```
motion.js
```
), the page shell (
```
base.css
```
),
```
build.py
```
(clip → self-contained HTML),
```
render.js
```
(frame-by-frame render with motion blur),
```
beats.js
```
(contact sheets of stills), fonts (Geist, OFL).

scripts/

setup.sh

inspect_video.py

words.py

composite.py

make_pages.py

```
reference/engine-api.md
```
: how to write a clip. Read it before writing your first clip.
```
examples/opus-aoe2/
```
: six finished clips for a real 54-second video. Use them as the quality bar and as starting points.

Below,

$SKILL

means this skill's folder. Work in a

motion/

folder in the user's project.

你将为创作者的视频制作动态图形片段。每个片段都是无镜头切换的单形状形态：它的大小、圆角和颜色会在不同状态间变形，同时内容会通过短暂模糊进行切换。由光标通过真实的点击和拖拽驱动变化，且每一次变化都精准对应说话人的某个词语。

输出内容是一组可直接导入剪辑软件的片段。你还会提供嵌入了这些片段的视频预览渲染文件，以及两个HTML页面：一个用于逐段查看片段，一个用于对比前后效果。

所有需要的资源都在这个技能文件夹中：

```
engine/
```
：动效引擎（
```
motion.js
```
）、页面框架（
```
base.css
```
）、
```
build.py
```
（将片段转换为独立HTML文件）、
```
render.js
```
（带动效模糊的逐帧渲染）、
```
beats.js
```
（生成静态帧联系表）、字体（Geist、OFL）。

scripts/

：包含

setup.sh

、

inspect_video.py

、

words.py

、

composite.py

、

make_pages.py

等脚本。

```
reference/engine-api.md
```
：片段编写指南。编写第一个片段前请务必阅读。
```
examples/opus-aoe2/
```
：为一个真实的54秒视频制作的6个完成版片段。可将其作为质量标准和参考模板。

下文的

$SKILL

指代此技能的文件夹。请在用户项目的

motion/

文件夹中开展工作。

1. Set up (first run only)

1. 环境搭建（仅首次运行需要）

bash

bash $SKILL/scripts/setup.sh ./motion

This checks for Node, Python 3 and ffmpeg, and installs Playwright + Chromium into

motion/node_modules

. Run every engine script with

NODE_PATH=./motion/node_modules

bash

bash $SKILL/scripts/setup.sh ./motion

该脚本会检查Node、Python 3和ffmpeg是否已安装，并将Playwright + Chromium安装到

motion/node_modules

中。运行所有引擎脚本时都需加上

NODE_PATH=./motion/node_modules

。

2. Interview

2. 需求确认

Use the AskUserQuestion tool; keep it to one round. You need:

The video. A path. Copy or reference it as
```
motion/work/source.*
```
.
The transcript. An SRT or VTT with timestamps is best. With plain text only, get word timestamps from the audio (
```
pip install faster-whisper
```
) or ask for an SRT.
Density:
- Light: 2–4 clips per minute, only the strongest moments.
- Medium (default): 4–7 per minute.
- Heavy: most lines covered, with short gaps of face.
Look:
- The default palette: warm gray canvas, black and white components, one orange accent.
- Or their brand: colours, and optionally a font. Ask them to drop a logo, screenshots or brand colours into
```
motion/inputs/
```
  , and read those.
Anything to avoid or include. Lines to leave on their face, real numbers or names to show, product screenshots to recreate.

Skip any question the user already answered.

使用AskUserQuestion工具，仅进行一轮询问。你需要收集以下信息：

视频文件：文件路径。将其复制或引用为
```
motion/work/source.*
```
。
字幕文件：最好是带时间戳的SRT或VTT格式。如果只有纯文本，可从音频中提取词语时间戳（
```
pip install faster-whisper
```
），或要求用户提供SRT文件。
片段密度：
- 轻度：每分钟2-4个片段，仅覆盖最核心的内容点。
- 中等（默认）：每分钟4-7个片段。
- 高密度：覆盖大部分台词，仅保留短暂的说话人镜头。
视觉风格：
- 默认配色：暖灰色画布、黑白组件、单个橙色强调色。
- 或使用用户的品牌风格：包括品牌色，可选自定义字体。请用户将logo、截图或品牌色值放入
```
motion/inputs/
```
  文件夹，然后读取这些资源。
特殊要求： 需要保留说话人镜头的台词、需要展示的真实数据或名称、需要还原的产品截图等。

用户已经回答过的问题无需再问。

3. Inspect the footage

3. 视频素材检查

bash

python3 $SKILL/scripts/inspect_video.py motion/work/source.mp4 motion/work
python3 $SKILL/scripts/words.py transcript.srt > motion/work/words.txt

Look at

motion/work/contact.png

yourself.

video.json

gives resolution, fps and layout sections:

full: the speaker fills the frame.
pip: the speaker is in a box and the rest is empty. It includes the box position and a warning if the box changes size or moves.

Clips must match the video's resolution and fps. Word times from an SRT are estimates (±0.2s); treat them as such.

bash

python3 $SKILL/scripts/inspect_video.py motion/work/source.mp4 motion/work
python3 $SKILL/scripts/words.py transcript.srt > motion/work/words.txt

请自行查看

motion/work/contact.png

。

video.json

文件包含分辨率、帧率以及画面布局信息：

全屏： 说话人占满整个画面。
PiP： 说话人位于一个框内，其余区域为空。该信息包含框的位置，如果框的大小变化或移动会给出警告。

片段必须与视频的分辨率和帧率保持一致。SRT文件中的词语时间戳为估算值（误差±0.2秒），需酌情使用。

4. Plan, and get approval before any code

4. 制定方案，编写代码前需获得用户确认

Show a table with one row per clip:

Creative direction: decide how much of the frame each clip takes. This is the most important call; make it per clip and give the reason.

Full-frame cutaway. The frame is all speaker, and the line describes something to see: a product, a process, a comparison, a number, a chapter change.
- Cut away for the length of the idea (3–10s), then give the face back.
- Don't cut away in the first second of the hook or on personal, emotional or opinion lines.
- Leave at least ~2s of face between cutaways.
Panel in the empty space. The edit already leaves room: a PiP box, a split, a plain region.
- Render a transparent clip (
```
bg:null
```
  ) centred in the empty area, sized to stay clear of the speaker's box at every moment.
- It can run long (15s+) as one continuous morph, because the speaker stays on screen.
- If
```
inspect_video.py
```
  reports the box changing, ask whether that's intended, then size for the largest box or split the panel at the change.
Nothing. The line is about the speaker, or it's too close to another clip.

Content rules:

Show the subject's real objects: the folder, the terminal, the file, the product, the result. Pull them from the words. Map each idea onto an interaction from the vocabulary in
```
reference/engine-api.md
```
(pill + click, progress, check, status island, card with a drag, slider, toggle, tabs, chart + tooltip, search/filter, file drag-and-drop, terminal typing, side-by-side comparison, chapter card).
Never invent numbers, quotes, prices or results. Use relative bars, skeleton text lines or labels taken from the transcript, and list what is illustrative. Put real figures in only when the user gives them.
One idea per clip. A continuous stretch (a whole PiP section) can be one long clip with several states.
Pace to speech, not music: one change per spoken beat, about 0.4–1.2s apart.

Wait for the user to approve or edit the plan.

展示一个表格，每个片段占一行：

创作方向：确定每个片段占用的画面比例。 这是最重要的决策，需为每个片段单独确定并说明理由。

全屏插播。 原画面为说话人全屏镜头，且台词描述的是需要可视化的内容：产品、流程、对比、数字、章节切换等。
- 插播时长与内容点长度匹配（3-10秒），之后切回说话人镜头。
- 不要在开篇钩子的第一秒切走，也不要在个人化、情绪化或表达观点的台词处切走。
- 两个插播之间至少保留约2秒的说话人镜头。
空白区域面板。 原视频已经预留了空间：比如PiP框、分屏、空白区域。
- 渲染透明背景的片段（
```
bg:null
```
  ），居中放置在空白区域，大小需确保始终不会遮挡说话人的框。
- 因为说话人始终在画面中，这类片段可以做得很长（15秒以上），作为一个连续的变形动画。
- 如果
```
inspect_video.py
```
  报告框的位置有变化，需询问用户是否为预期效果，然后按最大的框尺寸调整面板大小，或在变化处拆分面板。
不添加片段。 该台词是关于说话人本身的，或者距离上一个片段太近。

内容规则：

展示主题相关的真实对象：文件夹、终端、文件、产品、结果等。从台词中提取这些内容。将每个创意点映射到
```
reference/engine-api.md
```
中定义的交互组件（药丸按钮+点击、进度条、勾选、状态岛、可拖拽卡片、滑块、开关、标签页、图表+提示框、搜索/筛选、文件拖拽、终端打字、并排对比、章节卡片）。
严禁编造数字、引用、价格或结果。 使用相对条形图、骨架屏文本行或从字幕中提取的标签，并注明哪些是示意性内容。仅当用户提供真实数据时才使用。
每个片段只表达一个创意点。一段连续的空白区域（比如整个PiP段落）可以做成一个包含多个状态的长片段。
节奏跟随语音而非音乐：每个语音节拍对应一个变化，间隔约0.4-1.2秒。

等待用户确认或修改方案。

5. Build

5. 构建

Write one fragment per clip in

motion/clips/NN-name.html

, following

reference/engine-api.md

and the examples. Then build:

bash

python3 $SKILL/engine/build.py motion/dist motion/clips/*.html

Put each state change on its word: clip-local time = word time − clip in-point.

按照

reference/engine-api.md

和示例的要求，在

motion/clips/NN-name.html

中为每个片段编写一个片段文件。然后执行构建：

bash

python3 $SKILL/engine/build.py motion/dist motion/clips/*.html

将每个状态变化对应到相应的词语上：片段内时间 = 词语时间 − 片段入点时间。

6. Check stills on the key words

6. 检查关键词对应的静态帧

bash

NODE_PATH=./motion/node_modules node $SKILL/engine/beats.js motion/dist/NN-name.html motion/work/NN.png 0.4 1.2 2.1 …

Pick the times where each state has settled and a couple of mid-morph moments. Look at every sheet yourself. Fix anything cramped, clipped, unreadable or off-word, or where the cursor leaves the frame. Then check once more. Panel clips render on black in the sheet so you can judge them.

bash

NODE_PATH=./motion/node_modules node $SKILL/engine/beats.js motion/dist/NN-name.html motion/work/NN.png 0.4 1.2 2.1 …

选择每个状态稳定后的时间点，以及几个变形中间的时刻。请逐张查看所有联系表。修复任何拥挤、裁切、不可读、与词语不同步，或光标超出画面的问题。然后再次检查。面板类片段在联系表中会以黑色背景渲染，方便你判断效果。

7. Render

7. 渲染

bash

NODE_PATH=./motion/node_modules node $SKILL/engine/render.js motion/dist/NN-name.html motion/out/NN-name_0m32s40.mp4 30000/1001

Use the video's fps.
Panel clips (
```
bg:null
```
) must be written to
```
.mov
```
, which gives ProRes 4444 with alpha.
Name each file by its timeline in-point (
```
0m32s40
```
= 0:32.40).
Rendering takes 4 subframes per frame, so it is slower than real time. Run two clips in parallel on a multi-core machine.

bash

NODE_PATH=./motion/node_modules node $SKILL/engine/render.js motion/dist/NN-name.html motion/out/NN-name_0m32s40.mp4 30000/1001

使用原视频的帧率。
面板类片段（
```
bg:null
```
）必须输出为
```
.mov
```
格式，即带Alpha通道的ProRes 4444编码。
每个文件按其在时间线上的入点命名（
```
0m32s40
```
= 0分32.40秒）。
渲染时每帧会生成4个子帧，因此速度慢于实时。在多核机器上可同时渲染两个片段。

8. Deliver

8. 交付

Write

motion/plan.json

(schema in

reference/engine-api.md

), then:

bash

python3 $SKILL/scripts/composite.py motion/plan.json motion/out/preview.mp4
python3 $SKILL/scripts/make_pages.py motion/plan.json motion/out/preview.mp4

The user gets, all in

motion/out/

the clips
```
TIMING.md
```
: file, in, out, the line it covers, the treatment, and what is illustrative
```
preview.mp4
```
: their video with the clips cut in, hard cuts, original audio
```
viewer.html
```
: step through the clips
```
compare.html
```
: original vs preview, synced, as side by side, stacked or wipe

Say plainly that the preview is for review: for the final cut they place the clips in their own editor, where they can nudge timing, add transitions and mix audio.

编写

motion/plan.json

（格式定义见

reference/engine-api.md

），然后执行：

bash

python3 $SKILL/scripts/composite.py motion/plan.json motion/out/preview.mp4
python3 $SKILL/scripts/make_pages.py motion/plan.json motion/out/preview.mp4

用户将获得以下文件，全部存放在

motion/out/

目录中：

所有片段文件
```
TIMING.md
```
：包含文件名、入点、出点、覆盖的台词、呈现方式以及示意性内容说明
```
preview.mp4
```
：嵌入了片段的预览视频，采用硬切，保留原始音频
```
viewer.html
```
：用于逐段查看片段的页面
```
compare.html
```
：原始视频与预览视频的同步对比页面，支持并排、堆叠、擦除等对比方式

需明确告知用户该预览仅用于审核：最终剪辑时需将片段导入他们自己的剪辑软件中，可在其中微调时间、添加转场和混音。

Style defaults

默认样式

The user's brand overrides these.

Colour: canvas
```
#E9E7E2
```
, ink
```
#0B0B0B
```
, white components, one accent
```
#FF5A1F
```
. Panel clips on dark footage use light shapes (
```
#F4F2EE
```
).
Type and icons: Geist for UI text, Geist Mono for code, file names and terminals. One icon set with one stroke weight (
```
M.icon
```
).
Motion: springs with a tiny overshoot at most. Leading and trailing edges ride different springs so indicators stretch. The camera zooms so each state fills the frame.
Banned: bouncy easing, particles, glows, gradients on UI chrome, mixed icon strokes, dead time, anything that looks like a template, made-up data.

用户的品牌风格会覆盖这些默认设置。

颜色： 画布色
```
#E9E7E2
```
、文字色
```
#0B0B0B
```
、白色组件、单个强调色
```
#FF5A1F
```
。用于深色素材的面板类片段使用浅色形状（
```
#F4F2EE
```
）。
字体与图标： UI文本使用Geist字体，代码、文件名和终端使用Geist Mono字体。统一使用单描边粗细的图标集（
```
M.icon
```
）。
动效： 弹簧动画最多带有轻微的过冲效果。前后边缘使用不同的弹簧参数，因此指示器会有拉伸效果。相机会缩放以让每个状态填满画面。
禁用效果： 弹性缓动、粒子效果、发光、UI控件上的渐变、混合描边粗细的图标、空白停顿、任何模板感强的效果、编造的数据。

Gotchas

注意事项

Never put
```
will-change
```
on anything the camera scales; text renders blurry.
Text swapping inside a morphing container needs its own enter and exit timing (
```
M.vis
```
din/lin/lout), or the old and new text overlap.
```
mix-blend-mode: difference
```
labels must sit in a layer that has the blend mode itself. A filtered parent isolates them.
Items that slide under a highlight need
```
M.FAST
```
springs, or the highlight row sits empty for a moment.
Keep the cursor inside the frame at every camera zoom, including during morphs.
Word estimates from an SRT drift within a cue; put important changes on the first or last word of a cue when you can.
A clip ends by holding its last state; the composite holds the last frame if its slot is longer.

绝对不要在相机会缩放的元素上使用
```
will-change
```
，否则文字会渲染模糊。
变形容器内的文本切换需要单独的进入和退出时序（
```
M.vis
```
din/lin/lout），否则新旧文本会重叠。
使用
```
mix-blend-mode: difference
```
的标签必须位于自身带有该混合模式的层中。需通过一个带滤镜的父元素将其隔离。
在高亮条下方滑动的元素需使用
```
M.FAST
```
弹簧，否则高亮行会有短暂的空白。
在所有相机缩放场景下（包括变形过程中），都要确保光标在画面内。
SRT中的词语时间估算在一个字幕条内会有偏差；尽量将重要的变化放在字幕条的第一个或最后一个词语上。
片段结束时会保持最后一个状态；如果片段的时间槽更长，合成时会保持最后一帧。