ak:hyperframes은(는) 무엇을 하나요?
HeyGen의 hyperframes CLI를 래핑하여
HTML 기반의 프로그래매틱 비디오를 생성합니다. 이 스킬은 문서와 래핑만 제공합니다.
HeyGen 소스 코드나 HeyGen 에이전트 스킬을 포함하지 않습니다.
아래 모든 명령어는 npx를 통해 게시된 npm 패키지를 실행하며, 알려진 안정 버전에 고정됩니다.
사용 시기
- HTML/CSS로 렌더링된 짧은 세로/소셜 비디오 (1080×1920, 9:16).
- React 컴포넌트나 타임라인 편집기 대신 HTML 구성(composition)으로 작성된 제품 출시 클립, 프로모션 루프, 모션 그래픽.
data-composition-id/data-start타이밍 속성(참조: references/composition-basics.md)이 있는 HTML 마크업이 구성의 진실 공급원(source of truth)인 모든 작업.
React 기반 컴포지션, 프레임 정확한 보간 곡선, 또는 Remotion의 오디오/자막 생태계에는 적합하지 않습니다. 해당 대안(React 기반 프로그래매틱 비디오)으로 설치된 remotion 스킬을 참조하세요. 순수 FFmpeg/ImageMagick 인코딩 전용 작업에도 적합하지 않습니다. 해당 대안으로 ak-media-processing 스킬을 참조하세요.
사전 조건
- Node.js 22+
- FFmpeg이
PATH에 있어야 함 - 선택 사항: 원격 렌더링을 위한 HeyGen 클라우드/람다 API 키 (
HEYGEN_API_KEY); 로컬 렌더링은 키 없이 가능.
렌더링 작업을 시작하기 전에 번들된 검증기를 실행하세요:
node scripts/verify-prereqs.mjs
# 또는, 기계가 읽을 수 있는 출력:
node scripts/verify-prereqs.mjs --json
플랫폼별 설치 지침 및 고정 버전 확인 참고 사항은 references/env-and-deps.md를 참조하세요.
고정 CLI 버전
아래 모든 호출은 [email protected]에 고정됩니다 — 2026-08-07 기준 최신 게시 버전(npm view hyperframes version). 업그레이드 시 이 고정 값을 한 곳(이 파일 + references/render-workflow.md)에서 변경하세요; 스크립트나 문서에서 고정되지 않은 npx -y hyperframes ...를 실행하지 마세요.
워크플로우
표준 루프는 init → HTML 편집 → 미리보기 → lint → 렌더링입니다. 각 단계의 전체 구체적인 호출 방법은 references/render-workflow.md에 있습니다. 간단한 형태:
# 1. 새 컴포지션 프로젝트 생성.
npx -y [email protected] init my-composition --resolution portrait
# 2. 생성된 HTML 컴포지션 편집 (data-composition-id / data-start / data-width / data-height 계약은 composition-basics.md 참조).
# 3. 로컬 개발 서버에서 미리보기.
npx -y [email protected] preview my-composition
# 4. 렌더링 전 컴포지션 lint (잘못된 타이밍 속성 감지).
npx -y [email protected] lint my-composition
# 5. MP4로 렌더링.
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
render 전에 항상 lint를 실행하세요 — lint를 통과한 컴포지션은 렌더링 단계에서 훨씬 덜 실패합니다.
컴포지션 계약
HyperFrames 컴포지션은 루트 요소에 data-composition-id, data-start, data-width, data-height 속성이 주석으로 추가된 일반 HTML 파일입니다. 전체 속성 참조 및 완전한 세로 1080×1920 예제는 references/composition-basics.md를 참조하세요.
참고 자료
- references/heygen-skills.md — 이 래퍼가 재구현 대신 위임하는 25개의 HeyGen 에이전트 스킬; 더 깊은 HyperFrames 특화 전문성(애니메이션, 키프레임, 캡션, 제품 출시 템플릿 등)이 필요할 때
npx -y [email protected] skills를 통해 설치하세요. - references/composition-basics.md — 전체 세로 프리셋 예제가 포함된 HTML 컴포지션 속성 계약.
- references/render-workflow.md — 모든 고정 호출이 포함된
init → 편집 → 미리보기 → lint → 렌더링전체 흐름. - references/env-and-deps.md — 플랫폼별 Node/FFmpeg/API 키 설정.
문제 해결
| 증상 | 조치 |
|---|---|
command not found: ffmpeg | node scripts/verify-prereqs.mjs를 실행하여 플랫폼에 맞는 정확한 해결 방법 확인. |
npx hyperframes가 알 수 없는 플래그 출력 | 이 파일의 고정 버전이 업스트림보다 뒤쳐졌을 수 있음; 핀을 업데이트하기 전에 npx -y [email protected] --help로 현재 플래그 확인. |
render가 비어 있거나 짧은 MP4로 실패 | 먼저 lint 실행; 대부분의 렌더링 실패는 lint에서 잡히는 잘못된 data-start/data-composition-id 속성 때문. |
| 원격/클라우드 렌더링 필요 | HEYGEN_API_KEY를 references/env-and-deps.md에 따라 설정하고 hyperframes cloud render 사용 (별도의 최상위 명령어, render 플래그 아님) — references/render-workflow.md 참조. |
같이 보기
- 설치된 remotion 스킬 (
ak-remotion) — React 기반 프로그래매틱 비디오 생성; 컴포지션이 HTML 마크업보다 React 컴포넌트 트리인 경우 사용. - ak-html-video 스킬 — 자체 템플릿/스튜디오 워크플로우가 있는 별도의 HTML-to-MP4 래퍼 (
nexu-io/html-video); 작업이 HeyGen HyperFrames 컴포지션인 경우 ak-hyperframes를 구체적으로 사용. - ak-motion-graphics 스킬 — 저장소 내 모든 비디오/모션 스킬과 외부 모션 스킬 팩을 라우팅.