Remotion 视频自动化生产框架

概述

基于 Remotion 框架的视频自动化生产技能，实现从项目创建到最终渲染的全流程自动化。 包含 5 个专门 Agent 角色分工协作、6 阶段标准工作流程、10+ 常见坑预防方案和自动质量检查机制。

工作流程决策树

根据用户需求判断执行路径：

用户请求创建 Remotion 视频
│
├─ 1. 全新项目 → 执行完整六阶段流程（observe → define → execute → integrate → verify → render）
│
├─ 2. 已有项目修改 → 根据修改内容选择对应 Agent：
│   ├─ 修改场景/组件 → designer（Phase: execute）
│   ├─ 添加/修改音频 → audio_engineer（Phase: integrate）
│   ├─ 修复问题 → quality_inspector → 对应 Agent
│   └─ 重新渲染 → render_engine（Phase: render）
│
└─ 3. 仅咨询/问答 → 直接回答，引用 references/ 中的知识

六阶段标准流程

Phase 1: observe — 观察阶段（architect）

1. 分析用户需求：主题、时长、场景数量、是否需要音频、特殊要求
2. 检查环境依赖：

   node --version && npm --version
   python3 --version  # 可选，TTS 需要
   ffmpeg -version    # 可选，音频处理需要
   

3. 确定技术方案和依赖列表
4. 向用户确认需求理解

Phase 2: define — 定义阶段（designer）

1. 设计视频结构：场景列表、每个场景时长
2. 创建项目结构：

   mkdir -p src public/audio
   npm init -y
   npm install remotion @remotion/cli react react-dom
   npm install -D @remotion/player @types/react @types/react-dom typescript
   

3. 创建 tsconfig.json 和 src/Root.tsx 入口文件
4. 规划时间轴和组件架构

Phase 3: execute — 执行阶段（designer）

1. 创建各场景 React 组件

2. 实现动画效果（使用 spring()、interpolate()）

3. 严格遵守以下关键规则：

   致命规则（必须遵守）：

   • 统一坐标系 — 所有相关 SVG 元素必须在同一个 容器内
   • 组件引用验证 — 修改 Root.tsx 后立即确认导入路径正确
   • 时间计算使用 fps — const duration = fps * seconds，不使用硬编码数字
   • 使用 useVideoConfig() — 获取视频尺寸做响应式布局

   机械/物理动画正确性规则（当涉及物理对象动画时必须遵守）：

   • 齿轮统一模数系统 — 所有啮合齿轮必须共享同一个 module（模数）= 2 * pitchRadius / teeth。齿轮的 outerRadius/innerRadius 必须由 module 和 teeth 自动计算得出（addendum=module, dedendum=1.25*module），不能随意手写。违反此规则会导致齿大小不同，物理上无法啮合
   • 齿形对称性 — 齿轮路径生成的齿顶宽度和齿根宽度应接近 1:1（标准齿轮为 50/50），不能让齿顶只有齿距的 30%（会导致齿太窄，无法和对方的齿槽匹配）
   • 啮合相位偏移 — 两个啮合齿轮的从动轮必须偏移半个齿距。关键：SVG rotate() 用度数，不是弧度！ 必须用 180 / drivenTeeth（度），不能用 Math.PI / drivenTeeth（弧度）。弧度值被当成度数处理会导致偏移只有正确值的 1/57，几乎等于没有偏移
   • 角度/弧度单位一致性 — 任何涉及旋转的计算，必须确认全程使用同一单位。SVG rotate()、CSS transform rotate() 用度数；Math.sin/cos 用弧度。如果 driverRotation 是度数（如 localFrame * 1.2），则 phaseOffset 也必须是度数
   • 啮合间距 = 节圆半径之和 — 两个啮合齿轮的圆心距必须由 pitchRadius 计算得出，不能硬编码
   • 物理动画清单 — 编写完所有涉及物理对象（齿轮、杠杆、连杆、滑轮等）的组件后，必须逐场景确认：每个运动副的初始位置、旋转方向、相位关系、齿形比例是否在物理上正确。这一步在 TypeScript 编译检查之前执行

4. 运行 TypeScript 检查：npx tsc --noEmit

Phase 4: integrate — 集成阶段（audio_engineer）

1. 编写各场景的音频脚本文本
2. 使用 Edge-TTS 生成音频（详见 references/tts-guide.md）
3. 获取每个音频文件的精确时长：

   ffprobe -v error -show_entries format=duration -of csv=p=0 public/audio/title.mp3
   

4. 集成音频到视频组件：

   import { staticFile, Audio } from 'remotion';
   // 正确: 使用 staticFile() 包装路径
   

5. 根据音频时长调整视频总帧数：

   const totalFrames = Math.ceil(totalAudioDuration * fps);
   

Phase 5: verify — 验证阶段（quality_inspector）

执行质量门禁检查：

物理动画正确性检查清单（当视频包含齿轮、杠杆、连杆等物理对象时必查）：

1. 扫描所有场景组件代码，识别是否存在物理对象动画
2. 对每个运动副（啮合、铰接、滑动等），验证：
   • 单位一致性：所有角度计算是否统一使用度数（SVG）或弧度（Math），绝不混用。常见陷阱：Math.PI 返回弧度但被当作度数传给 SVG rotate()
   • 初始相位：从动件在 rotation=0 时是否处于正确初始位置（如齿轮的半个齿距偏移）
   • 空间间距：两个配合件的圆心距/接触点是否由它们的几何参数计算得出，而非硬编码
   • 传动关系：从动件的运动公式是否同时包含「速比」和「方向」两个要素
3. 如发现任何硬编码的位置参数、缺失的相位偏移、或单位混用，在渲染前修复
4. 渲染验证帧：渲染至少一帧静态截图，用视觉模型（如支持）或程序化分析确认物理动画正确

Phase 6: render — 渲染阶段（render_engine）

1. 停止预览服务器
2. 执行渲染：

   npx remotion render src/index.ts  out/output.mp4
   

3. 验证输出文件：

   ffprobe out/output.mp4
   

关键避坑规则

创建和修改 Remotion 项目时，必须遵守以下规则，避免常见致命错误：

1. staticFile() 包装 — 所有 public/ 目录下的资源必须使用 staticFile() 包装，路径相对于 public/ 目录，不包含 public 前缀
2. 单一 SVG 容器 — 相关的 SVG 元素必须在同一个 标签内，避免多个独立 SVG 导致坐标错位
3. Root.tsx 引用验证 — 每次创建或重命名组件后，必须检查 Root.tsx 中的导入路径
4. 时长类型安全 — 音频时长使用 number 类型，不使用字符串；使用 Math.ceil() 向上取整
5. 预览确认 — 每次代码修改后必须在预览中视觉确认

详细的问题描述和代码示例见 references/common-pits-and-solutions.md。

资源文件

references/

按需加载到上下文的参考文档：

• agent-roles.md — 5 个 Agent 角色的详细定义、职责、任务清单和检查点
• common-pits-and-solutions.md — 10+ 个常见坑的详细症状、原因、代码示例和解决方案
• workflow-phases.md — 六阶段工作流程的详细步骤和成功标准
• tts-guide.md — Edge-TTS 安装、配置、中文音色列表、语速调节和故障排除
• physical-animation-verification.md — ⭐ 物理动画验证检查范例（实战沉淀）：齿轮啮合四层 bug 剖析、通用验证四步流程（参数溯源→单位追踪→程序化验证→渲染帧确认）、Python 诊断脚本模板、扩展到其他物理对象的检查映射表

scripts/

可直接执行的脚本：

• generate-tts-audio.py — 使用 Edge-TTS 生成中文 TTS 音频文件，自动生成 audio-durations.json 时长配置
• setup.sh — 环境配置脚本，检查依赖、创建目录结构、安装 Node.js 依赖
• verify.sh — 验证脚本，检查项目结构、依赖安装、TypeScript 编译、音频文件等

实战示例

示例 1：创建全新视频项目

用户说："用 Remotion 创建一个关于量子计算的介绍视频，需要中文解说"

执行流程：

1. architect 分析需求：主题=量子计算，需要 TTS
2. designer 创建项目结构、设计 3-5 个场景
3. designer 开发各场景组件
4. audio_engineer 编写脚本、生成 TTS 音频、集成音频
5. quality_inspector 执行全部质量检查
6. render_engine 渲染最终视频

示例 2：为已有项目添加音频

用户说："给这个 Remotion 视频加上中文语音解说"

执行流程：

1. 检查现有项目结构
2. 编写音频脚本
3. 运行 generate-tts-audio.py 生成音频
4. 在组件中添加 组件
5. 根据音频时长调整视频时长
6. 验证和渲染

示例 3：修复问题

用户说："视频预览里元素位置对不上"

检查方向（引用 references/common-pits-and-solutions.md）：

1. 检查是否多个独立 SVG → 统一到单一 SVG 容器
2. 检查 Root.tsx 组件引用是否正确
3. 在预览中视觉确认修复效果