HyperFrames — 여기서 시작하세요
HyperFrames는 HTML로 비디오를 렌더링합니다. 컴포지션은 data-* 속성으로 DOM 타이밍을 선언하고, 애니메이션 런타임은 검색 가능하며, 미디어 재생은 프레임워크가 소유하는 HTML 파일입니다. 전체 작성 규약은 /hyperframes-core에 있습니다. 컴포지션 HTML을 작성하기 전에 먼저 읽어보세요.
아래는 기능 맵(온디맨드로 로드되는 도메인 스킬)과 의도 라우터("비디오 만들어 줘" 요청에 대한 워크플로우 선택)입니다.
기능 맵 — 도메인 스킬
다음은 온디맨드로 로드하는 원자적 기능입니다. 전체 비디오 워크플로우가 아닙니다. "비디오 만들어 줘" 요청에는 아래 의도 라우터를 사용하세요.
| 원하는 작업… | 스킬 |
|---|---|
HTML 컴포지션 작성/편집 — data-* 규약, 클립, 트랙, 서브 컴포지션, 변수 | /hyperframes-core |
| 애니메이션 — 원자적 모션, 씬 청사진, 전환, 런타임 어댑터 (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | /hyperframes-animation |
크리에이티브 디렉션 — frame.md / design.md, 팔레트, 타이포그래피, 내레이션, 비트 계획, 오디오 반응형 | /hyperframes-creative |
| 미디어 — TTS 음성 해설, 배경 음악, 자막, 배경 제거, 캡션 | /hyperframes-media |
미디어 리졸브 — HeyGen 카탈로그에서 BGM, SFX, 이미지, 아이콘을 찾아 .media/에 고정하고 매니페스트 추적 | /media-use |
| CLI 개발 루프 — 초기화, 린트, 검증, 검사, 미리보기, 렌더링, 게시, 닥터 | /hyperframes-cli |
레지스트리 블록/컴포넌트 설치 (hyperframes add) | /hyperframes-registry |
의도 라우팅 — 워크플로우 선택
이 섹션은 최상위 워크플로우만 알고 있습니다. 내부 참조나 위의 도메인 스킬은 로드하지 않습니다.
라우팅 전 — 사양이 아닌 입력을 확인하세요
라우팅은 비디오의 대상(입력과 주제)을 알아야 합니다. 입력(URL, 제품, 주제, 또는 에셋) 없이 "우리 제품에 대한 비디오를 만들어 줘"와 같이 지정되지 않은 경우, 워크플로우에 진입하기 전에 물어보세요. 워크플로우를 선택하는 것이 라우팅 결정입니다. 최대 두 가지 질문:
- 입력 — 제품(URL/브리프), 일반 웹사이트, GitHub PR, 설명할 주제, 또는 기존 토킹헤드 비디오?
사양 기본값 — 말하지 말고 적용(경로를 변경하지 않음): 가로 16:9 (명시적인 세로 목적지(TikTok / Reels / Shorts)인 경우에만 9:16 사용); 내레이션/캡션 언어 = 사용자의 언어. 선택된 워크플로우는 첫 단계에서 자체 세부 사항을 다시 확인합니다.
워크플로우 치트 시트
| 워크플로우 | 용도 |
|---|---|
/product-launch-video | 제품 판매(SaaS, 앱, 회사/제품 사이트) — URL, 브리프, 또는 스크립트에서 → 프로모션. 상업적 URL의 기본값이며, 사이트 이름만 언급된 경우에도 마찬가지입니다. |
/website-to-video | 사이트 자체를 보여주는 경우 — 사이트 스크린샷을 기반으로 한 투어/쇼케이스. 비상업적 사이트(포트폴리오, 블로그, 문서, 개인, 이벤트) 또는 사용자가 프로모션이 아닌 투어를 원할 때 사용합니다. |
/faceless-explainer | 텍스트로 주제/개념 설명 — 제품이나 URL 없음; 모든 시각 자료는 LLM이 생성합니다. |
/pr-to-video | GitHub PR / 코드 변경 → 체인지로그/기능 공개/수정/리팩터 설명 비디오 |
/embedded-captions | 기존 토킹헤드 비디오에 캡션/자막 추가(푸티지 수정 없음) |
/talking-head-recut | 기존 토킹헤드 비디오를 디자인된 그래픽 오버레이(로우더 서드, 데이터 콜아웃, 키네틱 타이틀, 풀 인용구)로 패키징 |
/motion-graphics | 짧고, 내레이션이 없으며, 디자인 중심의 모션 그래픽 — 키네틱 타이프, 통계/차트 하이라이트, 로고 스팅, 로우더 서드 오버레이 |
/music-to-video | 음악 트랙 → 비트 동기화 비디오 — 가사 비디오, 슬라이드쇼, 또는 키네틱 프로모션; 음악이 페이싱을 주도합니다(선택적 사용자 이미지/비디오가 비트 그리드에 맞춰짐) |
/slideshow | 프레젠테이션 / 피치 덱 / 인터랙티브 덱 — 개별 슬라이드, 조각, 분기, 핫스팟; 출력은 탐색 가능한 덱이며, 렌더링된 비디오가 아닙니다. |
/general-video | 기타 모든 것 — 더 길거나 여러 씬의 작품, 정적 루프/포스터, 커스텀 컴포지션 |
/remotion-to-hyperframes | 기존 Remotion(React) 컴포지션을 HyperFrames로 포팅(생성이 아닌 마이그레이션) |
혼동 가능한 경우 명확화:
- 모션 우선 및 내레이션 없음(약 10초 미만, 모션 자체가 메시지임) → 입력에 관계없이
/motion-graphics. - URL 또는 스크립트 — 한 가지 질문: 사이트가 제품을 판매하는가? 예(SaaS / 앱 / 제품 / 회사 사이트) →
/product-launch-video— 프로모션이며, 상업적 URL의 기본값(사이트 이름만 언급된 경우에도 마찬가지). 아니요, 또는 사용자가 사이트를 그대로 보여주길 원하는 경우(포트폴리오 / 블로그 / 문서 / 개인 / 이벤트) →/website-to-video— 투어. GitHub PR 링크 →/pr-to-video; 제품이나 사이트가 없는 개념 →/faceless-explainer. - 기존 푸티지 — 일반 음성 자막 →
/embedded-captions; 디자인된 오버레이 카드 →/talking-head-recut. 둘 다 푸티지 자체를 편집하지 않습니다(재타이밍/재색상/재구성/재정렬/오디오는 NLE 편집 — 범위 외). - 입력이 음악 트랙인 경우(오디오 파일 또는 오디오를 추출할 비디오) 내레이션 없음 →
/music-to-video— 음악의 비트/에너지가 페이싱을 주도합니다. (내레이션이 있는 작품은 위의 입력 매칭 워크플로우를 유지합니다./motion-graphics는 음악 주도가 아닌 짧은 내레이션 없는 모션용입니다.) - 프레젠테이션 / 피치 덱 / 인터랙티브 덱(개별 슬라이드, 탐색, 발표자 모드) →
/slideshow— 출력은 탐색 가능한 덱이며, 렌더링된 비디오가 아닙니다. 명시적인 "슬라이드쇼" 요청은 직접 진행합니다. 인접 트리거("덱 / 슬라이드 / 프레젠테이션 / 이 페이지 변환")는 작성 전에/slideshow가 슬라이드쇼인지 확인하고, 그렇지 않은 경우 적절한 비슬라이드쇼 워크플로우로 전환합니다. - 길이는 지침이지 제한이 아님 — 의도가 워크플로우를 선택합니다. 작품이 분명히 약 3분을 초과하거나, 정적/루프/커스텀 형식인 경우에만
/general-video로 이동합니다.
매칭된 워크플로우가 설치되지 않은 경우
워크플로우를 선택했으면, 사용 가능한지 확인하세요. 매칭된 워크플로우 스킬이 설치되지 않은 경우, 추측으로 대체하지 말고 사용자에게 먼저 설치하라고 알리세요:
- 이 워크플로우만:
npx skills add heygen-com/hyperframes --skill <워크플로우-이름>(예:--skill pr-to-video— 앞에/없이 이름만). - 모든 워크플로우 한 번에:
npx skills add heygen-com/hyperframes --all(코어 + 모든 워크플로우, 선택기 건너뜀).
실행 후, 워크플로우의 스킬을 다시 읽고 계속하세요.
스킬 최신 상태 유지
HyperFrames 스킬은 버전 관리됩니다. npx hyperframes init는 설치된 스킬을 GitHub의 최신 버전과 비교하여, 최신 버전이 아니거나 누락된 경우 전체 세트를 설치/새로고침합니다. 따라서 새로 init된 프로젝트는 항상 완전한 최신 세트를 갖습니다(최신 프로젝트에서 init를 다시 실행하면 아무 작업도 수행하지 않음). 확인은 빠른 GitHub 왕복입니다. 오프라인(또는 속도 제한) 상태에서는 짧은 타임아웃 후 설치로 폴백되므로, init는 네트워크 문제로 인해 절대 하드 실패하지 않습니다. 생성 워크플로우는 init로 스캐폴딩되므로, 새 프로젝트를 시작할 때 항상 이 확인을 실행하고, 스킬이 최신이 아니면 GitHub에서 최신 스킬을 가져옵니다. --skip-skills 플래그는 현재 중단되었습니다(skills.sh 레지스트리가 따라잡는 동안 임시 조치): 전달해도 확인을 건너뛰지 않으므로 모든 init가 GitHub를 확인합니다. CI/테스트는 HYPERFRAMES_SKIP_SKILLS=1 환경 변수를 통해 옵트아웃합니다.
작업이 예상치 못하게 동작하거나, 긴 빌드 전에 설치된 스킬이 최신인지 확인하세요:
- 확인:
npx hyperframes skills check(--json을 추가하면 기계가 읽을 수 있는 결과 제공; 최신 버전이 아니거나 누락된 경우 0이 아닌 값 반환). - 업데이트:
npx hyperframes skills update— 전체 세트를 최신 버전으로 가져오고, 아직 설치되지 않은 스킬을 설치합니다(init의 설치 단계와 동일).
CLI는 render / lint / validate 실행이 오래된 스킬을 감지하면 한 줄 알림을 표시합니다.
워크플로우 세부 사항
/product-launch-video
- 입력: 마케팅되는 제품 — (a) 제품 URL( headless Chrome으로 크롤링하여 에셋 + 브랜드 토큰 획득), (b) 제품 사이트를 언급하는 스크립트/브리프(링크가 없어도 PLV가 해석 + 크롤링, 사용자가 거부하지 않는 한), 또는 (c) 사이트를 유추할 수 없거나 "스크래핑하지 마세요"인 스크립트(캡처 금지 모드 — 팔레트 + 디자인 시스템을 제공하는 스타일 프리셋 선택). 제공된 스크립트는 그대로의 음성 해설 또는 씬별로 재구성될 수 있습니다 — PLV가 질문합니다.
- 출력: HyperFrames 컴포지션으로서의 제품 런칭 / SaaS 프로모션 → MP4 (최적 시간 30–90초) — 제품의 가치가 주제이며, 사이트 둘러보기가 아닙니다. 사이트의 일반 투어는
/website-to-video를 사용하세요. - 트리거: "X에 대한 런칭 비디오", "우리 사이트 프로모션", "내 SaaS를 1분 안에 설명해 줘", "내 스크립트를 60초 프로모션으로 만들어 줘", "텍스트 전용 런칭 비디오, 스크래핑하지 마".
/website-to-video
- 입력: 사이트 자체를 보여주는 것이 목적인 웹사이트/URL, 제품 판매가 아님. 비상업적 사이트(포트폴리오, 블로그, 문서, 개인, 이벤트)에 적합하며, 사용자가 사이트를 그대로 투어하길 원할 때 사용합니다. 실제 스크린샷 + 브랜드를 위해 headless Chrome으로