/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로 돌아가 작품을 재고하십시오; 단순히 재편집하지 마십시오.
전달 게이트 (필수)
각 단계는 코드로 강제됩니다: 하나를 건너뛰면 최종 컷을 전달할 수 없습니다.
- 먼저 브리프를 작성하십시오 (
$P/brief.json, 아래 템플릿) 등록:reel register brief.json. 전달 언어, 최종본 또는 샘플 여부, 전달 폴더, 변경할 수 없는 사항: 이 항목들을 채울 수 없으면 사용자에게 물어보십시오. 등록되면 Bash 가드 훅이 전달 폴더에 대한cp/mv/ffmpeg쓰기를 거부합니다. - 음성을 오디션하십시오. 기본 음성은 없습니다. 브리프에 맞는 음성을 선택하고, 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음성은 내부 초안 전용이며, 전달되는 비디오에는 절대 사용하지 마십시오.
- 렌더링을 검사하십시오:
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 없음)을 나열합니다; 해당 항목이 검사되었다고 말하지 마십시오.
- exit 1이면 전달할 수 없습니다.
- 검토하십시오. 모든
needs_review항목(reel scrub, 프레임 캡처)을 살펴보고 각 항목에 대해 타임코드 관찰 결과를 포함한 하나의 검토 레코드를 작성하십시오. 전체 컷을 직접 시청하고final_watch에 서명하십시오(샷당 최소 한 프레임); 처음부터 끝까지 듣고final_listen에 서명하십시오(에이전트 서명에는 타임코드 관찰 결과가 필요함; 사용자가 들었다면 그들의 정확한 말을quote로 기록하십시오). 두 가지 모두 서명했으면 최종본으로 전달하십시오: 영수증에는approved_by: agent가 표시되고, 답변에는 "Claude가 검토한 최종 컷, 아직 사용자가 보지 않음"이라고 말하십시오. 사용자의 피드백은 다음 버전이 됩니다.reviews.json형식은docs/ENGINE.md에 있습니다. - 전달:
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, 삭제 후 다시 등록하십시오.
- 최종 조건이 충족되지 않으면
- "완료" 선언은
status: final인 영수증이 필요합니다(reel receipt <receipt.json>으로 재검증). 그렇지 않으면 실제 상태를 명시하십시오: "미완료", "검토 보류 중인 샘플", "음성 오디션 안 됨". Stop 훅은 일치하는 영수증이 없는 완료 주장을 차단합니다. - 프로젝트 자체 렌더 스크립트(
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에 있습니다.
- 자료를
$P에 넣습니다(에셋,observations.json,plan.json, 프리뷰, 렌더링 및 검사 보고서가 모두 여기에 위치; 폴더당 하나의 계획). - 스크립트 및 음성. 내레이션 스크립트를 작성하고, 브리프에 맞는 음성을 선택하여 오디션을 통과시키십시오(게이트 단계 2).
voice.mp3(또는.wav)를 생성하고, 자막을 원하면voice.vtt를 생성하십시오. 공개 작업의 경우 실제 녹음 또는 사용 범위를 포함하는 라이선스가 있는 음성을 선호하십시오; 음악 전용 작품의 경우audio.voice를 음악 트랙으로 지정하십시오(타임라인 앵커 역할). - 보고 대상 선택:
reel inspect(각 파일 목록) →reel frame(0-1 그리드로 이미지를 읽고 피사체의 박스를 읽어냄) → 등록하려면reel observe, 또는reel locate --query ... --check-png ...(OWLv2; 감지를 사용하기 전에 검사 이미지를 확인). plan.json작성 (EditPlan v1):camera: []는 프레임을 고정합니다;observation_id와 함께zoom_to는 등록된 피사체를 확대합니다; 비디오에서 피사체가 움직일 때track을 사용하십시오; 전환에는transition_out을 사용하십시오. 비디오 샷이inspect가 보고한 장면 컷을 넘지 않도록 하십시오.audio.voice는 필수이며src_dir을 기준으로 확인됩니다.- 유효성 검사 및 프리뷰:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png, 그런 다음 콘택트 시트를 읽어 카메라 움직임을 판단하십시오. - 렌더링:
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, 브리프, 검토, 영수증 및 프로필.