Communitygithub.com

reel

비디오 제작/편집, 프로모션 영상, 립싱크/MV, 사진+음악+나레이션, 클립 편집, 줌 인/특수 효과, 웹 페이지 하이라이트 등 영상 제작의 모든 과정을 안내하는 도구입니다. 최종 결과물은 반드시 reel check → reel deliver 절차를 거쳐야 하며, 완료 확인서를 받아야 합니다.

reel란 무엇인가요?

reel은 ffmpeg 기반의 계층형 비디오 제작/편집 도구로, AI 에이전트가 자율적으로 영상 작업을 수행할 수 있도록 설계되었습니다. 에이전트는 먼저 소스 자료를 분석하고, 목표를 설정하며, 상세한 plan을 작성합니다. 그런 다음 코드가 프레이밍, 렌더링, 품질 검증을 담당합니다. 기본 해상도는 세로형 1080×1920이며, 다양한 프로필을 지원합니다. 이 스킬의 핵심은 엄격한 '딜리버리 게이트(delivery gate)' 프로세스입니다. 모든 작업은 brief 작성 및 등록, 사운드 샘플 승인, reel check를 통한 기술적/내용적 검증, 리뷰 기록, reel deliver 명령을 통한 최종 출력, 그리고 최종 완료 확인서(receipt) 수령까지의 단계를 반드시 거쳐야 합니다. 이 규칙은 코드 레벨에서 강제되며, 게이트를 통과하지 않은 결과물은 '완료'로 인정되지 않습니다. reel은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있도록 설계되었으며, 명령줄 인터페이스를 통해 호출됩니다. 또한 웹 페이지를 소스로 사용할 경우 DOM 기반 텍스트 하이라이트와 음성 싱크 기능을 제공하며, 원격 GPU를 활용한 고속 렌더링도 지원합니다. 이 모든 기능은 엄격한 품질 관리와 일관된 워크플로우를 유지하도록 설계되었습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/agent-reel/tree/HEAD/skill

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

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

문서

reel — agent용 비디오 제작/편집 도구

ffmpeg을 핵심으로 하는 계층형 도구입니다: agent는 소스 자료를 보고, 목표를 정하고, plan을 작성합니다; 코드는 프레이밍, 렌더링 및 검수를 담당합니다. 비율은 설정 가능하며(기본 세로형 1080×1920). 명령어와 형식 세부 사항은 엔진 README 및 docs/engine.zh.md에 있으며, 작업 전에 먼저 읽어야 합니다.

딜리버리 게이트(반드시 거쳐야 함)

규칙은 누군가 실행하지 않으면 없는 것과 같습니다. 아래 각 단계는 코드로 막혀 있습니다: 게이트를 통과하지 않으면 '최종 완료본'을 낼 수 없습니다.

  1. 작업 시작 전에 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를 통해서만 수행합니다.
  2. 사운드는 먼저 청취: 고정된 기본 사운드는 없습니다. 먼저 10-20초 샘플을 사용자에게 들려주고 동의를 받은 후, 원래 문구, 샘플 경로, 샘플 sha256을 brief.voice.approved에 기록합니다; 사운드를 변경하려면 다시 청취해야 합니다.
  3. 영상 제작 후 검사: reel check 최종본.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|프로젝트.json]. exit 1 = 배송 불가. result.gate.blockers(기술적 불합격)와 pending_review(사용자 확인 필요)를 확인합니다; not_covered는 검사하지 않은 항목을 나열하며, '검사 완료'라고 말할 수 없습니다.
  4. 영상 리뷰: needs_review 항목을 하나씩 확인하고(reel scrub / 프레임 추출), 각 항목에 대해 타임코드가 포함된 리뷰 기록을 작성합니다; 전체를 한 번 시청하여 final_watch를, 오디오를 들어 final_listen을 기록합니다.
  5. 배송: reel deliver 최종본.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json. 최종본 조건을 충족하지 못하면 DELIVERY_NOT_FINAL 오류가 발생하며, --sample만 가능하고 파일명에 '검토용 샘플'이 포함됩니다. 동일한 버전 번호로는 재배송할 수 없으며, 이전 버전은 삭제하거나 덮어쓰지 않습니다.
  6. '완료'라고 말할 수 있는 조건: status: final인 영수증을 받았을 때(reel receipt <영수증>으로 확인 가능). 그렇지 않으면 '미완료 / 검토용 샘플 / 청취 대기'라고如实 보고합니다. hooks/deliver_gate.py(Stop hook)는 영수증이 없는 '완료' 메시지를 차단합니다; 영수증은 해당 작품과 일치해야 합니다(작품명과 버전 번호를 명시할 때는 작품명과 버전 번호로 매칭). 이 hook은 기본적으로 등록된 프로젝트와 reel을 호출한 턴에만 적용되며, REEL_GATE_SCOPE=global로 설정해야 전역 범위로 적용됩니다.
  7. 프로젝트 자체 렌더링 스크립트로 제작된 영상도 3-6단계를 동일하게 따릅니다.
  8. MV: --contract mv.json 추가. 가사 검사는 계약에 명시된 가사 텍스트 레이어(각 문장이 불리는 동안 텍스트 레이어에 텍스트가 있고, 노래가 시작되기 전에는 텍스트가 없음)를 읽으며, 최종 영상의 픽셀은 읽지 않으므로, 이를 근거로 '화면 속 가사가 확인되었음'이라고 말할 수 없습니다. song_level은 앨범 및 policy: "trim"에 대해 각 곡의 라우드니스와 실제 피크를 비교하며, 허용 오차는 단일 곡과 동일합니다.
  9. 매개변수 오류도 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에 두지 않음

표준 워크플로우

  1. 소스 자료 준비를 프로젝트 디렉토리 $P에 합니다(소스, observations.json, plan.json, 미리보기, 최종본 모두 여기에; 하나의 디렉토리에 하나의 plan, .reel-history/에 수정 내역 기록).
  2. 소스 자료 확인 및 목표 설정:
    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 필요
    
  3. plan.json 작성(EditPlan v1): camera: []는 완전 정지; zoom_to는 observation을 참조하여 목표로 확대; track은 여러 시점의 observation을 따라 이동; transition_out은 전환 효과. 비디오 클립은 inspect가 제공하는 컷 지점을 넘지 않도록 합니다.
  4. 검증 + 미리보기: reel validate plan.json; reel compile plan.json; reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png", 모자이크를 보고 카메라 움직임 확인.
  5. 렌더링: 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에서 직접 읽고, 카메라 및 하이라이트는 브라우저가 프레임별로 그립니다.

  1. 웹 페이지 원문에 따라 나레이션 스크립트 작성(하이라이트할 문장은 페이지와一字不差), TTS로 voice.mp3 생성.
  2. reel words voice.mp3 --out words.json(로컬 whisper, 단어별 타임스탬프).
  3. plan에 kind: "web" 클립 사용, camera: [{"op": "follow"}], highlight: [{"text": "페이지 원문…", "sync": "voice"}], audio.words는 words.json을 가리킴.
  4. 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)를 생성합니다.

관련 스킬