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()→ 抛出异常。仅在合成组件内部调用它们。