kajisho5/remotion-ffmpeg-skill

remotion-ffmpeg-skill은(는) 무엇을 하나요?

ffmpeg-skill이 측정 → Remotion이 그림 → ffmpeg-skill이 확인하고 전달. 스크립트는 이 파일과 같은 디렉토리의 scripts/에 있으며, python3 <skill-dir>/scripts/<이름>.py로 실행합니다. --help 플래그는 전체 플래그 목록을 보여줍니다. references/timeline.md는 타임라인 형식과 모든 컴포지션이 사용하는 옵션을 설명합니다.

이 스킬은 ffmpeg-skill에 의존합니다 (이 스킬 옆, ~/.claude/skills/ffmpeg-skill, 또는 FFMPEG_SKILL_DIR 환경 변수로 지정). 절대 원시 ffmpeg/ffprobe 명령을 직접 실행하지 않습니다. 측정, 확인 및 전달은 ffmpeg-skill의 스크립트를 통해 이루어지므로, 그들의 보증이 그대로 적용됩니다.

공유 플래그 (모든 스크립트): --json (stdout에 단일 JSON 객체를 출력; 권장), --dry-run (계획만 세우고 아무것도 쓰지 않음), --overwrite (기존 출력을 덮어쓰는 유일한 방법), --timeout 초.

워크플로우 (이 순서대로)

1. 프로젝트 설정. 아직 Remotion 프로젝트가 없음: init.py ./motion --install (템플릿을 복사하고 npm install 실행; 첫 번째 렌더링 시 Remotion의 헤드리스 브라우저가 다운로드됨). 이 스킬로 만든 기존 프로젝트가 있으면 재사용.
2. 측정. analyze.py SOURCE [--captions FILE.srt] [--beats] -o SOURCE.timeline.json. 요약과 warnings를 읽으세요. VFR 또는 HDR 소스는 Remotion으로 그리기 전에 ffmpeg-skill로 수정해야 합니다 (color.py --to-sdr, 고정 프레임 레이트 내보내기) – Remotion은 고정 프레임 그리드에서 SDR로 렌더링합니다. 타임라인 숫자를 수동으로 쓰거나 편집하지 말고, 대신 다시 측정하세요 (--threshold, --min-silence는 조용한 방에 유용).
3. 스틸 미리보기. still.py --project ./motion --comp NAME --timeline TL --at 1.5 --at 6 PNG 확인: 캡션 배치, 확대 줌, 색상. 저렴하므로 전체 렌더링 전에 수행.
4. 렌더링. render.py --project ./motion --comp NAME --timeline TL [--options look.json] -o OUT.mp4 (--fast = 절반 크기 미리보기, --frames 0-89 = 범위 지정, --codec prores -o master.mov = 마스터 파일). 타임라인에 대해 출력을 검증(프레임 수, FPS, 크기, 오디오)하고 불일치 시 0이 아닌 종료 코드로 종료.
   • 형태: 전달될 형태로 그립니다. Reels / TikTok / Shorts 용은 --aspect 9:16 (또한 1:1, 4:5, 16:9 사용 가능); --fit blur (형태가 변경될 때 기본값: 흐릿한 복사본 위에 포함), contain (막대) 또는 cover (크롭 – 먼저 스틸에서 피사체 확인). 16:9로 렌더링하고 9:16 템플릿이 크롭하게 하지 마세요: 캡션이 가장자리를 잃습니다. pipeline.py --platform은 ffmpeg-skill의 템플릿에서 자동으로 종횡비를 선택합니다.
   • 폰트: 일본어/중국어/한국어 캡션은 ffmpeg-skill이 기기에서 찾은 CJK 폰트를 자동으로 사용합니다 (프로젝트에 스테이징되므로 토푸 현상 없음); --font-file F.ttf는 특정 폰트를 사용합니다; 보고서 줄 font:는 사용된 폰트 또는 폰트를 찾지 못했음을 알려줍니다.
   • 편집 앱 레이어: --overlay --keep-graphics (Captioned / PeakPulse, 소스 형태)는 투명 ProRes 4444 .graphics.mov로 그래픽만 그린 후 ffmpeg-skill overlay.py를 사용하여 손대지 않은 소스 위에 합성합니다. Premiere / Resolve / Final Cut에서 작업하는 사람에게 .mov 파일을 전달하세요. 일반 렌더링보다 빠르지 않습니다.
5. 전달. deliver.py OUT.mp4 --platform youtube|reels|tiktok|shorts|x|... ffmpeg-skill의 전달 템플릿과 check.py 테이블을 실행합니다. 형식 행은 수정해도 안전합니다. 판단 행(길이, 종횡비)은 내용을 변경합니다 – 질문하세요. WARN을 언급하되, 추적하지 마세요. 대상이 지정되지 않으면 이 단계를 건너뛰고 그렇게 말하세요.
6. 확인. 응답이 render.py가 작성한 연속 사진표 경로(Look: PATH)를 언급하고 무엇을 보여주는지 말할 때까지 완료되지 않습니다. 기계적 (확인 및 보고): 텍스트는 요청된 위치에 있고, 큐는 지정된 시간에 나타나며, 프레임에 의해 잘리지 않습니다. 판단 (본 것을 말하고, 사용자가 결정): 얼굴 위의 텍스트, 잘못 배치된 점프. 이미지를 볼 수 없음: Look: PATH (픽셀 검사 안 됨) – 절대 확인했다고 말하지 마세요. 연속 사진표 없음 (look_error 결과, 예: drawtext 없는 FFmpeg): 대신 still.py 프레임을 보고 오류가 지정한 수정 사항을 전달하세요.

옵션 파일은 렌더링 전에 검사됩니다. 알 수 없는 키나 잘못된 유형은 (kind: input) 무시되지 않고 거부됩니다.

MCP: mcp/server.py는 동일한 도구를 노출합니다 (스키마는 scripts/_contract.py에 있으며, contract --json으로 출력).

한 번에 모든 작업: pipeline.py SOURCE --project ./motion --comp NAME [--captions F] [--platform P]는 2→4→5단계를 동일한 검사와 함께 실행하고 첫 번째 실패 단계에서 중단됩니다.

요청 → 스크립트 / 컴포지션

요청	실행
"이 영상에 애니메이션 캡션/자막"	analyze.py --captions → render.py --comp Captioned
"무음 제거 / 점프 컷 / 이 대화를 더 타이트하게" (모션 포함)	analyze.py → render.py --comp Jumpcut (캡션이 있으면 재타이밍)
"오디오에 반응하는 그래픽 / 비트에 맞춰 / 컷에 맞춰"	analyze.py [--beats] → render.py --comp PeakPulse (그리드가 측정된 경우 비트에 맞춰 펄스)
"가라오케 캡션 / 말할 때 단어가 빛남"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke (로컬 음성 엔진의 단어 타이밍, whisper JSON; SRT 없으면 단어에서 큐 그룹화)
"로우어 서드 / 이름 타이틀 / 챕터 타이틀"	render.py --comp Titled --options와 lowerThirds / sceneTitles – 텍스트는 사용자에게 요청; 절대 이름을 지어내지 마세요
"하이라이트 릴 / 베스트 모먼트"	analyze.py --highlights N [--target S] → render.py --comp Highlights (오디오 에너지 순위: 후보 목록, 설명)
"비트에 맞춰 컷 / 음악 몽타주"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage (오디오는 끊기지 않고, 그림은 측정된 비트마다 beatsPerCut 만큼 컷; 신뢰할 수 있는 그리드가 없으면 장면 컷)
"YouTube / Reels / TikTok 용 ..."	pipeline.py --platform (템플릿의 종횡비로 렌더링 후 전달 및 확인), 또는 render.py --aspect + deliver.py --platform
"세로 / 9:16 / 정사각형"	render.py --aspect 9:16 (또는 1:1, 4:5)
"일본어 캡션" / 특정 폰트	CJK의 경우 별도 조치 불필요 (자동 폰트); 선택한 폰트는 --font-file
"그래픽을 별도 레이어로 주세요"	render.py --overlay --keep-graphics
"색상 / 폰트 / 캡션 크기 / 줌 변경"	--options JSON (references/timeline.md), 재렌더링
여러 클립 ("인트로 + 토크 + 아웃트로")	analyze.py A.mp4 B.mov C.mp4 (또는 여러 입력으로 pipeline.py): ffmpeg-skill join.py가 정규화 및 연결 후 연결된 파일에서 측정
"미리보기" / "프레임 보여줘"	still.py
새로운 종류의 그래픽	프로젝트의 src/에 src/timeline.ts에서 Props를 읽는 컴포지션을 추가; --comp YourId로 렌더링 (render.py는 내장 기대치 없이 측정된 숫자 보고)
그래픽 없는 단순 컷 / 트림 / 리사이즈 / 라우드니스	이 스킬이 아님: ffmpeg-skill 직접 사용
뭔가 고장남	doctor.py [--project DIR]

이 스킬이 결정하는 것과 결정하지 않는 것

• 결정 (기계적): 컴포지션 길이, FPS 및 크기 (조사로부터); 컷 위치 (측정된 무음으로부터); 큐 표시 시간 (캡션 파일로부터); 펄스 타이밍 (측정된 피크로부터); 렌더링이 타임라인과 일치하는지 여부.
• 결정하지 않음: 이름, 제목 및 챕터 이름 (로우어 서드와 장면 제목은 사용자의 텍스트 – 질문); 캡션이 말하는 단어 – 큐 텍스트는 정확히 쓰여진 대로 그려지며, "맞추기 위해" 축약하거나 의역하지 않음 (대신 더 작은 captionSize 제안); 무엇이 하이라이트인지; 룩이 좋은지 여부. 이 모든 것은 사용자 또는 호출하는 에이전트의 몫입니다.
• 데이터를 절대 지어내지 않음. 사용자 또는 로컬 음성-텍스트 엔진의 타임드 캡션 파일 없이 캡션 없음; --beats가 측정하지 않은 비트 그리드 없음.

작업 실패를 방지하는 규칙

• Remotion 라이선스: 개인 및 직원 3명 이하의 영리 조직은 무료; 더 큰 회사는 Remotion 회사 라이선스 필요 (https://www.remotion.dev/license). 사용자가 분명히 더 큰 회사라면 한 번 알리세요.
• 사용자의 원본 파일 보존: 소스는 프로젝트의 public/media/에 링크되며, 수정되지 않음; --overwrite 없이 기존 파일을 덮어쓰지 않음.
• CJK 캡션: 자동 폰트는 ffmpeg-skill의 폰트 감지에서 가져옴; 보고서에 폰트를 찾을 수 없다고 나오면 하나 설치하거나 (Noto Sans CJK) --font-file을 전달 – 연속 사진표의 토푸는 실패한 작업입니다. 일본어 줄은 구 사이에서 나누고, 단어 내에서는 나누지 않음.
• 속도 (2코어 Linux 머신, 모든 코어 – render.py의 기본값): 1080p30의 경우 클립 길이의 약 2.6배 (30초에 80초 소요). 긴 영상의 전체 렌더링 전에 still.py와 --fast로 미리보기; 긴 렌더링을 시작하기 전에 예상 시간을 사용자에게 알리세요. --concurrency가 코어 수를 초과하면 Remotion에서 거부.
• 프로젝트의 Remotion 패키지는 모두 동일한 버전이어야 함; 템플릿이 고정. 다른 remotion 버전을 섞지 마세요.
• 검증에 실패한 렌더링은 실패: --json에서 실패한 행을 보고하고, 배송하지 마세요.