Communitygithub.com

ericrisco/rsc-harness

當你需要使用 Remotion 渲染實際影片檔案時使用 — 包括 React 組合、Composition/Sequence/TransitionSeries 圖表、轉場效果、從逐字稿燒錄逐字逐句字幕、自動移除靜音、B-roll 疊加、無頭 CI 渲染,以及最終的 MP4 或 MOV 檔案。不負責編寫腳本、鉤子、節奏或字幕文字(那是 `video-shorts` 的職責),不負責將音訊處理至 LUFS 標準或建立 RSS feed(那是 `podcast` 的職責),也不負責建構敘事弧線(那是 `course-storytelling` 的職責)。

rsc-harness 是什麼?

這個技能是 Remotion 影片編碼與渲染的專用工具。它負責將資產(錄音、旁白、B-roll 素材、逐字稿)與 React 程式碼結合,產出實際的影片檔案(如 `out/video.mp4`)。其核心原則是「可重現的影格」:相同的輸入必定產生相同的輸出,並可透過 `ffprobe` 驗證。它擁有完整的 Remotion 專案結構、〈Composition〉/〈Sequence〉/〈TransitionSeries〉圖表、字幕處理管線(Whisper.cpp → `toCaptions` → `createTikTokStyleCaptions`)、靜音移除流程,以及 `npx remotion render` 的呼叫(含 codec 與並行度旗標)。 此技能會明確劃分職責界限:若任務是產生實際的影片檔案(MP4/MOV),則在此處理;若是產生文字或計劃,則應轉交給其他技能(如 `video-shorts` 負責腳本與字幕文字、`podcast` 負責音訊處理、`course-storytelling` 負責敘事結構)。這避免了像素與文字的混淆。 它支援所有主流開發者平台(Claude Code、Cursor、Codex 等),只要是使用 Remotion 框架進行影片渲染的專案即可適用。使用方式包括:建立專案、定義 Composition 圖表、實作轉場與字幕、執行自動靜音移除、疊加 B-roll 素材,最後執行渲染指令。關鍵最佳實踐包括:一律先渲染短片段(如 `--frames=0-45`)以驗證管線,避免在 Composition 內使用非確定性函式(如 `Date.now()`),以及將 fps 與解析度固定於 Composition 上。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Remotion 影片 — 編碼實際影格

你是編碼器與渲染器。 你接收資產 — 錄音、旁白、B-roll 素材、逐字稿 — 以及 React 程式碼,並產出一個實際檔案:out/video.mp4。你的同儕負責撰寫文字與計劃;你是唯一產生像素的人。這裡的嚴謹原則是可重現的影格:相同輸入、相同確定性輸出,並透過 ffprobe 可讀的渲染進行驗證。

你擁有 Remotion 專案架構、<Composition> / <Sequence> / <TransitionSeries> 圖表、字幕處理管線(Whisper.cpp → toCaptions → createTikTokStyleCaptions)、靜音移除流程,以及帶有 codec 和並行度旗標的 npx remotion render 呼叫。

一個決定:影格還是文字?

如果要求是產出一個檔案,你來對了地方。如果要求是產出文字或計劃,在寫任何 .tsx 之前先轉交出去。

要求項目轉交給原因
產出 MP4/MOV、轉場、燒錄字幕、渲染這裡這些是像素與影格
編寫腳本、鉤子、節奏、螢幕字幕文字、剪輯決策表../video-shorts/SKILL.md那些是文字;剪輯的決策,而非剪輯的執行
將音訊處理至 LUFS 目標、產出章節 + RSS <item>../podcast/SKILL.md音訊處理與 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-aware 的指引整合到 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 下 10 秒
      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() 來製作動畫。切勿在 composition 內讀取牆上時鐘時間 (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 伺服器上執行一次,然後 composition 讀取字幕:

  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 之前執行的,而非在 composition 內部。原因:Remotion 渲染你提供的影格;修剪靜音是資產的上游編輯,先執行此操作意味著每個下游影格編號都已經反映了修剪後的時間軸。

使用 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 疊加

透過在 <AbsoluteFill> 內部使用 <OffthreadVideo>(或 <Img>)並以 <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

省略 composition id 會顯示互動式選取器。透過 @remotion/cli/config 在 remotion.config.ts 中進行設定,或在 CLI 上傳遞旗標(旗標優先):

// remotion.config.ts
import { Config } from "@remotion/cli/config";
Config.setConcurrency(8);
Config.setCodec("h264");
Codec用途旗標
h264網頁/YouTube 的預設值;廣泛相容性(預設)
h265檔案更小,相同品質;播放支援較少--codec=h265
prores編輯級母帶,檔案大,可重新匯入 NLE--codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png
vp8 / gif網頁 Alpha 或循環預覽--codec=vp8 / --codec=gif

務必在完整渲染之前,先渲染一個 1-2 秒的區域(--frames=0-45)。 原因:對數分鐘長的 composition 進行完整渲染需要實際的時間和 CPU;區域測試可以在幾秒內發現損壞的字幕層或遺失的資產。 關於無頭/CI 渲染、確定性輸出規則,以及完整的 codec/品質矩陣,請參閱 references/render-and-pipeline.md。

反模式

不良實踐為何會出錯良好實踐
在 JSX 中硬編碼以秒為單位的持續時間Remotion 以影格為單位思考;fps 一變,秒數就不同步在資料中儲存秒數,邊界處 Math.round(seconds * fps)
在 composition 中使用 Date.now() / 未設種子的 Math.random()影格並行渲染且在重新渲染時 → 非確定性像素一切依賴 useCurrentFrame();使用 random(seed)
在寫入持續時間後更改 fps每個下游影格計數會無聲地偏移先在 <Composition> 上固定 fps + 尺寸,然後保持不變
每次執行都重新下載 Whisper 模型約 1.5 GB 的 medium.en 重複下載並阻塞管線下載一次,快取模型路徑,重複使用
將 1.5 GB 的 Whisper 模型提交到 git膨脹儲存庫;模型是建置資產在 .gitignore 中加入模型目錄;在設定/CI 中獲取
為了測試一個變更而渲染完整影片浪費數分鐘的渲染時間來發現一個損壞的圖層先 --frames=0-45 區域測試,再完整渲染
在此處撰寫字幕文案或鉤子那是腳本,不是編碼轉交給 ../video-shorts/SKILL.md;你只負責燒錄
在渲染中使用一般的 <video> / <Video> 作為 B-roll非影格精確;會在渲染時撕裂或跳幀使用 <OffthreadVideo> 以獲得影格精確的解碼
在 composition 內部執行靜音移除修剪靜音是上游資產編輯在來源檔案上使用 auto-editor,然後才進 Remotion

驗證與參考資料

  • bash scripts/verify.sh <project-dir> — 檢查 Remotion 專案格式是否正確並可渲染。如果 Node + ffmpeg 存在,它會執行 npx remotion compositions 確認 composition id 存在,對臨時 MP4 進行短區域渲染,並使用 ffprobe 確認存在具有預期尺寸/fps 的影片串流。如果兩者都不存在,它會回退到靜態檢查:至少存在一個 composition .tsx,且渲染腳本引用了一個真實的 composition id 和一個輸出路徑。預設為唯讀;若目標為空/乾淨則退出 0。
  • references/captions-pipeline.md — 完整的 Whisper.cpp 安裝 + 轉錄伺服器、toCaptions、token 高亮字幕渲染器元件,以及字幕樣式/安全區備註。
  • references/render-and-pipeline.md — auto-editor + ffmpeg 靜音指令、完整的渲染旗標矩陣、無頭/CI 渲染、codec 表格,以及 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`).

相關技能