Communitygithub.com

MotionSnip Studio 动效剪辑工作室

以代码构建动态图形,并在 MotionSnip Studio 本地播放器中预览、修改与迭代。适用于用户要求创建动态图形、宣传视频、产品演示或类似需用代码(如 Remotion 等渲染器)制作视频的场景。

MotionSnip Studio 动效剪辑工作室 是什么?

MotionSnip Studio 是一个 AI 智能体技能,旨在将动态图形(motion graphics)的构建、预览和迭代流程本地化、自动化。它通过一个`reel.json`清单文件、一个本地播放器服务器以及用户反馈驱动的编辑循环,让 AI 助手能够高效地协作制作视频。该技能支持任何能输出 MP4、WebM 或 MOV 格式的渲染工具(默认推荐 Remotion),并鼓励将内容(文案、颜色、字体等)集中在单一数据对象中,以实现低成本的快速编辑。工作流程是:AI 构建并渲染视频,播放器供用户预览,用户通过点击或圈选问题并一键“发送到 Claude”给出反馈,AI 读取一个标记文件(feedback-vN.md),精确应用这些编辑,然后重新渲染并递增版本号。自动生成的用户反馈文件会包含精确的文本改动、位置/大小调整、音频设置以及时间轴上的注释,AI 负责定位代码并进行精确修改。此外,播放器还能自动化处理多平台适配(如 9:16 竖屏裁剪)、音频替换(音乐与视频分离,无需重渲染即可换曲)、以及帧安全区域检查,大幅减少了手动编辑和重新渲染的时间。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jishanpathan7/motionsnip-studio/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

MotionSnip Studio

你负责构建视频。用户在本地播放器中预览。循环流程如下:

  1. 构建并渲染视频。
  2. 在 reel.json 中描述视频。
  3. 打开播放器。
  4. 用户预览,并点击 发送到 Claude。你会收到一行指令:Apply the MotionSnip Studio feedback in <绝对路径>。
  5. 应用反馈,重新渲染,版本号 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 中再次标记它们。
  • 场景。 每个场景的状态。除非编辑或备注提及,否则不要修改已批准的场景。

然后:

  1. 进行更改。保持 ID 稳定。
  2. 重新渲染到相同的 src 文件(或一个新文件并更新 src)。
  3. 检查联系表和您修改过的帧。
  4. 更新 reel.json 中每个更改的值,并将 version 设置为 N+1(文件中说明了该数字)。在渲染完成后最后递增版本号。
  5. 用一行告诉用户更改了什么,例如“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] 修剪掉

对于此类反馈,你需要:

  1. 使用 ffmpeg 对视频应用编辑(修剪、剪掉片段、添加文本/Logo/模糊)。
  2. 用相同的文件名覆盖视频(或提供一个新版本并由播放器重命名)。
  3. 播放器将检测到新文件并加载它。
  4. 不要创建或修改 reel.json。

相关技能