Communitygithub.com

oleg-motion

将静态图像转化为精致的动态效果——循环横幅、动画广告、故事、电影级短片(MP4/WebM/GIF)。支持平面 JPG/PNG(自动分割为背景、主体和文字层,带景深)、分层 PSD 或 PNG 层文件夹,并添加视差/2.5D 摄像机运动、粒子效果(雪、叶、尘、五彩纸屑、散景)、光效(扫光、星芒、耀斑、辉光)以及文字/产品动画,同时保持价格、标志和法律文本清晰。

oleg-motion 是什么?

oleg-motion 是一个用于 AI 代理(如 Claude Code、Cursor、Codex)的技能,可将静态图像转换为确定性的循环动画,生成 MP4、WebM 或 GIF 格式的视频。它通过无头 Chrome 逐帧渲染 HTML 场景,并使用 ffmpeg 编码,确保循环闭合精确且渲染可重现。该技能支持多种输入格式:平面 JPG/PNG(通过 ML 自动分层)、PSD 或 PNG 层文件夹,以及手动定义区域。用户可通过简短的问答流程定义动画特征(比例、情绪、结构、主要元素),然后生成运动计划,并基于该计划创建最终场景。参数如视差幅度、粒子数量和光效强度均可调整,以匹配品牌风格或临场需求。该技能针对 Mac 进行了优化,但所有核心依赖项均自动下载,无需管理员权限或 Homebrew。它强化了专业运动设计规则:仅限一种主要运动,价格、法律文本和标志保持静止,避免人物假动作,使用小幅度运动,并确保循环完整周期。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bonchuk/oleg-motion/tree/HEAD

在你喜欢的 AI 中提问

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

文档

oleg-motion 是做什么的?

从静态图像生成的确定性运动设计:通过无头 Chrome 逐帧渲染 HTML 场景,再由 ffmpeg 编码。一切都是时间的纯函数,因此循环精确闭合且渲染可重现。使用用户的语言进行交流;文件名和场景 JSON 保留英文。

下文中的 $OM 表示该技能所在的目录(包含此 SKILL.md 的文件夹)。

0. 确保它可用(每台机器仅一次)

通过启动器 $OM/om 运行所有内容——它会将该技能自带的 Node、ffmpeg 和 Python 置于 PATH 最前面,因此即使在没有开发者工具的干净 Mac 上也能工作。

$OM/om doctor              # 检查已安装的内容
bash $OM/scripts/setup.sh  # 核心:Node.js、ffmpeg、渲染引擎(下载缺失项)
$OM/om setup --psd         # + PSD 导入
$OM/om setup --ml          # + 平面图像的自动分层(约 1GB,含模型)
$OM/om update              # 从 GitHub 获取最新版本(无需 git),然后重新安装

设置过程无需管理员密码、Homebrew 或 git:缺失的工具会下载到 ~/.cache/oleg-motion/tools(可通过 OLEG_MOTION_HOME 覆盖文件夹);若机器上已有合格的工具,则直接使用。单靠核心就能为任意图像添加动画(摄像机、粒子、光效、叠加层)。在运行 --ml 前需先征得同意——它会下载模型。如果 om 不可执行(从 zip 包解压),请使用 bash $OM/om … 调用。

1. 简报——先观察,再用可点击选项提问

用户通常直接丢来一个文件并说“让它动起来”。大多数人无法用语言描述动态效果,因此不要提开放性问题——请先自己查看图像(打开它),列出其中的元素(标题、价格、按钮、标志、照片、产品、箭头……),然后再提问。

品牌套件优先。 如果请求中提到了品牌/项目,或者工作文件夹中存在 *.brand.json / oleg-motion.brand.json,或者 $OM/brands/ 中有匹配的套件,请加载它并将 --brand 参数传递给 scene:它的默认值能回答大部分问题(跳过这些),并且其 protect / avoid / notes 是硬性规则。格式参考:references/brand-kit.md。尚无套件?可在交付时提供保存选项(第 6 步)。

永远不要询问工艺细节——时间、缓动、幅度、交错、粒子数量等都有专业默认值(参考:references/motion-guidelines.md)。仅当用户主动询问时才修改。每个问题都应提供一个用户可以简单接受的默认值。

当用户说“просто зроби” / “just do it” / “on your own”,或者请求中已包含答案时,跳过所有问题:选择默认值并用一行说明即可。

否则,一次性提问,附带选项——尽可能使用 AskUserQuestion 工具(点击式卡片;否则用一条消息带编号选项)。最多提 4 个问题,每个问题都基于你在图像中看到的内容,将推荐选项放在第一位:

  1. 它将用于哪里? → 配置:"як є — не змінювати пропорції"(source:原始宽高比,长边上限为 1920 px)、Instagram 帖子 4:5(feed-portrait)、故事/Reels 9:16(story)、网站横幅(web-hero / web-strip)、展示广告 GIF(display-*)。根据图像调整 4 个选项:如果其比例已匹配某格式(例如 4:5 → Instagram 帖子),则直接提供该格式而非单独的 "як є"(结果相同)并推荐它;否则优先推荐 "як є"。使用不同比例的格式会裁剪图像(fit: cover)或添加模糊边缘(contain-blur)——请说明裁剪或模糊的效果,以及它会切掉什么(标题边缘、CTA),以便用户不会感到意外。
  2. 角色? → 3–4 种适合画面的情绪,用感觉描述而非名称:“宁静高级”、“充满活力”、“节日气氛”、“几乎不动”。请在描述中提到匹配的情绪(premium、energetic、festive、calm ……;完整列表:$OM/om moods)。
  3. 结构? → “元素出现,然后循环”(intro-loop,适合社交媒体帖子)、“仅无缝循环”(loop,适合网站横幅)、“单次播放并结束”(oneshot)。
  4. 主要元素是什么?(多选)→ 你找到的 3–4 个最突出的元素,例如“标题 SUMMER SALE”、“CTA 按钮”、“照片”、“产品”。主要元素会获得主要动画;其他元素保持平静。

无回答时的默认值:根据宽高比确定配置,6 秒(intro-loop 模式下 2 秒 intro + 4 秒 loop),MP4,从调色板和主题中选择情绪。参考视频("like this")优先级高于任何答案——请用 references/reference-analysis.md 分析其节奏并模仿,而非内容。

2. 运动计划——渲染前用文字达成一致

在首次渲染前,用通俗语言(用户语言)展示计划,每个元素一行并标注时间——例如:

Інтро(2 с): logo 出现 → 标题逐行上升 → «-30%» 弹出 → 按钮和商品从下方出现。 循环(4 с): «-30%» 微微发光,一道光闪烁划过 · 按钮脉动 · 商品微微浮动 · 背景暖色尘埃。 不动的: logo(仅少量闪烁),价格出现后保持静止,日期。

在同一消息中询问 "Так робимо, чи щось змінити?",仅在得到肯定回复后继续(或者当用户已跳过问题时,直接渲染并随结果展示计划)。修改计划只需几秒钟;修改渲染结果则需几分钟。计划还决定了哪些元素在下一步需要独立的图层。

3. 获取图层

根据输入类型选择——目标是生成一个包含角色信息的 layers.json(格式参考 references/scene-format.md):

输入类型命令
平面 JPG/PNG,已安装 ML$OM/om py $OM/scripts/ml/auto_layers.py in.jpg --out work/layers
PSD$OM/om py $OM/scripts/psd_layers.py in.psd --out work/layers
PNG 图层文件夹$OM/om layers-from-dir path/to/pngs
设计好的创意作品(卡片、按钮、箭头、头部超出画面的照片),或自动分层结果有误编写 regions.json(矩形/多边形 + 蒙版模式)→ $OM/om py $OM/scripts/ml/cut_regions.py regions.json --out work/layers(格式详见脚本的 docstring)
平面图像,无 ML手动编写 layers.json:一个 background 图层(如果粒子需要避开文字,还需询问文字框)

对于 regions.json,请通过测量而非肉眼观察来寻找坐标:对亮/暗像素设阈值并打印组件边界框;对于照片卡片,扫描框架的颜色并拟合边缘(多边形位于真实边缘内部 3–5 像素处,会在背景中留下亮线并裁剪卡片)。对于纯色背景上的文字/标志/线条,使用 mask: "contrast";对于头部伸出的照片卡片,使用 "full" + popout;对于忙碌照片中的物体,使用 "seg"。

在构建场景之前,务必打开 preview.png / 各个图层 PNG 文件并检查分割结果: 自动分层可能误标(标志被识别为文字、价格被识别为标题、本应是背景的物体被识别为主题)。在 layers.json 中修正角色——角色决定了哪些元素可以移动。如果主体切图质量差,请丢弃该图层,不要为粗糙的边缘添加动画。

4. 构建场景

$OM/om scene --layers work/layers/layers.json --mood energetic \
     --profile feed-portrait --structure intro-loop [--brand brand.json] \
     [--intensity 1] [--speed 1] [--density 1] --out work/scene.json

此命令根据情绪包(和品牌套件)草拟 scene.json。然后编辑它以匹配已商定的计划——这就是工艺所在:每层 intro 时间交错 50–100 毫秒(整个级联 ≤ 2 秒,入场 400–800 毫秒,缓出;仅一个俏皮元素使用弹跳),主要元素的辉光/光效,装饰运动(箭头弹跳,徽章旋转),粒子使用图像或品牌套件中的一种强调色。阅读 references/effects.md 了解每个效果及其参数,阅读 references/motion-guidelines.md 了解保持专业性的限制。

5. 渲染、查看、迭代

$OM/om render work/scene.json --out work/out --quality draft     # 快速检查
$OM/om render work/scene.json --out work/out --formats mp4,webm,gif  # 最终版本

每次渲染后查看 *-sheet.jpg(8 帧),若有疑问,提取单帧(ffmpeg -ss 2.5 -i out.mp4 -frames:v 1 f.png)并查看。报告(*-report.json,标准错误输出中会总结)检查:循环接缝、闪光(≤3/秒)、锁定图层未移动、安全区域(文字/价格/CTA 距离边缘 ≥ 10%,标志 ≥ 5%;cut 表示格式更改裁剪了它,as-designed 表示源文件本身已经这么紧凑)、文件大小预算。

在交付前修复问题——可见的接缝通常意味着非整数 cycles;预算失败意味着需要更少的粒子/颗粒,或更低的 GIF 尺寸/帧率。

向用户展示草稿(联系表或 MP4),邀请他们用自己语言提出调整意见——“повільніше”、“менше блиску”、“без частинок”、“кнопку яскравіше”、“прибери інтро”。references/tweaks.md 将此类短语映射到场景编辑;应用这些编辑,重新渲染为草稿,仅在他们满意时才渲染最终版本。

笔记本电脑上的成本(M1,8 GB):自动分层约每张图像 3–4 分钟(运行一次后,即可迭代场景);渲染约每帧 0.2–0.4 秒(6 秒 30 fps 约 1 分钟)。在执行耗时步骤前告知用户。

6. 交付

向用户提供:文件(路径 + 大小)、海报 JPG、一句关于运动效果的话,以及用于网站的嵌入提示 <video autoplay muted loop playsinline poster="…">。如果目标平台有硬性限制(精确尺寸、编解码器、最大 MB),请说明是否已满足。如果这是一项品牌任务且尚无套件,可主动提供一行保存选项(references/brand-kit.md),以便下次问题已预先回答。

保持高质量的规则(及原因)

  • 一个主要运动,最多两个环境运动。 观众一次只能关注一件事;额外的运动会与信息竞争。
  • 价格、法律文本和标志保持静止。 运动会使字母模糊和晃动——可读性和品牌信任优于花哨。角色设置强制执行此规则;不要为了给价格添加动画而将其角色重新分配给 text。
  • 不要伪造人物的移动。 抠出的人物不能跑步或挥手;让整个身体上下浮动或脉动看起来像纸板木偶。给人深度(摄像机视差)和一个入场效果,仅此而已。
  • 小幅度。 3–6% 的摄像机推进,2–4° 倾斜,≤ 2% 的呼吸。大的缩放和视差会引起晕动症并显得业余。
  • 仅完整周期。 因为每个运动在每个循环内都完成整数个周期,所以循环是无缝的——切勿设置分数 cycles。
  • 第一帧 = 完成的海报。 在 loop 模式下,第一帧已包含所有内容;需要入场效果时使用 intro-loop。
  • 不重新生成文字。 此技能从不重新绘制文字或产品;AI 视频(可选,参见 references/ai-video.md)仅用于背景,原始图层会合成回其上。

故障排除

  • Playwright is not installed,Node.js is missing,ffmpeg 错误 → bash $OM/scripts/setup.sh。
  • 空白或黑色帧 → 图层路径错误(检查标准错误输出警告)或场景没有背景图层。
  • 文字检测跳过 → ocrmac 仅适用于 macOS;在其他平台上手动传递文字图层。
  • 视差边缘光晕 → 降低 depthParallax.amp,或修复图像(auto-layers 默认会修复,除非使用了 --no-inpaint)。
  • GIF 过大 → display-* 配置会自动缩小;否则降低帧率/宽度。

相关技能