Pedrovbm1/explicador

애니메이션 설명 영상 (코드 기반 3D 모션 그래픽)

모든 것은 코드입니다: 영상의 각 부분은 3D 세계(escena/partes/<parte>.js)이며, 이는 시간의 순수 함수입니다. motor.js가 어떤 부분을 보여줄지 결정하고 카라오케 자막을 그리며, render.mjs가 Chrome 헤드리스에 각 프레임을 요청합니다. 수동 편집은 없습니다: 문제가 발생하면 코드를 수정하고 다시 렌더링합니다.

모든 파일 위치: HOME3D = $EXPLICADORES_3D 또는, 존재하지 않으면 ~/.explicadores-3d (설치 프로그램이 생성합니다). 여기에 biblioteca/ (3D 모델, vendor/ (three.js, 폰트))와 이 스킬의 복사본이 있습니다. SKILL_DIR = 이 SKILL.md의 폴더입니다.

파일	용도
nuevo.py <폴더>	템플릿으로 프로젝트 생성 (엔진, 스타일, lib2d, three.js, Fredoka 폰트, 음성/타이밍/오디오 스크립트, 예시 부분, 빈 CONTRATO.md 및 DECISIONES.md)
render.mjs	--hoja, --probe a,b,c, --rango a,b, --mitad, --sub N, --rapido, --sin-gpu
entregar.py <프로젝트> <이름> --ronda N [--escritorio]	비디오 + 오디오, 29MB 미만 모바일 버전, 0.5초마다 리뷰 시트 및 datos.txt (길이, LUFS, 피크)
revisar_hoja.py <프로젝트> [--tramo a,b | --ronda N | --cuadros …]	약 5초 만에 자동 리뷰, 토큰 소모 없음: 페이드에서 이중 텍스트, 후광, 쌍둥이 (눈처럼 보임), 번짐 흰색, 얼룩, 영역 밖, 밝기 점프
ENCARGO_CONSTRUCTOR.md	생성자 짧은 작업 템플릿 (에이전트당 한 부분)
ENCARGO_REVISORES.md	검수자 A (보유), B (데이터), D (이미지) 시트 및 비디오 검토

요구 사항: Node 18+, 프로젝트에 npm install playwright-core, Chrome (또는 CHROME_PATH, 또는 npx playwright install chromium), Python 3.10+ (numpy 및 faster-whisper 필요), ffmpeg.

기본 규칙

• 데이터 조작 금지: 모든 수치는 CONTRATO에 출처와 함께 생성 전에 명시.
• 마스코트나 눈이 있는 물체 금지, 눈으로 읽힐 수 있는 형태도 금지 ("일반적인 오류" 참조).
• 기본 스타일: 어두운 배경 위에 깔끔한 물체 하나, 따뜻한 후광, 항상 부드럽게 움직이는 매크로 카메라, 금색 키워드, 전체 내레이션의 카라오케 자막, 첫 프레임에서 루프.
• 리듬: 3.0-3.2 단어/초, 약 3초마다 구도 변경, 5초 이상 정지 없음, 4.5초 이내에 후크.
• 길이: 단독 영상은 15-30초; 시리즈의 일부(이름과 번호 있음)인 경우에만 60초 이상.

워크플로우

1. python SKILL_DIR/nuevo.py <주제>-YYYY-MM (현재 디렉토리에 폴더 생성). 열고 테스트: npx http-server escena -p 8080 (또는 escena/ 내에서 python -m http.server) 실행 후 localhost:8080 접속.
2. guion 스킬로 대본 작성: 출처 조사, MAPA, 라운드 0 (A ≥ 9, C ≥ 9, 최대 2라운드) 및 중단 조건 GUION LISTO. 사용자 확인 없이 진행하지 마세요.
3. 음성 (크레딧 또는 CPU 시간 소모, 확인 후 진행):
   • ElevenLabs: export ELEVENLABS_API_KEY=... (사용자가 설정, 절대 파일에 직접 작성 금지) 및 python scripts/voz_eleven.py [--voz <id>] → voz/tomas_eleven/. 무료 플랜 = 상업적 사용 불가 및 크레딧 한도.
   • 무료 로컬: pip install kokoro soundfile (+ 시스템 espeak-ng) 및 python scripts/voz_local.py [--voz em_alex] → voz/tomas_local/.
   • python scripts/verificar_voz.py (Whisper large-v3, 한 번만, 백그라운드) 잘못 발음된 단어 표시.
   • python scripts/tiempos.py --tomas tomas_eleven (또는 tomas_local) → voz/voz_completa.wav, escena/beats.js (각 키워드의 초, voz/claves.json 기준) 및 escena/palabras.js (카라오케).
4. 완전한 CONTRATO (escena/CONTRATO.md): 각 부분별 구간 B.*, 각 키에서 보여줄 내용, 정확한 텍스트, 출처 포함 데이터, 안전 영역, 리듬. 생성자가 읽는 유일한 문서: 여기에 없는 것은 추측합니다. motor.js에서 PLAN (부분 순서 및 전환) 및 CLAVE (카라오케 금색 단어) 변경.
5. 3D 모델: 모델링 전에 라이브러리 검색 (biblioteca 스킬, HOME3D/biblioteca/CATALOGO.md) 및 필요한 것을 escena/modelos/로 복사. 부족한 것은 단일 에이전트가 생성 (공유 모델, 노력 medium, 상한 150k) 하고 modelos/LISTO_<물체>.txt로 알림.
6. 생성자, ENCARGO_CONSTRUCTOR.md 사용:
   • 부분당 한 에이전트 (≤ 15초 장면), 백그라운드, 최대 3개 동시 실행;
   • 짧은 작업: 자신의 구간, 자신의 모델(API 한 줄), 규칙만 제공; 생성자는 엔진이나 전체 CONTRATO를 읽지 않음;
   • "일반적인 오류" 블록과 "생성자 상한"을 그대로 첨부;
   • 수정 라운드마다 새로운 생성자 사용, 40턴 초과한 에이전트와 계속 대화 금지;
   • 다른 에이전트를 "기다리게" 하지 않음: 먼저 공유 모델, 그 다음 부분.
7. 렌더 전 시트: node render.mjs --hoja (비트당 한 프레임: 시각적 대본) 및 python SKILL_DIR/revisar_hoja.py .. 빨간색 = 새로운 low 에이전트로 수정 후 진행. 그 다음 시트에 대한 검수자 A, B, D (ENCARGO_REVISORES.md, 라운드 1), revisar_hoja.py 출력을 D 작업에 포함.
8. python scripts/audio.py → audio/mezcla.wav -14 LUFS (합성 음악 및 효과; 파일 상단에서 EFECTOS 및 CAMBIOS 편집).
9. 반복 렌더: node render.mjs --rapido --sub 1. 그 다음 python SKILL_DIR/entregar.py . 이름 --ronda 1 및 python SKILL_DIR/revisar_hoja.py . --ronda 1을 A와 D에 보내기 전에 실행 (비디오에 대해 1라운드).
10. 최종 렌더, 한 번만: node render.mjs --sub 6. 두 렌더를 동시에 실행하지 마십시오.
11. python SKILL_DIR/entregar.py . 이름 --ronda N --escritorio 및 모바일 버전 전달.
12. 라이브러리 기여 (기본 활성화): biblioteca 스킬의 "새 모델 기여" 절차 따름 (nuevos.py → 준비 → 라이브러리에 업로드할까요? (S/n)). 사용자가 이 프로젝트에서 이미 아니오라고 말했다면, 묻지 않음.

역할별 노력 및 모델

전체 테이블은 저장소의 AGENTS.md 참조. 요약 (Claude Code 이름; 다른 하네스에서는 동등한 "빠름/중간/깊음" 사용):

역할	모델	노력
영상 조정 세션	사용 중인 모델	medium
데이터 연구원 및 검수자 B	중간 (Sonnet)	high
공유 3D 모델	중간	medium, 상한 150k
장면 생성자	중간	medium, 상한 40턴 / 120k
검수자 A, C, D	중간	medium (Haiku 같은 작은 모델은 규칙 위반: 사용 금지)
장면의 작은 수정	중간	low
max	절대 사용 금지	너무 느리고 과도한 사고

토큰 및 세션 예산

비용은 턴 수 × 대화 길이이며, 작성하는 내용이 아닙니다. 규칙:

• 비디오당 새 세션 하나. 150k 컨텍스트에서 핸드오프: AVANCE.md (남은 작업, 다음 단계, 결정사항)를 남기고 이를 읽는 새 세션에서 진행.
• 마일스톤에서만 알림: GUION LISTO, VIDEO RÁPIDO LISTO, TERMINADO 또는 막혔을 때. 그 외는 알리지 않고 TIEMPOS.md에 기록.
• 메인 세션에서 스크린샷이나 이미지 사용 금지: 하위 에이전트가 보고 텍스트로 응답.
• 검수자 예산: MAPA에 대한 라운드 0 최대 2라운드; 시트에 대한 라운드 1 1회; 비디오에 대한 라운드 1은 A와 D만. 8.5 미만인 영역에 대해서만 2라운드.

생성자 상한 (각 작업 끝에 그대로 첨부, 공유 모델의 경우 150k):

예산: 최대 40턴 및 120k 컨텍스트 토큰. 둘 중 하나에 도달하면 작업 폴더에 AVANCE.md (무엇이 남았고, 무엇이 필요하며, 무엇을 시도했고 실패했는지)를 작성하고 5줄 요약으로 종료; 다른 에이전트가 이어받습니다. 엔진, 전체 CONTRATO 또는 다른 부분을 읽지 마십시오: 필요한 것은 이 작업에 있습니다. 300줄이 넘는 파일은 절대 전체를 읽지 마십시오: 범위나 grep을 사용하세요. 스크린샷은 node render.mjs --probe <초> --mitad로만, 5턴당 최대 1개. 스크린샷 요청 전에 revisar_hoja.py를 실행하십시오 (토큰 소모 없음). 누구도 기다리지 마십시오: 부족한 것이 있으면 AVANCE.md에 기록하고 종료하십시오.

일반적인 오류 (각 생성자 작업에 그대로 첨부, (자동) = revisar_hoja.py가 감지):

1. 페이드에서 이중 텍스트 (자동): 새 텍스트가 들어오기 전에 이전 텍스트를 완전히 제거 (0.15초 이내) 또는 하드 컷 사용; 같은 영역에 두 개의 텍스트가 동시에 나타나지 않도록 함.
2. 후광 및 아우라 (자동): 부드러운 광채가 있는 구, 원반 또는 조명은 눈이나 태양으로 읽힘. 평면 방사, 방사형 스프라이트 없음; 무언가 빛나야 한다면 길쭉하고 고리 없이.
3. 쌍둥이 (자동): 같은 크기와 밝기의 두 개의 창문, 조명 또는 구가 함께 있으면 눈으로 읽힘. 크기 다르게, 다른 높이, 또는 하나만.
4. 번짐 흰색 (자동, 경고): 블룸과 함께 순수 흰색 사용 금지; 팔레트 색상, 무광택.
5. 얼룩 및 떨어진 점 (자동, 경고): 단독 입자, 텍스트 상자 뒤 그림자, 남은 가장자리.
6. 영역 밖 (자동): y < 215 및 y > 1450 (카라오케) 위치에 아무것도 없음; 어떤 것도 텍스트 상자를 가로지르지 않음.
7. 밝기 점프 (--ronda로 자동): 평균 조도 60-90, 컷 사이 25 이상 점프 없음.
8. 중복: 같은 텍스트가 텍스트 상자와 카라오케에 동시에 나타남; 아이디어당 텍스트 상자 하나.
9. 얼굴 및 손: 사람은 뒷모습 또는 3/4 뒷모습; 손은 옆면 또는 손등으로 들어옴.
10. 작은 텍스트: 모두 >= 42px (텍스트 상자는 >= 52px).

렌더: 시간이 소요되는 부분 (통합 GPU가 있는 4코어 노트북에서 측정)

단계	프레임당
Chrome에서 프레임 가져오기 (JPEG, GPU는 ANGLE)	~0.07초
x264 slow CRF 16 (전달용)	+0.11초
--rapido (Windows/Intel에서 Quick Sync; 기타에서 x264 veryfast; CODEC_RAPIDO로 선택)	+0.02-0.05초
블러 --sub 6	+0.09초

GPU 없음 (--sin-gpu)은 약 40% 느림. 재질에 transmission 사용 금지, 각 부분 프레임당 80ms 미만.

잊으면 한 바퀴 손해 보는 교훈

• update(t)는 t의 순수 함수: 렌더러는 개별 프레임과 서브프레임을 요청함. Math.random (E.azar(시드) 사용) 또는 프레임 간 상태 사용 금지. t < 0 보호.
• ≥ 0.6초의 카메라 움직임은 inOutCubic 사용: --sub 6에서 whip pan이 유령처럼 나타남.
• 테스트에 다른 프레임 조각이 나오면 다른 프로세스가 동시에 렌더링 중인 것임: 다시 실행.
• 렌더 종료 시 "Failed to load resource" 404는 정상; 실제 오류는 pageerror.
• scene.environment 사용 시 three r186은 scene.environmentIntensity를 사용하며, 재질의 envMapIntensity가 아님.
• 라이브러리의 입자 (three.quarks)는 시간에 따라 결정론적: 그룹을 이동하지 말고 pos를 사용.
• 마우스 조정 패널: URL에 ?ajustes=1 (biblioteca/base/LEEME.md 참조); 렌더는 절대 로드하지 않음.
• 실제 재질 (사진, 아카이브 영상): Wikimedia Commons 및 Internet Archive는 퍼블릭 도메인 및 CC BY 제공; 설명에 크레딧을 표기.