remotion-core

Remotion Core

Remotion 使用 React 渲染视频。合成是一个 React 组件，其输出是帧索引的纯函数——同一帧始终产生相同的像素。所有动画都必须由 useCurrentFrame() 推导，绝不能使用 Date.now()、Math.random() 或任何外部可变状态。

本技能是技术规范——介绍如何构建一个 Remotion 项目。下文是构建指南；各主题的详细内容位于 references/（见下方索引），按需阅读。

参考资料

文件	阅读目的…
references/minimal-composition.md	从最小可渲染的合成骨架开始
references/composition-patterns.md	选择独立或嵌套结构；组织 Root.tsx；使用 Sequence 和 Series
references/timing-api.md	使用 useCurrentFrame、useVideoConfig、interpolate、spring、measureSpring
references/sequence-and-series.md	使用 <Sequence from> 为片段计时、使用 <Series> 串联场景、处理嵌套偏移
references/media-elements.md	放置 <OffthreadVideo>、<Audio>、<Img>，进行裁剪、调节音量、设置 startFrom
references/determinism-rules.md	构建帧确定性合成；了解禁用的 API 和允许使用的动画原语
references/calculate-metadata.md	动态声明时长、fps、尺寸；在渲染前获取数据；定义 InputProps 架构
references/static-files.md	通过 staticFile() 引用资源；使用 getStaticFiles()；了解 public/ 目录
references/storyboard-format.md	编写 STORYBOARD.md 计划
references/review-loop.md	执行计划 → 草稿 → 构建评审流程
references/production-loop.md	将已批准的计划制作成最终交付视频
references/brief-format.md	编写 BRIEF.md——已确认的意图文档
references/script-format.md	编写可选的 SCRIPT.md 定稿旁白

动画相关细节（弹簧物理、interpolate 外推、交错）请参阅 remotion-animation → adapters/。

构建合成

唯一的根规则

每个合成入口文件（src/Root.tsx）都导出一个 RemotionRoot，通过 <Composition> 注册合成。每个 <Composition> 都指向一个 React 组件——不得有全局可变状态，也不得在模块加载时产生副作用。

// src/Root.tsx
import {Composition} from 'remotion';
import {MyScene} from './MyScene';

export const RemotionRoot: React.FC = () => (
  <>
    <Composition
      id="MyScene"
      component={MyScene}
      durationInFrames={150}
      fps={30}
      width={1920}
      height={1080}
    />
  </>
);

由帧驱动渲染（不可妥协）

每个视觉值都由 useCurrentFrame() 计算。渲染器使用可能并行运行的浏览器实例独立捕获每一帧——读取外部可变状态的代码会在不同线程上产生不同像素。

import {useCurrentFrame, useVideoConfig, interpolate, spring} from 'remotion';

const MyScene: React.FC = () => {
  const frame = useCurrentFrame();
  const {fps, durationInFrames} = useVideoConfig();

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

  return (
    <AbsoluteFill style={{opacity, transform: `scale(${scale})`}}>
      <h1>Hello Remotion</h1>
    </AbsoluteFill>
  );
};

不可妥协的规则（自动检查可能漏掉的隐蔽错误）

• 禁止使用 Math.random()——使用 'remotion' 中的 random(seed) 生成带种子的伪随机数
• 禁止使用 Date.now() / performance.now()——所有基于时间的值都使用 useCurrentFrame()
• 渲染路径中禁止使用 setTimeout / setInterval——仅可在 calculateMetadata 的异步作用域中使用
• 禁止使用 useState/useEffect 控制视觉属性——所有视觉状态都必须从帧索引推导
• 禁止使用 CSS transitions/animations——它们独立于 Remotion 的时间线定位运行
• 禁止无限循环——repeat(-1) 或等效写法会让渲染器卡住
• 禁止使用 useRef 保存由帧推导的可变状态——定位时 refs 会重置

完整说明 → references/determinism-rules.md。

合成尺寸

始终在 <Composition> 上显式提供 width、height、fps 和 durationInFrames。在由 props 驱动时，可通过 calculateMetadata 动态设置这些值。

AbsoluteFill——场景根节点

<AbsoluteFill> 等同于 position: absolute; top: 0; left: 0; width: 100%; height: 100%——将其用作场景根节点，取代手动创建的 div。它可确保内容铺满画面，并正确进行合成。

import {AbsoluteFill} from 'remotion';

const MyScene = () => (
  <AbsoluteFill style={{backgroundColor: '#0f0f0f'}}>
    {/* scene content */}
  </AbsoluteFill>
);

Sequence — 片段原语

<Sequence from={startFrame} durationInFrames={duration}> 会为其子元素偏移时间线。子元素看到的第 0 帧对应父级的 from 帧。这样组合场景时就不必到处硬编码帧数计算。

import {Sequence} from 'remotion';

const Timeline = () => (
  <>
    <Sequence from={0} durationInFrames={60}>
      <IntroScene />
    </Sequence>
    <Sequence from={60} durationInFrames={90}>
      <MainScene />
    </Sequence>
    <Sequence from={150} durationInFrames={60}>
      <OutroScene />
    </Sequence>
  </>
);

媒体元素

• <OffthreadVideo> — 用于视频文件；在主线程之外渲染每一帧；支持 startFrom、endAt、volume
• <Audio> — 音频文件；支持 startFrom、endAt、volume
• <Img> — 图片；public/ 目录中的资源使用 staticFile()

public/ 目录中的所有媒体路径都必须通过 staticFile('filename') 设置。

编辑现有合成

• 先阅读文件。保留无关的时间设置、ID 和 props 接口。
• 与现有合成 ID 和组件签名保持一致。
• 添加场景时：使用不重叠的 <Sequence from> 偏移量。
• calculateMetadata 会在渲染前运行一次 — 切勿在渲染时调用。

验证

使用 remotion-cli 查看命令详情：

• npx remotion studio 可打开，且控制台无错误
• 所有合成都能在时间线中显示并可拖动定位
• npx remotion render <entry> <id> out/test.mp4 --concurrency=1 可生成非空文件
• ffprobe out/test.mp4 报告预期的时长和分辨率
• 仅在用户批准预览后进行渲染