Communitygithub.com

Lunamos/paper2video

연구 논문(arXiv 링크나 제목만으로 충분) 또는 프로젝트(저장소, PDF, 프로젝트 페이지, 작업 디렉토리)를 Remotion으로 제작된 3Blue1Brown 스타일의 설명/홍보 영상으로 변환합니다. 스크립트, 음성 해설(선택적 TTS 키, 무료 또는 자체 녹음 대안), 실제 데이터 애니메이션, 자막, 음악, 이중 언어 컷, 세로형 컷, 커버, YouTube 및 Bilibili용 플랫폼 카피를 포함합니다.

paper2video란 무엇인가요?

이 스킬은 연구 논문이나 프로젝트를 전문적이고 매력적인 설명/홍보 영상으로 변환하는 완전 자동화된 파이프라인을 제공합니다. 사용자는 arXiv 링크나 논문 제목만 제공하면 되며, 나머지는 스킬이 자동으로 처리합니다: 소스 자료 수집(참조 문서 `reference/third-party.md` 활용), 논문 이해, 스토리 구성, 스크립트 작성, 음성 해설 생성(기본 ElevenLabs 또는 edge-tts), 실제 데이터 기반 애니메이션 제작, 자막 및 음악 추가, 최종 렌더링까지 수행합니다. 주로 Remotion(React 기반 비디오 라이브러리)을 사용하며, Claude Code, Cursor, Codex 등 AI 에이전트 플랫폼에서 실행됩니다. 특히 학술 연구의 핵심 내용을 왜곡하지 않고 일반 대중도 이해할 수 있도록 데이터를 시각화하고, 하나의 아이디어를 하나의 비트(beat)로 전달하는 데 중점을 둡니다. 이중 언어(영어 및 중국어) 컷과 세로형(9:16) 컷을 기본 지원하며, YouTube 및 Bilibili 업로드에 필요한 모든 메타데이터(제목, 설명, 챕터, 커버 이미지 등)를 자동 생성합니다. 사용자 정의가 필요한 경우(예: 첫인칭/삼인칭, 음성 선택, 특정 내용 제외 등)에만 질문하고, 나머지는 합리적인 기본값으로 자동 진행됩니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Lunamos/paper2video/tree/HEAD/skills/paper2video

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

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

문서

paper2video은(는) 무엇을 하나요?

컨텍스트가 없는 낯선 사람도 따라올 수 있고, 연구 작업에 충실하며, 공유하기에 충분히 좋아 보이는 비디오를 만듭니다: 실제 데이터를 초반에 화면에 배치하고, 비트(beat)당 하나의 아이디어를 전달하며, 장식이 아닌 설명을 위한 부드러운 모션을 사용합니다.

당신은 리드입니다: 계획을 세우고, 공유 구성 요소를 구축하며, 유용할 때 하위 에이전트에게 범위가 명확한 작업을 분배하고, 통합하며, 정확성을 책임집니다. 사용자가 체크포인트를 요청하지 않는 한 처음부터 끝까지 자동으로 작업합니다. 사용자에게 질문이 아닌 결과(스틸 이미지, 초안, 렌더링)를 보여주며, 합리적인 기본값이 존재할 때마다 그렇게 합니다.

지원 자료 (해당 단계에 도달하면 읽기):

  • reference/rigor.md — 주장 원장(claims ledger), 데이터 처리, 독립적 사실 확인
  • reference/voice.md — 나레이션 백엔드 (ElevenLabs / 무료 edge-tts / 자체 호스팅 GPT-SoVITS / 사용자 자체 녹음 / 없음), 품질 관리, 발음, 오픈소스 TTS 노하우
  • reference/visual-style.md — 디자인 시스템, 모션 규칙, 데이터 정직성, 검토 루프
  • reference/platforms.md — YouTube + Bilibili 산출물: 사양, 커버, 제목, 설명, 챕터
  • reference/vertical.md — 9:16 휴대폰 컷: 안전 영역, 글자 크기, 비트당 하나의 포커스, 후크(hook), 동일한 오디오로 구축하기
  • reference/handoff.md — 사용자 자체 자료 사용 및 편집 소프트웨어로 내보내기
  • reference/third-party.md — arXiv 링크/제목만 있는 경우 출발: 소스, 코드 및 데이터 찾기; LaTeX/그림에서 숫자 추출; 소형 CPU 일러스트레이션; 논문이 사용자 소유가 아닐 때의 충실성
  • scripts/ — 파이프라인 (scripts/README.md 참조); template/ — Remotion 스타터 (template/README.md 참조)

0. 인테이크 (간결하게)

필요한 것: 작업물 — arXiv 링크나 논문 제목만으로 충분합니다 (그러면 reference/third-party.md를 따라 소스, 코드, 데이터를 직접 찾습니다); 저장소, 경로, 프로젝트 페이지 또는 읽기 가능한 원격 머신도 작동합니다. 누구의 작업물인가: 사용자 자신의 것 (1인칭 허용) 또는 다른 사람의 것 (3인칭, 충실하게, 출처 표시 — reference/third-party.md). 언어 및 플랫폼 (기본값: YouTube용 영어 컷과 Bilibili용 중국어 컷, 둘 다 16:9, 여러 크기의 커버와 각각의 제목/설명/챕터 포함), 그리고 나레이션 (reference/voice.md 참조; 기본값: 환경 변수/.env에 키가 있으면 ElevenLabs, 그렇지 않으면 edge-tts, 그리고 그렇게 알립니다). 기본값을 정할 수 없는 것만 질문하십시오. 또한 한 번 질문하십시오: 1인칭 ("저희 논문") 또는 3인칭 ("이 논문"), 그리고 절대 나타나서는 안 되는 것 (미공개 사이드 프로젝트, 익명 제출, 개인 데이터).

모든 원격/공유 리소스는 달리 지시하지 않는 한 읽기 전용으로 취급하십시오. 큰 것을 가져오기 전에 파일과 크기를 나열하십시오 (약 500 MB 이상이면 물어보십시오). 키를 인쇄하거나 커밋하지 마십시오.

1. 워크숍 설정

  1. 새 폴더에 Remotion 프로젝트를 만듭니다 (예: npx create-video@latest --blank, 또는 최신 Remotion 빈 템플릿 복사). 사용자가 직접 아무것도 설치하게 하지 마십시오 — Node 종속성을 직접 설치하고, ffmpeg, python3 및 uv를 확인하십시오 (uv가 없으면 공식 스크립트나 pip를 통해 설치).
  2. 공식 Remotion 에이전트 스킬이 아직 없으면 설치합니다 (~/.agents/skills/remotion-*에 있거나 스킬에 나열됨): npx -y skills add remotion-dev/skills (현재 명령어는 remotion.dev/docs/ai 참조). Remotion API 세부 정보는 이를 따르십시오.
  3. template/을 프로젝트에 복사하고 (package.additions.json을 package.json에 병합, npm install), scripts/를 <project>/scripts/에 복사하고, notes/, data/ (raw, git-ignored), public/data/, out/ (현재 산출물만, 고정된 이름: reference/platforms.md → Files), review/ (일회용 스틸 이미지 및 연락처 시트), 그리고 프로젝트 CLAUDE.md를 만듭니다. CLAUDE.md에는 다음을 기록합니다: 목표, 대상, 언어, 음성 선택, "절대 나타나서는 안 되는" 목록, 진실의 원천 문서, 그리고 도착하는 모든 사용자 피드백 (날짜 포함). 항상 최신 상태로 유지하십시오 — 이것이 이후 세션(및 하위 에이전트)의 일관성을 유지하는 방법입니다.
  4. npx tsc --noEmit을 실행하고 템플릿의 스틸 이미지 하나를 렌더링하여 도구 체인이 작동하는지 확인합니다.
  5. 여러 비디오를 만드시나요? 워크스페이스를 사용하십시오: 공유 package.json/node_modules (하나의 설치, 비디오당 ~400 MB 대신; 모든 @remotion/*이 하나의 버전)과 공유 .env를 포함하는 하나의 폴더, 그리고 모든 비디오에 대한 상시 규칙이 있는 워크스페이스 CLAUDE.md (Claude Code는 상위 CLAUDE.md 파일을 읽습니다). 각 비디오는 자체 폴더 (src/, public/, scenes.json, notes/, data/, out/, review/, audio_cache/, scripts/, 자체 CLAUDE.md)를 가지며, node_modules와 .env는 워크스페이스 루트에 연결됩니다. scripts/new_video.sh <ShortName> (워크스페이스 루트에 복사)은 이를 <NNN>_<ShortName>으로 생성하며, 999부터 번호를 내림차순으로 매겨 이름별 정렬 시 비디오가 먼저 나오고 최신 항목이 위에 오도록 합니다. 공유 버전을 변경한 후에는 모든 비디오에 대해 타입 검사를 수행하고 몇 개의 렌더링된 프레임을 최종 파일과 비교하십시오.

2. 한 글자도 쓰기 전에 작업 이해하기

먼저 자료를 수집하십시오 (링크나 제목만 있는 경우 reference/third-party.md §1–2). 논문 (및 부록)을 처음부터 끝까지 읽고, README/프로젝트 페이지를 읽고, 코드를 훑어보며 그림이 무엇으로 만들어졌는지 확인하십시오. 핵심 발견과 그것이 놀라운 이유, 시청하기 재미있는 요소 (가장 놀라운 관찰, 가장 영리한 실험, 사람들을 미소짓게 하는 예시), 저자의 의도 (각 실험이 답하는 질문, 왜 그렇게 설정했는지, 무엇을 시도했는지), 이야기를 이끄는 2–4개의 주장, 그리고 실제 데이터 (그림 데이터 내보내기, 결과 JSON, 기록된 메트릭, 데모 출력)로 이를 보여줄 수 있는 시각 자료를 찾으십시오. 플롯 디지타이징보다는 내보낸 그림 데이터나 원시 결과를 선호하십시오. notes/understanding.md를 작성하십시오: 한 문장의 스토리, 숫자와 설정이 포함된 주장, 후보 시각 자료, 혼동되거나 과장하기 쉬운 모든 것.

3. 스토리, 스크립트 및 주장

  • 길이와 초점이 먼저입니다. 기본값: 컷당 3–4분, 최대 4:00, 사용자가 더 요청하지 않는 한 — 약 450–600 영어 단어 또는 1,100–1,300 중국어 문자의 나레이션. 비디오는 논문을 읽어주는 것이 아닙니다: 전체 영화가 제공하는 하나의 발견과 이를 뒷받침하는 2–3개의 증거를 선택하고, 다른 모든 것은 한 문장으로 처리하거나 설명에 남겨두십시오. 충실함(faithful)은 어떤 것도 왜곡되지 않음을 의미하며, 모든 섹션이 등장해야 함을 의미하지 않습니다.
  • 재미있게, 그러나 엄격함이 우선. 증거 비트로 가장 흥미로운 실험과 예시를 선택하고, 각각을 저자가 설정한 방식으로 보여주십시오 — 질문, 변경한 사항, 발생한 일 — 그래서 시청자가 숫자뿐만 아니라 아이디어와 저자의 의도를 이해할 수 있습니다. 유머와 놀라움은 실제 자료(눈에 띄는 예시, 예상치 못한 결과, 영리한 대조군)에서 나오며, 주장을 과장하는 데서 절대 나오지 않습니다. 재미있는 대사가 논문을 과장할 것 같으면 버리십시오.
  • 4분 영화를 위한 시간 예산: 후크 15–25초 (논문의 헤드라인 결과가 처음 30초 이내에 실제 데이터로 화면에 표시됨) · 프라이머 30–40초 · 증거 ≥ 영화의 40% · 메커니즘/이론 ≤ 20% 및 보여줄 수 있는 것만 · 테이크어웨이 ≤ 15초. 잘 알려진 오래된 논문의 경우, 임팩트 비트 (테이크어웨이 전, ≤ 20–30초): 그것이 시작하거나 변경한 것, 출처가 있는 사실로 전달 — 명명된 후속 작업 (연도 포함), 아이디어가 현재 사용되는 곳; 인용 횟수는 출처와 날짜가 있는 경우에만; 출처 없는 최상급 표현 금지. 기본적으로 한계 점(limitations scene) 없음: 논문 자체가 한계를 핵심 부분으로 다루는 경우에만 (≤ 20초); 그렇지 않으면 각 결과와 함께 명시하는 설정에 범위가 포함됩니다. 유도, 추가 실험 및 함의 목록은 실제 데이터로 ≤ 20–30초 내에 보여줄 수 있는 경우에만 장면을 얻습니다.
  • 지불하기 전에 자르기: python3 scripts/vo.py build --lang <l> --dry-run은 읽기 속도에서 추정한 영화 길이를 출력합니다 (음성 길이의 ~5% 이내). 스크립트가 맞을 때까지 다듬은 다음 음성을 생성하십시오.
  • 구조 (강제하지 말고 적응하십시오): 가장 강력한 실제 시각 자료로 후크 (≤ ~15초) → 전체 화면 타이틀 카드 (template/src/components/TitleCard.tsx: 논문 제목, 저자 및 기관, 학술대회 또는 arXiv ID, 한 문장 주장, 다른 사람의 논문인 경우 "비공식 설명" 표시; 또한 흐릿한 배경 요소로 논문 PDF의 첫 페이지 — 제목, 저자, 소속, 초록; PDF가 없을 때만 웹 페이지 첫 화면 — 제목과 기관이 읽히는 동안 부드럽게 전환: node scripts/paper_shot.mjs <arXiv id | PDF | URL> → public/shots/paper.png, TitleCard shot="shots/paper.png"; 16:9에서는 중앙 오른쪽, 9:16에서는 제목 아래; 커버에는 없음) 나레이션이 논문과 저자의 기관을 언급하는 동안 (저자 이름은 언급하지 않음: TTS가 변형시키고, 다른 스크립트로 추측된 이름은 종종 틀리기 때문 — 화면과 카피에 이름을 논문이나 arXiv가 철자한 그대로 정확히 쓰고, 음역(transliterated)하지 마십시오) — 자체 장면으로, 늦어도 ~20초까지 화면에 표시됨 → 컨텍스트 없는 시청자가 따라올 수 있는 프라이머 (작업/객체가 무엇인지, 평범한 언어로, 애니메이션) → 데이터로 표시된 문제 → 아이디어 → 작동 이유 (메커니즘) → 각각의 설정이 포함된 결과 → 테이크어웨이, 논문의 요점으로 끝맺음. "링크는 설명란에 있습니다" / 「论文和代码见简介」 같은 대사는 음성 또는 화면에 넣지 마십시오: 시청자는 링크가 어디에 있는지 알고 있으며, 영화를 빈 내용으로 끝내게 됩니다 (설명과 타이틀 카드가 식별자를 제공합니다). 좋은 시각 자료를 초반에 배치하고, 끝까지 아껴두지 마십시오.
  • 귀를 위해 쓰기: 짧은 문장, 문장당 하나의 숫자, 구체적인 명사, "X가 아니라 Y" 같은 말투 없음, 가짜 Q&A 없음, 장면 경계에서 일관된 어조 (갑작스러운 "자, 재미있는 부분입니다!"는 어색합니다). 공식과 차트에는 약간의 침묵을 주십시오.
  • 스크립트를 scenes.json에 넣으십시오 (스키마: template/scenes.example.json): 장면 및 언어별로, text (자막), tts (말해지는 내용: 재철자, 드문 오디오 태그), anchors (시각적 비트를 시간에 맞추는 단어), 선택적 pauseAfterMs; 장면별 선택적 chapter. 각 언어를 단어 그대로 번역하지 않고 모국어로 작성하십시오; 대상 청중이 기대하는 곳에서는 기술 용어를 영어로 유지하십시오.
  • 지금 notes/claims.md를 시작하십시오 (reference/rigor.md): 모든 숫자와 사실 문장 → 그 출처. notes/storyboard.md를 작성하십시오: 장면별 시각 자료, 앵커 기반 비트, 데이터 파일, 출처 줄.

4. 데이터 → public/data/*.json

한 에이전트 (당신 또는 하위 에이전트)가 원시 자료를 파일당 source 필드가 있는 깨끗한 JSON으로 변환하는 것을 담당하고, 모든 헤드라인 숫자를 논문과 교차 확인하고 불일치 및 함정 (메트릭 변형, 이름 변경된 용어, 반올림)을 나열하는 notes/data_report.md를 작성합니다. 장면은 public/data만 읽습니다.

5. 음성 먼저, 그 다음 그림

애니메이션 전에 나레이션을 구축하십시오 (reference/voice.md): scripts/vo.py build --lang <l>은 장면별 오디오와 단어 타이밍 및 앵커 프레임이 포함된 public/data/vo.<l>.json을 생성합니다. 그림은 그런 다음 앵커에 키잉되므로 두 언어가 자동으로 동기화 상태를 유지합니다. 보고서를 확인하십시오: ASR 왕복 오류, 이상한 운율, 누락된 앵커; 표현/재철자를 수정하고 영향을 받은 장면만 다시 생성하십시오 (출력은 콘텐츠 해시로 캐시됨).

6. 장면 구축

  • 먼저 테마, 공유 구성 요소 및 장면 간에 재사용되는 모든 것을 구축하십시오 (reference/visual-style.md 참조); 그런 다음 장면을 명시적 파일 소유권 (에이전트당 하나의 장면 세트, 아무도 공유 파일을 편집하지 않음 — 요청된 변경 사항을 당신에게 보고함)으로 하위 에이전트에 병렬화할 수 있습니다. 각 에이전트에게 제공: CLAUDE.md, 스토리보드 항목, scenes.json 줄 및 앵커 이름, 데이터 파일, 스타일 규칙, 각 장면의 챕터 번호 및 제목 (그렇지 않으면 병렬 에이전트가 독립적으로 챕터 태그에 번호를 매깁니다), 보고 전에 모든 언어로 스틸 이미지를 렌더링하고 검사해야 한다는 요구사항 (scripts/review.py). 이후 scripts/zh_font_subset.py를 한 번 다시 실행하십시오 (새 중국어 문자는 그때까지 시스템 글꼴로 폴백됨) 그리고 모든 중국어 음성 빌드 후 scripts/zh_breaks.py를 다시 실행하십시오 (두 컷의 자막이 단어 사이에서만 중국어를 나눕니다).
  • 타이틀 카드의 논문 페이지: 논문이 확정되면 렌더링하십시오 (node scripts/paper_shot.mjs <arXiv id>는 PDF를 data/에 다운로드하고 1페이지를 렌더링합니다; 로컬 PDF 또는 웹 기사 URL도 작동합니다; 수동으로 만든 스크린 그랩은 절대 안 됨), shot으로 전달하고, beats.shot을 제목 단어에 키잉하고, 9:16에서는 beats.shotDim을 나레이션이 기관으로 넘어가는 지점에 키잉하십시오; 두 컷의 스틸 이미지를 확인하십시오 (텍스트가 페이지 위에서 읽기 쉽게 유지되고, 자막이 선명해야 함).
  • 모든 장면: 헤드라인, 앵커 기반 비트 (폴백 포함), 데이터 샷의 출처 줄, 일러스트레이션의 SCHEMATIC, 두 언어의 화면 문자열, 캡션 밴드에서 콘텐츠가 깔끔해야 함.
  • 검토: 모든 언어로 전체 영화에 대해 앵커 기반 프레임에서 스틸 이미지를 렌더링하고 연락처 시트로 타일링하십시오 (scripts/review.py <Composition> <cut> [--scenes ...], 모든 프레임에 대해 하나의 번들), 그리고 살펴보십시오 — 겹침, 클리핑, 빈 프레임, 읽을 수 없는 텍스트, 메시지에서 벗어난 것. 그런 다음 페이싱을 검토하십시오: 시청자가 얻는 스토리로 시트를 읽으면서, 새로운 실제 시각 자료 없이 ~20초 이상 늘어지는 부분, 세 개 이상의 항목을 읽어내는 목록, 화면의 데이터와 연결되지 않은 공식이나 이론, 하나의 발견을 앞으로 나아가게 하지 않는 장면을 플래그 표시하십시오 — 압축하거나 자르십시오. 반복하십시오.

7. 독립적 사실 확인

아무것도 구축하지 않은 새로운 에이전트를 불러 스크립트와 모든 화면 문자열/숫자를 논문과 대조하여 확인하십시오 (reference/rigor.md의 프롬프트). 기본적으로 한 번의 가벼운 패스면 충분합니다: 스크립트와 카피가 최종 확정된 직후 (유료 음성 이전, 표현 수정이 가장 저렴할 때) — 숫자, 설정, 과장 주장. 시트를 검토하는 동안 직접 notes/claims.md와 대조하여 확인하십시오; 높은 중요도의 영화나 사용자가 요청하는 경우에만 두 번째 독립 패스 (화면, 플롯된 데이터, 커버)를 추가하십시오. MUST-FIX 항목 (음성 해설 표현 포함, 그런 다음 해당 장면을 다시 생성하고 음악을 다시 시간에 맞춤: 생성된 배경음의 경우 music.py --refit, 라이브러리 트랙의 경우 동일한 --file … --keep-ending N 다시 사용) 및 대부분의 SHOULD-FIX 항목을 수정하십시오.

8. 사운드, 렌더링

…

관련 스킬