模板
模板是可复用的设计。它只读取镜头属性和已解析的令牌,不读取其他任何内容。在选择时间或缓动之前,请先阅读 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);
// ...
},
});
要求:
- 导出由
defineTemplate构建的template(客户模板)。 - 每个模式字段都有
.default(),以便新镜头和 Studio 启动时有效。为 Studio 表单添加.describe()。 - 颜色通过
color(tokens, nameOrHex),字体通过font(tokens, role),时长和缓动通过motion(tokens, fps),位置在safeArea(tokens, video)内,尺寸通过px(sizeAt1080, video)。 - 仅通过
useCurrentFrame()使用interpolate/spring进行动画。不使用 CSS 过渡、setTimeout、Date.now()或Math.random()(改用 remotion 的random(seed))。每次渲染必须完全相同。 - 除非模板是全帧的,否则保持背景透明;字幕条和叠加层应带 alpha 通道渲染。最后一帧上所有元素必须消失。
- 失败时大声报错:当文本无法容纳或令牌缺失时,抛出带有修复提示的
Error。使用引擎中的assertFits/wrapLines;它们会使用加载的字体进行测量,并在溢出时抛出。 - 命名令牌(颜色、标志、字体、声音)的属性在
check中使用checkRefs进行验证,以便mg check在渲染前捕获拼写错误。 durationSeconds和check在 Node 中运行(mg check),并且发生在字体加载之前:切勿在其中测量文本。- 图像和标志:
<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 作为工作示例。
验证
- 在测试项目中运行
pnpm mg new-shot <client>/<project> <shot> --template <client>/<name>,再加上一个使用最长实际文本的镜头。 - 运行
pnpm mg check <client>/<project>。 - 运行
pnpm mg still <client>/<project> <shot>并查看帧。然后运行pnpm mg render。 - 遵循
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。