remotion-video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Remotion Video

Creates production-grade videos using Remotion — a React framework where video is code. Every frame is a React component. Animations use spring physics and frame-based interpolation.

使用Remotion创建生产级视频——这是一个将视频视为代码的React框架。每一帧都是一个React组件。动画采用弹簧物理效果和基于帧的插值实现。

Reference Files

参考文件

File	Purpose
`references/rules/fundamentals.md`	useCurrentFrame, useVideoConfig, interpolate, spring, core hooks
`references/rules/animations.md`	Easing, spring config, interpolateColors, timing patterns
`references/rules/compositions.md`	Composition, registerRoot, Folder, calculateMetadata
`references/rules/media.md`	Img, Video, OffthreadVideo, Audio, staticFile, async loading
`references/rules/text-and-fonts.md`	Google Fonts, local fonts, text measurement, typography
`references/rules/tailwind.md`	TailwindCSS integration, utility-first styling in Remotion
`references/rules/audio.md`	Audio component, volume curves, trimming, frame-synced audio
`references/rules/subtitles.md`	Caption system, SRT/VTT parsing, word-level timing
`references/rules/three-d.md`	@remotion/three, ThreeCanvas, React Three Fiber integration
`references/rules/charts.md`	Bar, pie, line chart animation patterns
`references/rules/rendering.md`	CLI render, renderMedia API, quality presets
`references/rules/data-driven.md`	Dataset rendering, batch generation, parametric compositions
`references/templates/explainer.tsx`	Parametric tech explainer template
`references/templates/product-demo.tsx`	Product showcase template
`references/templates/data-viz.tsx`	Animated chart composition template
`scripts/scaffold_project.sh`	Bootstrap a new Remotion project with TailwindCSS
`scripts/render.sh`	Render wrapper with quality presets and format options

文件路径	用途
`references/rules/fundamentals.md`	useCurrentFrame、useVideoConfig、interpolate、spring等核心钩子函数
`references/rules/animations.md`	缓动效果、弹簧配置、颜色插值、时序模式
`references/rules/compositions.md`	Composition、registerRoot、Folder、calculateMetadata相关用法
`references/rules/media.md`	Img、Video、OffthreadVideo、Audio、staticFile、异步加载
`references/rules/text-and-fonts.md`	Google Fonts、本地字体、文本测量、排版
`references/rules/tailwind.md`	TailwindCSS集成、Remotion中的实用优先样式设计
`references/rules/audio.md`	Audio组件、音量曲线、音频裁剪、帧同步音频
`references/rules/subtitles.md`	字幕系统、SRT/VTT解析、逐词时序控制
`references/rules/three-d.md`	@remotion/three、ThreeCanvas、React Three Fiber集成
`references/rules/charts.md`	柱状图、饼图、折线图的动画实现模式
`references/rules/rendering.md`	CLI渲染、renderMedia API、画质预设
`references/rules/data-driven.md`	数据集渲染、批量生成、参数化合成
`references/templates/explainer.tsx`	参数化技术解说视频模板
`references/templates/product-demo.tsx`	产品展示视频模板
`references/templates/data-viz.tsx`	动画图表合成模板
`scripts/scaffold_project.sh`	快速搭建集成TailwindCSS的Remotion项目
`scripts/render.sh`	带画质预设和格式选项的渲染包装脚本

Why Remotion

为什么选择Remotion

Remotion treats video as a React application. Each frame is a pure function of time — given frame N and total frames F, your component renders deterministically. This means:

Component composition: Nest scenes, reuse components, apply CSS.
Spring physics:
```
spring()
```
gives natural motion without hand-tweaking cubic beziers.
Asset pipeline: Import images, audio, video — the same way you import in React.
Iterative workflow: Edit code → hot-reload preview → render final. The
```
.tsx
```
file IS the editable intermediate.
Data-driven at scale: Render thousands of personalized videos by passing different props to the same composition.

Remotion将视频视为React应用。每一帧都是时间的纯函数——给定第N帧和总帧数F，组件会确定性地渲染。这意味着：

组件化合成：嵌套场景、复用组件、应用CSS样式。
弹簧物理效果：
```
spring()
```
无需手动调整三次贝塞尔曲线即可实现自然运动。
资源管道：像在React中一样导入图片、音频、视频。
迭代式工作流：编辑代码 → 热重载预览 → 渲染最终视频。
```
.tsx
```
文件就是可编辑的中间产物。
规模化数据驱动：通过向同一个合成组件传递不同props，渲染数千个个性化视频。

Workflow

工作流

text

Scaffold → Compose → Preview → Iterate → Render

Scaffold the project (once per video project)
Interpret the user's concept — choose the right template and rule files
Compose React components for each scene
Preview in Remotion Studio (
```
npm run dev
```
)
Iterate based on user feedback
Render final video via
```
scripts/render.sh
```

text

项目搭建 → 组件合成 → 预览 → 迭代优化 → 渲染输出

项目搭建（每个视频项目执行一次）
理解需求——选择合适的模板和规则文件
合成组件——为每个场景编写React组件
预览——在Remotion Studio中查看（
```
npm run dev
```
）
迭代优化——根据用户反馈调整
渲染输出——通过
```
scripts/render.sh
```
生成最终视频

Step 0: Ensure Dependencies

步骤0：确认依赖环境

Node.js 18+ is required. Check before scaffolding:

bash

node --version   # Must be >= 18.0.0
npm --version

If Node.js is not available, inform the user — Remotion cannot run without it.

需要Node.js 18及以上版本。搭建项目前请检查：

bash

node --version   # 版本需 >= 18.0.0
npm --version

如果没有Node.js，请告知用户——Remotion无法在无Node.js的环境中运行。

Step 1: Scaffold the Project

步骤1：搭建项目

Run

scripts/scaffold_project.sh

to create a new Remotion project. The script is idempotent — it detects an existing project and skips re-initialization.

bash

bash scripts/scaffold_project.sh my-video-project
cd my-video-project
npm run dev   # Opens Remotion Studio at localhost:3000

运行

scripts/scaffold_project.sh

创建新的Remotion项目。该脚本支持幂等操作——会检测现有项目并跳过重复初始化。

bash

bash scripts/scaffold_project.sh my-video-project
cd my-video-project
npm run dev   # 在localhost:3000打开Remotion Studio

Step 2: Interpret the Concept

步骤2：理解需求

Determine the best approach. Read the relevant rule file for detailed patterns.

Content type	Rule file	Template
Explainer / educational	fundamentals.md	explainer.tsx
Product demo / marketing	animations.md	product-demo.tsx
Data visualization / animated chart	charts.md	data-viz.tsx
Video with voiceover / narration	audio.md + subtitles.md	explainer.tsx
Social media clip (short, looping)	animations.md	product-demo.tsx
3D scene / abstract motion graphics	three-d.md	(custom)
Personalized / batch generation	data-driven.md	any
Video with embedded media	media.md	any

确定最佳实现方案。阅读相关规则文件获取详细模式。

内容类型	规则文件	模板文件
解说/教育类视频	fundamentals.md	explainer.tsx
产品演示/营销视频	animations.md	product-demo.tsx
数据可视化/动画图表	charts.md	data-viz.tsx
带旁白/配音的视频	audio.md + subtitles.md	explainer.tsx
社交媒体短视频（短时长、循环播放）	animations.md	product-demo.tsx
3D场景/抽象动态图形	three-d.md	（自定义）
个性化/批量生成视频	data-driven.md	任意模板
嵌入媒体的视频	media.md	任意模板

Step 3: Compose the Components

步骤3：合成组件

Core rules for writing Remotion components:

One composition per video:
```
registerRoot
```
points to one root composition.
Sequences for timing: Use
```
<Sequence from={30} durationInFrames={60}>
```
to place scenes at specific frames.
AbsoluteFill for layering: Use
```
<AbsoluteFill>
```
as the base for any full-screen element.
Frame-based math only: Derive all animation state from
```
useCurrentFrame()
```
. Never use
```
Date.now()
```
or
```
setTimeout
```
.
Spring over easing: Prefer
```
spring({ frame, fps })
```
for natural motion.
Props for everything variable: Hardcoded values → props. This enables data-driven rendering.

编写Remotion组件的核心规则：

一个视频对应一个合成组件：
```
registerRoot
```
指向一个根合成组件。
用Sequence控制时序：使用
```
<Sequence from={30} durationInFrames={60}>
```
将场景放置在特定帧位置。
用AbsoluteFill实现分层：使用
```
<AbsoluteFill>
```
作为全屏元素的基础容器。
仅基于帧的数学计算：所有动画状态都从
```
useCurrentFrame()
```
获取。禁止使用
```
Date.now()
```
或
```
setTimeout
```
。
优先使用弹簧效果而非缓动：优先选择
```
spring({ frame, fps })
```
实现自然运动。
用Props传递所有可变内容：将硬编码值改为Props传递，支持数据驱动渲染。

Component structure pattern

组件结构示例

tsx

import {
  useCurrentFrame,
  useVideoConfig,
  interpolate,
  spring,
  AbsoluteFill,
  Sequence,
} from "remotion";

type MySceneProps = {
  title: string;
  accentColor: string;
};

export const MyScene: React.FC<MySceneProps> = ({ title, accentColor }) => {
  const frame = useCurrentFrame();
  const { fps, durationInFrames } = useVideoConfig();

  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });
  const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100 } });

  return (
    <AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>
      <div
        style={{ opacity, transform: `scale(${scale})`, color: accentColor }}
      >
        {title}
      </div>
    </AbsoluteFill>
  );
};

tsx

import {
  useCurrentFrame,
  useVideoConfig,
  interpolate,
  spring,
  AbsoluteFill,
  Sequence,
} from "remotion";

type MySceneProps = {
  title: string;
  accentColor: string;
};

export const MyScene: React.FC<MySceneProps> = ({ title, accentColor }) => {
  const frame = useCurrentFrame();
  const { fps, durationInFrames } = useVideoConfig();

  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });
  const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100 } });

  return (
    <AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>
      <div
        style={{ opacity, transform: `scale(${scale})`, color: accentColor }}
      >
        {title}
      </div>
    </AbsoluteFill>
  );
};

Step 4: Preview

步骤4：预览

Remotion Studio provides hot-reload preview. Start it with:

bash

npm run dev

Studio opens at

http://localhost:3000

. The timeline scrubber lets you inspect any frame.

Use

<Still>

component for frame-accurate screenshots during iteration.

Remotion Studio提供热重载预览功能，启动命令：

bash

npm run dev

Studio会在

http://localhost:3000

打开。时间轴滑块可用于查看任意帧的效果。

迭代过程中可使用

<Still>

组件获取帧精确的截图。

Step 5: Iterate

步骤5：迭代优化

Request	Action
"Slower/faster"	Adjust `durationInFrames` on `<Sequence>` or change FPS
"Different color"	Update props passed to composition
"Add a section"	Add new `<Sequence>` block with incremented `from` offset
"Change font"	Load via `@remotion/google-fonts` , apply as CSS `fontFamily`
"Add background music"	Add `<Audio src={staticFile('audio.mp3')} />` to root composition
"Make it loop"	Set `durationInFrames` and design matching first/last frame state
"Add captions"	See subtitles.md for SRT parsing and word-level timing

用户需求	操作方案
"变慢/变快"	调整 `<Sequence>` 的 `durationInFrames` 或修改FPS值
"更换颜色"	更新传递给合成组件的Props
"添加一个章节"	新增 `<Sequence>` 块并设置递增的 `from` 偏移值
"更换字体"	通过 `@remotion/google-fonts` 加载字体，作为CSS `fontFamily` 应用
"添加背景音乐"	在根合成组件中添加 `<Audio src={staticFile('audio.mp3')} />`
"设置循环播放"	设置 `durationInFrames` 并确保首尾帧状态匹配
"添加字幕"	参考subtitles.md中的SRT解析和逐词时序控制方法

Step 6: Render

步骤6：渲染输出

Use

scripts/render.sh

to render the final video:

bash

bash scripts/render.sh --composition MyComposition --quality final --format mp4

使用

scripts/render.sh

渲染最终视频：

bash

bash scripts/render.sh --composition MyComposition --quality final --format mp4

Quality presets

画质预设

Preset	Resolution	FPS	Use case
`preview`	480p	15	Fast layout check
`draft`	720p	30	Client draft review
`final`	1080p	30	Standard delivery
`4k`	2160p	60	Presentation / cinema

预设值	分辨率	帧率	适用场景
`preview`	480p	15	快速布局检查
`draft`	720p	30	客户初稿审核
`final`	1080p	30	标准交付版本
`4k`	2160p	60	演示/影院级交付

Format options

格式选项

Format	Use case
`mp4`	Standard delivery (H.264)
`webm`	Web-optimized
`gif`	Embeddable in docs, social media

格式	适用场景
`mp4`	标准交付格式（H.264编码）
`webm`	网页优化格式
`gif`	可嵌入文档、社交媒体的动图格式

Error Handling

错误处理

Error	Cause	Resolution
`node: command not found`	Node.js not installed	Install Node.js 18+ from nodejs.org
`Cannot find module 'remotion'`	Dependencies not installed	Run `npm install` in the project directory
`Composition not found`	Wrong composition ID	Check `registerRoot` and `<Composition id=` match
`delayRender timed out`	Async asset load > 30s	Increase timeout via `delayRender('reason', { timeoutInMilliseconds: 60000 })`
`OffthreadVideo failed`	Video codec not supported	Convert to H.264 MP4 with ffmpeg first
`ENOMEM` during render	Out of memory on large compositions	Reduce `--concurrency` flag, or lower resolution
`Port 3000 already in use`	Another dev server running	Kill existing process or set `--port 3001`
Spring animation goes past 1.0	Missing `{ extrapolateRight: 'clamp' }`	Add extrapolation clamp to `interpolate` calls
Fonts not loading in render	Font not loaded before render starts	Use `@remotion/google-fonts` or `delayRender` for font face load

错误信息	原因	解决方案
`node: command not found`	未安装Node.js	从nodejs.org安装Node.js 18+版本
`Cannot find module 'remotion'`	未安装依赖包	在项目目录中运行 `npm install`
`Composition not found`	合成组件ID错误	检查 `registerRoot` 与 `<Composition id=` 是否匹配
`delayRender timed out`	异步资源加载超时（超过30秒）	通过 `delayRender('reason', { timeoutInMilliseconds: 60000 })` 增加超时时间
`OffthreadVideo failed`	视频编码不支持	先用ffmpeg转换为H.264编码的MP4格式
`ENOMEM` during render	大型合成组件导致内存不足	降低 `--concurrency` 参数值，或降低分辨率
`Port 3000 already in use`	已有开发服务器在运行	终止现有进程或设置 `--port 3001` 指定其他端口
Spring animation goes past 1.0	缺少 `{ extrapolateRight: 'clamp' }` 配置	在 `interpolate` 调用中添加外插限制配置
Fonts not loading in render	渲染前未加载字体	使用 `@remotion/google-fonts` 或通过 `delayRender` 等待字体加载完成

Limitations

限制说明

Node.js required — Remotion is a Node.js framework. Cannot run in Python-only or headless container environments.
Chromium dependency — Remotion renders via Chromium. The
```
npx remotion render
```
command downloads it automatically, but it requires ~300MB disk space.
No server-side Lambda in v1 — Cloud rendering via
```
@remotion/lambda
```
is deferred to a future skill version. Local rendering only.
Large renders are slow — A 60-second 1080p video at 30fps = 1800 frames rendered through Chromium. Plan for 10-30 minutes on a typical laptop.
GIF size — GIFs at full resolution are large. Limit to 480p and <10 seconds for embeddable GIFs.
Audio in preview — Remotion Studio supports audio playback in preview. Rendered audio requires ffmpeg.

必须依赖Node.js —— Remotion是Node.js框架，无法在纯Python或无头容器环境中运行。
依赖Chromium —— Remotion通过Chromium渲染。
```
npx remotion render
```
命令会自动下载Chromium，但需要约300MB磁盘空间。
v1版本不支持Lambda云端渲染 ——
```
@remotion/lambda
```
云端渲染功能将在后续版本支持，当前仅支持本地渲染。
大型视频渲染速度慢 —— 60秒1080p/30fps的视频需要渲染1800帧，普通笔记本电脑预计需要10-30分钟。
GIF体积大 —— 全分辨率GIF体积庞大，建议限制为480p且时长小于10秒，以便于嵌入使用。
预览中的音频 —— Remotion Studio支持预览时播放音频，渲染后的音频需要依赖ffmpeg。

Design Principles

设计原则

Frame-based thinking: Every visual state is a function of the current frame number. No timers, no intervals.
Composition-first: Split video into logical
```
<Sequence>
```
blocks. Each scene is its own component.
Spring over easing:
```
spring()
```
gives physically accurate motion. Only use
```
interpolate
```
with easing when spring doesn't fit.
Props for content: Never hardcode strings, colors, or data inside components. Pass via props to enable reuse.
Type everything: All composition props have TypeScript types enforced via
```
z.infer<typeof schema>
```
(Zod) or explicit interfaces.

基于帧的思维：所有视觉状态都是当前帧号的函数，禁止使用定时器或间隔函数。
合成优先：将视频拆分为逻辑
```
<Sequence>
```
块，每个场景作为独立组件。
优先使用弹簧效果：
```
spring()
```
可实现物理精确的运动效果，仅在弹簧效果不适用时才使用带缓动的
```
interpolate
```
。
用Props传递内容：组件内部禁止硬编码字符串、颜色或数据，通过Props传递以支持复用。
类型化所有内容：所有合成组件的Props都通过
```
z.infer<typeof schema>
```
（Zod）或显式接口实现TypeScript类型校验。

Cross-Reference

交叉参考

For mathematical animations, algorithm visualizations, or when Node.js is unavailable, use

concept-to-video

(Manim/Python) instead. Manim runs in any Python environment and excels at geometric proofs, equation animations, and LaTeX rendering.

若需制作数学动画、算法可视化，或在无Node.js环境下工作，请改用

concept-to-video

（Manim/Python）。Manim可在任意Python环境中运行，擅长几何证明、公式动画和LaTeX渲染。