HyperFrames — 여기서 시작하세요
HyperFrames는 HTML로 비디오를 렌더링합니다. composition은 data-* 속성으로 타이밍을 선언하는 HTML 파일이며, 애니메이션 런타임은 탐색 가능하고 미디어 재생은 프레임워크가 관리합니다. 전체 작성 계약은 /hyperframes-core에 있습니다. composition HTML을 작성하기 전에 먼저 읽으세요.
아래는 기능 맵(필요 시 로드되는 도메인 스킬)과 의도 라우터("비디오 만들어 줘" 요청에 대한 워크플로우 선택)입니다.
기능 맵 — 도메인 스킬
필요 시 로드하는 원자적 기능입니다. 전체 비디오 워크플로우가 아닙니다. "비디오 만들어 줘"에는 아래 의도 라우터를 사용하세요.
| 원하는 작업 | 스킬 |
|---|---|
HTML composition 작성/편집 — data-* 계약, 클립, 트랙, 하위 composition, 변수 | /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 개발 루프 — init, lint, validate, inspect, preview, render, publish, doctor | /hyperframes-cli |
레지스트리 블록/컴포넌트 설치 (hyperframes add) | /hyperframes-registry |
의도 라우팅 — 워크플로우 선택
이 섹션은 최상위 워크플로우만 알고 있습니다. 내부 참조나 위의 도메인 스킬은 로드하지 않습니다.
라우팅 전 — 명세가 아닌 입력 확인
라우팅은 비디오의 내용 — 입력과 주제를 알아야 합니다. URL, 제품, 주제, 에셋 없이 "우리 것에 대한 비디오 만들어 줘"처럼 명시되지 않은 경우, 워크플로우에 진입하기 전에 물어보세요. 워크플로우를 선택하는 것이 라우팅 결정입니다. 최대 두 가지 질문:
- 입력 — 제품(URL/브리프), 일반 웹사이트, GitHub PR, 설명할 주제, 또는 기존 토킹헤드 비디오?
명세 기본값 — 묻지 말고 명시 (경로를 바꾸지 않습니다): 종횡비 16:9 (명명된 세로 대상 — TikTok / Reels / Shorts에만 9:16 사용); 내레이션/자막 언어 = 사용자의 언어. 선택된 워크플로우는 첫 번째 단계에서 자체 세부 사항을 다시 확인합니다.
워크플로우 치트시트
| 워크플로우 | 용도 |
|---|---|
/product-launch-video | 제품 마케팅/런칭/프로모션 — URL, 브리프, 또는 스크립트(사이트 이름만 언급돼도) |
/faceless-explainer | 텍스트로 주제/개념 설명 — 제품 없음, URL 없음; 모든 비주얼은 LLM이 생성 |
/pr-to-video | GitHub PR / 코드 변경 → 체인지로그/기능 공개/수정/리팩터 설명 영상 |
/embedded-captions | 기존 토킹헤드 비디오에 자막/서브타이틀 추가 (영상 그대로) |
/talking-head-recut | 기존 토킹헤드 비디오를 디자인된 그래픽 오버레이로 패키징 — 하단 1/3, 데이터 콜아웃, 운동 타이틀, 풀 인용구 |
/motion-graphics | 짧고 내레이션 없는 디자인 중심 모션 그래픽 — 운동 타이포그래피, 통계/차트 히트, 로고 스팅, 하단 1/3 오버레이 |
/music-to-video | 음악 트랙 → 비트 동기화 비디오 — 가사 비디오, 슬라이드쇼, 또는 운동 프로모션; 음악이 페이싱 주도 (선택적 사용자 이미지/비디오가 비트 그리드에 편집) |
/slideshow | 프레젠테이션/피치 덱/대화형 덱 — 개별 슬라이드, 프래그먼트, 분기, 핫스팟; 출력은 탐색 가능한 덱, 렌더링된 비디오 아님 |
/general-video | 그 외 모든 것 — 긴 또는 다중 씬 작품, 정적 루프/포스터, 커스텀 composition, 또는 전문 워크플로우에 맞지 않는 일반 사이트 투어 |
/remotion-to-hyperframes | 기존 Remotion(React) composition을 HyperFrames로 포팅 (마이그레이션, 생성 아님) |
명확화 (혼동 가능한 경우만):
- 모션 우선 & 내레이션 없음 (약 ~10초 미만, 모션 자체가 메시지) →
/motion-graphics, 입력과 무관. - URL 또는 스크립트 — 특정 제품 마케팅(사이트 이름만 언급해도) →
/product-launch-video; 일반 비제품 사이트 →/general-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가 질문.
- 출력: 제품 런칭/SaaS 프로모션 → HyperFrames composition → MP4. (적정 시간 30~90초).
- 트리거: "X 런칭 영상", "우리 사이트 프로모션", "내 SaaS를 1분 안에 설명해줘", "내 스크립트를 60초 프로모션으로", "텍스트 전용 런칭 영상, 스크랩 금지".
/faceless-explainer
- 입력: 임의의 텍스트 — 설명할 주제, 기사, 또는 노트; 마케팅 제품 없고 캡처할 사이트 없음. (
/product-launch-video에서 포크; headless Chrome 없음.) - 출력: 얼굴 없는 설명 영상 → MP4, 모든 비주얼은 씬별로 LLM이 생성 (타이포그래피/추상/다이어그램/데이터 시각화);
pin-and-paper프리셋 포함. (적정 시간 30~90초). - 트리거: "X에 대한 얼굴 없는 설명 영상", "DNS 작동 방식을 영상으로 설명해줘", "이 기사를 설명 영상으로", "내 노트로 설명 영상".
/pr-to-video
- 입력: GitHub 풀 리퀘스트 — PR URL,
owner/repo#N참조, 또는 "이 PR" —ghCLI로 읽음 (스크랩할 사이트 아님). - 출력: 코드 변경 설명 영상 (체인지로그/기능 공개/수정/리팩터) → MP4 — diff 하이라이트, 전후 비교, 파일 트리+영향 씬. (적정 시간 30~90초).
- 트리거: "이 PR에 대한 영상 만들어 줘", "PR #1187을 체인지로그 영상으로", "github.com/org/repo/pull/123에서 릴리스 노트 영상".
/embedded-captions
- 입력: 자막을 추가할 기존 토킹헤드 비디오 (MP4) — 실제 영상, URL이나 브리프 아님. 로컬에서 전사 (Whisper, API 키 없음) 및 매팅 (RVM)되어 주제가 자막을 가릴 수 있음.
- 출력: 동일한 영상 그대로에 자막 레이어 추가 — 표준 (그대로 하단 레일 + 주제 뒤에 내장된 클라이맥스) 또는 시네마틱 (모든 자막이 주제 뒤에 합성). 모든 길이.
- 트리거: "이 비디오에 자막/서브타이틀 추가", "주제 뒤에 자막", "내 클립에 시네마틱 자막".
/talking-head-recut
- 입력: 화면 그래픽으로 패키징할 기존 토킹헤드/인터뷰/팟캐스트 비디오 (MP4) — 실제 영상. 로컬에서 전사 (Whisper). 클립은 그대로 아래에서 전체 재생.
- 출력: 동일한 영상에 전사와 동기화된 시간 기반 그래픽 오버레이 카드 — 운동 타이틀, 하단 1/3, 데이터 콜아웃, 풀 인용구, 측면 패널, 화면 속 화면. 모든 길이.
- 트리거: "이 비디오 패키징", "내 토크에 그래픽 오버레이/하단 1/3/데이터 콜아웃 추가", "이 인터뷰를 그래픽 패키징 편집으로".
/motion-graphics
- 입력: 모션이 메시지인 짧은 디자인 중심 모션 그래픽 — 일반적으로 ~10초 미만, 내레이션 없음. 장르: 운동 타이포그래피, 통계/숫자 카운트업, 차트 히트, 로고 스팅, 하단 1/3/오버레이, 또는 검색 기반 페이지/트윗/헤드라인 샷.
- 출력: 짧은 모션 그래픽 → MP4 또는 투명 오버레이 (알파 WebM/MOV) — 하단 1/3/콜아웃용.
- 트리거: "8초 로고 스팅", "이 통계 애니메이션", "운동 타이포 인트로", "이 트윗을 모션 그래픽으로", "투명 하단 1/3 오버레이".
/music-to-video
- 입력: 음악 트랙 — 오디오 파일, 또는 오디오를 추출할 비디오 — 내레이션 없고 웹사이트 캡처 없음. 선택적으로 사용자가 제공한 이미지/비디오를 포함. 트랙은 전체 비디오의 기반이 되는 결정론적 비트/에너지 맵(
audiomap.json)으로 한 번 분석. - 출력: 비트 동기화 HyperFrames composition → MP4, 음악이 페이싱 주도. 타이포그래피와 템플릿이 바닥 (완전한 비디오는 에셋 제로로 가능); 제공된 미디어는 동일한 비트 그리드에 편집 (비트 컷/켄 번스). 장르 — 가사 비디오, 슬라이드쇼, 운동 프로모션 — 프레임별 선택에서 결정되며 파이프라인이 분기하지 않음.
- 트리거: "이 노래에 대한 비디오 만들어 줘", "이 트랙에서 비트 동기화 비디오", "가사 비디오", "이 음악을 비디오로", "이 비트에 맞는 음악 시각화/운동 프로모션".
/slideshow
- 입력: 작성할 프레젠테이션/피치 덱/대화형 덱 — 브리프, 개요, 또는 슬라이드로 변환할 기존 페이지. 렌더링된 비디오 요청 아님; 의도가 모호하면 작성 전에 "HyperFrames 슬라이드쇼로 원하세요?" 확인.
- 출력: 실행 가능한 HyperFrames composition + 플레이어의
SlideshowController가 읽는 JSON 아일랜드로 프레젠테이션을 탐색 가능한 덱으로 전환 (이전/다음, 스와이프, 발표자 모드, 분기). MP4 아님. - 트리거: "슬라이드쇼 만들어 줘", "이 페이지를 덱으로 변환", "우리 피치를 대화형 프레젠테이션으로", "발표자 노트가 있는 슬라이드".
/general-video
다른 워크플로우에 맞지 않는 모든 것. 일반 사이트 투어, 긴 (~3분+) 멀티 씬 작품, 완전 커스텀 HTML 작성 흐름, 또는 정적 루프/포스터.
- 입력: 위 워크플로우에 맞지 않는 모든 입력.
- 트리거: "사이트 투어", "우리 제품의 전체 워크스루", "커스텀 composition", "루프 포스터".
/remotion-to-hyperframes
기존 Remotion (React) composition을 HyperFrames로 마이그레이션. 새 비디오 생성 아님.
- 입력: Remotion 프로젝트 경로 또는 소스 코드.
- 트리거: "이 Remotion composition을 HyperFrames로 포팅", "React 비디오를 HTML composition으로 변환".
HyperFrames 스킬 맵 (참조용 다이어그램)
flowchart TD
Start["비디오 요청"] --> Route["의도 라우터: 스킬 맵 + 워크플로우 선택"]
Route --> W1["/product-launch-video"]
Route --> W2["/faceless-explainer"]
Route --> W3["/pr-to-video"]
Route --> W4["/embedded-captions"]
Route --> W5["/talking-head-recut"]
Route --> W6["/motion-graphics"]
Route --> W7["/music-to-video"]
Route --> W8["/slideshow"]
Route --> W9["/general-video"]
Route --> W10["/remotion-to-hyperframes"]
subgraph DomainSkills["도메인 스킬 (필요 시 로드)"]
CORE["/hyperframes-core"]
ANIM["/hyperframes-animation"]
CRE["/hyperframes-creative"]
MEDIA["/hyperframes-media"]
MEDIAUSE["/media-use"]
CLI["/hyperframes-cli"]
REG["/hyperframes-registry"]
end
W1 -.-> DomainSkills
W2 -.-> DomainSkills
W3 -.-> DomainSkills
W4 -.-> DomainSkills
W5 -.-> DomainSkills
W6 -.-> DomainSkills
W7 -.-> DomainSkills
W8 -.-> DomainSkills
W9 -.-> DomainSkills
W10 -.-> DomainSkills
주요 워크플로우 진입점:
/product-launch-video,/faceless-explainer,/pr-to-video— 자산 + 통계 수집을 위해 스크래핑 모듈 (headless Chrome) 가능./embedded-captions,/talking-head-recut— Whisper(로컬 전사) + RVM(매팅) 사용./music-to-video—audiomap.json(비트/에너지 맵) 생성에 Librosa/유사 오디오 분석 의존./slideshow— HyperFramesSlideshowController를 읽는 JSON을 출력; MP4 아님.- 모든 워크플로우는 /hyperframes-core의 HTML composition 계약과 애니메이션, 미디어, CLI 도메인 스킬을 필요 시 사용합니다.