Remotion
Remotion 将 React 组件转化为视频。你编写 JSX,Remotion 在每个固定 fps 的帧上调用你的组件一次,然后将生成的帧拼接成 MP4(或其他格式)。
核心思维模型
Remotion 给你一个帧号和一个空白画布。你的 React 组件决定在该帧上渲染什么。
没有命令式的动画时间线。时间只是一个数字(frame),而你的组件是该数字和 props 的纯函数。这就是为什么动画必须由 useCurrentFrame() 驱动 — CSS 过渡和 setTimeout 在渲染期间是非确定性的,会导致闪烁或不同步。
何时使用此技能
- 用户有一个 Remotion 项目(
remotion.config.ts或package.json中有@remotion/*),并希望构建、更改或调试一个 composition - 用户说“让我们用 Remotion / 用代码 / 编程方式制作一个视频”
- 用户粘贴了一个 Remotion 错误,或询问关于
interpolate、spring、Sequence、useCurrentFrame、Composition等 - 用户想要渲染现有的 Remotion 项目或设置 Lambda 渲染
何时不使用
- 使用 AI 模型(Veo、Sora、Runway、Kling、HeyGen)生成视频 → 使用 video 技能
- 编辑现有视频文件(剪切/裁剪/拼接)→ 使用 ffmpeg,而非 Remotion
- 实时流媒体 → Remotion 仅支持离线渲染
工作流程
-
检测或搭建项目。
- 新项目:
npx create-video@latest(交互式 — 选择一个模板,如 Hello World、Blank、JavaScript、TikTok 等) - 现有项目:检查
remotion.config.ts、src/Root.tsx和package.json中的@remotion/cli。注意 Remotion 主版本号 — API 会演变,正确的文档 URL 是https://www.remotion.dev/docs(最新版)或版本固定的页面。
- 新项目:
-
定位或创建 composition。 Compositions 在
src/Root.tsx中通过<Composition id="..." component={...} durationInFrames={...} fps={30} width={1920} height={1080} defaultProps={{...}} />注册。id是 CLI 按名称渲染的标识。 -
使用
useCurrentFrame+useVideoConfig构建组件以获取时间和元数据。使用<AbsoluteFill>布局,使用<Sequence>进行时间切片。 -
在 Studio 中预览:
npx remotion studio(自动重新加载)。不要试图“测试”孤立的帧 — 直接打开 Studio。 -
渲染:
npx remotion render <CompositionId> [output.mp4]。默认编解码器为 H.264 / MP4。参见 references/rendering.md 获取标志和编程 API。
快速 API 参考
请参阅链接文件以获取详细信息 — 仅在任务需要时加载这些文件。
| 主题 | 文件 |
|---|---|
| Composition、hooks、Sequence、AbsoluteFill、布局 | references/core-concepts.md |
interpolate、spring、Easing、交错、常见动画模式 | references/animation.md |
渲染:CLI 标志、@remotion/renderer、Lambda、编解码器、props | references/rendering.md |
音频/视频/图片:<Audio>、<Video>、<Img>、<OffthreadVideo>、字幕 | references/media.md |
项目设置、文件约定、remotion.config.ts | references/project-setup.md |
| 常见模式:打字动画、下部三行、数据驱动、视差 | references/patterns.md |
硬性规则
- 通过
useCurrentFrame()制作动画。 永远不要使用setTimeout、requestAnimationFrame或 CSStransition。它们在渲染期间会闪烁,因为每一帧都是在无头浏览器中独立渲染的。 durationInFrames是必需的且必须为整数。 总秒数 =durationInFrames / fps。- 保持组件纯函数。 没有顶层副作用,没有不带确定性种子的
Math.random()— 同一帧必须始终产生相同的像素。 - 不要在渲染过程中进行数据获取。 使用
delayRender()/continueRender()在数据加载时阻止帧准备就绪,或者预取数据并通过 props 传递。 - 尽可能使用
<OffthreadVideo>代替<Video>,以实现渲染期间非阻塞视频读取(更快,更少内存)。 - 通过
--props(CLI)或inputProps(Studio/编程方式)传递动态数据,而不是编辑文件。
常见错误
| 错误 / 症状 | 原因 | 修复 |
|---|---|---|
| MP4 与 Studio 预览中闪烁 / 动画不匹配 | 使用了 CSS 过渡或非帧驱动的动画 | 替换为 interpolate(frame, ...) 或 spring({ frame, fps }) |
| “Composition not found” | ID 拼写错误或缺少 <Composition> 注册 | 检查 src/Root.tsx |
| 渲染挂起 | 挂起的 delayRender() 从未调用 continueRender() | 找到未解决的 promise;添加 try/finally |
| 长视频内存不足 | <Video> 在内存中保留帧 | 切换到 <OffthreadVideo> |
| 音频不同步 | 音频文件 fps 不匹配或从错误的帧开始 | 将 <Audio> 包装在 <Sequence from={...}> 中 |
验证
做出更改后,始终:
- 运行
npx remotion studio并拖动时间轴,以确认更改在多个帧(开始、中间、结束)上看起来正确 - 对于编程更改,渲染一个短测试片段:
npx remotion render <id> out.mp4 --frames=0-60 - 类型检查:如果项目是 TypeScript,运行
npx tsc --noEmit
未经上述验证,不要声称成功。能编译的代码并不等同于看起来正确的视频。