Communitygithub.com

ak:hyperframes

HeyGen HyperFrames CLI를 활용한 HTML 기반 프로그래매틱 비디오 생성. 짧은 세로/소셜 비디오, 제품 출시 클립, HTML 구성에서 렌더링된 모션 그래픽에 사용합니다. React 기반 대안으로 설치된 remotion 스킬도 참조하세요.

ak:hyperframes란 무엇인가요?

이 스킬은 HeyGen의 HyperFrames CLI를 래핑하여 HTML 기반의 프로그래매틱 비디오 생성을 지원합니다. 복잡한 React 컴포넌트나 타임라인 편집기 없이 HTML/CSS 마크업만으로 1080×1920 (9:16) 세로 동영상, 제품 출시 클립, 프로모션 루프, 모션 그래픽을 제작할 수 있습니다. Claude Code, Cursor와 같은 AI 에이전트 도구와 함께 사용하여, `data-composition-id`, `data-start`, `data-width`, `data-height` 속성으로 주석이 달린 HTML 파일을 자동 생성하고, `init → edit → preview → lint → render` 워크플로우를 통해 최종 MP4를 렌더링합니다. 로컬 렌더링은 API 키 없이 가능하며, 원격 클라우드 렌더링을 위해 HEYGEN_API_KEY 옵션을 제공합니다. React 기반 컴포지션이나 프레임 정확한 보간이 필요한 경우, 설치된 remotion 스킬을 대안으로 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ngocsangyem/reporeaper/tree/HEAD/.claude/skills/ak-hyperframes

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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를 참조하세요.

참고 자료

문제 해결

증상조치
command not found: ffmpegnode 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 스킬 — 저장소 내 모든 비디오/모션 스킬과 외부 모션 스킬 팩을 라우팅.

관련 스킬