HyperFrames 중국어 영상 실전
HTML 안에서 영상을 작성하고, 엔진이 프레임별로 MP4로 렌더링합니다. 이 스킬은 2026년 10월에 제작된 6.5분 분량의 완성된 중국어 과학 영상(실제 데이터, 더빙, 스크린샷 포함)의 실전 경험을 집약한 것으로, 특히 공식 문서에는 없고 직접 부딪혀서만 알 수 있는 함정에 초점을 맞춥니다.
전체 워크플로우(5단계)
- 초기화:
npx hyperframes init <dir>→ Node22+, FFmpeg 사전 설치 필수; 로컬 환경에서는HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome설정 필요(엔진이 자동으로 chrome-headless-shell을 다운로드하려 하지만 네트워크 문제로 실패할 수 있음, pitfalls#1 참고) - 구조 및 콘텐츠: 메인
index.html이 장면 sub-composition을 연결합니다. 콘텐츠 자료(실제 데이터/스크린샷)는 먼저scripts/sources.md에 정리한 후 화면에 배치하세요. 정보 밀도가 강의 영상의 생명입니다. - 애니메이션: 각 장면마다 일시 정지된 GSAP 타임라인 사용; 문장별 자막 시스템 + 리듬 강조(
references/scene-recipe.md참고) - 검증:
npx hyperframes check가 모두 통과되어야 렌더링이 가능합니다. 수정 방법은references/pitfalls.md를 참고하세요(90%의 오류는 이 매뉴얼에 해결책이 있습니다). - 더빙(선택 사항): edge-tts로 생성 → 측정된 실제 런타임에 맞게 속도 조정 → 오디오는 반드시 메인 index의 root 내부에 연결(sub-composition에서는 작동하지 않음, pitfalls#6 참고) → 재렌더링
- 품질 검사 및 납품: 렌더링 후
npx hyperframes snapshot으로 주요 프레임을 하나씩 확인합니다(시각적 자체 검증 루프: 렌더링 → 프레임 확인 → 개선 → 재렌더링); 표지 이미지는 snapshot 결과물을 그대로 사용하며 별도 도구를 열지 않습니다.
주요 명령어: 미리보기는 --background 사용(핫 리로드 가능); 365초@1080p 렌더링에 약 9-10분 소요(5 worker 스크린샷 모드, GPU 미사용 환경).
언제 어떤 참고 문서를 읽을까요?
- 오류/렌더링 이상 발생 → 먼저
references/pitfalls.md확인(증상별로 검색, 카메라 transform 체인이라는 미해결 엔진 버그에 대한 결론 포함) - 새 장면 작성 →
references/scene-recipe.md(문장별 자바스크립트 템플릿, 주석 애니메이션 패턴 포함) - 더빙 추가 →
references/voice-pipeline.md - 참고 영상(틱톡 등) 분석 → pitfalls.md 마지막 절 "참고 영상 정량 분해"
- 기성 애니메이션 블록/동일 분야 스킬/더빙 업그레이드/지앤잉 연동 등 외부 도구 찾기 →
references/ecosystem.md(오픈소스 생태계 목록. 공식 capture --video 1:1 복제 포함)
내장 스크립트
scripts/inject_subtitles.py— 문장별 자막 일괄 주입(HTML/CSS/JS를 한 번에 처리, 수동 오류 방지)scripts/gen_voice.py— edge-tts 일괄 생성 + 장면 런타임에 맞춰 자동 속도 조정(uv run실행)scripts/frame_audit.py— 렌더링 프레임 중심 감사(프레임 오프셋/빈 프레임 자동 감지, 샷 문제 해결 필수)
세 가지 불문율
- 장면 파일 수정 전에 반드시 grep: Studio가 요소에
data-hf-id를 삽입하므로, 문자열 교체는 조용히 실패합니다(pitfalls#2) - 대규모 캔버스 카메라 방식 사용 금지: 엔진 렌더링 파이프라인이 연속적인 transform 체인에서 정렬 오류를 일으키며, 여러 대안 검증 결과 해결 불가능(pitfalls#8). 애니메이션은 요소 단위로만 합니다.
- 서사 타임라인 우선: 자막 시간 + 더빙 길이가 모든 애니메이션 리듬을 결정합니다. 타임라인을 먼저 확정한 후 애니메이션을 만들면 재작업 비용이 가장 낮습니다.