Communitygithub.com

notque/vexjoy-agent

비디오 편집 파이프라인: FFmpeg와 Remotion을 활용하여 푸티지를 자르고 클립을 조합합니다.

vexjoy-agent란 무엇인가요?

이 스킬은 6단계 파이프라인을 구현하여 AI가 판단 작업(무엇을 유지하고, 자르고, 하이라이트를 선택할지)을 처리하고 FFmpeg와 Remotion이 결정론적으로 기계적 실행을 담당합니다. 사용자는 사전 확인, 비디오 추출, AI 기반 구조화, FFmpeg 절단, Remotion 합성, AI 생성 및 최종 인간 검수를 거쳐 완성된 비디오를 얻을 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 에이전트 플랫폼에서 사용할 수 있으며, 각 단계별 명령 블록과 참조 문서가 포함되어 있습니다. 특히 AI가 편집 결정 목록(EDL)을 생성하고, 이를 기반으로 FFmpeg가 정확하게 컷을 수행하며, Remotion으로 프로그래매틱 오버레이를 추가할 수 있습니다. 오류 처리 및 게이트 조건이 명확하게 정의되어 있어 안정적인 파이프라인 실행이 가능합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

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

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

문서

비디오 편집 스킬

개요

이 스킬은 AI가 판단 작업(무엇을 유지하고, 자르고, 하이라이트를 선택할지)을 처리하고 FFmpeg/Remotion이 결정론적으로 기계적 실행을 담당하는 6단계 파이프라인을 구현합니다.

단계이름메커니즘주요 도구
1CAPTURE소스 푸티지 인벤토리 수집Bash + Glob
2AI STRUCTURE트랜스크립트를 EDL로 변환LLM 판단
3FFMPEG CUTSEDL을 세그먼트 파일로 변환FFmpeg (결정론적)
4REMOTION COMPOSITION세그먼트를 TSX 구성으로 변환Remotion + TypeScript
5AI GENERATION생성된 자산으로 격차 채우기ElevenLabs / fal.ai (조건부)
6FINAL POLISH인간 취향 레이어인간 + NLE

심층 참조

신호로드내용
각 단계의 셸 명령, 게이트 검사references/phase-commands.md1-6단계 전체 명령 블록
FFmpeg 레시피: 절단, 연결, 프록시, 감지references/ffmpeg-commands.md타임스탬프 추출, 배치 절단, 오디오 정규화, 장면/무음 감지
Remotion 구성 스캐폴드references/remotion-scaffold.mdTSX 구성 템플릿, 렌더 명령, 재사용 패턴
이미지-비디오 파이프라인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 401ELEVENLABS_API_KEY가 설정되지 않음5단계 전에 export ELEVENLABS_API_KEY=your_key 실행.
트랜스크립트 추출에서 .vtt 파일 없음비디오에 요청한 언어의 자막이 없음yt-dlp --list-subs '<URL>' 실행하고 사용 가능한 언어 선택.

관련 스킬