Communitygithub.com

motion-template

创作或修改 mg Remotion 模板(一种由属性和令牌驱动的可复用动画图形)。当现有模板不适用或需要修改动画时使用。

motion-template 是什么?

这个技能专注于在 mg 工具链中创建和修改 Remotion 动画模板。模板是基于 Zod 模式定义的可复用设计,接收 shot 属性和已解析的令牌,不依赖外部状态。它支持生成仅限特定客户的模板(存储在 `clients/<client>/templates/` 下)和通用模板(存储在 `motion-toolkit` 仓库中)。模板必须遵循严格的契约:导出由 `defineTemplate` 构建的 `template`,所有字段必须有默认值,动画只能通过 `useCurrentFrame()`、`interpolate` 和 `spring` 驱动以确保确定性渲染,还要在 `check` 函数中通过 `color`、`font` 和 `motion` 引擎工具验证令牌和颜色。此外还支持“外观”(looks)系统,通过 `roleo`、`reveal` 和 `type` 等助手函数实现一致的企业、动态或极简风格。“QA”步骤包括生成测试帧、运行 `mg check` 和渲染,开发者还可以从参考剪辑中提取帧来反向设计动画的时间线和缓动曲线。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ryodeushii/motion-graphics/tree/HEAD/skills/motion-template

在你喜欢的 AI 中提问

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

文档

模板

模板是可复用的设计。它只读取镜头属性和已解析的令牌,不读取其他任何内容。在选择时间或缓动之前,请先阅读 motion-style。对于 Remotion API 细节,请使用已安装的 Remotion 技能(npx remotion skills add)或访问 https://www.remotion.dev/docs。

存放位置

  • 客户专属:以 pnpm mg new-template <client> <name> 开始。它会在 clients/<client>/templates/<name>/index.tsx 处(id 为 <client>/<name>)写入一个符合以下契约的可用起始文件;请替换其设计。
  • 通用(所有客户):在 motion-toolkit 仓库的 templates/<name>/index.tsx 中,并在 templates/index.ts 中注册,随新工具包版本发布。不要写入 node_modules。

在编写动画代码之前,先提出模式(用户无需代理即可更改的属性)并与用户确认。

契约

import { interpolate, useCurrentFrame } from "remotion";
import { z } from "zod";
import { color, defineTemplate, font, motion, px, safeArea } from "motion-toolkit/engine";

const schema = z.object({
  headline: z.string().min(1).default("Headline"),
  holdSeconds: z.number().positive().default(3),
  accent: z.string().default("accent").describe("Color token name or #hex"),
});

export const template = defineTemplate({
  title: "Title card",
  schema,
  durationSeconds: ({ props, tokens }) => {
    const m = motion(tokens, 1);
    return m.seconds("enter") + props.holdSeconds + m.seconds("exit");
  },
  check: ({ props, tokens }) => {
    color(tokens, props.accent); // 在未知令牌名称时抛出错误;在 `mg check` 中运行
  },
  component: ({ props, tokens, video }) => {
    const frame = useCurrentFrame();
    const m = motion(tokens, video.fps);
    // ...
  },
});

要求:

  1. 导出由 defineTemplate 构建的 template(客户模板)。
  2. 每个模式字段都有 .default(),以便新镜头和 Studio 启动时有效。为 Studio 表单添加 .describe()。
  3. 颜色通过 color(tokens, nameOrHex),字体通过 font(tokens, role),时长和缓动通过 motion(tokens, fps),位置在 safeArea(tokens, video) 内,尺寸通过 px(sizeAt1080, video)。
  4. 仅通过 useCurrentFrame() 使用 interpolate/spring 进行动画。不使用 CSS 过渡、setTimeout、Date.now() 或 Math.random()(改用 remotion 的 random(seed))。每次渲染必须完全相同。
  5. 除非模板是全帧的,否则保持背景透明;字幕条和叠加层应带 alpha 通道渲染。最后一帧上所有元素必须消失。
  6. 失败时大声报错:当文本无法容纳或令牌缺失时,抛出带有修复提示的 Error。使用引擎中的 assertFits/wrapLines;它们会使用加载的字体进行测量,并在溢出时抛出。
  7. 命名令牌(颜色、标志、字体、声音)的属性在 check 中使用 checkRefs 进行验证,以便 mg check 在渲染前捕获拼写错误。
  8. durationSeconds 和 check 在 Node 中运行(mg check),并且发生在字体加载之前:切勿在其中测量文本。
  9. 图像和标志:<Img src={staticFile(tokens.logos[name])} /> 或 staticFile(props.someAsset)。声音:<Html5Audio src={staticFile(file)} /> 放在 <Sequence from={frame}> 内,文件来自 tokens.sounds[name]。CLI 会暂存这些文件。

外观

通用模板以及旨在与之匹配的客户模板,应接受 look: lookSchema 并通过 resolveLook(props.look, tokens) 解析。使用共享助手构建它们,以使所有三种外观保持一致(参见 motion-style):

  • choreo(tokens, look, fps) 返回 beat(frame, index, exitStart, steps) → 每个元素按进入顺序的 { inP, outP };choreoSeconds(...) 给出匹配的时长。
  • reveal(look, beat, video) 是元素的外观进入样式(对于 corporate 模式,用 overflow: hidden 包裹)。
  • typo(tokens, look, "display" | "title" | "body" | "label", size) 是外观的排版样式;onColor(hex) 在色块上选择可读的文本;cornerPlacement(corner, inset) 定位角图形。

阅读通用模板,例如 node_modules/motion-toolkit/templates/title-card/index.tsx 作为工作示例。

验证

  1. 在测试项目中运行 pnpm mg new-shot <client>/<project> <shot> --template <client>/<name>,再加上一个使用最长实际文本的镜头。
  2. 运行 pnpm mg check <client>/<project>。
  3. 运行 pnpm mg still <client>/<project> <shot> 并查看帧。然后运行 pnpm mg render。
  4. 遵循 motion-qa。

从参考剪辑着手

当用户提供参考视频时,请先提取帧再进行设计。先创建 renders/reference/;捆绑的 ffmpeg 是不带滤镜的最小构建,因此使用 -r 设置帧率:

pnpm mg ffmpeg -i reference.mp4 -r 10 renders/reference/f_%03d.png

根据帧描述哪些元素在移动、移动顺序、每个阶段持续多长时间(以 10 fps 计数帧)以及缓动感觉。与用户确认该分解,然后将其映射到令牌:时长映射到 motion.durations,曲线映射到 motion.easings。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相关技能