Communitygithub.com

remotion-motion-design

使用 Remotion 设计和实现合成、时间线、场景系统、2D/3D 动画、排版、过渡效果和可复用组件。

remotion-motion-design 是什么?

该技能是一个面向 Remotion 视频开发者的专业实现指南,涵盖了从项目架构到具体API使用的全过程。它提供了编写确定性动画的严格规则(如`useCurrentFrame()`、`interpolate`、`spring`的准确使用),强调时间线工程中帧范围的集中管理和场景无重叠/间隙。技能详细解释了`<Sequence>`与`<Series.Sequence>`中局部帧与全局帧的区别——这是最常见的错误来源,并提供了全局帧路由器和Series两种一致的场景调度模式。此外,它还涵盖了媒体资产处理(`staticFile`、`onError`)、2D/3D动画、像素画和火柴人支持、排版与过渡效果,以及交付前的QA检查清单。本技能适用于所有支持Remotion的AI编码环境(如Claude Code、Cursor、Codex),帮助开发者在复杂的视频项目中避免常见陷阱,生成稳定、可维护的视频代码。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/achmdfzn/motionforge-atelier/tree/main/.claude/skills/remotion-motion-design

在你喜欢的 AI 中提问

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

文档

REMOTION 动态设计 — 实现技能

1. 编码前审查

  • 阅读 CLAUDE.md、MASTER_PROMPT.md 以及架构文档。
  • 检查实际的 Remotion/React/TypeScript 版本和包管理器。
  • 找到现有的入口点和合成注册表。
  • 遵循仓库的约定;不要无故更换依赖。
  • 使用 beyond-video、脚本、故事板和风格圣经的输出作为生产规范。
  • 在依赖记忆之前,根据已安装版本的 Remotion 源码(例如,参考克隆中的 packages/core/src)验证你使用的API。

2. 合成配置文件

默认值:

  • width: 1080
  • height: 1920
  • fps: 60
  • aspect: 9:16
  • duration: 以帧为单位的正整数

每个合成都需要一个唯一的 ID 和明确的元数据。没有合理原因时,不要在不同层中存储不同的 FPS 值。

<Composition> 接受 id、fps、width、height、durationInFrames、defaultProps,以及可选的 calculateMetadata(根据props动态计算时长/元数据)和 schema。durationInFrames 必须为正数。

3. 时间线工程

  • 将持续时间和起始帧保持在中心化的数据/配置中。
  • 使用一种帧间隔约定;推荐使用 [start, end)。
  • 场景的 durationInFrames 必须为正数。
  • 确保合成的总时长包含所有场景加上结尾/结束部分。
  • 验证重叠和间隙;仅在为过渡/合成而故意设计时才允许重叠。
  • 最终帧边界不要依赖浮点数。

4. 确定性动画 — 时间/帧 API(Remotion 4.x)

时间来源:

  • useCurrentFrame() — 当前帧,从0开始索引。仅可在合成组件内部使用;在合成外部使用时抛出异常。
  • useVideoConfig() — 返回 {width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...};在合成外部使用时抛出异常。

插值和弹簧:

  • interpolate(input, inputRange, outputRange, options?) — 支持 number、string、boolean 和 array 输出的重载。选项包括:easing、extrapolateLeft / extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap')、output、outputType、posterize。当运动不得超出范围时,使用 clamp 外推。
  • spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false})。SpringConfig:damping(默认10)、mass(1)、stiffness(100)、overshootClamping(false)。damping <= 0 会使动画永不停止(导致无限循环错误)。
  • measureSpring({fps, config?, threshold=0.005}) — 弹簧稳定所需的帧数;threshold=0 返回 Infinity。

规则:

  • 运动必须是帧和 props 的函数。
  • 对粒子/噪声/随机值进行播种。
  • 避免使用 setInterval、setTimeout、requestAnimationFrame、Date.now() 以及自运行的 CSS关键帧作为视频运动的主要来源。
  • 在合成渲染期间不要获取网络数据。
  • 不要包含来自不稳定URL或需要登录的URL的音频/视频。
  • delayRender(label?, options?) 会保持渲染状态,直到调用 continueRender(handle)(例如,异步资源);其超时时间通过 CLI 的 --timeout 设置。

5. Sequence、Series 以及局部帧与全局帧

这是最容易出错的规则——曾经因为一个组件在 Series.Sequence 内部计算了全局帧而导致了真正的bug:

  • 在 <Sequence> 内部,useCurrentFrame() 返回的是相对于该 Sequence 起始位置的帧:(frame - (cumulatedFrom + relativeFrom)) * playbackRate。Sequence 内部的组件不会看到全局帧。
  • <Sequence> 属性:from?、name?、durationInFrames?(必须为正数;使用 loop 时需要)、layout('absolute-fill' | 'none')、premountFor、loop 以及裁剪属性(仅在与 layout="absolute-fill" 同时使用时)。
  • <Series.Sequence> 仅能用于 <Series> 内部;在 <Series> 外使用 Series.Sequence 会抛出“此组件必须位于 <Series /> 组件内部”。
  • 两种有效的路由模式——选择一种并保持一致性:
    • 全局帧路由器(在视频项目中使用):一个路由器组件使用全局的 useCurrentFrame() 并根据其 [start, end) 范围选择节拍;节拍组件从全局帧进行计算。
    • Series:每个 Series.Sequence 包含一个节拍;节拍组件从局部帧(在 Sequence 起始处为0)进行计算。
  • 在没有明确理由的情况下,不要在一个合成中混用两种模式。

6. 场景/组件结构

  • 一个场景承担一个叙事/视觉责任。
  • 场景 props 用 TypeScript 定义。
  • 可复用组件解决一个清晰的视觉任务。
  • 避免单个文件包含整个视频。
  • 分离内容配置、渲染器、样式令牌和资源引用。
  • 为可选资源添加设计好的备用方案;永远不要隐藏缺失的关键资源。

7. 媒体组件和资源

  • <Img src> — 没有 onError 的图像加载失败会取消渲染(cancelRender)。始终为关键资源提供 onError,或者在渲染前确保资源存在。
  • staticFile(path) — 映射 public/ 中的文件;用于每个本地资源(图像、音频、视频)。
  • <Audio> — 参见 sound-design 以了解如何将提示表映射到 props(trimBefore/After — 旧别名 startFrom/endAt — volume、playbackRate)。提示在时间线上的位置由 <Sequence from> 设置;修剪属性仅控制播放文件的哪一部分。<Audio> 没有 muted 属性;静音是一个 CLI 标志(--muted)。
  • <Video> / <OffthreadVideo> 和 <Still> 遵循相同的帧规则;媒体时长必须根据帧来安排,而不是根据文件元数据。

8. 2D 动态

根据需要使用 SVG/形状/CSS/光栅。注意锚点、变换原点、抗锯齿、分层、裁剪和安全区域。每个变换都必须由帧驱动。

9. 像素画和火柴人支持

像素画:

  • 锁定逻辑画布和像素缩放比例;
  • 缩放精灵时使用最近邻插值;
  • 必要时将位置对齐到网格;
  • 锁定调色板和精灵尺寸;
  • 避免模糊和子像素闪烁。

火柴人:

  • 保持比例和枢轴点一致;
  • 当项目规模允许时使用姿态/绑定库;
  • 动画轮廓和手势以便识别;
  • 将表情/姿态与故事节拍同步。

关于行走循环、跟随动作和空闲运动,请参见 character-animation。

10. 3D 动态

  • 仅当能带来创意价值时才添加3D。
  • 检查 three、@react-three/fiber、@remotion/three 的版本及其文档。
  • 对于 Remotion ThreeCanvas 集成,遵循已安装API版本的帧驱动方法;不要假设实时的 R3F 模式自动具有确定性。
  • 使用帧驱动相机、变换、材质、光照和粒子。
  • 考虑渲染器/无头兼容性、纹理大小、几何体和计算成本。
  • 当有助于提高可读性和可维护性时,将3D层与2D排版/叠加层分离。
  • 关于详细指导3D场景,请参见 3d-scene-director。

11. 排版和过渡效果

  • 优先考虑层级结构和可读性。
  • 永远不要让过渡效果覆盖重要的文案。
  • 每个过渡效果连接两个节拍;不要添加没有功能的效果。
  • 保持运动曲线和强度与风格圣经一致。
  • 根据阅读需求匹配文本时长。

12. 结尾实现

根据 beyond-video 工作表实现结尾标志和 CTA。标志必须来自官方资源或经批准的占位符。文案、时机、主题和合成必须感觉是为当前视频量身定制的。

13. 移交前 QA

检查合成 ID、元数据、帧范围、导入、类型、静态资源、字体、样式一致性、安全区域、结尾和资源许可。运行可用的 lint/类型检查/测试。不要渲染 MP4。不要提交/推送。

输出格式

  • 合成注册表:ID、1080×1920、60 FPS、durationInFrames、场景列表 + 帧范围。
  • 使用的 API:API 名称 + 相关签名 + 验证位置(已安装的 Remotion 版本)。
  • 帧路由模式:全局或 Series — 一种选择,在合成中保持一致。
  • 资源注册表:文件、staticFile、每个关键资源的备用/onError。
  • QA 检查清单 + 类型检查/lint 结果。

小型示例

全局帧路由器(视频项目模式):

const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
  <AbsoluteFill>
    {beat?.id === 'S01-B01' && <Hook />}
    {beat?.id === 'S01-B02' && <Problem />}
  </AbsoluteFill>
);

带有测量时长的弹簧:

const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});

失败模式

  • 组件在 Series.Sequence 内部计算全局帧 → 节拍错误,场景出现时间不对。修复:从局部帧计算,或切换到全局帧路由器。
  • 在没有 <Series> 的情况下使用 Series.Sequence → 渲染时抛出异常。将其包裹在 <Series> 中,或直接使用 <Sequence>(而不是 Series.Sequence)。
  • spring 的 damping <= 0 → 动画永不停止。保持 damping > 0。
  • 图像缺少 onError → 渲染被取消。添加 onError 或在渲染前确保资源存在。
  • 在合成外部使用 useCurrentFrame()/useVideoConfig() → 抛出异常。仅在合成组件内部调用它们。

Individual skills in this repo

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

相关技能