Communitygithub.com

ericrisco/rsc-harness

用于渲染实际的 Remotion 视频文件——React 组合、Composition/Sequence/TransitionSeries 图表、过渡效果、从转录文本逐词烧录字幕、自动静音移除、B-roll 叠加、无头 CI 渲染以及最终生成 MP4 或 MOV 文件。

rsc-harness 是什么?

这是一个专注于 Remotion 视频编码与渲染的专业技能。它的核心职责是将 assets(录音、画外音、B-roll、转录文本等)和 React 代码转化为可复现的帧,最终输出 `out/video.mp4` 文件。该技能覆盖了 Remotion 项目的完整搭建、Composition/Sequence/TransitionSeries 图表构建、字幕管线(Whisper.cpp → `toCaptions` → `createTikTokStyleCaptions`)、自动静音移除、B-roll 叠加以及使用 `npx remotion render` 命令进行渲染的完整流程。它强调“可复现的帧”:相同的输入必须产生相同的确定性输出,且可通过 `ffprobe` 验证。该技能与编写脚本、音频 mastering 或叙事结构设计的技能严格区分,专注于像素和帧的执行,而非文字或流程设计。技能中详细说明了各种抗反模式(anti-patterns),例如在 Composition 中使用 `Date.now()` 或未种子化的 `Math.random()`、更改 fps 后不更新 duration 等,并提供了正确的实践方案。它适用于 macOS 15+ 和 Node 16+ 或 Bun 1.0.3+,Remotion 当前稳定版本为 4.0.471。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/remotion-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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硬边扫过;充满活力,“下一个主题”
flip3D 卡片翻转;有趣,用于揭示
clockWipe径向擦除;倒计时,“时光流逝”
none无动作的硬切,但仍作为 TransitionSeries 节点

linearTiming 用于可预测的、帧精确的剪辑;springTiming 用于有机动感。 原因:线性在持续时间上是确定性的,因此可以精确预算帧;弹簧效果会超调并稳定下来,这看起来很自然,但需要 durationRestThreshold 以便渲染知道何时完成。

动画烧录字幕

原生的 @remotion/captions 包在 v4.0.216 中提供(与弃用旧版 convertToCaptions() 助手相同的版本)。管线在 Node 服务器上运行一次,然后合成读取字幕:

  1. 转录。 @remotion/install-whisper-cpp 下载 Whisper.cpp 和一个模型(medium.en 约 1.5 GB)并在 Node 服务器上转录音频为 Whisper JSON。
  2. 转换。 @remotion/install-whisper-cpp 中的 toCaptions() 将该 JSON 转换为带有每个 token 时间戳的 Caption[]。 (convertToCaptions() 是旧版别名——自 v4.0.216 起已弃用;请使用 toCaptions()。)
  3. 分段为页面。 @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 / gifWeb 透明度或循环预览--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 验证。

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

ericrisco/rsc-harness

Use when writing the words on a single conversion page — the hero headline and subhead, the offer, the proof and testimonials, and one primary CTA — or diagnosing a page that gets traffic and does not convert, as a copy problem rather than a layout one. NOT the paid ad that drives the click (that is `ads`), NOT the visual layout the words sit in (that is `design`), NOT the experiment that picks the winning variant (that is `ab-testing`).

ericrisco/rsc-harness

Use when you have raw 9:16 footage and need it cut into a post-ready vertical short — dead air removed, fast jump cuts, karaoke word-by-word burned-in captions from a transcript, cuts and zooms snapped to the music beat, safe-area placement so captions clear the platform UI, and a platform-correct MP4 export. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT building a Remotion React composition codebase (that is `remotion-video`), NOT deciding when or where to post (that is `social-publisher`).

ericrisco/rsc-harness

Use when a Reels/TikTok/Shorts account needs its next video ideas scored into a ranked backlog, grounded in its own performance log plus dated trending sounds, each bet logged so its outcome feeds the next batch. NOT scripting a chosen idea (that is `video-shorts`), NOT pillars or cadence (that is `shortform-strategy`), NOT packaging a finished cut (that is `shortform-packaging`).

ericrisco/rsc-harness

Use when a vertical short is shot or scripted and you need the upload-form copy and cover that win the feed — the hook line, the first-frame on-screen text, the search-led caption, a tight hashtag set, and the cover frame; it learns from what performed via the 02-DOCS log. NOT inventing the idea (that is `shortform-ideation`), NOT scripting or directing the cuts (that is `video-shorts`), NOT executing the edit (that is `shortform-editing`), NOT scheduling the post (that is `social-publisher`).

ericrisco/rsc-harness

Use when the unit of work is a TikTok/Reels account, not one clip: positioning, sustainable cadence and format mix, ride-or-skip on a trend or sound, recurring series, diagnosing a flat account, and the dated learning loop. NOT the single script or hook variants (that is `video-shorts`), NOT the idea backlog (that is `shortform-ideation`).

ericrisco/rsc-harness

Use when planning a posting schedule, building a multi-platform content calendar, or reshaping one source asset into channel-native posts across X, LinkedIn, Instagram, Threads, Bluesky, TikTok, Facebook or YouTube — cadence, best-time slots, per-platform format limits, API publish caps, and a dated CSV or JSON calendar a scheduler can import. NOT the brand voice the posts speak in (that is `brand-voice`), NOT the editorial strategy of what to make (that is `content-engine`).

ericrisco/rsc-harness

Use when connecting a real TikTok account to code via the Content Posting, Display and Business Account APIs — OAuth, chunked video publish with status polling, and pulling views, watch time and impression sources, then logging that performance into the wiki as a dated feedback record. Covers short-lived tokens breaking a cron, unverified pull-from-URL ownership, and rate limits. NOT what to post or how to package it (that is `shortform-strategy` and `shortform-packaging`).

ericrisco/rsc-harness

Use when scripting or directing the edit of a single vertical short that has to hold attention from the first frame — turning a topic, a clip or a long video into a shot-by-shot script and an edit decision sheet, fixing a hook that dies in second three, generating hook variants to test, and planning cuts and on-screen text. NOT scheduling or cross-platform cadence (that is `social-publisher`), NOT running the editorial calendar (that is `content-engine`), NOT defining the durable brand tone (that is `brand-voice`).

ericrisco/rsc-harness

Use to judge whether a short-form clip is worth publishing — scores a reel, short or podcast excerpt 0-100 on ten weighted criteria with automatic penalties, then ranks a batch and says where the cut-off falls. Run it on transcript candidates before rendering. NOT writing the hook or caption (that is `shortform-packaging`), NOT inventing the idea (that is `shortform-ideation`), NOT executing the edit (that is `shortform-editing`).

相关技能