설명 영상 만들기
당신은 특정 시청자가 이해할 수 있고 정확한 설명 영상을 만듭니다. 두 가지가 결과를 결정합니다:
references/STYLE.md의 규칙(실제 리뷰어 피드백에서 비롯됨)과 표시하는 모든 숫자를 계산하고 확인하는 습관입니다. 렌더링은 쉬운 부분입니다.
저장소 맵: 라이브러리 animkit/ (API 참조 animkit/README.md), 도구 tools/, 예제 examples/, 완성된 두 편의 에피소드 episodes_example/ (스토리보드와 샷 형식을 복사하세요; CLAIMS 형식은 references/VERIFY.md에 있습니다), 당신의 작업은 episodes/<ID>_<topic>/에 들어갑니다.
0. 시작하기 전에
- 환경이 작동하는가?
python -I -B -X utf8 tools/selftest.py가all OK를 출력해야 합니다.config/animkit.json이 없으면python -X utf8 tools/setup_config.py를 실행하세요 (설정은 체크아웃별로 있습니다: 새 클론이나 git 워크트리는 다시 필요하거나ANIMKIT_CONFIG를 설정하세요). 문제가 있으면:SETUP.md. - 기본값으로 정할 수 없는 것만 사용자에게 물어보세요 (한 메시지, 짧게):
- 주제와 출처 자료 (강의 노트, 논문, 페이지); 모든 주장에 출처가 필요합니다;
- 시청자와 그들이 이미 알고 있는 것 (깊이 설정,
references/STORYBOARD.md§Audience); - 길이; 번역 버전 / 나레이션 / 음성 해설이 필요한가?
- 실제 모델을 실행해도 되는가 (GPU, 다운로드)? 기본값: 아니요, 알려진 정답이 있는 합성 장면을 사용합니다.
- 답변이 없을 경우 기본값: 1080×1440, 30fps, 캡션만, 음성 없음, 계획된 리뷰 라운드 1회.
episodes/<ID>_<topic>/를 만들고STATUS.md(단계 / 다음 단계 / 대기 중 /date의 시간)를 작성하세요.
1. 파이프라인 (세부 사항 및 명령어: references/PIPELINE.md)
| 단계 | 당신이 생성하는 것 | 다음 단계로 가기 위한 게이트(Gate) |
|---|---|---|
| A. 연구 | 출처 요약; 선택적 참조 영상 분석 (references/REFERENCES.md) | 메커니즘을 입력 → 공식 → 도형 → 작은 숫자 예제 → 이유 순서로 설명할 수 있음 |
| B. 스토리보드 | storyboard.md, CLAIMS_to_verify.md, episode.json (+ 라이브러리에 없는 것이 있으면 elements_needed.md) | 긴 에피소드의 경우 사용자가 개요에 OK; 독립 검증 라운드 1 완료 및 수정 사항 적용 (references/VERIFY.md) |
| C. 샷 | shots/sNN_*.py, 각각 @shot.check 포함 | --check-only 통과; 연락처 시트 검사; 전체 렌더링; check.json 경고 수정됨 |
| D. 조립 | render/<ID>.mp4 (tools/concat.py), review/round1/review.html (tools/review_page.py) | 모든 샷의 시트를 직접 확인함; 화면의 숫자 = CLAIMS |
| E. 리뷰 라운드 | review/roundN/feedback.md (사용자 노트), review/roundN+1/changes.md, 재렌더링 | 각 피드백 항목에 답변; 새 주장 검증됨 (항목당 최대 2라운드) |
| F. 선택 사항 | 번역 버전 (references/I18N.md), 나레이션 (references/NARRATION.md), 음성 해설 (references/TTS.md) | 각각 자체 검사 있음 |
영상의 언어로 직접 샷을 작성하세요 (예제는 영어): 캡션, 제목 및 레이블은 스크립트의 일반 문자열입니다. --lang은 두 번째 번역 버전에만 사용됩니다.
마이크로 경로 (≤ 60초, 1–3개 샷). 동일한 단계, 더 가볍게. episodes/<ID>_<topic>/의 최소 파일 목록:
storyboard.md: 하나의 테이블, 캡션당 하나의 행 (시간 범위, 캡션, 화면에서 변경되는 사항, 계산된 것인지 예시인지). 골격:templates/storyboard_skeleton.md.CLAIMS_to_verify.md: 화면에 표시되는 숫자/사실당 하나의 행 (주장, 출처, 확인 방법, 측정됨/계산됨/추론됨/논문).shots/s01_<name>.py(templates/shot_template.py에서), 표시된 문자열로 모든 계산된 숫자를 단언하는@shot.check포함.- 검증:
templates/verifier_prompt.md를 사용하는 새로운 하위 에이전트, 모든 CLAIMS 행을 대상으로 함; 수정 사항 적용 (이전 표현은 취소선). - 렌더링:
--check-only→--sheet-only(sheet.jpg확인) → 전체 렌더링. episode.json+tools/concat.py는 샷이 2개 이상인 경우에만;tools/review_page.py <EP> --round 1리뷰 페이지용 (1라운드). 주장 테이블,@shot.check, 연락처 시트 확인을 건너뛰지 마세요.
2. 절대 선택 사항이 아닌 규칙
- 계산 가능한 모든 시각적 요소는 계산됩니다 (투영, 어텐션 가중치, 형태 변환, 역투영, 피팅된 선) 그리고
@shot.check에서 단언되며, 표시된 문자열도 포함합니다:ck.eq("화면의 깊이", f"{z:.3f}", "1.976"). 전체 정밀도에서 형식 지정; 인쇄된 값을 다시 반올림하지 마세요. 예시 시각적 요소는shot.tag("Illustration")를 얻습니다; 차원 축소된 그림은 그렇게 명시하세요. - 모든 숫자에는 출처가 있습니다 (논문 § / 표 / 방정식, 공식 코드 파일 + 줄, 또는 당사 스크립트)
CLAIMS_to_verify.md에, 측정됨 / 계산됨 / 추론됨 / 논문으로 레이블 지정됩니다. 비교는 메트릭, 단위, 더 낮거나 높은 것이 더 나은지 명시합니다; 백분율은 분모를 명시합니다. - 모든 기호는 나타나는 곳에서 정의됩니다, 매번; 시청자가 모를 수 있는 용어는 설명하고 닫히는 팝업 사이드 윈도우 (
animkit.Popup)를 얻습니다. - 하나의 캡션 = 하나의 시각적 변경, ≤ 12단어이고 프레임보다 넓지 않음 (렌더링이 경고함; 42px에서 줄당 약 8개의 긴 단어, 최대 2줄), 각각 2–3초, 정적인 것은 없음.
- 그림이 먼저, 그 다음 공식, 용어별로 조명, 각 용어는 그림의 해당 부분에 색상이 지정되거나 연결됨.
- 자체 테스트는 당사의 것으로 레이블 지정됨 (논문의 실험이 아님) 처음 나타날 때와 동일한 태그로 이후에도.
- 독립 검증: 주장을 작성한 사람은 이를 검증하지 않음; 수정은 새로운 주장; 최대 2라운드, 그 후에는 그대로 적용하고 스팟 체크. 이전 표현은 취소선 (
~~old~~ → new)으로 표시되며, 절대 조용히 삭제되지 않음. - 번역 또는 나레이션에서 사실을 지어내지 마십시오: 검증된 캡션 / CLAIMS가 말하는 내용만 말할 수 있음.
- 전체 체크리스트:
references/STYLE.md(§A 내용, §B 리듬, §C 시각적 문법, §D 전달 전, §E 규칙이 된 리뷰어 피드백). 스토리보드를 작성하기 전과 각 리뷰 라운드 전에 읽으십시오.
3. 작업 스타일
- 필요한 API 섹션을
animkit/README.md에서 읽으십시오 (길다: 요소를 grep한 다음 해당 부분을 읽으십시오). 레이아웃을 새로 발명하는 대신episodes_example/에서 가장 가까운 샷의 패턴을 복사하십시오.templates/shot_template.py는 최소한의 완전한 샷입니다. --still t1 t2(PNG 프레임)와--sheet-only(12프레임 연락처 시트)로 샷을 반복하고; 전체 렌더링은 마지막에 합니다. 시트를 직접 확인하십시오 (겹침, 텍스트가 캔버스를 벗어남, 상자 = 누락된 글리프, 그림 위의 캡션). 스틸은 이후 렌더링에서 새로 고쳐지지 않습니다: 편집 후--still을 다시 실행하십시오.- 3D 장면:
animkit/README.md§3D 장면 (PinholeCam, OrbitCam az / el 규칙: az=90, el=0은 측면도). 핀홀 측면도와 같은 2D 다이어그램: §2D 측면도 (동일한 축척의 Plot2D). - Python을
python -I -B -X utf8로 실행하십시오; 다른 세션이 렌더링하는 동안 라이브러리 파일을 편집하지 마십시오 (references/PITFALLS.md). STATUS.md를 짧고 최신 상태로 유지하십시오;effort_log.csv에 노력을 기록하십시오 (item,size,start,end,render_s,iterations,note).- 긴 에피소드 또는 많은 샷:
references/DISPATCH.md에 따라 작업을 여러 세션/하위 에이전트로 분할하십시오 (메인 세션당 컨텍스트 예산 ≈ 300k, 일회성 하위 에이전트당 ≤ 150k, 전환 전 핸드오프 파일).
4. 전달
사용자에게 알리십시오: 비디오 경로, 리뷰 페이지 경로 (review/roundN/review.html, 브라우저에서 열기; 샷당 댓글 상자와 "모두 복사" 버튼이 있음), 계산된 것과 예시적인 것, 검증된 내용과 검증자, 미해결 질문. 사용자의 노트가 돌아오면, 그대로 review/roundN/feedback.md에 저장하고 (샷 ID당 한 줄, 예: E03-02: ...), 각각에 답변하고, 일반적인 선호 사항을 에피소드의 로컬 규칙에 새 줄로 추가하십시오 (episodes/에 STYLE_local.md에 추가), 다음 에피소드가 이를 가지고 시작하도록 합니다.
참조 색인
| 파일 | 언제 읽을까 |
|---|---|
references/PIPELINE.md | 시작할 때; 단계 명령어, 파일 형식, 게이트 |
references/STYLE.md | 스토리보드 작성 시; 각 리뷰 라운드 전 |
references/STORYBOARD.md | B단계: 시청자 깊이, 스토리보드 + CLAIMS 형식, 스토리 패턴 |
references/REFERENCES.md | 참조 영상 / 출처 논문 연구 시 |
references/VERIFY.md + templates/verifier_prompt.md | CLAIMS 후, 모델 실행 후, 나레이션/번역 후 |
references/REVIEW.md | D-E단계: 리뷰 페이지, 피드백 파일, 라운드 |
references/I18N.md | 영어 에피소드의 번역 버전 (--lang) |
references/NARRATION.md | 시각적 세그먼트별 음성 스크립트 |
references/TTS.md | 로컬 TTS 음성 해설, 타이밍, 믹싱 |
references/DISPATCH.md | 다중 세션/하위 에이전트 작업, 비용, 공유 시스템 에티켓 |
references/PITFALLS.md | 문제가 발생할 때; 라이브러리 변경 전 |
templates/ | 세션 및 하위 에이전트용 프롬프트, 골격 파일, 샷 템플릿 |