Communitygithub.com

remotion-topic-explainer

AI 에이전트가 Remotion을 사용하여 60~90초 분량의 짧은 설명 영상(TikTok/YouTube Shorts/Reels)을 기획, 제작, 편집하는 방법을 안내하는 스킬입니다.

remotion-topic-explainer란 무엇인가요?

이 스킬은 AI 에이전트(예: Claude Code, Cursor, Codex)가 Remotion 프레임워크를 활용하여 고품질의 짧은 설명 영상(60~90초, 1080x1920, 30fps)을 제작할 수 있도록 상세한 워크플로우를 제공합니다. Hook-Problem-Solution-Value-Outro 구조의 6개 장면으로 구성된 비디오 구조와 정확한 타임라인(1800~2700 프레임)을 정의하며, OpenAI TTS(edge) 또는 CIT Voice Studio(오프라인 베트남어 음성)를 이용한 AI 음성 해설 생성 및 Remotion 프레임과의 동기화 방법을 포함합니다. 또한 Remotion 코딩 규칙(spring 애니메이션, 안전한 보간, Sequence/Series를 통한 오디오 동기화, 스냅한 전환 버퍼 등)을 필수적으로 준수하도록 안내하며, 최종적으로 Compositio을 등록하고 렌더링하는 전체 파이프라인을 단계별로 안내합니다. 이 스킬은 주로 Antigravity, Codex 등 Remotion 기반 비디오 생성 플랫폼에서 사용됩니다.

지원 대상✓Claude Code✓Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/hoangtuanqn/remotion-template/tree/HEAD/.agents/skills/remotion-topic-explainer

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

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

문서

Remotion 주제 설명 영상 스킬 (60-90초)

이 스킬은 주어진 주제로 고품질의 60-90초 짧은 설명 영상(TikTok / YouTube Shorts / Reels 형식: 1080x1920 @ 30fps)을 제작하는 방법을 안내합니다.

다음 요소들을 결합합니다:

  1. remotion-dev/skills의 시각적 모범 사례 (프레임 정확한 스프링, 클램핑 보간, 시퀀스 구성, 타이포그래피 계층 구조).
  2. AI 음성 해설 합성 - .env의 TTS_PROVIDER를 통해: edge (edge-tts-universal, 온라인, 무료) 또는 cit (CIT Voice Studio, 오프라인 베트남어 스튜디오 음성 - github.com/Cuongyd196/cit-voice-studio에서 다운로드, API 문서: docs/cit-voice-studio.md).
  3. 정확한 타이밍 동기화 - 오디오 음성 해설 길이를 Remotion 프레임 시퀀스에 직접 매핑.

1. 영상 구조 및 타이밍 (60-90초 / 1800-2700 프레임 @ 30fps)

매력적인 짧은 영상은 Hook-Problem-Solution-Value-Outro 프레임워크를 따릅니다:

장면이름시간프레임 범위 (@ 30fps)목적 및 시각 자료
1Hook0초 – 6초~180 프레임호기심을 유발하는 약속이나 질문과 함께 숫자, 처음 2초 안에 말함. 큰 제목, video-style의 hook 효과.
2맥락 / 문제점6초 – 17초~330 프레임문제나 주제가 중요한 배경을 제시. 양쪽에서 미끄러져 들어오는 대조되는 두 개의 카드.
3핵심 개념 파트 117초 – 32초~450 프레임핵심 원리 1: 흐릿한 유리 카드, 강조된 키워드.
4핵심 개념 파트 232초 – 48초~480 프레임작동 메커니즘: 3단계 프로세스, 점차 연결선 표시.
5실제 영향48초 – 64초~480 프레임실제 적용, 조언 또는 올라가는 숫자.
6아웃트로 및 CTA64초 – 75초~330 프레임한 마디로 요약, 채널 구독 버튼.

90초까지 길게 하려면 Outro 전에 1-2개의 추가 장면(구체적인 예, 참고 사항)을 추가합니다. 13초를 초과하는 장면은 둘로 나눕니다.

총 길이: 1800 – 2700 프레임 (약 60 – 90초).


2. TTS 음성 해설 생성 (edge | cit)

2.1 .env를 통한 음성 설정

.env 파일이 구성되었는지 확인합니다 (전체 내용은 .env.example 참조):

TTS_PROVIDER=edge                    # edge | cit
TTS_OUTPUT_DIR=public/audio

# Edge TTS (TTS_PROVIDER=edge)
EDGE_TTS_VOICE=vi-VN-HoaiMyNeural    # 또는 vi-VN-NamMinhNeural, en-US-ChristopherNeural
EDGE_TTS_RATE=+10%                   # +10% ~ +15%는 짧은 영상의 빠른 템포를 매력적으로 만듦

# CIT Voice Studio (TTS_PROVIDER=cit)
CIT_TTS_BASE_URL=http://127.0.0.1:8001
CIT_TTS_VOICE=Hải Đăng               # 음성 목록: docs/cit-voice-studio.md 또는 GET /voices
CIT_TTS_SPEED=1.1                    # 0.5 - 2.0

TTS_PROVIDER=cit인 경우:

  • CIT Voice Studio 앱이 열려 있어야 합니다. 스크립트는 오디오 생성 전에 자동으로 GET /health를 호출하고, 연결할 수 없다고 보고하면 사용자에게 앱을 열도록 안내합니다(또는 github.com/Cuongyd196/cit-voice-studio에서 다운로드).
  • 대사에 감정 태그 [cười], [thở dài], [hắng giọng] 및 휴지 태그 [nghỉ 0.5s]를 삽입할 수 있습니다(소리 내어 읽히지 않음). 남용 금지: 장면당 최대 1개 태그.
  • 오류 400 Voice not found = 잘못된 음성 이름(대소문자 구분). CIT_TTS_VOICE를 확인하세요.

2.2 오디오 파일 생성 절차

주제를 받으면 먼저 src/<TopicName>/ 디렉토리를 생성합니다. src/<TopicName>/audioData.ts는 이 디렉토리가 이미 존재할 때만 생성되기 때문입니다. 그런 다음 scripts/generate-<topic>-audio.ts를 만들고 실행하여 오디오를 생성합니다:

import { generateTopicVoices } from "./generate-tts";

const scenes = [
  {
    id: "scene1_hook",
    text: "Bạn có biết Docker thực chất là gì và tại sao mọi lập trình viên đều cần nó?",
  },
  {
    id: "scene2_problem",
    text: "Trước đây, câu nói 'trên máy tôi vẫn chạy được' luôn là cơn ác mộng khi bàn giao sản phẩm.",
  },
  {
    id: "scene3_concept1",
    text: "Docker giải quyết việc này bằng Container - đóng gói toàn bộ code và môi trường vào một khối duy nhất.",
  },
  {
    id: "scene4_concept2",
    text: "Khác với máy ảo nặng nề, Docker chia sẻ chung nhân hệ điều hành, giúp khởi động chỉ trong tích tắc.",
  },
  {
    id: "scene5_impact",
    text: "Nhờ đó, bạn deploy ứng dụng mượt mà trên mọi máy chủ từ AWS, GCP cho đến VPS giá rẻ.",
  },
  {
    id: "scene6_outro",
    text: "Follow kênh để nắm trọn các kiến thức công nghệ ngắn gọn mỗi ngày nhé!",
  },
];

generateTopicVoices("DockerShort", scenes).catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

오디오 파일은 각 장면에 대해 public/audio/<TopicName>/<sceneId>.<ext> (edge는 .mp3, cit는 .wav)에 자동 저장되며, 각 장면의 정확한 프레임 수(durationInFrames)와 audioPath를 기록한 manifest.json 파일이 함께 생성됩니다.

  • 각 장면에 대한 선택 사항: voice (선택한 공급자의 음성), rate/pitch/volume (edge만 해당), speed 0.5-2.0 (cit만 해당).
  • 이미 존재하는 파일은 재사용됩니다(캐시). 대사를 수정하거나 음성을 변경한 후 다시 생성하려면 해당 오디오 파일을 먼저 삭제하세요.

3. Remotion 코딩 규칙 (remotion-dev/skills에서)

Remotion 소스 코드를 작성할 때는 다음 규칙을 반드시 준수해야 합니다:

3.1 Spring 애니메이션 사용

CSS keyframes/transitions 또는 무의미한 linear easing을 사용하지 마세요. spring()을 사용하세요:

import { spring, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

// Card/Icon에 대한 부드러운 바운스 Spring
const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,    // 15 미만은 자연스러운 탄성 바운스 생성
    stiffness: 100,  // 장력
    mass: 0.8,
  },
});

const entrance = spring({
  frame: frame - 10, // 10 프레임 지연
  fps,
  from: 50,
  to: 0,
});

3.2 안전한 보간 (항상 Clamp)

타임라인이 범위를 벗어날 때 값 오버플로를 방지하기 위해 항상 extrapolateLeft: "clamp" 및 extrapolateRight: "clamp"를 제공하세요:

import { interpolate } from "remotion";

const opacity = interpolate(frame, [0, 15], [0, 1], {
  extrapolateLeft: "clamp",
  extrapolateRight: "clamp",
});

3.3 오디오 임베드 및 시퀀스 동기화

Composition의 각 장면은 <Sequence> 또는 <Series>를 사용하여 정확한 타이밍을 관리합니다:

import { Audio, staticFile, Sequence } from "remotion";

// Scene 컴포넌트 내에서 - manifest에서 경로를 가져오고, .mp3 확장자를 하드코딩하지 마세요(cit 공급자는 .wav 출력):
<Sequence from={0} durationInFrames={sceneDuration}>
  <Audio src={staticFile(audioManifest.scenes[0].audioPath)} />
  <SceneContent />
</Sequence>
  1. 간결한 장면 전환 버퍼 (Snappy Transition Buffer):
    • 장면 간 간격은 음성 해설이 끝난 후 +3 ~ +4 프레임(약 0.1초)만 남겨야 합니다.
    • 버퍼가 너무 길면(+15 ~ +20 프레임) 장면 사이에 침묵/데드 비트가 발생하여 영상의 빠른 템포와 매력을 유지하지 못합니다. 다음 장면은 이전 문장이 끝나자마자 나타나야 합니다.
// Series 내 장면 길이 계산 예시
// manifest의 값에는 이미 10프레임 버퍼가 포함되어 있으므로, 버퍼를 추가하기 전에 빼야 합니다.
const d1 = audioManifest.scenes[0].durationInFrames - 10 + 3;
const d2 = audioManifest.scenes[1].durationInFrames - 10 + 3;
// ...

3.4 시각적 디자인 표준 (세로 1080x1920)

전체 스타일(배경, 흐릿한 유리 카드, 브랜딩, 글꼴 크기, 레이아웃, 자막, 모션, 후크)은 video-style 스킬을 따릅니다. src/ClaudeBugHunterRepo/에서 theme.ts 및 components/를 복사하세요. 텍스트 내 장식용 이모지나 아이콘을 사용하지 마세요.


4. Antigravity / Codex를 위한 단계별 비디오 제작 절차

"[주제 X]에 대한 설명 비디오를 만들어 주세요" 라는 요청을 받으면:

단계 1: 대본 작성 (Scripting)

  1. 6개 장면(Hook, Problem, Concept 1, Concept 2, Impact, Outro)을 식별합니다.
  2. 자연스러운 베트남어 대사를 간결하게 작성합니다. 짧은 문장(총 260-330단어, 각 장면 35-50단어). 장면 1은 구체적인 약속이나 결과로 시작합니다. video-style의 Hook 및 대사 부분을 참조하세요.

단계 2: 음성 해설 생성 (TTS Generation)

  1. .env에서 TTS_PROVIDER를 읽어 edge 또는 cit를 사용 중인지 확인합니다.
  2. src/<TopicName>/ 디렉토리를 만든 다음 generateTopicVoices를 호출하는 scripts/generate-<topic>-audio.ts 스크립트를 만들고 npx tsx scripts/generate-<topic>-audio.ts를 실행합니다.
  3. manifest.json / src/<TopicName>/audioData.ts에서 실제 프레임 길이 목록을 가져옵니다.

단계 3: 코드 디렉토리 src/<TopicName>/ 생성

표준 디렉토리 구조:

src/<TopicName>/
├── <TopicName>.tsx          # 여러 Series.Sequence를 구성하는 메인 Composition
├── types.ts                 # Schema 및 Props
├── audioData.ts             # 오디오 길이 메타데이터
└── scenes/
    ├── Scene1Hook.tsx
    ├── Scene2Problem.tsx
    ├── Scene3Concept1.tsx
    ├── Scene4Concept2.tsx
    ├── Scene5Impact.tsx
    └── Scene6Outro.tsx

사운드 효과: src/sfx/SfxTrack.tsx의 <SfxTrack cues={...} />를 메인 컴포넌트에 배치하여 사용합니다. 오디오 파일은 public/sfx/에 있으며, npx tsx scripts/generate-sfx.ts를 실행하여 다시 생성합니다.

시점사운드
각 장면 시작, 새 문장 앞의 침묵 구간에 맞추기 위해 3프레임 일찍 (장면 1은 프레임 0)mallet
카드 또는 항목 등장pop 또는 tick
강조점, 결론ding
구독 유도 멘트chime
  • 각 cue의 frame은 비디오 시작부터의 프레임 번호이며, 해당 요소가 나타나는 시점과 일치해야 합니다.
  • 사운드 중복을 직접 피할 필요 없음: SfxTrack은 이전 cue와 0.4초 미만의 간격인 cue를 자동으로 제거하고, 동일한 사운드가 바로 뒤에 반복되면 볼륨을 줄입니다.
  • myinstants 또는 라이선스가 불명확한 사이트에서 사운드를 다운로드하지 마세요. 새 사운드가 필요하면 scripts/generate-sfx.ts에 추가하세요.

단계 4: src/Root.tsx에 Composition 등록

src/Root.tsx에 새로운 Composition을 추가합니다:

<Composition
  id="<TopicName>"
  component={<TopicName>}
  durationInFrames={totalFrames}
  fps={30}
  width={1080}
  height={1920}
  defaultProps={{}}
/>

단계 5: 확인 및 보고

  1. npm run lint를 실행하여 TypeScript/ESLint 오류를 확인합니다.
  2. 사용자에게 Remotion Studio에서 Composition을 열 수 있는 링크(http://localhost:3000) 또는 MP4 렌더링 명령어를 보고합니다:
    npx remotion render <TopicName> out/<TopicName>.mp4
    

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬