reel — agent용 비디오 제작/편집 도구
ffmpeg을 핵심으로 하는 계층형 도구입니다: agent는 소스 자료를 보고, 목표를 정하고, plan을 작성합니다; 코드는 프레이밍, 렌더링 및 검수를 담당합니다. 비율은 설정 가능하며(기본 세로형 1080×1920).
명령어와 형식 세부 사항은 엔진 README 및 docs/engine.zh.md에 있으며, 작업 전에 먼저 읽어야 합니다.
딜리버리 게이트(반드시 거쳐야 함)
규칙은 누군가 실행하지 않으면 없는 것과 같습니다. 아래 각 단계는 코드로 막혀 있습니다: 게이트를 통과하지 않으면 '최종 완료본'을 낼 수 없습니다.
- 작업 시작 전에 brief 작성(
$P/brief.json) 및 등록:reel register brief.json. 배송 언어, 완성본인지 샘플인지, 배송 디렉토리, 변경 금지 사항을 명확히 기재합니다; 잘 모르면 사용자에게 물어봅니다. 등록 후, Bash에서 cp/mv/ffmpeg를 사용하여 배송 디렉토리에 직접 쓰거나,reel … --out PATH/--out=PATH(--png,--sheet,--report,--check-png도 동일)를 사용하여 배송 디렉토리를 지정하면hooks/guard_delivery.py에 의해 거부됩니다. 이 guard는 명령어 텍스트만 파싱하며 최선을 다하지만, 와일드카드, 중괄호, 명령어 치환, 스크립트 내부 및 원격 쓰기는 막지 못할 수 있으므로 이를 허가로 간주하지 말고, 배송은 오직reel deliver를 통해서만 수행합니다. - 사운드는 먼저 청취: 고정된 기본 사운드는 없습니다. 먼저 10-20초 샘플을 사용자에게 들려주고 동의를 받은 후, 원래 문구, 샘플 경로, 샘플 sha256을
brief.voice.approved에 기록합니다; 사운드를 변경하려면 다시 청취해야 합니다. - 영상 제작 후 검사:
reel check 최종본.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|프로젝트.json]. exit 1 = 배송 불가.result.gate.blockers(기술적 불합격)와pending_review(사용자 확인 필요)를 확인합니다;not_covered는 검사하지 않은 항목을 나열하며, '검사 완료'라고 말할 수 없습니다. - 영상 리뷰:
needs_review항목을 하나씩 확인하고(reel scrub/ 프레임 추출), 각 항목에 대해 타임코드가 포함된 리뷰 기록을 작성합니다; 전체를 한 번 시청하여final_watch를, 오디오를 들어final_listen을 기록합니다. - 배송:
reel deliver 최종본.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json. 최종본 조건을 충족하지 못하면DELIVERY_NOT_FINAL오류가 발생하며,--sample만 가능하고 파일명에 '검토용 샘플'이 포함됩니다. 동일한 버전 번호로는 재배송할 수 없으며, 이전 버전은 삭제하거나 덮어쓰지 않습니다. - '완료'라고 말할 수 있는 조건:
status: final인 영수증을 받았을 때(reel receipt <영수증>으로 확인 가능). 그렇지 않으면 '미완료 / 검토용 샘플 / 청취 대기'라고如实 보고합니다.hooks/deliver_gate.py(Stop hook)는 영수증이 없는 '완료' 메시지를 차단합니다; 영수증은 해당 작품과 일치해야 합니다(작품명과 버전 번호를 명시할 때는 작품명과 버전 번호로 매칭). 이 hook은 기본적으로 등록된 프로젝트와 reel을 호출한 턴에만 적용되며,REEL_GATE_SCOPE=global로 설정해야 전역 범위로 적용됩니다. - 프로젝트 자체 렌더링 스크립트로 제작된 영상도 3-6단계를 동일하게 따릅니다.
- MV:
--contract mv.json추가. 가사 검사는 계약에 명시된 가사 텍스트 레이어(각 문장이 불리는 동안 텍스트 레이어에 텍스트가 있고, 노래가 시작되기 전에는 텍스트가 없음)를 읽으며, 최종 영상의 픽셀은 읽지 않으므로, 이를 근거로 '화면 속 가사가 확인되었음'이라고 말할 수 없습니다.song_level은 앨범 및policy: "trim"에 대해 각 곡의 라우드니스와 실제 피크를 비교하며, 허용 오차는 단일 곡과 동일합니다. - 매개변수 오류도 JSON으로 출력(
ARG_INVALID, 종료 코드 2),--help는 도움말 텍스트를 출력합니다.reel voice check는 중국어 확인(기본--lang zh)에pypinyin이 필요하며(동일한 venv에 설치), 없으면BACKEND_UNAVAILABLE을 보고합니다;reel words는whisper-cli와 모델만 필요합니다.
brief.json 예시(MV의 경우 "kind": "mv" 추가):
{"version": "reel.brief.v1", "name": "입학 홍보", "language": "zh-CN", "deliverable": "final",
"delivery_root": "~/Deliveries/<프로젝트>", "must_not_change": ["엔딩 크레딧"],
"voice": {"mode": "tts", "voice_id": "zh-CN-XiaoxiaoNeural",
"approved": {"voice_id": "zh-CN-XiaoxiaoNeural", "by": "user", "quote": "이 목소리 괜찮아요",
"sample": "voice_sample.mp3", "sample_sha256": "<shasum -a 256 결과>"}},
"profile": "default"}
- brief에서
name,must_not_change및 키 이름이text/title/caption/label인 필드만 텍스트 스캔에 포함됩니다;language,delivery_root,voice.*는 스캔되지 않습니다. - 나레이션이 없으면
"voice": {"mode": "none"}; 실제 녹음은"recorded"로 작성합니다. 무음 버전은 프로젝트 프로필 사용:{"extends": "default", "audio": "silent"}. - profile:
default(일반 임계값),social-vertical(세로형 소셜 플랫폼: 1080×1920 30fps, -16 LUFS); 프로젝트별 차이는 프로젝트 프로필(extends)로 작성하며, 의도적인 긴 머무름은allow에 등록하고 이유를 기재합니다. 텍스트 스캔 단어 목록은 profile의text섹션에 있습니다:banned및extra_banned(대소문자 구분 없는 부분 문자열, 일치 시 fail, 프로젝트 자체 금칙어는extra_banned에 추가),banned_words(대소문자 구분하는 전체 단어TODO/TBD/FIXME, 일치 시 fail),review(placeholder,lorem ipsum, 전체 단어, 일치 시 needs_review,text_scan리뷰 기록 필요).
각 Bash 호출 블록의 시작 부분
agent의 각 Bash 호출은 완전히 새로운 셸이므로 함수는 유지되지 않습니다. 따라서 reel은 함수가 아니라 PATH 상의 스크립트(bin/reel)입니다. REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3 순서로 인터프리터를 선택합니다. 환경에 문제가 있으면 먼저 reel doctor를 실행하세요(필수 및 선택 종속성과 복구 방법 나열, 필수 항목 누락 시 exit 1):
command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<프로젝트>"; mkdir -p "$P/preview" && cd "$P" # 결과물은 프로젝트 디렉토리에, /tmp에 두지 않음
표준 워크플로우
- 소스 자료 준비를 프로젝트 디렉토리
$P에 합니다(소스, observations.json, plan.json, 미리보기, 최종본 모두 여기에; 하나의 디렉토리에 하나의 plan,.reel-history/에 수정 내역 기록). - 소스 자료 확인 및 목표 설정:
reel inspect 소스/a.jpg 소스/b.mp4 reel frame 소스/a.jpg --out "$P/preview/a_grid.png" # 0-1 그리드가 있는 이미지를 읽고 목표 프레임 파악 reel observe --obs observations.json --src 소스 --asset a.jpg --bbox x0,y0,x1,y1 --label "목표" reel locate --obs observations.json --src 소스 --asset b.mp4 --t 2 --query "빨간 컵" --check-png "$P/preview/chk.png" # OWLv2, torch 필요 - plan.json 작성(EditPlan v1):
camera: []는 완전 정지;zoom_to는 observation을 참조하여 목표로 확대;track은 여러 시점의 observation을 따라 이동;transition_out은 전환 효과. 비디오 클립은inspect가 제공하는 컷 지점을 넘지 않도록 합니다. - 검증 + 미리보기:
reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png", 모자이크를 보고 카메라 움직임 확인. - 렌더링:
reel render plan.json --out "$P/최종본.mp4" --sheet "$P/preview/final.png" --where mac. 최종 오디오는 AAC 48 kHz로 고정,checks에 샘플레이트 포함.checks를 모두 통과해도 렌더링이 깨지지 않았음을 의미할 뿐, 딜리버리 게이트 3-6단계를 계속 진행해야 합니다.
타임라인 및 비트 매칭
- 보기:
reel timeline plan.json --format text;reel timeline plan.json --png tl.png [--beats beats.json];reel scrub plan.json --cuts --render 최종본.mp4 --out 디렉토리. - 수정:
reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}'(각 단계 검증 후 기록);reel undo plan.json --to r2;reel history plan.json. - 비트 매칭:
reel beats 음악.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat(--dry-run으로 먼저 보고서 확인).
웹 페이지: 말하면서 따라가며 하이라이트
소스가 웹 페이지인 경우 OCR을 하지 않습니다: 텍스트 위치를 DOM에서 직접 읽고, 카메라 및 하이라이트는 브라우저가 프레임별로 그립니다.
- 웹 페이지 원문에 따라 나레이션 스크립트 작성(하이라이트할 문장은 페이지와一字不差), TTS로
voice.mp3생성. reel words voice.mp3 --out words.json(로컬 whisper, 단어별 타임스탬프).- plan에
kind: "web"클립 사용,camera: [{"op": "follow"}],highlight: [{"text": "페이지 원문…", "sync": "voice"}],audio.words는words.json을 가리킴. TEXT_NOT_FOUND= 페이지에 해당 원문 없음;TEXT_NOT_IN_VOICE= 나레이션이 일치하지 않음.
원격 GPU(선택 사항)
REEL_REMOTE=user@gpu-host(공백으로 여러 개 구분 가능) 설정 후,reel render --where 5090/--where auto는 렌더링을 원격 NVIDIA 호스트(NVENC + libass)로 전송하고, 결과물을 로컬로 가져와 다시 한 번 검증합니다. 설정하지 않으면 로컬만 사용합니다.- VRAM은 기본 ≤80%, 초과 시
NEED_USER_APPROVAL을 보고하고 사용자에게 알린 후 동의를 받아야--allow-over-80추가 가능; GPU 사용률 ≥50%이면GPU_BUSY를 보고하며 점유하지 않습니다. 원격 flock은 동시에 하나의 reel GPU 작업만 실행되도록 보장합니다. reel remote probe로 상태 확인;reel remote setup-vision은 원격에 독립 venv(torch + OWLv2)를 생성합니다.