Remotion 视频 —— 编码实际帧
你是编码器和渲染器。 你获取 assets——录音、画外音、B-roll、转录文本——加上 React 代码,并输出一个真实文件:out/video.mp4。你的兄弟技能编写文字和计划;你是唯一生成像素的那个。这里的严谨之处在于可复现的帧:相同的输入,相同的确定性输出,通过 ffprobe 可读取的渲染进行验证。
你拥有 Remotion 项目脚手架、<Composition> / <Sequence> / <TransitionSeries> 图表、字幕管线(Whisper.cpp → toCaptions → createTikTokStyleCaptions)、静音移除处理以及 npx remotion render 命令及其编解码器和并发标志。
唯一的决策:帧还是文字?
如果要求是生成一个文件,那你就来对地方了。如果要求是生成文本或计划,则在编写任何 .tsx 文件之前路由出去。
| 需求 | 转至 | 原因 |
|---|---|---|
| 生成 MP4/MOV、过渡效果、烧录字幕、渲染 | 这里 | 这些是像素和帧 |
| 编写脚本、钩子、节拍、屏幕字幕文本、剪辑决策表 | ../video-shorts/SKILL.md | 那些是文字;剪辑决策,而非剪辑执行 |
将音频 mastering 到 LUFS 目标,生成章节 + RSS <item> | ../podcast/SKILL.md | 音频 mastering 和 feed,而非视频编码 |
| 构建课程/视频叙事弧线和流程 | ../course-storytelling/SKILL.md | 叙事架构,而非渲染 |
| 设计缩略图 | ../youtube-thumbnails/SKILL.md | 静态图像,而非视频 |
一句话边界:video-shorts 决定剪辑并编写字幕文本;你用代码执行剪辑并将字幕烧录到帧中。
搭建项目
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npm run dev # 在浏览器中打开 Remotion Studio
Remotion 当前稳定版本是 4.0.471;它需要 Node 16+(或 Bun 1.0.3+),本地渲染目标为 macOS 15 (Sequoia)+。自 2026 年 1 月起,Remotion 附带 Agent Skills——npx skills add remotion-dev/skills 将 Remotion 感知的指导接入 Claude Code。在 Remotion 项目中运行此命令,当你希望框架自身的技能与本技能一同加载时。
首先在 <Composition> 上固定 fps 和尺寸,并且永远不要在项目中期更改它们。 原因:每个下游持续时间都以帧为单位衡量,并且 frames = seconds * fps。在编写了持续时间后更改 fps,每个时间都会悄然偏移。 垂直短视频为 1080×1920 @ 30;横向为 1920×1080 @ 30。
合成图
// src/Root.tsx
import { Composition } from "remotion";
import { MyVideo } from "./MyVideo";
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo" // 你传递给 `remotion render` 的 id
component={MyVideo}
durationInFrames={300} // 30fps 下为 10s
fps={30}
width={1080}
height={1920}
/>
);
};
// src/MyVideo.tsx
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
export const MyVideo: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ frame, fps, config: { damping: 200 } });
return (
<AbsoluteFill style={{ backgroundColor: "black" }}>
<Sequence from={0} durationInFrames={90}>
<AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* 场景 1 */}</AbsoluteFill>
</Sequence>
<Sequence from={90} durationInFrames={210}>{/* 场景 2 */}</Sequence>
</AbsoluteFill>
);
};
仅使用 useCurrentFrame() 配合 interpolate() 和 spring() 进行动画。永远不要在合成内部读取挂钟时间(Date.now())或调用未种子化的 Math.random()。 原因:渲染是并行的且帧可寻址——每个帧独立计算,因此任何非帧输入都会在重新渲染时产生不同的像素,破坏“相同输入,相同输出”的保证。 如果你需要随机性,请使用 Remotion 的 random(seed)。
过渡效果
使用 @remotion/transitions(自 v4.0.53 起可用)。<TransitionSeries> 交织 .Sequence(一个片段,带有 durationInFrames)和 .Transition(一个 presentation + 一个 timing)。过渡持续时间会从总长度中减去,因此相邻序列会在擦除期间重叠。
import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
import { slide } from "@remotion/transitions/slide";
import { fade } from "@remotion/transitions/fade";
import { Easing } from "remotion";
<TransitionSeries>
<TransitionSeries.Sequence durationInFrames={90}>{/* 场景 A */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={slide({ direction: "from-left" })}
timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
/>
<TransitionSeries.Sequence durationInFrames={120}>{/* 场景 B */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={fade()}
timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
/>
<TransitionSeries.Sequence durationInFrames={90}>{/* 场景 C */}</TransitionSeries.Sequence>
</TransitionSeries>
每个 presentation 都是一个子导入(@remotion/transitions/slide, /fade, /wipe, /flip, /clockWipe, /none)。
| Presentation | 感觉/使用时机 |
|---|---|
slide | 场景将下一个推入;节拍之间的方向性动感 |
fade | 柔和的交叉淡入淡出;平静、中性的场景切换 |
wipe | 硬边扫过;充满活力,“下一个主题” |
flip | 3D 卡片翻转;有趣,用于揭示 |
clockWipe | 径向擦除;倒计时,“时光流逝” |
none | 无动作的硬切,但仍作为 TransitionSeries 节点 |
linearTiming 用于可预测的、帧精确的剪辑;springTiming 用于有机动感。 原因:线性在持续时间上是确定性的,因此可以精确预算帧;弹簧效果会超调并稳定下来,这看起来很自然,但需要 durationRestThreshold 以便渲染知道何时完成。
动画烧录字幕
原生的 @remotion/captions 包在 v4.0.216 中提供(与弃用旧版 convertToCaptions() 助手相同的版本)。管线在 Node 服务器上运行一次,然后合成读取字幕:
- 转录。
@remotion/install-whisper-cpp下载 Whisper.cpp 和一个模型(medium.en约 1.5 GB)并在 Node 服务器上转录音频为 Whisper JSON。 - 转换。
@remotion/install-whisper-cpp中的toCaptions()将该 JSON 转换为带有每个 token 时间戳的Caption[]。 (convertToCaptions()是旧版别名——自 v4.0.216 起已弃用;请使用toCaptions()。) - 分段为页面。
@remotion/captions中的createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })将 token 分组为一起出现的“页面”。
combineTokensWithinMilliseconds 值是页面大小调节器。 原因:低值(~200ms)将每个单词保留在自己的页面上 → 逐词弹出动画;高值(~1200ms)将短语打包到一个页面中。 低 ms = TikTok 逐词能量;高 ms = 可读短语。根据格式而非默认值选择。
完整的 Whisper.cpp 安装、转录服务器以及 token 高亮字幕渲染器组件(带有安全区样式)位于 references/captions-pipeline.md 中——在构建字幕层之前阅读它。
自动静音移除
静音处理在源音频/视频进入 Remotion 之前运行,而不是在合成内部。 原因:Remotion 渲染你给它的帧;修剪静音是对 asset 的上游编辑,首先进行修剪意味着每个下游帧号码都已经反映了收紧的时间线。
使用 auto-editor(一个 Python + ffmpeg 引擎)进行初始处理,通过音频响度剪切静音区域:
auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
--margin为每个保留区域添加边距,以免剪切干扰语音。--edit audio:threshold=4%设置响度阈值,低于该阈值的区域被视为“静音”。--export premiere输出 EDL/XML 而不是文件,以便重新导入 NLE。
pip 发行版已过时/停止维护——通过官方二进制文件或 pipx 安装,不要使用 pip install。 原因:PyPI 包滞后,可能无法匹配已记录的标志。 当 auto-editor 不可用时,底层回退方案是 ffmpeg 的 silencedetect / silenceremove 滤镜。两者及其完整标志矩阵均在 references/render-and-pipeline.md 中。
B-roll 叠加
通过将 <OffthreadVideo>(或 <Img>)嵌套在 <AbsoluteFill> 内,并使用 <Sequence from> 进行门控,将叠加层堆叠在主视频之上:
import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
const fps = 30;
const broll = { start: 4.0, duration: 3.0 }; // 秒
<AbsoluteFill>
<OffthreadVideo src={staticFile("main.mp4")} /> {/* 基础层 */}
<Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
<AbsoluteFill style={{ /* 例如,画中画的嵌入样式 */ }}>
<OffthreadVideo src={staticFile("broll.mp4")} /> {/* 叠加层 */}
</AbsoluteFill>
</Sequence>
</AbsoluteFill>
在边界处用 Math.round(seconds * fps) 将所有时间码转换为帧,只做一次。 原因:4.0秒的 B-roll 提示在 30fps 下是第 120 帧,但在 60fps 下是第 240 帧——在你的数据中保留秒数,并通过 useVideoConfig() 中的 fps 相乘,这样更改 fps 就永远不会使叠加层不同步。 在渲染期间使用 <OffthreadVideo>(而非 DOM <video> 或 <Video>)以实现帧精确解码。
渲染
# 首先测试区域:1-2 秒,低成本验证管线
npx remotion render MyVideo out/test.mp4 --frames=0-45
# 然后完整渲染
npx remotion render MyVideo out/video.mp4
省略合成 id 将获得交互式选择器。通过 @remotion/cli/config 在 remotion.config.ts 中配置,或通过 CLI 传递标志(标志优先):
// remotion.config.ts
import { Config } from "@remotion/cli/config";
Config.setConcurrency(8);
Config.setCodec("h264");
| 编解码器 | 用途 | 标志 |
|---|---|---|
h264 | 网络/YouTube 的默认值;广泛兼容性 | (默认) |
h265 | 文件更小,相同质量;播放兼容性较低 | --codec=h265 |
prores | 编辑级母版;文件大;重新导入 NLE | --codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png |
vp8 / gif | Web 透明度或循环预览 | --codec=vp8 / --codec=gif |
在进行完整渲染之前,始终先渲染 1–2 秒的区域(--frames=0-45)。 原因:几分钟长的合成完整渲染会消耗实际时间和 CPU;区域测试可以在几秒钟内揭示损坏的字幕层或缺失的 asset。 有关无头/CI 渲染、确定性输出规则以及完整的编解码器/质量矩阵,请参见 references/render-and-pipeline.md。
反模式
| 不良实践 | 为什么出错 | 正确做法 |
|---|---|---|
| 在 JSX 中硬编码以秒为单位的持续时间 | Remotion 以帧为单位思考;更改 fps 时秒钟会不同步 | 在数据中以秒存储,在边界处用 Math.round(seconds * fps) 转换 |
在合成中使用 Date.now() / 未种子化的 Math.random() | 帧并行渲染且重新渲染时 → 非确定性像素 | 一切基于 useCurrentFrame();使用 random(seed) |
编写持续时间后更改 fps | 每个下游帧计数悄然偏移 | 一开始就在 <Composition> 上固定 fps 和尺寸,不要改动 |
| 每次运行都重新下载 Whisper 模型 | ~1.5 GB 的 medium.en 下载重复进行,阻塞管线 | 下载一次,缓存模型路径,重复使用 |
| 将 1.5 GB 的 Whisper 模型提交到 git | 仓库膨胀;模型是构建 asset | 在 .gitignore 中忽略模型目录;在 setup/CI 中获取它 |
| 渲染完整视频来测试更改 | 浪费数分钟渲染来找出一个损坏的层 | 使用 --frames=0-45 区域测试,然后再完整渲染 |
| 在此处编写字幕副本或钩子 | 那是脚本,不是编码 | 路由到 ../video-shorts/SKILL.md;你只负责烧录 |
在渲染中使用普通的 <video> / <Video> 作为 B-roll | 帧不精确;渲染时撕裂或跳过 | 对于帧精确解码使用 <OffthreadVideo> |
| 在合成内部运行静音移除 | 修剪静音是上游 asset 编辑 | 在 Remotion 之前对源文件使用 auto-editor |
验证与参考资料
bash scripts/verify.sh <project-dir>— 检查 Remotion 项目格式是否正确并能够渲染。如果 Node + ffmpeg 存在,它会运行npx remotion compositions确认合成 id 存在,执行一个短区域渲染到临时 MP4,并使用ffprobe确认视频流具有预期的尺寸/fps。如果两者都不存在,则回退到静态检查:至少存在一个合成.tsx文件,并且渲染脚本引用了真实的合成 id 和输出路径。默认情况下为只读;在目标为空/清洁的情况下退出 0。references/captions-pipeline.md— 完整的 Whisper.cpp 安装 + 转录服务器、toCaptions、token 高亮字幕渲染器组件以及字幕样式/安全区说明。references/render-and-pipeline.md—auto-editor+ ffmpeg 静音命令、完整渲染标志矩阵、无头/CI 渲染、编解码器表格以及ffprobe验证。