오픈소스

HyperFrames 쓰는 법

HeyGen 오픈소스 HyperFrames는 HTML·CSS·미디어로 영상을 정의하고 deterministic MP4로 렌더하는 CLI·에이전트 스킬 툴이다. Node 22+·FFmpeg 설치부터 skills/init·preview·render·doctor까지 공식 문서 기준으로 따라가는 검색형 가이드다.

jaykim

• 7 min read
Share
HyperFrames 쓰는 법

HeyGen이 공개한 오픈소스 HyperFrames는 HTML·CSS·미디어로 영상을 정의하고, 같은 입력에서 같은 MP4가 나오도록 렌더하는 프레임워크다. Remotion처럼 헤드리스 Chrome + FFmpeg를 쓰지만, 작성 모델은 React가 아니라 일반 HTML이라 사람·에이전트 둘 다 다루기 쉽다.

이 글은 “HyperFrames 쓰는 법”만 따라간다. 설치 → 스킬(또는 CLI) → preview → render → doctor까지, 공식 README·docs·npm 기준으로만 적는다.

핵심 요약 (TL;DR)

HyperFrames 쓰는 법 가이드 표지
HyperFrames 쓰는 법 가이드 표지.
  • 무엇인가: HTML 컴포지션 → deterministic MP4. CLI·에이전트 스킬·로컬/클라우드 렌더 경로가 있다.
  • 요구사항: Node.js >=22, FFmpeg. (npm·README 공통)
  • 설치: npx hyperframes <cmd> 또는 npm install -g hyperframes
  • 에이전트: 사람용 픽커는 npx skills add heygen-com/hyperframes. 에이전트·비대화형은 npx hyperframes skills update로 코어 세트.
  • 수동 루프: init → preview → render. 환경 점검은 doctor.
  • 버전(작성 시점): npm latest 0.8.44, 라이선스 Apache-2.0.

할 수 있는 일

HyperFrames GitHub 소셜 프리뷰
HyperFrames GitHub 소셜 프리뷰. 출처: GitHub

먼저 용어만 짧게 풀어 둔다.

  • 코딩 에이전트: Cursor, Claude Code, Codex, Gemini CLI처럼 터미널·에디터 안에서 코드를 쓰고 명령을 실행하는 AI 조수.
  • 스킬(agentskills): 에이전트가 읽는 짧은 지침 묶음. HyperFrames는 /hyperframes 라우터와 도메인 스킬을 제공해 “영상 만들어줘” 요청을 올바른 워크플로로 보낸다.
  • 하네스: 에이전트가 도구·스킬·CLI를 붙잡고 작업을 돌리는 실행 틀.
  • Deterministic render: 같은 HTML·미디어·설정이면 프레임 단위로 같은 영상이 나오게 설계된 렌더. CI·회귀 테스트·자동 파이프라인에 맞춘다.
HyperFrames 공식 쇼케이스 포스터 프레임
공식 Showcase 포스터 프레임(journey-introduction). 출처: hyperframes.heygen.com / HeyGen static CDN

공식 README·Showcase가 예시로 드는 산출물이다.

  • 제품 런치·기능 소개 영상
  • GitHub PR을 changelog·피처 리빌 영상으로
  • 데이터 시각화·차트·맵 애니메이션
  • 캡션·오버레이·음악이 들어간 숏폼
  • 문서·PDF·사이트 투어 설명 영상
  • 자동 콘텐츠 파이프라인용 모션 그래픽
HyperFrames 소개 문서 OG
공식 문서 «What is HyperFrames?» OG. 출처: hyperframes.heygen.com

필요한 것

항목공식 근거메모
Node.jsnpm engines / README>=22
FFmpegnpm README / CLI doctor렌더·인코딩에 필요. doctor가 버전을 보여 준다
Chrome/ChromiumCLI browser / doctor시스템 Chrome 또는 CLI가 받는 번들. npx hyperframes browser ensure
패키지npm hyperframes작성 시점 latest 0.8.44
라이선스README / LICENSEApache-2.0
선택: DockerCLI render --docker환경 차이를 줄인 deterministic 렌더용
선택: 코딩 에이전트README Skills스킬을 쓰면 HTML을 에이전트가 작성

로컬 렌더는 HeyGen 크레딧을 쓰지 않는다고 Quickstart가 명시한다. 호스팅 TTS·아바타·클라우드 렌더 같은 부가 서비스는 각자 과금이 있을 수 있다.

단계 A — 코딩 에이전트 + 스킬

HyperFrames Quickstart 문서 OG
공식 Quickstart OG. 출처: hyperframes.heygen.com/quickstart

사람이 대화형으로 설치할 때 (픽커에서 Core Skills 선택):

npx skills add heygen-com/hyperframes

일부 가이드는 레지스트리 지연을 줄이려고 --full-depth를 붙인다. README 기본 예시는 위 한 줄이다.

에이전트·CI·비대화형은 픽커 대신 코어 세트만 맞춘다.

npx hyperframes skills update

설치 후 에이전트 세션을 새로 열고 /hyperframes로 시작하는 게 README 권장이다. Quickstart가 추천하는 짧은 프롬프트 예:

Using /hyperframes, make a 10-second product intro for https://example.com.

URL만 실제 제품 페이지로 바꾸면 된다. 에이전트가 프로젝트 폴더를 만들고 preview까지 열어 주는 흐름이다.

상태만 보려면:

npx hyperframes skills check
npx hyperframes skills check --json

단계 B — CLI만으로 init → preview → render

HyperFrames CLI 문서 OG
공식 CLI 패키지 문서 OG. 출처: hyperframes.heygen.com/packages/cli
  1. 프로젝트 스캐폴드
npx hyperframes init my-video
cd my-video

에이전트·CI에서는 --non-interactive를 붙인다. 해상도 프리셋은 --resolution landscape|portrait|square 등(문서에 1080p/4k 별칭 포함).

  1. 브라우저 미리보기 (기본 포트 3002)
npx hyperframes preview
# 포트 바꾸기
npx hyperframes preview --port 4567

대화형 터미널에서는 Ctrl+C까지 붙고, 코딩 에이전트처럼 비대화형이면 managed background preview로 남는다고 npm README에 있다. --status / --stop / --list / --kill-all, 기계 판독은 --json.

  1. MP4 렌더
npx hyperframes render -o output.mp4
# 다른 컴포지션 파일
npx hyperframes render -c ./my-composition.html -o output.mp4
# 환경 고정이 필요하면
npx hyperframes render --docker -o output.mp4

자주 쓰는 플래그(CLI 문서 기준): --format mp4|webm|mov|gif|png-sequence, --fps, --quality draft|looks|delivery|…, --gpu, --json(배치 등).

  1. 환경 점검
npx hyperframes doctor
npx hyperframes doctor --json
npx hyperframes info
npx hyperframes browser ensure

doctor는 Node·FFmpeg·Chrome·(있으면) Docker 등을 본다. JSON 모드는 명령 자체 exit 0이고, 환경 OK 여부는 페이로드의 ok 필드로 게이트하라고 문서가 적는다.

  1. 작성 중 검증 (선택)
npx hyperframes lint ./my-video
npx hyperframes check ./my-video
npx hyperframes lint ./my-video --json

막히는 지점

증상문서 근거대응
Node 버전이 22 미만npm enginesNode 22+로 올린 뒤 다시 실행
FFmpeg / Chrome 없음doctornpx hyperframes doctor → FFmpeg 설치, browser ensure
스킬 픽커가 비대화형에서 전부 설치됨README Skills에이전트는 npx hyperframes skills update (코어만)
skills.sh 레지스트리가 main보다 오래됨READMEnpx hyperframes skills update로 GitHub main 기준 갱신
skills add 중 Git LFS post-checkout 오류CLI skills 절hyperframes skills 경로 사용. 업스트림 직접 호출 시 GIT_CLONE_PROTECTION_ACTIVE=0
preview가 에이전트 세션에서 바로 죽음npm previewmanaged 모드/--background; --status --json으로 URL 확인
렌더 타임아웃·미디어 미준비CLI render타임아웃 플래그·env 상향, --best-effort 동작 이해, lint/check 먼저
머신마다 픽셀이 미묘하게 다름README Why / render --docker로컬은 참고용, 고정 출력은 --docker 또는 동일 환경
CLI가 최신인지 모름upgradenpx hyperframes upgrade --check --json

버전 확인

# npm에 올라온 latest
npm view hyperframes version

# 로컬/ npx 복사본
npx hyperframes info
npx hyperframes upgrade --check --json

이 글을 쓰는 시점(2026-09-17, Asia/Seoul)에 확인한 값: npm [email protected], license Apache-2.0, engines.node >=22. 숫자·플래그는 설치본 --help와 공식 문서가 최종 권위다.

마치며

HyperFrames 쓰는 법은 두 갈래로 보면 된다. 에이전트면 스킬을 심고 /hyperframes로 짧게 지시하고, CLI만 쓰면 init → preview → render다. 막히면 doctor와 skills check부터. HTML이 타임라인인 deterministic 렌더라서, 검색으로 “설치·첫 MP4”만 필요한 사람에게는 이 루프면 충분하다.

더 볼 곳: Quickstart, CLI 레퍼런스, heygen-com/hyperframes.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.