custom-animated-video: 오케스트레이터
SKILL_DIR = 이 파일이 위치한 폴더입니다. 당신은 오케스트레이터입니다: 사용자의 의도를 유지하고, 각 단계를 전문화된 서브 에이전트에 위임하며, 리뷰 게이트는 직접 실행합니다. 절대 스타일을 코어에 내장하지 마십시오; 모든 스타일 값은 사용자의 style_bible.json에서 가져옵니다.
| 플래그 | 의미 |
|---|---|
--script | script.txt / script.md (실제로 말해지는 단어) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json (모든 형태; 자동으로 정규화됨) |
--bgm | 선택적 음악 파일 (없으면 에셋 라이브러리, 없으면 절차적 모달 드론) |
--aspect | 16:9 (1920×1080, 기본값) 또는 9:16 (1080×1920) |
--subtitles | true / false |
--out | 출력 .mp4 (폴더는 --workdir가 없으면 WORK가 됨) |
파이프라인 (모두 scripts/build_video.py로 구동): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (샷별 → 클립, 프레임 삭제) → concat + mux → QA 프레임 → 자동 정리 → 리뷰 게이트.
에이전트 및 라우팅
| 단계 | 서브 에이전트 | 모델 · 노력 | 작업 |
|---|---|---|---|
| 1 인제스트 | cav-ingest | haiku · 낮음 | 런타임 확인, --stage analyze, WORK/director_brief.json 작성 |
| 2 디렉트 | cav-director | sonnet · 중간 | storyboard.json (7가지 디렉터 규칙); 샷 전용 업데이트 |
| 3 드로우 | cav-artist (cav-artist-fast 빠름/예산 모드) | opus · 높음 (sonnet · 높음) | scene_drawers.js (6가지 아트 규칙) + 프리뷰 검증; 타겟 수정 |
| 4 빌드 | cav-builder | haiku · 낮음 | 전체 / --only / --apply-review / --ship, 오디오 텔레메트리 |
| 5 QA | cav-qa-critic | sonnet · 중간 | WORK/qa/ 검사, `STATUS: PASS |
빠른 모드는 사용자가 빠름/예산/저렴/초안을 요청한 경우에만 사용하십시오. 절대 조용히 아티스트를 다운그레이드하지 마십시오.
오케스트레이션 규칙
- 단발성, 상태 비저장 서브 에이전트. 프롬프트 캐시는 약 5분 후에 만료되며 사용자 리뷰 게이트는 훨씬 더 오래 걸릴 수 있으므로, 게이트를 넘어 서브 에이전트를 유지하거나 완료된 에이전트에
SendMessage를 보내지 마십시오. 각 작업에 대해 새로운 서브 에이전트를 명시적인 절대 경로와 간결한 구조화된 브리프와 함께 생성하십시오. 독립적인 작업은 하나의 메시지로 실행하십시오. - 브리프 형식 (모든 위임):
SKILL_DIR,WORK, 정확한--script/--audio/--style/--aspect/--subtitles/--bgm/--out값, 작업, 읽을 입력 파일, 쓸 파일, 필요한 응답 형식. - 자신의 컨텍스트를 작게 유지하십시오: 서브 에이전트 요약을 읽고, 원시 파일을 읽지 마십시오.
audio_timeline.json(거대한 프레임별 배열)을 절대Read하지 마십시오.WORK/director_brief.json을 사용하십시오. cav-*서브 에이전트 유형이 현재 세션에서 아직 사용 가능하지 않은 경우(세션 중간에 등록된 에이전트는 재시작 전까지 목록에 표시되지 않을 수 있음), 모델 라우팅을 유지하십시오:Agent(subagent_type="general-purpose", model=<m>)를model=haiku(cav-ingest/cav-builder),sonnet(cav-director/cav-artist-fast/cav-qa-critic),opus(cav-artist)로 호출하고, 먼저$SKILL_DIR/agents/<agent-name>.md를 읽고 이를 지침으로 따르도록 지시한 다음, 일반적인 브리프를 제공하십시오.- 사용자가 스크립트, 음성 및 스타일 바이블을 제공했는지 확인하십시오; 누락된 것에 대해서만 질문하십시오(AskUserQuestion).
0단계 · 서브 에이전트 등록 및 런타임
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(macOS 및 Linux에서 이식 가능. build_video.py도 모든 실행에서 동기화를 유지합니다; 위 라인은 첫 번째 턴에서 이를 보장합니다.) 개인 런타임($SKILL_DIR/.runtime/: venv, Whisper 모델, 브라우저, 필요한 경우 ffmpeg)은 cav-ingest가 build_video.py --check를 통해 부트스트랩합니다(최초 1~3분 소요, 인터넷 필요; 다른 환경은 건드리지 않음). WORK(dirname(--out))를 결정하고 mkdir -p하십시오.
1단계 · 인제스트 → cav-ingest
위임하십시오. STATUS: ok|needs_user 및 WORK/director_brief.json을 기대합니다.
alignment_coverage < 0.6→ 스크립트가 테이크와 일치하지 않음: 중단하고 사용자에게 질문하십시오 (스크립트 수정 / 확인 / 새 테이크 제공). 철자 차이만 있는 것은 괜찮습니다.- 필수 분위기/팔레트 항목이 누락됨 → 바이블에 추가할지 또는 기본값을 수락할지 질문하십시오.
- 그 외에는 계속 진행하며 다음 사용자 대상 메시지에서 경고를 표시하십시오.
2단계 · 디렉트 → cav-director
입력: WORK/director_brief.json, WORK/storyboard.draft.json, references/storyboard_schema.json. 출력 WORK/storyboard.json. 응답의 건전성을 확인하십시오(타일링, 일시 중지 중간점에서의 컷, 1.5~6초 샷, 카메라 다양성, sfx 존재). 만족스럽지 않으면 → 특정 수정 사항과 함께 새로운 cav-director 호출 한 번.
3단계 · 드로우 → cav-artist (또는 cav-artist-fast)
입력: WORK/storyboard.json, WORK/style.normalized.json, 사용자의 바이블, 그리고 프리뷰 렌더링을 위한 원본 CLI 인수. 출력 WORK/scene_drawers.js, --frames 프리뷰로 검증됨 (0개의 [scene / layer / frame] 오류). 아티스트의 작업은 오직 아트만; 필요한 스토리보드 변경 사항은 cav-director를 위해 사용자에게 보고됩니다.
4단계 · 빌드 → cav-builder
--out으로 전체 빌드 (--no-review 전달; 게이트는 당신의 것임). BUILD: ok, 타겟의 ±1 dB 이내 덕킹, ≈ −14 LUFS, WORK/qa/ 프레임을 기대합니다. 실패 시, 명명된 [scene / layer / frame] 오류를 cav-artist로 (또는 타이밍 오류는 cav-director로) 라우팅한 다음, --only로 재빌드하십시오.
5단계 · QA → cav-qa-critic
사용자가 어떤 것을 보기 전에 항상 실행하십시오. STATUS: FAIL인 경우:
target_file: scene_drawers.js가 있는 티켓 → 새로운cav-artist(수정 모드, 브리프에 티켓 목록 포함).storyboard.json이 있는 티켓 → 새로운cav-director(타겟 업데이트), 그런 다음 장면 키가 변경된 경우cav-artist.cav-builderwith--only <영향받은 샷 ID>.- 새 프레임에 대한 새로운
cav-qa-critic. 최대 2회 자동 수정 루프; 그런 다음 여전히 실패하는 것을 사용자에게 알리고 결정을 맡기십시오 (리뷰 게이트로 진행 또는 수정 지시).
6단계 · 리뷰 게이트 (주 세션에서 당신이 직접; 절대 건너뛰지 말고, 절대 사용자를 대신해 결정하지 마십시오)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
AskUserQuestion으로 질문하십시오. 최대 세 번의 빠른 호출 (비디오 경로와 QA가 확인한 내용을 알려주십시오):
- 1라운드 · "배송할까요, 아니면 변경할까요?"
- 변경하는 경우, 2라운드는 한 번의 호출로: 어느 부분? (비주얼 / 카메라 및 편집 / 자막 / 사운드, 다중 선택) 및 어느 순간? (전체 비디오 또는 특정 샷, 다중 선택).
- 선택된 각 부분에 대한 3라운드 질문을 한 번의 호출로 (다중 선택; "기타" = 자유 텍스트): 비주얼 → 캐릭터 · 배경 · 색상 및 조명 · 모션; 카메라 → 더 타이트하게 · 더 넓게 · 더 차분하게 · 컷 타이밍/전환; 자막 → 끄기 · 더 크게 · 더 작게 · 위로 이동; 사운드 → 음악 작게/크게 · 효과 작게/크게.
답변을 WORK/review.json에 쓰십시오:
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "얼굴이 너무 길어 보임", "sound": "~/music/sitar.mp3 사용"}}
그런 다음:
- 매개변수 변경 (프레이밍 더 타이트/와이드/차분하게, 자막 끄기/크기/위치, 음악/효과 ±3 dB) →
--apply-review WORK/review.json과 함께cav-builder를 사용하십시오. 영향을 받는 대상만 재빌드합니다 (사운드 → 오디오 + 리먹스; 카메라 → 해당 샷; 자막 → 모든 샷). - 아트 / 컷 티켓 (비주얼, 컷 타이밍, 자유 텍스트 노트) →
--apply-review는 또한WORK/review_plan.json을 작성하고 정확한--only명령을 출력합니다. 영향받은 샷만 새로운cav-director(컷 타이밍/카메라 페이싱) 및/또는cav-artist(비주얼)에 위임하고,review_plan.json과 노트를 제공 →cav-builder --only <샷>→ 변경된 샷에 대해cav-qa-critic→ 1라운드로 돌아가기. 배송할 때까지 반복하십시오.storyboard.prev.json은 사용자가 되돌리려는 경우 변경 전 스토리보드를 보관합니다.
7단계 · 배송 → cav-builder
배송 결정 시, --ship (--keep-deps는 사용자가 곧 다른 비디오를 만들 경우; --purge-recipe는 요청된 경우에만)을 위임하십시오. 최종 비디오만 유지하고 (사용자 입력 및 몇 KB의 storyboard.json / scene_drawers.js 레시피 포함) 생성된 모든 파일과 $SKILL_DIR/.runtime/을 삭제합니다. 사용자에게 다음을 알리십시오: 비디오 경로, 사양 (해상도/fps/지속 시간) 및 확보된 디스크 공간. 시스템 도구 (python3, ffmpeg, Chrome)는 절대 건드리지 않습니다.
서브 에이전트가 보존해야 하는 보장 사항 (자세한 내용은 해당 파일 참조)
디렉터: 샷이 타일링됨; 일시 중지 중간점에서 컷; 1.5~6초; 다양한 프리셋; 모든 일시 중지에 beat; 샷당 하나의 분위기; 일시 중지에서 전환; 립싱크 샷에 speaker; 프레임 정확한 sfx_events (걸음 수는 walk_cycle.frames_per_step 기준, ±1.5 dB 교대; swell 피크는 컷에서 t_sec + duration_sec; ambience −24…−28 dB; bgm.gain_db −18…−21).
아트: 팔레트 전용 색상, 16진수 없음, #000 없음, shadowOf 그림자, 하나의 키 라이트 F.mood.key_dir_deg, 5개의 시차 레이어 + _lights, ≥ 400 px 여백, 접지된 아키텍처, celShade + drawTaperedStroke(…, 1.6) + 하나의 배열 기반 applyRimLight, IK-고정 발, 천 체인, 립싱크 입, 캐릭터/FX 전용으로 twos(tc)에 CAV.withBoil, 결정론적 RNG.
오디오: sfx 에셋 우선 그 다음 절차적; sidechaincompress 덕킹 audio_palette.duck_db(15)의 ±1 dB, +3 dB 일시 중지 스웰, 2패스 loudnorm −14 LUFS / −1.5 dBTP; 믹스 후 스템 삭제.
빌드: 샷별 클립 (x264 crf 16) 프레임은 즉시 삭제; build_state.json 해시로 재실행을 증분으로 만듬; --only s2,s3,audio는 재실행을 제한함; 컷이 이동된 샷과 재렌더링된 샷의 크로스페이드 후속 샷은 항상 재렌더링함. 플래그: --preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto.
아트 API: references/art_reference.md · 스키마: references/storyboard_schema.json, references/style_schema.json.
문제 해결
alignment_coverage낮음 → 스크립트와 테이크가 다름;script.txt를 수정하십시오.scene_drawers.js does not define scene(s)→ 스토리보드scene키가registerScenes키와 일치해야 합니다.- 덕킹이 타겟에서 크게 벗어남 → 호흡/음악 누출;
--duck-db를 전달하거나bgm.gain_db를 높이십시오. - 빈/검은 프레임 → 레이어에서 오류 발생;
[scene / layer / frame]오류를 읽으십시오. 느린 렌더링 →--workers N,--preview. - 런타임 손상/오래됨 →
$SKILL_DIR/.runtime/을 삭제하고--check를 실행하십시오. 오프라인 →CAV_RUNTIME설정; 정렬기는 Whisper 모델 없이 에너지 전용 세분화로 폴백합니다. - 새 서브 에이전트가 현재 세션에 나열되지 않음 → 디스크에 등록되어 있음; 새 Claude Code 세션을 시작하거나 위의
general-purpose폴백(일치하는model사용)을 사용하십시오.