Communitygithub.com

reel

에이전트가 숏폼 영상(릴)을 기획, 제작 또는 편집하여 완성된 비디오 컷을 결과물로 내는 방법을 제시합니다. /reel 절차에 따라 진행되며, 방향 설정 우선, 편집 순서로 작업하고 전달 게이트가 필수입니다.

reel란 무엇인가요?

이 스킬은 Claude Code와 같은 AI 에이전트가 ffmpeg 기반의 'reel' 도구를 사용하여 전문 수준의 숏폼 비디오(릴)를 제작할 수 있도록 안내합니다. 핵심 워크플로우는 'direction first, then editing' 원칙을 따르며, 반드시 7단계 전달 게이트(brief 작성, 음성 오디션, 렌더링 검사, 검토, 전달, 완료 선언, 타 도구 비디오 처리)를 통과해야 최종 결과물로 인정됩니다. macOS, Linux 플랫폼에서 사용 가능하며, 로컬 GPU(기본) 또는 원격 GPU(옵션)에서 렌더링할 수 있습니다. 작업 전 반드시 `docs/ENGINE.md` 문서를 읽어 명령어와 파일 형식을 숙지해야 하며, 모든 명령은 JSON 객체를 반환하고 실패 시 exit 1을 출력합니다. 에이전트는 직접 의사 결정(샷 선택, 카메라 움직임, 페이싱 등)을 내리고, 인식, 지오메트리, 렌더링 및 검증은 코드가 처리합니다. GPT-4o, Sonnet, Gemini 등 다양한 LLM과 호환되도록 설계되었습니다.

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

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

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

문서

/reel: AI 에이전트를 위한 숏폼 영상 제작

ffmpeg 기반의 계층적 도구입니다. Claude 등 AI 에이전트가 원본 자료를 살펴보고, 무엇을 보여줄지 결정하여 계획을 세우고; 코드가 프레이밍 지오메트리, 렌더링 및 검사를 수행합니다. 출력 크기는 설정 가능합니다(기본값 세로 1080x1920).

명령어와 파일 형식은 reel 저장소의 docs/ENGINE.md에 문서화되어 있습니다. 첫 명령 전에 반드시 읽으십시오: cat "$(reel --root)/docs/ENGINE.md". reel <command> --help는 모든 옵션을 나열합니다. 모든 명령은 하나의 JSON 객체 ({"ok": true, "result": ...} 또는 {"ok": false, "error": {"code": ..., ...}})를 출력하고, 실패 시 exit 1을 반환합니다.

작업 순서: 방향 설정 우선, 그 다음 편집

사용자 외에 다른 사람이 볼 비디오에 대해서는 SOP.md를 따르십시오: S0 인테이크, S1 소스 패키징, S2 에셋 인벤토리, S3-S4 director 에이전트가 direction/BRIEF.md와 스토리보드를 작성하고, 즉시 편집합니다(승인 단계 G1은 기본적으로 차단하지 않음). 그 다음 아래 전달 게이트를 수행합니다. S7에서 별도의 director 에이전트가 컷을 BRIEF와 비교하여 검토합니다. 플러그인으로 설치되며 에이전트 이름은 reel:director입니다.

  • 디렉터에게 자신의 결론이 아닌 원본 자료의 경로를 제공하십시오.
  • 승인된 BRIEF가 존재하고 목적, 대상 및 자료 범위가 변경되지 않은 경우 이를 따르십시오.
  • 사용자가 비디오가 지루하거나 무의미하다고 말하면 S3로 돌아가 작품을 재고하십시오; 단순히 재편집하지 마십시오.

전달 게이트 (필수)

각 단계는 코드로 강제됩니다: 하나를 건너뛰면 최종 컷을 전달할 수 없습니다.

  1. 먼저 브리프를 작성하십시오 ($P/brief.json, 아래 템플릿) 등록: reel register brief.json. 전달 언어, 최종본 또는 샘플 여부, 전달 폴더, 변경할 수 없는 사항: 이 항목들을 채울 수 없으면 사용자에게 물어보십시오. 등록되면 Bash 가드 훅이 전달 폴더에 대한 cp/mv/ffmpeg 쓰기를 거부합니다.
  2. 음성을 오디션하십시오. 기본 음성은 없습니다. 브리프에 맞는 음성을 선택하고, 10-20초 샘플을 렌더링한 후 reel voice check sample.mp3 --script sample.txt --brief brief.json을 실행하십시오. 로컬 whisper가 샘플을 전사하고 텍스트와 비교합니다(--lang 기본값은 en; 중국어 내레이션의 경우 --lang zh를 전달하면 성조 없는 병음으로 비교하므로 동음이의어 철자가 오류로 간주되지 않음); 오류율이 10% 이하인 경우에만 승인이 brief.voice.approved에 기록됩니다(by: claude, 전사 결과 증거 포함). 사용자가 직접 들었다면 그들의 정확한 말을 대신 기록하십시오.
    • STT는 단어가 올바르고 명확하게 읽혔음을 증명합니다. 음성이 작품에 적합하다는 것을 증명하지는 않습니다: 답변에 음성을 선택했다고 말하고, 사용자가 마음에 들어하지 않으면 다음 버전에서 음성을 바꾸십시오.
    • 새 음성은 새 검사가 필요합니다. macOS say 음성은 내부 초안 전용이며, 전달되는 비디오에는 절대 사용하지 마십시오.
  3. 렌더링을 검사하십시오: reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt].
    • exit 1이면 전달할 수 없습니다. result.gate.blockers(기술적 실패: 샘플도 전달할 수 없음)와 result.gate.pending_review(검토자가 확인해야 할 항목)를 읽으십시오.
    • ok만 믿지 마십시오. result.gate.not_covered는 검사되지 않은 항목(예: 화면상 텍스트, OCR 없음)을 나열합니다; 해당 항목이 검사되었다고 말하지 마십시오.
  4. 검토하십시오. 모든 needs_review 항목(reel scrub, 프레임 캡처)을 살펴보고 각 항목에 대해 타임코드 관찰 결과를 포함한 하나의 검토 레코드를 작성하십시오. 전체 컷을 직접 시청하고 final_watch에 서명하십시오(샷당 최소 한 프레임); 처음부터 끝까지 듣고 final_listen에 서명하십시오(에이전트 서명에는 타임코드 관찰 결과가 필요함; 사용자가 들었다면 그들의 정확한 말을 quote로 기록하십시오). 두 가지 모두 서명했으면 최종본으로 전달하십시오: 영수증에는 approved_by: agent가 표시되고, 답변에는 "Claude가 검토한 최종 컷, 아직 사용자가 보지 않음"이라고 말하십시오. 사용자의 피드백은 다음 버전이 됩니다. reviews.json 형식은 docs/ENGINE.md에 있습니다.
  5. 전달: reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json.
    • 최종 조건이 충족되지 않으면 DELIVERY_NOT_FINAL 오류와 함께 실패하고 이유를 나열합니다. 그러면 --sample만 가능합니다: 파일 이름에 sample-pending-review가 포함되며, 사용자에게 알릴 때 샘플이라고 불러야 합니다.
    • 버전 번호는 한 번만 전달할 수 있습니다; 이전 버전은 절대 삭제되거나 덮어쓰이지 않습니다. 사용자가 명시적으로 이전 버전 제거를 요청한 경우에만: reel register brief.json --remove, 삭제 후 다시 등록하십시오.
  6. "완료" 선언은 status: final인 영수증이 필요합니다(reel receipt <receipt.json>으로 재검증). 그렇지 않으면 실제 상태를 명시하십시오: "미완료", "검토 보류 중인 샘플", "음성 오디션 안 됨". Stop 훅은 일치하는 영수증이 없는 완료 주장을 차단합니다.
  7. 프로젝트 자체 렌더 스크립트(build_*.py 등)로 제작되었거나 다른 도구에서 구성되어 내보낸 비디오도 3-6단계를 거칩니다.
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
 "delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
 "voice": {"mode": "recorded"}, "profile": "default"}
  • voice.mode: none(음성 없음), recorded(실제 녹음), tts 또는 clone(이 두 가지는 voice_id와 reel voice check로 작성된 approved 블록, 또는 quote, sample, sample_sha256이 포함된 사람의 승인도 필요).
  • delivery_root는 반드시 존재하는 절대 경로(또는 ~로 시작)여야 합니다. 홈 폴더, Desktop, Documents, Downloads, iCloud Drive 루트, 프로젝트 폴더 또는 그 상위 폴더일 수 없습니다.
  • 무음 버전은 프로젝트 프로필을 사용합니다: {"extends": "default", "audio": "silent"}.
  • 프로필: default(일반 시작 임계값) 및 vertical-strict(1080x1920 30fps, -16 LUFS, 엄격). 프로젝트 차이점은 extends를 사용하여 프로젝트 프로필에 넣고; 의도된 긴 홀드는 이유와 함께 allow에 등록하고; 금지된 단어(이전 제품명, 채우기 텍스트)는 text.extra_banned에 추가하십시오.

모든 Bash 호출 시작 부분

각 Bash 호출은 새 셸을 시작하므로, 모든 호출을 다음으로 시작하십시오:

REEL_PROJECT=spring-promo                      # 이 프로젝트의 이름
command -v reel >/dev/null || { echo "reel이 PATH에 없습니다 (플러그인을 활성화하거나 ./install.sh --link를 실행하십시오)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg를 찾을 수 없습니다" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"

모든 출력은 $P에 저장되며, 임시 폴더에 저장되지 않습니다; 아래 상대 경로는 $P 기준입니다.

컷 만들기

에이전트가 결정(어떤 샷, 어떤 피사체, 카메라 움직임, 페이싱)을 내립니다; 인식, 지오메트리, 렌더링 및 검사는 코드가 수행합니다. 전체 명령어 구문은 docs/ENGINE.md에 있습니다.

  1. 자료를 $P에 넣습니다(에셋, observations.json, plan.json, 프리뷰, 렌더링 및 검사 보고서가 모두 여기에 위치; 폴더당 하나의 계획).
  2. 스크립트 및 음성. 내레이션 스크립트를 작성하고, 브리프에 맞는 음성을 선택하여 오디션을 통과시키십시오(게이트 단계 2). voice.mp3(또는 .wav)를 생성하고, 자막을 원하면 voice.vtt를 생성하십시오. 공개 작업의 경우 실제 녹음 또는 사용 범위를 포함하는 라이선스가 있는 음성을 선호하십시오; 음악 전용 작품의 경우 audio.voice를 음악 트랙으로 지정하십시오(타임라인 앵커 역할).
  3. 보고 대상 선택: reel inspect(각 파일 목록) → reel frame(0-1 그리드로 이미지를 읽고 피사체의 박스를 읽어냄) → 등록하려면 reel observe, 또는 reel locate --query ... --check-png ...(OWLv2; 감지를 사용하기 전에 검사 이미지를 확인).
  4. plan.json 작성 (EditPlan v1): camera: []는 프레임을 고정합니다; observation_id와 함께 zoom_to는 등록된 피사체를 확대합니다; 비디오에서 피사체가 움직일 때 track을 사용하십시오; 전환에는 transition_out을 사용하십시오. 비디오 샷이 inspect가 보고한 장면 컷을 넘지 않도록 하십시오. audio.voice는 필수이며 src_dir을 기준으로 확인됩니다.
  5. 유효성 검사 및 프리뷰: reel validate → reel compile → reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png, 그런 다음 콘택트 시트를 읽어 카메라 움직임을 판단하십시오.
  6. 렌더링: reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(사용자가 원격 GPU를 구성하고 요청한 경우에만 --where remote 사용). 렌더링 검사를 통과한다는 것은 파일이 손상되지 않았다는 의미일 뿐입니다; 게이트 단계 3-6을 계속 진행하십시오.

docs/ENGINE.md에 각각 섹션이 있는 다른 진입점:

  • 타임라인 검사 및 변경: reel timeline(--format text 또는 --png 멀티트랙 이미지), reel scrub(각 컷 주변 프레임), reel edit / undo / history, reel preview --range(저해상도 프리뷰 + 사운드).
  • 비트에 맞추기: reel beats music.mp3 --out beats.json → reel snap plan.json --beats beats.json --mode downbeat; 그런 다음 모든 컷을 reel timeline --png --beats로 확인하십시오. ./install.sh --beats 필요.
  • 웹 페이지 하이라이트 내레이션: kind: "web" 샷; 텍스트 위치는 DOM에서 가져오므로(OCR 없음), 강조 표시된 문장은 페이지 텍스트와 정확히 일치해야 합니다; reel words voice.mp3는 단어별 타이밍을 제공합니다. ./install.sh --web 필요.
  • Shotcut 프로젝트: reel mlt project.mlt --video-only; --dupes는 두 번 사용된 소스 푸티지를 찾습니다.

사용 가능: 계획 조립, 서브픽셀 확대, 움직이는 피사체 추적, xfade 전환, 번인 자막, 배경 음악, 그레이딩 및 LUT, 웹 샷, OWLv2 피사체 검색, 기술 검사, 게이트 전달.

내장되지 않음: 이징 전환, 프레임 보간, 음성 복제.

원격 GPU (선택 사항)

--where remote 부분은 코드로 강제됩니다.

  • 사용자가 REEL_REMOTE(SSH 대상)를 구성하고 요청한 경우에만 사용하십시오; 그렇지 않으면 --where local로 렌더링하십시오.
  • VRAM 사용량은 기본적으로 80%로 제한됩니다. 작업에 더 많은 VRAM이 필요하면 도구가 NEED_USER_APPROVAL을 반환합니다: 먼저 사용자에게 알리고, 동의가 있을 때만 --allow-over-80을 추가하십시오. GPU 사용률이 50% 이상이면 다른 사람이 사용 중인 것입니다; 점유하지 마십시오.
  • 한 번에 하나의 reel GPU 작업(원격 파일 잠금). 전력 제한을 변경하지 마십시오. 호스트를 재부팅하거나 종료하지 마십시오.
  • reel remote probe는 호스트 정보를 보고합니다; reel remote setup-vision은 원격 호스트에 torch 및 OWLv2 가중치가 포함된 별도의 venv를 설치합니다.

동봉 파일

  • SOP.md: 방향 설정 우선 워크플로우, 역할, 단계 및 종료 조건.
  • director 에이전트 (저장소의 agents/director.md): 브리프, 스토리보드 및 검토.
  • 저장소의 docs/ENGINE.md: 명령어, EditPlan, 브리프, 검토, 영수증 및 프로필.

관련 스킬