설명형 영상 스킬 (Hellboy)은(는) 무엇을 하나요?
당신은 하나의 기술 주제를 비전문가가 처음 보자마자 이해하는 완성된 2-3분 분량의 1080×1920 MP4 영상으로 바꿉니다. 시각 스타일, 속도감, 스크립트 구조는 참조 채널(docs/01-style-bible.md에서 분석)에서 가져옵니다. 우리만의 것으로 고정된 두 가지는 **캐릭터(Hellboy)**와 음성입니다.
당신은 텍스트 파일(스크립트와 storyboard.json)만 작성합니다. engine/ 내의 엔진이 음성, 자막, 애니메이션, 캐릭터, 배경 음악 및 렌더링을 처리합니다.
사용자가 주제만 제시했을 때
추가 질문 없이 전체 작업을 수행합니다:
- 주제로부터 슬러그(slug)를 만듭니다 (예:
how-dns-works) 그리고python engine/make_video.py new videos/<slug>를 실행합니다. videos/<slug>/script.md(docs/02)를 작성한 다음,videos/<slug>/storyboard.json(docs/03 + docs/04)를 작성합니다.examples/upi-explained/의 패턴을 복사합니다.python engine/validate_storyboard.py videos/<slug>를 실행합니다. 모든 ERROR를 수정하고0 error(s)가 출력될 때까지 반복합니다.python engine/make_video.py preview videos/<slug>를 실행합니다. 이미지가 보이면build/preview.png를 docs/06 섹션 B와 비교하여 수정합니다.python engine/make_video.py render videos/<slug>를 실행합니다. 경로output/<slug>.mp4, 재생 시간, 2줄 요약과 함께 응답합니다.
절대 지켜야 할 사항
- Hellboy는 절대 다시 그려지지 않습니다. 그는 오직
character/hellboy/hellboy.js에서만 가져옵니다.show,arm(down/point/explain),expression만 설정할 수 있으며 그 외는 불가능합니다.character/hellboy/CHARACTER_BIBLE.md를 한 번 읽으십시오. - 음성은 고정되어 있습니다 (
engine/config.json에서 설정). 비디오마다 변경하지 마십시오. - 길이: 내레이션 360–470단어, 2:00–2:50분. 문장은 20단어 이하.
- 모든 문장은 화면에서 무언가를 변경합니다. 항목은 해당 단어가 언급되는 시점(
"at")에 나타납니다. - 정확함이 단순함보다 우선입니다. 거짓된 내용을 말하지 말고, 내용을 생략함으로써 단순하게 만드십시오.
- 검증기는 통과해야 합니다 (렌더링 전
0 errors).
워크플로우 (순서대로 수행)
| # | 단계 | 읽을 문서 | 산출물 |
|---|---|---|---|
| 1 | 스캐폴드 | – | python engine/make_video.py new videos/<slug> |
| 2 | 계획 및 스크립트 작성 | docs/02-script-writing.md | videos/<slug>/script.md (360–470단어, 7비트) |
| 3 | 시각 자료 계획 | docs/03-visual-planning.md | 장면 목록: 내레이션 → 유형, 헤드라인, 캐릭터 |
| 4 | 스토리보드 작성 | docs/04-storyboard-reference.md | videos/<slug>/storyboard.json (또는 meta.json + scenes.jsonl → assemble) |
| 5 | 유효성 검사 | – | python engine/validate_storyboard.py videos/<slug> → 오류 0개가 될 때까지 수정 |
| 6 | 프리뷰 + QA | docs/06-qa-checklist.md | make_video.py preview videos/<slug> → build/preview.png 검사 후 수정 |
| 7 | 렌더링 | docs/05-production.md | make_video.py render videos/<slug> → output/<slug>.mp4 |
| 8 | 최종 QA | docs/06-qa-checklist.md | 점수 ≥ 85, 모든 MUST 항목 통과 |
소형/로컬 모델인 경우? 단계 2–5 대신 docs/07-small-model-playbook.md를 따르십시오. 작업을 한 번에 한 장면씩 처리하는 프롬프트로 나눕니다.
7비트 스크립트 (암기)
훅 (22단어 이하: "X 설명" / "X는 실제로 어떻게 작동할까?" / 놀라운 주장 / 공감 가는 행동) → 긴장 (미스터리) → 로드맵 ("함께 따라가 봅시다…") → 본문 (3–6개 챕터: 개념 → 쉬운 설명 → 일상 예시 → 결과; 이름이 있는 사람을 포함한 하나의 실행 예시) → 반전 ("하지만 여기서 재미있는 점은…") → 요약 ("이렇게 기억하세요." 챕터당 한 줄) → 마무리 (훅을 반향하는 단편: "한 번의 스캔. 네 명의 플레이어. 2초.").
장면 레시피 (암기)
- 1개 장면 = 1–3문장 (8–28단어, 3–8초); 비디오당 20–32개 장면.
visual.type은docs/03-visual-planning.md의 결정 테이블에서 선택합니다. 비디오당 7–12가지 유형을 사용합니다.- 40–70%의 장면에서 Hellboy를 표시합니다 (항상: 첫 장면, 반전, 요약, 마지막 장면).
sequence,hub,diagram,compare유형에서는 숨깁니다. - 큰 다이어그램은
"continue": true+"shown": true항목과 동일한 헤드라인을 사용하여 2–4개 장면에 걸쳐 구축합니다. - 헤드라인은 2–6단어이며 하나의
*강조*단어를 포함합니다. 화면 라벨은 1–4단어입니다.
명령어 (저장소 루트에서 실행)
# 먼저 활성화: source .venv/bin/activate | Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new videos/<slug> # 템플릿 생성
python engine/make_video.py assemble videos/<slug> # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py videos/<slug> # 오류 0개여야 함
python engine/make_video.py preview videos/<slug> # build/preview.png (장면당 1 프레임)
python engine/make_video.py render videos/<slug> [--fast]
해당 머신에서 처음 실행 시: ./setup.sh (Linux/macOS) 또는 setup.ps1 (Windows). 완성된 비디오는 **output/<slug>.mp4**에 저장됩니다.
참고 자료
examples/upi-explained/(따뜻한 종이 스타일) 및examples/load-balancer-explained/(청사진 스타일) — 완전한 작업 예제입니다. 그 패턴을 복사하십시오.templates/—script.template.md,storyboard.template.json.docs/01-style-bible.md— 참조 채널의 방식과 측정된 규칙 (규칙이 존재하는 이유).engine/icon_names.txt— 허용된 2,359개의 아이콘 이름 (Lucide).