비디오 편집 스킬
개요
이 스킬은 AI가 판단 작업(무엇을 유지하고, 자르고, 하이라이트를 선택할지)을 처리하고 FFmpeg/Remotion이 결정론적으로 기계적 실행을 담당하는 6단계 파이프라인을 구현합니다.
| 단계 | 이름 | 메커니즘 | 주요 도구 |
|---|---|---|---|
| 1 | CAPTURE | 소스 푸티지 인벤토리 수집 | Bash + Glob |
| 2 | AI STRUCTURE | 트랜스크립트를 EDL로 변환 | LLM 판단 |
| 3 | FFMPEG CUTS | EDL을 세그먼트 파일로 변환 | FFmpeg (결정론적) |
| 4 | REMOTION COMPOSITION | 세그먼트를 TSX 구성으로 변환 | Remotion + TypeScript |
| 5 | AI GENERATION | 생성된 자산으로 격차 채우기 | ElevenLabs / fal.ai (조건부) |
| 6 | FINAL POLISH | 인간 취향 레이어 | 인간 + NLE |
심층 참조
| 신호 | 로드 | 내용 |
|---|---|---|
| 각 단계의 셸 명령, 게이트 검사 | references/phase-commands.md | 1-6단계 전체 명령 블록 |
| FFmpeg 레시피: 절단, 연결, 프록시, 감지 | references/ffmpeg-commands.md | 타임스탬프 추출, 배치 절단, 오디오 정규화, 장면/무음 감지 |
| Remotion 구성 스캐폴드 | references/remotion-scaffold.md | TSX 구성 템플릿, 렌더 명령, 재사용 패턴 |
| 이미지-비디오 파이프라인 | references/image-to-video.md | 검증, 준비, 인코딩, 확인 워크플로 |
| 시각화를 위한 FFmpeg 필터 그래프 | references/ffmpeg-filters.md | 크기 조정/패딩, 쇼웨이브, 쇼스펙트럼, 오버레이, 전체 필터 그래프 |
지침
사전 점검 (1단계 실행 전)
하드 요구사항 (누락 시 차단): ffmpeg (모든 단계), node (Remotion / npx).
소프트 요구사항 (누락 시 경고): remotion (4단계에서만 필요).
which ffmpeg >/dev/null 2>&1 || { echo "ERROR: ffmpeg not found. Install: brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "ERROR: node not found. Install: https://nodejs.org or via nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "WARNING: remotion CLI not found. Phase 4 unavailable. Install: npm install @remotion/cli"
1단계: CAPTURE
목표: 모든 소스 푸티지를 인벤토리화하고 처리 전에 파일이 디스크에 존재하는지 확인합니다.
제약사항: 소스 파일은 읽기 전용입니다. 모든 FFmpeg 명령은 새 파일에만 씁니다. 소스 푸티지를 덮어쓰지 마십시오.
단계: 소스 파일 찾기(find), ffprobe로 각 파일 검사, 10분 초과 파일용 프록시 생성(references/ffmpeg-commands.md -> 프록시 생성 참조), 작업 디렉토리 생성(segments/, assembled/). 전체 명령 블록: references/phase-commands.md -> 1단계.
게이트: 소스 파일이 디스크에 확인됨. 파일 목록이 source-inventory.txt에 기록됨. 게이트 통과 시에만 진행.
2단계: AI STRUCTURE
목표: 콘텐츠를 분석하고 모든 다운스트림 절단을 구동하는 서면 EDL(cuts.txt)을 생성합니다.
제약사항: cuts.txt가 계약입니다. EDL 파일은 다운스트림 단계의 유일한 정보 원천입니다. FFmpeg 명령을 수동으로 편집하지 마십시오. EDL에서 명령을 생성하십시오.
제약사항: EDL을 수동으로 작성하기 전에 FFmpeg 장면/무음 감지를 실행하십시오. 감지 출력은 판단에 정보를 제공하며, 대체하지 않습니다.
단계: whisper/AssemblyAI로 트랜스크립션, 장면/무음 감지 실행, 판단 적용(내러티브를 진행시키는 것, 필러인 것, 대상 길이), EDL 형식 START_TIME,END_TIME,LABEL로 cuts.txt 작성, 중복 및 총 길이 검토. 전체 명령 블록 및 EDL 형식 예시: references/phase-commands.md -> 2단계.
게이트: transcript.txt가 존재함. cuts.txt가 디스크에 기록됨. 두 파일 모두 존재할 때만 진행.
3단계: FFMPEG CUTS
목표: EDL을 결정론적으로 실행합니다. cuts.txt의 세그먼트당 하나의 FFmpeg 컷입니다.
제약사항: 루프를 사용하여 EDL에서 배치 컷을 수행합니다. 컷당 개별 FFmpeg 명령을 생성하지 마십시오. 이렇게 하면 재현성과 목록으로 검토 기능이 보장됩니다.
제약사항: 항상 cuts.txt 순서에서 concat-list.txt를 생성하고 셸 glob에서 생성하지 마십시오. 셸 glob(segments/*.mp4)은 알파벳순으로 정렬되며 EDL 순서가 아닙니다.
단계: while 루프로 EDL에서 배치 컷(libx264/aac, -avoid_negative_ts make_zero), 세그먼트 확인, EDL 순서로 concat-list.txt 생성, -f concat -safe 0 -c copy로 연결. 전체 명령 블록: references/phase-commands.md -> 3단계. references/ffmpeg-commands.md -> 배치 절단도 참조.
게이트: 모든 세그먼트 파일이 존재함. assembled/rough-cut.mp4가 디스크에 기록됨. 게이트 통과 시에만 진행.
4단계: REMOTION COMPOSITION
목표: 프로그래매틱 오버레이, 제목 또는 전환을 위해 세그먼트를 Remotion TSX 구성으로 래핑합니다.
사용 시기: rough-cut.mp4에 프로그래매틱 요소(애니메이션 제목, 하단 써드, 캡션 트랙, 브랜드 오버레이)가 필요한 경우에만 사용합니다. rough-cut.mp4로 충분하면 6단계로 건너뜁니다.
제약사항: 4단계는 TypeScript/React가 필요합니다. TSX 작업은 typescript-frontend-engineer에 넘기고, 5단계부터는 python-general-engineer로 돌아옵니다.
단계: Remotion 초기화(처음에는 npm create video@latest, 그렇지 않으면 npm install @remotion/cli @remotion/player remotion), 구성 스캐폴드(references/remotion-scaffold.md 참조), npx remotion render로 렌더링. 전체 명령 블록: references/phase-commands.md -> 4단계.
게이트: assembled/remotion-output.mp4가 존재함. 게이트 통과 시에만 진행.
5단계: AI GENERATION
목표: 필요한 경우에만 생성된 자산으로 소스 자료의 실제 격차를 채웁니다.
제약사항: 무엇이든 생성하기 전에 기존 푸티지가 격차를 커버하는지 확인하십시오. 존재하지 않는 것만 생성하십시오.
의사 결정 트리: 격차 주위를 잘라냄 -> cuts.txt 업데이트 및 3단계 재실행; 음성 해설 -> ElevenLabs (인증 필요); 음악 -> fal.ai (fal-ai-media에 위임); B-롤 -> fal.ai (fal-ai-media에 위임). ElevenLabs Python 도우미, 인증 패턴 및 디스크 저장 흐름: references/phase-commands.md -> 5단계.
게이트: 진행 전에 필요한 모든 생성 자산이 assets/ 디렉토리에 저장됨.
6단계: FINAL POLISH
목표: 조립된 출력물을 전달하고 취향 레이어 작업을 인간에게 넘깁니다.
제약사항: 6단계는 인간의 영역입니다. 스킬은 조립하고 인간이 마무리합니다. 다음은 인간의 판단이 필요하며 프로그래매틱 방식으로 시도해서는 안 됩니다:
- 클립 간 색상 그레이딩 및 색상 매칭
- 음악 타이밍 및 볼륨 덕킹
- 캡션 스타일, 글꼴, 위치
- 전환 타이밍 및 스타일
- 최종 오디오 믹스 레벨
핸드오프 템플릿(handoff-notes.txt - 소스 목록, EDL, 러프 컷 경로, 인간용 남은 작업 체크리스트 포함): references/phase-commands.md -> 6단계.
게이트: assembled/rough-cut.mp4 (또는 assembled/remotion-output.mp4)가 존재함. handoff-notes.txt가 디스크에 기록됨.
비디오 트랜스크립트 추출
비디오의 트랜스크립트를 읽을 수 있는 단락으로 가져옵니다. 업로더 자막을 선호하고, 자동 생성된 자막을 대체 수단으로 사용합니다.
# 경로 1: 업로더 자막 (정확)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# 경로 2: 자동 생성 (경로 1에서 파일을 쓰지 않을 때 대체)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# VTT를 단락으로 정리
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <work-dir>/<id>.en.vtt
옵션: --timestamps는 [mm:ss] 마커, --keep-brackets는 큐 태그, -o FILE은 파일 출력. 다른 언어: --sub-langs 변경. 사용 가능한 목록: yt-dlp --list-subs '<URL>'.
오류 처리
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| 소스에서 "No such file or directory" | cuts.txt의 경로가 파일 이름과 일치하지 않음 | cat source-inventory.txt 실행. 공백이 있는 경로는 인용. |
| FFmpeg "Invalid option" 또는 코덱 오류 | 코덱을 사용할 수 없거나 플래그 구문 오류 | `ffmpeg -codecs |
| Remotion "Could not find composition" | 구성 ID 불일치 | src/index.ts에서 등록된 ID 확인. 렌더 명령에서 정확히 일치. |
| 세그먼트 연결이 잘못된 순서로 됨 | 셸 glob이 EDL 순서가 아닌 알파벳순으로 정렬 | glob이 아닌 cuts.txt 순서에서 concat-list.txt 생성. |
| ElevenLabs 401 | ELEVENLABS_API_KEY가 설정되지 않음 | 5단계 전에 export ELEVENLABS_API_KEY=your_key 실행. |
| 트랜스크립트 추출에서 .vtt 파일 없음 | 비디오에 요청한 언어의 자막이 없음 | yt-dlp --list-subs '<URL>' 실행하고 사용 가능한 언어 선택. |