활성화 조건
사용자가 카툰/셀 셰이딩 3D 설명 클립(평평한 색상, 검은 윤곽선, 물체가 튀어나오는 효과, 움직이는 카메라, 큰 자막)을 원하거나, 'Stupy Doo' 스타일 비디오를 재현하려 하거나, 텍스트로부터 Blender에서 다이어그램을 애니메이션화해 달라고 요청할 때 로드됩니다.
엄격한 규칙
- 절대로 이미지/비디오 AI 모델로 시각 자료를 생성하지 마십시오. 외형은 Blender가 렌더링한 3D 지오메트리 + Freestyle 윤곽선입니다.
- Blender 바이너리:
~/.local/bin/blender(5.1.x, 사용자 설치). 항상-b -P옵션으로 헤드리스 모드로 실행하십시오. - 스토리보드는 유일한 진실 공급원입니다:
storyboard.json(스키마는references/storyboard-schema.md참조). JSON을 편집하고 다시 렌더링하십시오..blend파일을 절대 수동 편집하지 마십시오. - 전체 비디오를 렌더링하기 전에 항상 살펴보십시오: 3~5회
--stills렌더링 후 접촉 시트(contact sheet)를 만들어 읽고 겹침이나 카메라 밖 물체를 수정하십시오. - 자막과 오디오는 후처리(
mix.py,captions.py)로 처리하며, Blender 텍스트 객체를 사용하지 마십시오. - SFX는
audio섹션의action:참조를 통해 액션 시간에 맞춰 배치되며, 액션이 존재할 경우 절대 수동으로 초를 입력하지 마십시오. - 내레이션 언어는 중립적인 스페인어를 유지합니다. UI/자막 텍스트는 사용자 언어를 따릅니다.
- 클립은 스토리보드당 8~30초로 짧게 유지하십시오. 더 긴 비디오는 ffmpeg concat으로 클립을 연결하십시오.
결정 게이트
| 필요 | 수행 |
|---|---|
| 내레이션이 있는 비디오 | 내레이션 먼저, 자막을 내레이션에 맞춘 후 애니메이션. voice-video (tts.py)로 audio.narration에 음성 생성. |
| SFX / 음악 | audio 섹션: action: 참조가 포함된 내레이션, 음악, SFX. assets/sfx/에 플레이스홀더, CC0 소스는 README에. |
| 제공된 음악 | 스틸 렌더링 전에 beats.py snap storyboard.json --music track.mp3 --write 실행. |
| 빠른 확인 | --preview --stills t1,t2,t3 (절반 해상도, 8 샘플). |
| 최종 렌더링 | --preview 없음; 기본 1080x1920, 30fps. |
| 프리팹에 없는 객체 | 프리팹: box, plane, cylinder, sphere, panel, panel_row, cable, device, car, charger, transformer, cloud, tree, pole. 그 외는 기본형 또는 model (glb/obj). |
| 프레임이 조잡해 보임 | 샷당 한 주제, 카메라 8~13m, tree/pole/cloud 장식, draw 후 flow인 케이블. 자세한 내용은 references/style-notes.md 참조. |
| 수동 조정 필요 | --blend 추가 후 out/scene.blend를 Blender UI에서 열기. |
실행 단계
references/storyboard-schema.md와references/style-notes.md를 읽으십시오.<workdir>/storyboard.json을 생성하는 작은gen.py를 작성하십시오: z=0의 바닥면 위에 객체들, 샷(각각 한 주제), 액션, 자막,post,audio.- 스틸:
~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5. Pillow로 접촉 시트를 만들고 읽으십시오. - JSON에서 구도와 타이밍을 수정하십시오. 모든 샷이 명확하게 보일 때까지 3단계를 반복하십시오.
- 미리보기 비디오:
--preview만 추가하여 동일한 명령어 실행. ffprobe로out/raw.mp4확인 (길이, fps). - 오디오 (
audio가 있을 경우):python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav. 큐 테이블 읽기. - 자막 + 먹싱:
python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav(또는audio가 없으면--audio narration.wav). - 최종:
--preview제거 후 5~7단계 재실행.xdg-open으로out/final.mp4열기.
출력 계약
반환: storyboard.json 경로, out/final.mp4 경로, 길이, 해상도, 화면에 표시되는 내용을 설명하는 샷당 한 줄. 렌더링 시간 보고. 아직 구현되지 않은 항목(립싱크, 멀티클립 연결) 목록 작성.
참조 자료
references/storyboard-schema.md— JSON 스키마, 프리팹, 액션, 카메라 규칙.references/style-notes.md— 참조 외형, Blender 5 주의사항, 조잡함을 해결한 방법, 사운드 디자인.references/external/— MIT 라이선스 복사본: EL4CTEO의blender-stylized-npr, arjun988의camera-cinematography.assets/toonlib.py— bpy 라이브러리 (재질, 프리팹, 카메라, 애니메이션).assets/build.py— 스토리보드 → Blender 렌더링.assets/mix.py—audio섹션을 하나의 WAV로 믹싱 (음악 덕킹, SFX 큐).assets/beats.py— 비트 감지 및 액션 시간 스냅.assets/sfx/— 플레이스홀더 SFX, CC0 소스.assets/captions.py— ffmpeg 자막 및 오디오 먹싱.assets/storyboard.example.json— 태양광 지붕 예제, 9초.