HyperFrames은(는) 무엇을 하나요?
개요
HyperFrames는 HeyGen에서 제공하는 오픈소스(Apache-2.0) 프레임워크로, HTML, CSS, 미디어 및 애니메이션을 결정론적 MP4 비디오로 변환합니다. 동일한 입력은 항상 동일한 출력을 생성합니다. 이 도구는 data-* 타이밍 속성으로 주석이 달린 HTML 구성을 파싱하고, 헤드리스 Chrome을 구동하여 각 프레임을 탐색 및 캡처한 후 FFmpeg로 인코딩합니다. 빌드 단계가 없고 React가 필요하지 않으며 렌더링당 비용이 없습니다. 에이전트 친화적으로 설계되어 CLI가 기본적으로 비대화형이므로 자동화된 콘텐츠 파이프라인에 깔끔하게 통합됩니다.
GSAP, CSS, Lottie, Three.js, Anime.js 또는 Web Animations API로 구동되는 애니메이션을 포함하여 프로젝트 스캐폴딩, HTML 구성 작성, 실시간 리로드로 미리보기, 프레임 정확한 비디오 렌더링에 이 스킬을 사용하세요.
지침
사전 요구 사항
시작하기 전에 환경을 확인하세요:
- Node.js 22+ (
node --version) - PATH에 FFmpeg (
ffmpeg -version) - 헤드리스 Chrome/Chromium은 처음 실행 시 엔진에 의해 다운로드됩니다.
프로젝트 스캐폴딩
npx hyperframes init my-video # 프로젝트 스캐폴딩 (index.html + package.json 생성)
cd my-video
기존 AI 에이전트 워크스페이스 내에서 에이전트가 관리하는 설정을 위해, 스킬은 npx skills add heygen-com/hyperframes로 설치할 수 있습니다.
구성 작성하기
구성은 일반 index.html 파일입니다. 루트 스테이지 요소는 캔버스와 컴포지션 ID를 선언하고, 하위 요소는 data-* 속성을 통해 나타나는 시점과 지속 시간을 선언합니다. 시간 값은 초 단위입니다.
| 속성 | 목적 |
|---|---|
data-composition-id | 컴포지션 이름 지정 (렌더/검사 대상) |
data-start | 요소가 타임라인에 진입하는 시점 (초) |
data-duration | 요소가 타임라인에 머무는 시간 (초) |
data-width / data-height | 캔버스 크기 (픽셀, 스테이지 요소에 설정) |
data-track-index | 오디오 또는 비디오 적층을 위한 레이어/트랙 순서 |
data-volume | 오디오 레벨, 0.0–1.0 |
미리보기 및 렌더링
npx hyperframes preview # 작성 중 실시간 리로드로 브라우저 미리보기
npx hyperframes render # 헤드리스 Chrome에서 모든 프레임 탐색, FFmpeg로 MP4 인코딩
npx hyperframes lint # 렌더링 전에 구성 구조 검증
npx hyperframes inspect # 컴포지션 메타데이터 출력 (지속 시간, 트랙, 크기)
해상도는 스테이지의 data-width/data-height에서 가져옵니다. 프레임 속도, 출력 경로 및 코덱은 렌더링 매개변수입니다(설치된 버전의 정확한 플래그는 npx hyperframes render --help를 확인하세요. 플래그 이름은 변경될 수 있습니다). 출력이 결정론적이므로 변경되지 않은 입력을 다시 렌더링하는 것은 캐싱해도 안전합니다.
컴포넌트 카탈로그 사용하기
사전 제작된 블록(전환, 오버레이, 자막, 애니메이션 차트, 지도, 효과)을 프로젝트에 설치합니다:
npx hyperframes add flash-through-white # 전환 효과
npx hyperframes add data-chart # 애니메이션 차트 블록
npx hyperframes add instagram-follow # 소셜 오버레이
전체 카탈로그는 hyperframes.heygen.com/catalog에서 확인한 후, 블록 이름으로 add하세요.
애니메이션
엔진이 실시간으로 녹화하는 대신 각 타임라인 위치를 결정론적으로 탐색하기 때문에 탐색 가능하고 프레임 정확한 모든 애니메이션이 작동합니다. 지원되는 어댑터: GSAP, CSS 애니메이션, Lottie, Three.js, Anime.js, WAAPI 및 사용자 정의 프레임 어댑터. 시간 기반 무작위성이나 Date.now()/벽시계 기반 모션은 피하세요. 애니메이션 진행률을 컴포지션 타임라인에 바인딩하여 탐색이 재현 가능하도록 하세요.
에이전트 / CI 파이프라인
CLI는 비대화형이므로 일반적인 자동화 흐름은: HTML 생성/템플릿 작성 → hyperframes lint → hyperframes render → MP4 수집입니다. 대규모 작업을 위해 @hyperframes/aws-lambda 패키지를 사용하면 Lambda에서 분산 렌더링이 가능합니다.
예제
예제 1: 제품 런칭 컴포지션 렌더링
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Launch day</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # 확인: launch, 6초, 1920x1080
npx hyperframes lint # 렌더링 시간 투자 전에 검증
npx hyperframes render # 1080p MP4 생성
예제 2: 탐색 가능한 GSAP 타이틀 애니메이션
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Q3 Results</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 진행률을 타임라인에 바인딩 (일시 정지된 트윈을 엔진이 탐색), 실시간 아님.
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // 엔진이 프레임당 호출
</script>
</div>
npx hyperframes preview # 실시간으로 반복 작업 후:
npx hyperframes render
가이드라인
- 결정론 우선. 모든 모션을 컴포지션 타임라인에 바인딩하세요.
Math.random(),Date.now(), 실시간 루프 또는 렌더링 중 네트워크 호출은 피하세요. 재현성을 깨뜨립니다. - 렌더링 전에 린트하세요.
hyperframes lint는 구조적/타이밍 오류를 저렴하게 잡아냅니다. 렌더링이 비용이 많이 드는 단계입니다. - 스테이지에 캔버스를 설정하세요.
data-width/data-height는 루트 컴포지션 요소에 있습니다. 하위 요소의 타이밍(data-start/data-duration)은 각 요소에 초 단위로 설정합니다. - 도구 체인을 확인하세요. 대부분의 실패는 FFmpeg 누락, Node < 22, 또는 방화벽에 막힌 Chromium 다운로드에서 비롯됩니다.
- 정확한 플래그는
--help를 사용하세요.render/add옵션은 버전에 따라 다릅니다. 설치된 CLI에 대해 fps/출력/코덱 플래그를 확인하고 가정하지 마세요. - 카탈로그 블록을 선호하세요.
hyperframes add는 수동으로 전환과 차트를 만드는 대신 유지 관리되는 탐색 가능한 컴포넌트를 가져옵니다. - Lambda로 확장하세요. 배치/대규모 작업의 경우 긴 로컬 작업 대신
@hyperframes/aws-lambda를 통해 렌더링하세요. - 미디어를 로컬에 유지하고 커밋하세요. 자산은 안정적인 경로로 참조하세요. 렌더링 중 원격 가져오기는 결정론과 재현성을 훼손합니다.