Communitygithub.com

ericrisco/rsc-harness

Remotion을 사용해 실제 비디오 파일을 렌더링할 때 사용하세요. React 컴포넌트, Composition/Sequence/TransitionSeries 그래프, 전환 효과, 대본에서 추출한 단어별 캡션, 자동 무음 제거, B-롤 오버레이, 헤드리스 CI 렌더링, 최종 MP4/MOV 파일을 생성합니다. 스크립트, 훅, 비트 또는 캡션 텍스트를 작성하는 것이 아니라면(이 경우 `video-shorts` 사용), 오디오를 LUFS로 마스터링하거나 RSS 피드를 구축하는 것이 아니라면(이 경우 `podcast` 사용), 내러티브 아크를 구성하는 것이 아니라면(이 경우 `course-storytelling` 사용) 이 스킬을 사용하세요.

rsc-harness란 무엇인가요?

이 스킬은 AI 코딩 에이전트(Claude Code 등)가 Remotion을 사용하여 실제 비디오 파일을 렌더링할 수 있도록 설계된 전문 도구입니다. 개발자가 비디오 편집 파이프라인 전반을 코드로 제어할 수 있게 해주며, 특히 React 컴포넌트를 기반으로 한 프레임 정확한 비디오 생성에 초점을 맞춥니다. 이 스킬의 핵심은 '동일한 입력, 동일한 출력'이라는 결정론적 렌더링 원칙에 있으며, 모든 프레임이 `useCurrentFrame()`과 같은 Remotion의 프레임 기반 API로 제어되어야 합니다. 주요 기능으로는 Composition/Sequence/TransitionSeries 그래프 구축, Whisper.cpp를 이용한 단어별 애니메이션 캡션 생성, `@remotion/transitions`를 사용한 다양한 전환 효과(슬라이드, 페이드, 와이프, 플립 등), `auto-editor`를 이용한 소스 오디오/비디오의 자동 무음 제거, 그리고 CI/CD 환경에서의 헤드리스 렌더링을 지원합니다. 또한 여러 코드(h264, h265, ProRes 등)를 지원하며, `video-shorts`, `podcast`, `course-storytelling` 같은 보완 스킬과의 명확한 경계를 정의하여 각 스킬이 특정 영역(텍스트 생성, 오디오 마스터링, 내러티브 설계 vs. 픽셀 렌더링)에 집중하도록 합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/remotion-video

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Remotion 비디오 — 실제 프레임 인코딩

당신은 인코더이자 렌더러입니다. 에셋(녹화본, 음성 해설, B-롤, 대본)과 React 코드를 입력받아 실제 파일인 out/video.mp4를 출력합니다. 당신의 동료 스킬들은 단어와 계획을 작성하지만, 당신은 픽셀을 생성하는 유일한 스킬입니다. 여기서 중요한 것은 재현 가능한 프레임입니다: 동일한 입력에 대해 동일한 결정론적 출력을 보장하며, ffprobe가 읽을 수 있는 렌더링으로 검증됩니다.

당신은 Remotion 프로젝트 스캐폴드, <Composition> / <Sequence> / <TransitionSeries> 그래프, 캡션 파이프라인(Whisper.cpp → toCaptions → createTikTokStyleCaptions), 무음 제거 패스, 그리고 코드 및 동시성 플래그가 포함된 npx remotion render 호출을 담당합니다.

하나의 결정: 프레임인가 단어인가?

요청이 파일을 생성하는 것이라면, 당신이 올바른 위치에 있습니다. 텍스트나 계획을 생성하는 것이라면, .tsx 파일 하나를 작성하기 전에 다른 경로로 라우팅하세요.

요청대상이유
MP4/MOV 생성, 전환 효과, 캡션 자막, 렌더링여기이것들은 픽셀과 프레임입니다
스크립트, 훅, 비트, 화면 내 캡션 텍스트, 편집 결정 시트 작성../video-shorts/SKILL.md이것들은 단어입니다; 컷 결정이지 컷 실행이 아닙니다
오디오를 LUFS 목표로 마스터링하고 챕터 + RSS <item> 생성../podcast/SKILL.md오디오 마스터링 및 피드지, 비디오 인코딩이 아닙니다
수업/비디오 내러티브 아크와 흐름 구성../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 명령어는 Claude Code에 Remotion 인식 가이드를 연결합니다. 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()만을 사용하여 애니메이션을 적용하세요. 컴포지션 내에서 벽시계 시간(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을 사용하세요. 이유: linear는 지속 시간이 결정적이어서 프레임을 정확하게 예산할 수 있습니다. spring은 오버슈트 후 안정되며 자연스러워 보이지만 렌더링이 완료되었는지 알기 위해 durationRestThreshold가 필요합니다.

애니메이션 자막 캡션

기본 @remotion/captions 패키지는 v4.0.216에서 제공되었습니다(이전 convertToCaptions() 헬퍼를 deprecated한 동일한 릴리스). 파이프라인은 Node 서버에서 한 번 실행된 후, 컴포지션이 캡션을 읽습니다:

  1. 전사. @remotion/install-whisper-cpp가 Whisper.cpp와 모델(medium.en은 약 1.5 GB)을 다운로드하고 Node 서버에서 오디오를 Whisper JSON으로 전사합니다.
  2. 변환. @remotion/install-whisper-cpp의 toCaptions()가 해당 JSON을 토큰별 타임스탬프가 있는 Caption[]로 변환합니다. (convertToCaptions()는 레거시 별칭입니다. v4.0.216부터 deprecated되었으며 toCaptions()를 사용하세요.)
  3. 페이지로 분할. @remotion/captions의 createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })는 토큰을 함께 표시될 "페이지"로 그룹화합니다.

combineTokensWithinMilliseconds 값은 페이지 크기 다이얼입니다. 이유: 낮은 값(~200ms)은 각 단어를 자체 페이지에 유지하여 단어별 팝 애니메이션을 만듭니다. 높은 값(~1200ms)은 구를 페이지당 패키징합니다. 낮은 ms = TikTok 단어별 에너지; 높은 ms = 읽기 쉬운 구. 기본값이 아닌 형식에 따라 선택하세요.

전체 Whisper.cpp 설치, 전사 서버, 토큰 강조 캡션 렌더러 구성 요소(안전 영역 스타일링 포함)는 references/captions-pipeline.md에 있습니다. 캡션 레이어를 구축하기 전에 읽어보세요.

자동 무음 제거

무음 패스는 Remotion에 들어가기 전에 소스 오디오/비디오에서 실행됩니다. 컴포지션 내부가 아닙니다. 이유: Remotion은 제공된 프레임을 렌더링합니다. 데드 에어를 트리밍하는 것은 에셋에 대한 업스트림 편집이며, 먼저 수행하면 모든 다운스트림 프레임 번호가 이미 단축된 타임라인을 반영합니다.

1차 패스로 오디오 볼륨에 따라 데드 스페이스를 잘라내는 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 배포는 오래되었거나 중단되었습니다. pip install 대신 공식 바이너리 또는 pipx를 통해 설치하세요. 이유: PyPI 패키지는 뒤쳐져 있으며 문서화된 플래그와 일치하지 않을 수 있습니다. auto-editor를 사용할 수 없는 경우, 저수준 대체 방법은 ffmpeg의 silencedetect / silenceremove 필터입니다. 두 가지 모두 전체 플래그 매트릭스와 함께 references/render-and-pipeline.md에 있습니다.

B-롤 오버레이

메인 비디오 위에 오버레이를 쌓으려면 <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={{ /* 예: PIP를 위한 삽입 영역 */ }}>
      <OffthreadVideo src={staticFile("broll.mp4")} />    {/* 오버레이 레이어 */}
    </AbsoluteFill>
  </Sequence>
</AbsoluteFill>

모든 타임코드를 Math.round(seconds * fps)를 사용하여 프레임으로 변환하고, 경계에서 한 번 수행하세요. 이유: 4.0초의 B-롤 큐는 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.config.ts에서 @remotion/cli/config를 통해 구성하거나 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웹 알파 또는 루프 미리보기--codec=vp8 / --codec=gif

전체 렌더링 전에 항상 1-2초 영역(--frames=0-45)을 먼저 렌더링하세요. 이유: 수 분 길이의 컴포지션을 전체 렌더링하는 데는 실제 시간과 CPU가 소모됩니다. 영역 테스트는 손상된 캡션 레이어나 누락된 에셋을 몇 초 만에 찾아냅니다. 헤드리스/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에 커밋저장소가 비대해집니다. 모델은 빌드 에셋입니다.모델 디렉토리를 .gitignore에 추가하고 설정/CI에서 가져오세요.
변경 사항을 테스트하기 위해 전체 비디오 렌더링손상된 레이어를 찾기 위해 몇 분의 렌더링이 낭비됩니다.--frames=0-45 영역 테스트 후 전체 렌더링
여기에서 캡션 사본 또는 훅 작성그것은 스크립트이지 인코딩이 아닙니다.../video-shorts/SKILL.md로 라우팅하세요. 당신은 자막만 입힙니다.
렌더링에서 B-롤에 일반 <video> / <Video> 사용프레임 정확하지 않으며 렌더링 시 찢어짐 또는 건너뛰기가 발생합니다.프레임 정확한 디코딩을 위해 <OffthreadVideo> 사용
컴포지션 내부에서 무음 제거 실행데드 에어 트리밍은 업스트림 에셋 편집입니다.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, 토큰 강조 캡션 렌더러 구성 요소, 캡션 스타일링/안전 영역 참고 사항.
  • 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`).

관련 스킬