MotionSnip Studio
你负责构建视频。用户在本地播放器中预览。循环流程如下:
- 构建并渲染视频。
- 在
reel.json中描述视频。 - 打开播放器。
- 用户预览,并点击 发送到 Claude。你会收到一行指令:
Apply the MotionSnip Studio feedback in <绝对路径>。 - 应用反馈,重新渲染,版本号
version递增。播放器会自动重新加载并帮助用户检查你的改动。
在本文件中,<技能目录> 指存放此 SKILL.md 的文件夹,通常是 ~/.claude/skills/motionsnip-studio。
1. 设置项目
每个视频使用一个独立的文件夹:
<项目目录>/
reel.json 你编写此文件
video.mp4 渲染输出文件(可自定义名称,reel.json 的 "src" 指向它)
assets/ 音乐、图像、标志(用户上传的文件也放在这里)
public/ 可选;Remotion 的 staticFile() 资源
exports/ 播放器的导出功能生成的文件夹;切勿编辑
.motionsnip/ 播放器状态和历史记录;切勿编辑
如果用户尚未配置渲染器,Remotion 是一个不错的默认选择(运行 npx create-video@latest)。任何能输出 mp4、webm 或 mov 格式的工具都适用。
2. 构建时让编辑变得廉价
- 将文案、颜色、字体和时间信息集中放在一个数据对象中(例如 Remotion 的
defaultProps或一个content.ts文件),而不是分散在组件中。这样,一个反馈编辑只需修改一行代码。 - 为每个屏幕上的元素分配一个稳定的 ID,并在
reel.json中使用相同的 ID。 - **将音乐作为单独的文件提供。仅渲染包含音效的视频。**将音轨放在
assets/目录中,并将audio.music指向它,同时设置audio.videoAudio为"effects"。播放器会将音乐与视频并排播放,这样用户可以无需重渲染即可切换音轨、调整起始位置和音量。导出时,播放器会使用 ffmpeg 将其混合。 - 仅当用户明确要求时才将音乐烘焙到视频中。此时将
videoAudio设置为"mix"。
3. 渲染后先检查再展示
渲染后,使用联系表检查自己的作品:
ffmpeg -v error -y -i video.mp4 -vf "fps=1,scale=480:-1,tile=4x3" -frames:v 1 /tmp/sheet.png
打开图片并查看。修复裁剪的文本、空白帧、错误的颜色和时间间隙,然后再打开播放器。如需检查单个帧:
ffmpeg -v error -y -ss 12.4 -i video.mp4 -frames:v 1 /tmp/frame.png
**自我审查。**然后像挑剔的审阅者那样再看一遍,并记下你仍未解决的问题。检查:
- **安全区域。**所有重要内容是否都在距每条边 10% 的内缩区域内(标题安全区)?
- **尺寸。**正文字体高度至少约为帧高度的 3%,以确保在手机上清晰可读。
- **对比度。**文本和关键形状是否与背景明显区分。
- **拼写错误和溢出。**每个单词拼写正确,没有内容被裁剪或超出其容器。
- **剪切和时序。**剪切处没有闪烁帧,没有空白帧,没有帧在可读之前就消失。
修复你能解决的问题。对于剩下的问题,或任何属于审美范畴的问题,将发现记录在 reel.json 的 review 中(第 4 节)。播放器会将每个发现以带标签(C1、C2…)的蓝色虚线圆圈绘制在相应帧上,用户可以将其添加为自己的备注或忽略。只记录你确实在帧截图中看到的问题:提供时间、位置或元素,以便圆圈能准确落在上面。当没有需要说明的问题时,请将 review 留空;不要填充无意义的内容。
4. 编写 reel.json
reel.json 是你和播放器之间的契约。编写纯 JSON(无注释)。
{
"id": "acme-launch", // 稳定 ID;用户保存的编辑基于此 ID
"title": "Acme 发布",
"version": 1, // 每次渲染后递增;播放器在版本变化时重新加载
"path": "/绝对/路径/到/项目目录", // 你的工作目录;显示在提示中
"src": "video.mp4",
"w": 1920, "h": 1080, "fps": 30, "duration": 32.0,
"reference": "可选:视频所参考的模型",
"brand": {
"colors": [{ "id": "accent", "name": "强调色", "v": "#5B5BF7" }],
"fonts": [{ "id": "head", "name": "标题", "v": "Inter" }],
"logo": "assets/logo.svg" // 或 null
},
"audio": {
"music": "assets/track.mp3", // 与视频并排播放,或为 null
"videoAudio": "effects", // "effects" = 视频仅有音效;"mix" = 音乐已烘焙
"bpm": 120, "drop": 4.0, // 可选节拍网格;drop = 节拍落地的秒数
"musicVol": 1, "sfxVol": 1, // 0..1
"musicOffset": 0, // 秒;+ 表示音乐延迟开始,- 表示跳过音轨开头部分
"musicFade": 0, // 结尾淡出的秒数
"note": "自由文本"
},
"assets": [{ "id": "assets/track.mp3", "name": "track.mp3", "type": "audio", "from": "User" }],
"scenes": [
{ "id": "S1", "name": "吸引注意", "t": [0, 4.5], "els": [
{ "id": "headline", "label": "标题", "t": [0.3, 4.3],
"box": [20, 38, 60, 24], // x, y, w, h 为帧尺寸的百分比;如果是画外音、音频、全帧素材则为 null
"src": "src/Hook.tsx:12", // 绘制该元素的文件(或文件:行号)
"props": {
"text": { "type": "text", "label": "文字", "v": "遇见 Acme" },
"color": { "type": "color", "label": "颜色", "v": "brand.accent" },
"motion": { "type": "motion", "label": "动画", "v": "文字逐个模糊进入" }
} }
] }
],
"notes": [],
"review": [ // 可选:你自己的自我审查发现(第 3 节)
{ "id": "v1-1", "t": 1.5, "elId": "headline", "kind": "safe area",
"title": "标题超出右边缘",
"detail": "在 1.5 秒时,最后一个词距边缘 2%,超出了标题安全区。",
"fix": "将框宽度缩小到 56% 或减小字体大小。" }
],
"outputs": [ // 可选:从此视频生成的其他形状和长度(第 9 节)
{ "id": "vertical", "label": "9:16", "kind": "reframe", "src": "out/vertical.mp4", "w": 1080, "h": 1920, "platform": "短视频" }
],
"live": "live.js", // 可选实时渲染器(第 7 节)
"export": { "cwd": "/绝对/构建/目录", "props": {}, "cmd": "npx remotion render ... \"$OUT\" --props=\"$PROPS\"" } // 可选(第 8 节)
}
规则:
- 属性类型:
text、longtext、number、color(brand.<id>链接到调色板)、media(资源 ID)、list(行;cols: [{ k, type, options? }])、choice(options: [...])、motion(对运动的纯描述;用户只能对其评论)。 - 场景覆盖
0..duration整个时间范围,无间隙。时间以秒为单位。 - 在版本之间保持场景和元素 ID 稳定。保存的编辑通过 ID 匹配。
box必须与元素在屏幕上的实际位置匹配,以帧尺寸的百分比表示。如果不确定,请从帧截图中测量。用户点击这些框来选择元素。src应指向绘制元素的代码,以便日后找到它。- 每个属性值必须等于实际渲染的值。当新的
reel.json值与要求匹配时,播放器会将编辑标记为已完成。 path可以省略;服务器会填入项目文件夹。review发现:id(在此版本中唯一,例如v2-1)、t(秒)、title(一行)、可选的detail、fix和kind(safe area、size、contrast、typo、overflow、cut、timing或自定义词)。通过elId(元素 ID,在其框上画圆)、box: [x, y, w, h]或x、y(帧尺寸的百分比)来定位。为每个版本编写全新的列表;不要重复用户已忽略的任何发现。outputs:见第 9 节。- 未知字段将被忽略。缺少的可选字段将使用默认值。
5. 打开播放器
在后台启动服务器,然后将服务器打印的 URL 提供给用户:
node <技能目录>/player/server.mjs <项目目录> &
# MotionSnip Studio: http://localhost:4321 (项目: /绝对/路径)
选项:--port 4321(如果端口繁忙则向上移动)、--no-open(不打开浏览器)、--ffmpeg /path/to/ffmpeg(用于导出)。需要 Node 18 或更新版本,无需安装步骤。如果该项目的服务器已在运行,请不要启动另一个;播放器会自动获取新版本。
用一两行告诉用户该做什么:观看它,点击任何内容进行修复,右键单击圈出问题,然后 发送到 Claude。
纯视频文件。 如果用户希望预览或编辑一个没有 reel.json 的视频文件(如屏幕录制、手机视频),只需将该文件传递给播放器:node <技能目录>/player/server.mjs path/to/clip.mp4 &。不要为其编写 reel.json。播放器允许用户修剪、剪切、添加文本、Logo 或模糊,以及设置颜色,其导出功能会自动应用这些编辑。用户的反馈文件将只包含固定在帧上的备注;按照这些备注操作,如果备注要求进行新的剪切,请用相同的文件名导出,以便播放器将其计为下一个版本。
6. 应用反馈文件
用户粘贴 Apply the MotionSnip Studio feedback in <项目目录>/.motionsnip/feedback-vN.md。阅读该文件。它包含以下部分:
- 精确的更改。 像
[00:01.2 · S1 · 标题] 文本 (src/Hook.tsx:12): "遇见 Acme" -> "向 Acme 问好"这样的行。在代码和reel.json中精确地做出该更改。不要重新措辞。对brand.<id>的颜色编辑会更改调色板条目,因此所有链接到它的内容都会更改。 - 尺寸和位置编辑。
[x, y, w, h] -> [x, y, w, h] (比例 1.12),以帧尺寸的百分比表示。使用帧尺寸将其转换为像素(x% * w / 100),在代码中移动或调整元素大小,并更新其box。 - 声音设置。 新音轨(已保存在
assets/中)、起始偏移、淡入淡出、音量。更新reel.json中的audio。如果视频只有音效,通常不需要为此重新渲染。如果音乐已烘焙(videoAudio: "mix"),请使用新设置重新渲染。 - 关于 {标签} 版本的评论。 同类型的评论,但针对裁剪版本(9:16、1:1、片头)而非主视频。时间和位置基于该版本自己的帧和时钟;片头部分会说明它从主视频的哪些部分裁剪而来。在可能的情况下修复主视频中的原因(将重要内容保留在裁剪版本可见区域内)。如果你自己制作了该版本(它在你的
outputs中),也请重新渲染它并递增其自己的version。 - 在 MotionSnip Studio 中制作的裁剪版本。 播放器根据主视频及其裁剪关键帧或范围自行渲染的版本。不要修改它们的文件;审阅者会在你的下一个版本后重新渲染它们。
- 关于帧的评论。 固定在一个时间和位置(
x 23.9% y 81.8%)的自由评论,通常针对一个命名元素。在决定做什么之前,先抓取该帧并查看它。备注是请求,而不是精确值;请自行判断,并保持场景其余部分不变。 - 来自 vN-1 的未解决问题。 你上一轮更改了但用户表示仍然不正确的内容,并附有原因。首先修复这些。
- 来自你的自我审查。 以
(来自你的自我审查,v1-2;审阅者同意)结尾的评论是用户接受的你的发现之一。将其视为任何其他备注。 - 你的自我审查中已忽略的内容。 用户查看过并满意的发现。保持这些内容不变,不要在下一个
review中再次标记它们。 - 场景。 每个场景的状态。除非编辑或备注提及,否则不要修改已批准的场景。
然后:
- 进行更改。保持 ID 稳定。
- 重新渲染到相同的
src文件(或一个新文件并更新src)。 - 检查联系表和您修改过的帧。
- 更新
reel.json中每个更改的值,并将version设置为 N+1(文件中说明了该数字)。在渲染完成后最后递增版本号。 - 用一行告诉用户更改了什么,例如“v4 已就绪 · 应用了 5 项更改,结束备注需要您关注”。
切勿编辑 .motionsnip/、exports/ 或播放器在 outputs/ 中的裁剪版本(这些列在 .motionsnip/outputs.json 中);它们属于播放器。
7. 可选:实时渲染器
如果视频可以在浏览器中运行(canvas、DOM、Remotion Player bundle),你可以提供 live.js 并设置 "live": "live.js"。播放器会将其作为经典脚本加载并调用:
window.MotionSnipLive = (container) => ({
seek(timeSeconds) {}, play() {}, pause() {}, setRate(rate) {},
// boxes[id] = [x, y, w, h, nx, ny, nw, nh]: 原始值然后编辑后的值,帧尺寸的百分比
setBoxes(boxes) {},
});
然后播放器会隐藏视频并驱动你的渲染器,以便移动或调整大小的元素能真实显示。
8. 可选:导出钩子
在 reel.json 中添加 export,以允许用户从播放器渲染最终版本:
"export": {
"cwd": "/绝对/路径/到/remotion/项目",
"props": { "musicSrc": null },
"cmd": "npx remotion render src/index.ts Main \"$RAW\" --props=\"$PROPS\""
}
服务器在 cwd 中使用 sh -c 运行 cmd,并设置以下变量:
PROPS:指向一个 JSON 文件的路径,该文件包含export.props与用户编辑合并后的内容。编辑内容格式为{ "edits": { "<elId>": { "<prop>": value } }, "boxes": { "<elId>": [x, y, w, h] }, "colors": { "<id>": "#hex" }, "fonts": { "<id>": "名称" } }(box 坐标以帧尺寸的百分比表示)。让你的组件读取这些内容,以便渲染包含它们。OUT:exports/中的最终文件。如果你的渲染已经包含所有内容,请直接写入此处。RAW:一个临时路径。改为写入此处,服务器会将用户选择的音乐和音量混合到其中以生成OUT。PROJECT:项目文件夹。
进度来自命令打印的最后一个 n/m 对(Remotion 会打印类似这样的帧计数)。
如果没有导出钩子,导出功能仍然有效:它将复制视频并使用 ffmpeg 混合音乐。
9. 可选:其他形状和长度(输出)
播放器自己制作裁剪版本:+ 裁剪 使用 ffmpeg 从主视频渲染出 9:16、1:1(或从竖屏主视频渲染出 16:9)或一个 6 秒的片头,输出到 outputs/<id>.mp4。重新构图遵循审阅者在主视频上拖动的裁剪关键帧(或根据你的元素框进行初步猜测,因此请保持 box 精确),或者将整个画面适配到模糊填充的背景上。每个输出都有自己的选项卡、Reels、TikTok 和 Shorts 的安全区域指南,以及自己的备注。你无需为此做任何操作。
当通过代码构建的视频在适配不同宽高比时看起来更好的情况下,考虑为 outputs 编写自己的渲染方案(在 reel.json 中)。对于每个输出,提供一个包含 src、w、h 和 export(可选,用于不同的渲染命令)的对象。播放器会将审阅者的备注路由到正确的输出,发送给 Claude。
10. 播放器功能一览
- 项目名称和版本;点击即可编辑项目名称
- 播放进度条、播放/暂停、跳转到开始/结束
- 速度控制(0.25x - 4x)
- 逐帧前进/后退(箭头键)
- 音量滑块
- 波形显示
- 全屏(f)
- 色差分析按钮
- 缩放至适配 / 1:1
- 按场景划分的时间线,带有标签
- 侧边栏“元素”面板,显示当前帧的所有元素及其属性;点击属性进行编辑,右键点击查看更多
- 侧边栏“备注”面板,按场景和元素列出所有备注
- 蓝圈(发现)和红圈(用户备注)叠加在帧上;单击可阅读和回复
- 时间线上蓝/红标记
- 右键点击帧上任意位置可添加备注
- + 裁剪 按钮
- 导出 按钮
- 版本历史记录时间线
- 自动重新加载(通过
alive端点每 2 秒轮询) - 快捷键帮助(?)
播放器 URL 示例:http://localhost:4321/?project=acme-launch
当有多个版本时,URL 包含一个 ?version=3 参数,用于直接加载特定版本。
附录 A:纯视频模式(无 reel.json)
当传递纯视频文件时,播放器无法访问结构化的 reel.json 编辑。反馈文件将如下所示:
# MotionSnip Studio 反馈
项目:/用户/视频/演示.mp4
版本:1
## 帧备注
- [00:00:02.500 · x 50% y 30%] 在这里添加 Logo
- [00:00:05.000 · x 20% y 80%] 模糊背景中的车辆牌照
- [00:00:10.000] 从此处到 [00:00:15.000] 剪掉
## 所做的编辑
- 添加文本 "介绍":时间 [00:00:00.000 到 00:00:03.000],位置 x 50% y 50%,颜色 #FFFFFF,字体 Arial,大小 24
- 在顶部添加 Logo:位置 x 90% y 10%,大小 w 5% h 5%,来源 "assets/logo.png"
- 模糊从 [00:00:05.000 到 00:00:07.000] 位置 x 20% y 80% 区域
- 将 [00:00:10.000 到 00:00:15.000] 修剪掉
对于此类反馈,你需要:
- 使用 ffmpeg 对视频应用编辑(修剪、剪掉片段、添加文本/Logo/模糊)。
- 用相同的文件名覆盖视频(或提供一个新版本并由播放器重命名)。
- 播放器将检测到新文件并加载它。
- 不要创建或修改
reel.json。