remotion-video

Remotion Video

使用 Remotion 创建可用于生产环境的视频——Remotion 是一个将视频视为代码的 React 框架。 每一帧都是一个 React 组件。动画使用弹簧物理和基于帧的插值。

参考文件

文件	用途
references/rules/fundamentals.md	useCurrentFrame、useVideoConfig、interpolate、spring、核心 Hook
references/rules/animations.md	缓动、弹簧配置、interpolateColors、时间模式
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	带有质量预设和格式选项的渲染封装

为什么选择 Remotion

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

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

工作流

Scaffold → Compose → Preview → Iterate → Render

1. 初始化项目（每个视频项目执行一次）
2. 解读用户的构想——选择合适的模板和规则文件
3. 合成每个场景的 React 组件
4. 在 Remotion Studio 中预览（npm run dev）
5. 根据用户反馈迭代
6. 通过 scripts/render.sh 渲染最终视频

步骤 0：确保依赖项已就绪

需要 Node.js 18+。初始化前先检查：

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

如果无法使用 Node.js，请告知用户——Remotion 必须依赖它才能运行。

步骤 1：初始化项目

运行 scripts/scaffold_project.sh 创建新的 Remotion 项目。该脚本具有幂等性——会检测现有项目并跳过重新初始化。

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

步骤 2：解读概念

确定最佳方案。阅读相关规则文件，了解详细模式。

内容类型	规则文件	模板
讲解／教育	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	任意

步骤 3：编写组件

编写 Remotion 组件的核心规则：

• 每个视频使用一个合成：registerRoot 指向一个根合成。
• 使用序列控制时间：使用 <Sequence from={30} durationInFrames={60}> 将场景放置在指定帧。
• 使用 AbsoluteFill 分层：将 <AbsoluteFill> 用作任何全屏元素的基础。
• 仅使用基于帧的计算：通过 useCurrentFrame() 推导所有动画状态。切勿使用 Date.now() 或 setTimeout。
• 优先使用弹簧动画，而非缓动：优先使用 spring({ frame, fps }) 实现自然运动。
• 所有可变内容都使用属性：将硬编码值改为属性。这样可支持数据驱动渲染。

组件结构模式

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>
  );
};

步骤 4：预览

Remotion Studio 提供热重载预览。使用以下命令启动：

npm run dev

Studio 会在 http://localhost:3000 打开。使用时间轴滑块可检查任意帧。

迭代时，使用 <Still> 组件截取帧精确的屏幕截图。

步骤 5：迭代

请求	操作
“慢一些／快一些”	调整 <Sequence> 的 durationInFrames，或更改 FPS
“换个颜色”	更新传递给合成的属性
“添加一个部分”	添加新的 <Sequence> 块，并递增 from 偏移量
“更改字体”	通过 @remotion/google-fonts 加载，并将其应用为 CSS fontFamily
“添加背景音乐”	在根合成中添加 <Audio src={staticFile('audio.mp3')} />
“让它循环播放”	设置 durationInFrames，并设计首帧和末帧状态，使其相互匹配
“添加字幕”	查看 subtitles.md，了解 SRT 解析和逐词时间设置

步骤 6：渲染

使用 scripts/render.sh 渲染最终视频：

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

质量预设

预设	分辨率	FPS	用途
preview	480p	15	快速检查布局
draft	720p	30	客户审核草稿
final	1080p	30	标准交付
4k	2160p	60	演示／影院

格式选项

格式	用途
mp4	标准交付（H.264）
webm	针对 Web 优化
gif	可嵌入文档和社交媒体

错误处理

错误	原因	解决方法
node: command not found	未安装 Node.js	从 nodejs.org 安装 Node.js 18+
Cannot find module 'remotion'	未安装依赖	在项目目录中运行 npm install
Composition not found	Composition ID 错误	检查 registerRoot 和 <Composition id= 是否匹配
delayRender timed out	异步资源加载超过 30 秒	通过 delayRender('reason', { timeoutInMilliseconds: 60000 }) 增加超时时间
OffthreadVideo failed	不支持视频编解码器	先用 ffmpeg 转换为 H.264 MP4
渲染期间出现 ENOMEM	大型 Composition 内存不足	降低 --concurrency 标志的值，或降低分辨率
Port 3000 already in use	另一个开发服务正在运行	终止现有进程，或设置 --port 3001
Spring 动画超过 1.0	缺少 { extrapolateRight: 'clamp' }	在 interpolate 调用中添加外推限制
渲染时字体未加载	渲染开始前字体尚未加载	使用 @remotion/google-fonts 或通过 delayRender 加载字体

限制

• 需要 Node.js — Remotion 是一个 Node.js 框架。无法在仅有 Python 的环境或无头容器环境中运行。
• 依赖 Chromium — Remotion 通过 Chromium 渲染。npx remotion render 命令会自动下载 Chromium，但需要约 300MB 的磁盘空间。
• v1 不支持服务端 Lambda — 通过 @remotion/lambda 进行云端渲染将推迟到未来版本的技能中。目前仅支持本地渲染。
• 大型渲染速度较慢 — 一段 60 秒、1080p、30fps 的视频需要通过 Chromium 渲染 1800 帧。在普通笔记本电脑上，请预留 10-30 分钟。
• GIF 文件大小 — 全分辨率 GIF 文件很大。要生成可嵌入的 GIF，请将分辨率限制在 480p，时长控制在 10 秒以内。
• 预览中的音频 — Remotion Studio 支持在预览中播放音频。渲染后的音频需要 ffmpeg。

设计原则

• 以帧为基础思考：每个视觉状态都是当前帧编号的函数。不使用计时器或间隔计时器。
• 优先考虑 Composition：将视频拆分成逻辑清晰的 <Sequence> 区块。每个场景都是一个独立组件。
• 优先使用 Spring，而非缓动：spring() 可生成符合物理规律的运动。只有在 Spring 不适用时，才使用带缓动的 interpolate。
• 通过 Props 传递内容：不要在组件中硬编码字符串、颜色或数据。通过 Props 传入，以便复用。
• 为所有内容添加类型：所有 Composition Props 都通过 z.infer<typeof schema>（Zod）或显式接口强制指定 TypeScript 类型。

交叉参考

对于没有明确要求使用 React/Remotion 的数学动画或算法可视化，请使用 animate（Manim/Python）。Manim 使用自带的 Python、Cairo/Pango 和 FFmpeg 配置，而非 Node.js。缺少 Node.js 不能作为将明确要求使用 React 的请求切换到其他引擎的理由；请说明缺少该前置条件。

对于用户明确要求使用纯 HTML 和 CSS 制作，或使用 Hyperframes 渲染的视频，请改用 html-video；这不是 React 项目。明确指定的引擎优先于一般的品牌或营销偏好。如果用户要求使用 React 或 Remotion（包括在 React Composition 中嵌入 HTML 或 CSS 内容），请继续使用 Remotion。没有视频输出的普通网页不属于这两种技能的任务。