当此技能被激活时,务必以 :clapper: 表情符号开始你的第一个回复。
Remotion 视频
Remotion 是一个使用 React 进行程序化视频创建的框架。与基于时间线的编辑器不同,你可以将视频合成编写为 React 组件,其中的每一帧都是当前帧编号的函数。这为你提供了 TypeScript、npm 包和基于组件的架构的全部能力来构建视频——从动画解说和社交媒体剪辑,到数据驱动可视化和大规模个性化视频。
本技能涵盖项目设置、合成结构、基于帧的动画(使用 interpolate 和 spring)、场景排序、资产管理、音频集成、使用 Zod 模式参数化视频,以及通过 CLI 或程序化 API 渲染为 MP4/WebM。
何时使用本技能
当用户出现以下情况时触发此技能:
- 想要使用 React/TypeScript 程序化创建视频
- 询问关于 Remotion 合成、useCurrentFrame 或 useVideoConfig
- 需要对文本、元素或场景之间的过渡进行动画处理
- 想要将视频从代码渲染为 MP4、WebM 或 GIF
- 询问关于 spring 动画、interpolate 或基于帧的时序
- 需要从头开始搭建一个新的 Remotion 项目
- 想要为 Remotion 视频添加音频、图像或字体
- 询问关于参数化/数据驱动视频生成
- 需要配置 Remotion Studio 用于预览合成
在以下情况下不要触发此技能:
- 与视频创建无关的通用 React 问题——请使用 React 技能
- 使用传统时间线工具(Premiere、DaVinci、FFmpeg CLI)进行视频编辑
- 网页的 CSS 动画——请使用动画/动效设计技能
- Web 应用中的视频播放或流媒体——请使用媒体播放器技能
核心原则
-
每一帧都是纯函数 - Remotion 组件通过
useCurrentFrame()接收当前帧,并且必须为该帧进行确定性渲染。无副作用,无无种子的随机性,不依赖墙钟时间。相同的帧编号必须始终产生相同的视觉输出。 -
合成是视频的单元 - 每个
<Composition>定义了一个具有明确尺寸(宽度、高度)、帧率(fps)和时长(durationInFrames)的视频。将合成视为项目中的“页面”——每个独立可渲染的视频变体或场景对应一个合成。 -
使用 interpolate 处理一切 -
interpolate()函数将帧编号映射到任何数值(不透明度、位置、缩放、颜色通道)。结合extrapolateRight: 'clamp',它是所有动画的主力。当你需要基于物理的缓动效果时,请使用spring()。 -
使用 Sequence 处理时间偏移 - 使用
<Sequence from={frame}>延迟子元素开始出现的时间,使用<Series>逐个播放子元素。切勿使用 setTimeout 或手动帧计算进行排序——声明式原语在预览和渲染中都能正确处理。 -
资产是静态的,数据是动态的 - 将图像、字体和音频文件放在
public/文件夹中,并使用staticFile()引用它们。对于动态数据(API 响应、数据库记录),使用delayRender()/continueRender()来暂停渲染,直到数据加载完毕。
核心概念
合成结构
每个 Remotion 项目都有一个注册合成的根文件:
import { Composition } from 'remotion';
import { MyVideo } from './MyVideo';
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo"
component={MyVideo}
durationInFrames={150}
fps={30}
width={1920}
height={1080}
/>
);
};
基于帧的时序
Remotion 中的所有时序都以帧表示,而非秒。转换方式如下:
- 秒到帧:
秒 * fps - 帧到秒:
帧 / fps
在 30fps 时,5 秒的视频对应 150 帧。第 0 帧是起始帧。
动画模型
Remotion 提供了两个核心动画原语:
| 原语 | 用途 | 示例 |
|---|---|---|
interpolate() | 从帧到值的线性/强制映射 | 淡入、滑动、缩放 |
spring() | 基于物理的动画,带阻尼/质量 | 弹跳入场、自然运动 |
两者都返回一个数值,你可以将其应用于样式(不透明度、变换等)。
常见任务
1. 搭建一个新的 Remotion 项目
npx create-video@latest
这将会创建一个包含 TypeScript、示例合成和配置好的 Remotion Studio 的项目。项目结构如下:
my-video/
src/
Root.tsx # 注册所有合成
MyComp.tsx # 你的第一个合成组件
public/ # 静态资产(图像、字体、音频)
remotion.config.ts # Remotion 配置
package.json
使用以下命令启动预览工作室:
npx remotion studio
2. 使用 useCurrentFrame 创建一个基本合成
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate } from 'remotion';
export const FadeInText: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 30], [20, 0], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#0f0f0f',
}}
>
<h1
style={{
fontSize: 80,
color: 'white',
opacity,
transform: `translateY(${translateY}px)`,
}}
>
Hello Remotion
</h1>
</AbsoluteFill>
);
};
3. 逐字动画文本
将文本拆分为单词,并使用 <Sequence> 交错显示每个单词:
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate } from 'remotion';
const AnimatedWord: React.FC<{ children: string }> = ({ children }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 15], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 15], [10, 0], {
extrapolateRight: 'clamp',
});
return (
<span
style={{
display: 'inline-block',
opacity,
transform: `translateY(${translateY}px)`,
marginRight: 12,
}}
>
{children}
</span>
);
};
export const WordByWord: React.FC<{ text: string }> = ({ text }) => {
const words = text.split(' ');
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#1a1a2e',
flexWrap: 'wrap',
padding: 100,
}}
>
{words.map((word, i) => (
<Sequence key={i} from={i * 8}>
<AnimatedWord>{word}</AnimatedWord>
</Sequence>
))}
</AbsoluteFill>
);
};
4. 使用 spring 进行元素动画
使用 spring() 创建自然流畅的基于物理的动画:
import { AbsoluteFill, useCurrentFrame, useVideoConfig, spring } from 'remotion';
export const SpringCard: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const scale = spring({
frame,
fps,
config: { damping: 200, stiffness: 100, mass: 0.5 },
});
const slideUp = spring({
frame: frame - 10,
fps,
config: { damping: 12, stiffness: 100 },
});
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center', backgroundColor: '#0d1117' }}>
<div
style={{
width: 400,
height: 250,
backgroundColor: '#161b22',
borderRadius: 16,
transform: `scale(${scale}) translateY(${(1 - slideUp) * 50}px)`,
}}
>
<p style={{ color: 'white', fontSize: 32 }}>Spring Animation</p>
</div>
</AbsoluteFill>
);
};
5. 使用 Sequence 和 Series 进行场景过渡
使用 <Sequence> 处理重叠场景,使用 <Series> 处理顺序播放:
import { AbsoluteFill, Sequence, Series, useCurrentFrame, interpolate } from 'remotion';
const Scene: React.FC<{ color: string; title: string }> = ({ color, title }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 20], [0, 1], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill style={{ backgroundColor: color, justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ color: 'white', fontSize: 72, opacity }}>{title}</h1>
</AbsoluteFill>
);
};
export const MultiScene: React.FC = () => {
return (
<AbsoluteFill>
<Series>
<Series.Sequence durationInFrames={60}>
<Scene color="#e63946" title="Scene One" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#457b9d" title="Scene Two" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#2a9d8f" title="Scene Three" />
</Series.Sequence>
</Series>
</AbsoluteFill>
);
};
6. 资产处理(图像、字体、staticFile)
使用 staticFile() 引用 public/ 文件夹中的静态资产:
import { AbsoluteFill, Img, staticFile } from 'remotion';
export const AssetDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<Img
src={staticFile('logo.png')}
style={{ width: 300, height: 300 }}
/>
</AbsoluteFill>
);
};
使用 @remotion/google-fonts 或 CSS @font-face 加载自定义字体:
import { loadFont } from '@remotion/google-fonts/Inter';
const { fontFamily } = loadFont();
export const FontDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ fontFamily, fontSize: 64, color: 'white' }}>
Custom Font
</h1>
</AbsoluteFill>
);
};
7. 音频集成
添加带音量控制和时序的音频:
import { AbsoluteFill, Audio, Sequence, staticFile, interpolate } from 'remotion';
export const WithAudio: React.FC = () => {
return (
<AbsoluteFill style={{ backgroundColor: '#000' }}>
<Audio
src={staticFile('background-music.mp3')}
volume={(f) =>
interpolate(f, [0, 30, 120, 150], [0, 0.8, 0.8, 0], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
})
}
/>
<Sequence from={15}>
<Audio src={staticFile('whoosh.mp3')} volume={0.5} />
</Sequence>
</AbsoluteFill>
);
};
8. 渲染视频
从命令行渲染为 MP4:
# 渲染默认合成
npx remotion render src/index.ts MyVideo out/video.mp4
# 以 4K 分辨率渲染
npx remotion render src/index.ts MyVideo out/video.mp4 --width 3840 --height 2160
# 渲染为 WebM
npx remotion render src/index.ts MyVideo out/video.webm --codec vp8
# 渲染特定帧范围
npx remotion render src/index.ts MyVideo out/video.mp4 --frames 0-90
# 使用自定义属性渲染
npx remotion render src/index.ts MyVideo out/video.mp4 --props '{"title": "Hello"}'
关于程序化渲染,请参阅 references/rendering-guide.md。
反模式 / 常见错误
| 错误 | 错误原因 | 正确做法 |
|---|---|---|
使用 Math.random() 而未带种子 | 在渲染过程中每帧产生不同输出 | 使用确定性种子或 Remotion 的 random() |
使用 setTimeout / setInterval | 破坏基于帧的渲染——定时器不会按帧推进 | 使用 useCurrentFrame() 和帧计算处理所有时序 |
缺少 extrapolateRight: 'clamp' | 值在后续帧上超出目标范围 | 始终在 interpolate() 中添加 { extrapolateRight: 'clamp' } |
| 在帧计算中硬编码 fps | 当合成 fps 更改时失效 | 使用 useVideoConfig().fps 推导时序 |
使用 <Video> 进行渲染输出 | 由于寻轨开销导致渲染性能降低 | 使用 <OffthreadVideo> 获得更好的渲染性能 |
忘记为异步数据使用 delayRender() | 在数据加载前渲染,显示空/损坏的帧 | 立即调用 delayRender(),数据就绪时调用 continueRender() |
| 使用非确定性值的内联样式 | 预览和渲染之间出现闪烁或不一致 | 仅从帧编号推导所有样式值 |
| 庞大的单一合成 | 难以维护,且无法独立渲染场景 | 拆分为多个合成或使用 Series 处理场景 |
注意事项
-
extrapolateRight 默认值为 'extend' - 如果你编写
interpolate(frame, [0, 30], [0, 1])而没有进行强制限制,该值在第 30 帧之后将持续增加(例如,第 60 帧时透明度为 2)。除非你故意需要外推,否则始终传递{ extrapolateRight: 'clamp' }。 -
spring() 从其上下文的第 0 帧开始 - 当在
<Sequence from={60}>内部使用spring()时,传递给 spring 的帧会在父级的第 60 帧处重置为 0。如果你传递父级的原始帧,动画将已经完成。请在 Sequence 子级内部使用useCurrentFrame(),而不是使用来自父级的帧。 -
staticFile() 路径相对于 public/ - 调用
staticFile('images/logo.png')会查找public/images/logo.png。使用绝对路径或public/外部的路径将在预览中静默失败,并在渲染期间报错。确保所有资产都在public/目录中。 -
delayRender 有 30 秒超时 - 如果你的异步操作(API 调用、字体加载)耗时超过 30 秒,渲染将中止。对于慢速操作,请使用
delayRender('Loading data', { timeoutInMilliseconds: 60000 })增加超时时间。 -
合成尺寸必须为偶数 - 视频编解码器(H.264、VP8)需要偶数宽度和高度。如果你传递奇数值,Remotion 会抛出错误。