HeyGen HyperFrames 분석: HTML로 영상 만드는 AI 에이전트 전용 오픈소스 프레임워크
HeyGen HyperFrames 분석: HTML로 영상 만드는 AI 에이전트 전용 오픈소스 프레임워크
비유: 그동안 영상은 "타임라인 위에 클립을 드래그하는 편집 프로그램"이었습니다. HyperFrames는 "영상도 하나의 웹페이지"라고 다시 정의합니다. 그리고 그 웹페이지를 사람 대신 AI 에이전트가 쓰도록 설계했습니다.
AI 에이전트가 코드를 작성하고, 블로그를 쓰고, 이미지를 생성하는 시대입니다. 그런데 영상만큼은 여전히 사람이 편집 소프트웨어를 열어서 클립을 자르고 이어 붙여야 했습니다. HeyGen이 2026년 공개한 오픈소스(Apache 2.0) 프레임워크 HyperFrames는 이 단절을 해결합니다. 홈페이지 헤드라인 한 줄이 전부를 설명합니다. "Now Claude Code can edit videos."
이 글에서는 공식 문서 5개(홈페이지, 프롬프트 가이드, Compositions 개념, Common Mistakes, GitHub 리포)를 기반으로 HyperFrames의 핵심 아이디어와 실전 사용법을 정리합니다.
HyperFrames란 무엇인가
HyperFrames는 "Write HTML. Render video. Built for agents." 라는 세 문장이 전부인 프레임워크입니다.
기존 프로그래밍 방식 영상 도구(예: Remotion)가 React 컴포넌트로 영상을 만든다면, HyperFrames는 순수 HTML과 data 속성, 그리고 GSAP 타임라인으로 영상을 선언합니다. 그 이유는 단 하나, AI 에이전트가 가장 잘 다루는 형태이기 때문입니다.
공식 홈페이지에서 강조하는 지원 에이전트는 네 가지입니다.
- Claude Code (Anthropic)
- Cursor
- Codex (GitHub/OpenAI)
- Gemini CLI (Google)
이들 에이전트가 공통으로 잘하는 것이 HTML을 읽고 수정하는 일입니다. HyperFrames는 그 강점에 정확히 베팅한 설계입니다.
왜 React/Vue가 아니라 HTML인가
React 컴포넌트로 영상을 만든다고 상상해 봅시다. 에이전트는 이렇게 추론해야 합니다. "JSX를 작성하고, 상태를 관리하고, 빌드를 거쳐 프레임을 렌더링한 뒤, FFmpeg으로 인코딩한다." 추상화 레이어가 많을수록 에이전트의 실수 가능성도 올라갑니다.
HyperFrames는 그냥 이렇게 씁니다.
<div id="root" data-composition-id="root"
data-start="0" data-width="1920" data-height="1080">
<video id="clip-1" data-start="0" data-duration="5" data-track-index="0"
src="intro.mp4" muted playsinline></video>
<img id="overlay" class="clip" data-start="2" data-duration="3"
data-track-index="1" src="logo.png" />
<audio id="bg-music" data-start="0" data-duration="9" data-track-index="2"
data-volume="0.5" src="music.wav"></audio>
</div>
정확히 세 가지만 알면 됩니다.
- Clip 타입:
<video>,<img>,<audio>, 또는 중첩된<div data-composition-id> - 필수 속성:
data-start,data-duration,data-track-index - 보이는 타이밍:
class="clip"이 있어야 프레임워크가 타이밍을 제어합니다
이것이 전부입니다. 에이전트는 HTML 편집이라는 익숙한 언어로 영상을 다룰 수 있습니다.
결정론적 렌더링이라는 비타협 원칙
자동화 파이프라인에서 가장 중요한 조건은 재현성입니다. 같은 입력이 항상 같은 출력을 만들어야 CI/CD에 태울 수 있습니다.
HyperFrames는 이 원칙을 설계에 박아 넣었습니다. 공식 문서에 명시된 일곱 가지 규칙 중 하나가 이겁니다.
Math.random() 금지. 필요하면 seeded PRNG (mulberry32)를 사용하라.
랜덤 함수조차 금지할 정도로 결정성을 중요시합니다. 100번 렌더링해도 같은 영상이 나와야 하고, 그래야 에이전트가 안전하게 반복 수정할 수 있습니다.
설치 한 줄, 슬래시 커맨드 다섯 개
Claude Code를 쓴다면 이 한 줄이면 끝입니다.
npx skills add heygen-com/hyperframes
이 명령이 Claude Code의 skill 시스템에 다섯 개의 슬래시 커맨드를 설치합니다.
| 커맨드 | 역할 |
|---|---|
/hyperframes | Composition 저작(HTML 구조, 타이밍, 캡션, TTS, 전환) |
/hyperframes-cli | init, lint, preview, render, transcribe, tts |
/hyperframes-registry | 블록/컴포넌트 설치 (hyperframes add) |
/website-to-hyperframes | URL 한 줄로 영상 파이프라인 시작 |
/gsap | GSAP 타임라인, 이징, ScrollTrigger API |
Cursor, Codex, Gemini CLI에도 동일한 방식으로 skill이 설치됩니다. 설치 후에는 에이전트가 이미 프로젝트 구조와 규칙을 이해한 상태에서 작업을 시작합니다.
두 가지 프롬프트 형태: Cold Start vs Warm Start
공식 프롬프트 가이드는 두 가지 프롬프트 형태를 구분합니다.
Cold start — 백지에서 영상 설명
10초 제품 인트로, 페이드인 타이틀, 다크 배경, BGM
간단하지만 포함 권장 요소가 있습니다.
- Duration (10초, 30초, 60초)
- Aspect ratio (16:9, 9:16, 1:1)
- Mood (energetic, calm, premium, playful)
- Key elements (타이틀, 자막, 배경, 음악)
Warm start — 기존 컨텍스트를 영상으로 합성
이 GitHub 리포를 45초 피치 영상으로 만들어줘
이 PDF를 30초 요약 영상으로 만들어줘
이 쪽이 HyperFrames의 진짜 강력함입니다. 에이전트가 리서치 + 프로덕션을 한 번에 처리합니다. 리포를 읽고 핵심을 추출하고 영상 스크립트와 비주얼을 설계해서 렌더링까지 한 흐름으로 이어집니다.
자연어가 기술 설정으로 변환되는 어휘표
HyperFrames 프롬프트 가이드의 가장 실용적인 부분은 자연어 → 기술 파라미터 매핑 테이블입니다.
Motion & Easing
| 감정 | GSAP Easing | 효과 |
|---|---|---|
| smooth | power2.out | 자연스러운 감속 |
| snappy | power4.out | 빠르고 결정적 |
| bouncy | back.out | 오버슈트 후 안착 |
| springy | elastic.out | 진동하며 안착 |
| dramatic | expo.out | 빠른 시작, 긴 활공 |
| dreamy | sine.inOut | 느리고 대칭적 |
Timing
- Fast (0.2s): 에너지
- Medium (0.4s): 프로페셔널
- Slow (0.6s): 럭셔리
- 1-2s: 시네마틱
Caption Tones
| 톤 | 폰트 | 애니메이션 | 크기 |
|---|---|---|---|
| Hype | 헤비 웨이트 | Scale-pop | 72-96px |
| Corporate | 클린 산세리프 | Fade+Slide | 56-72px |
| Tutorial | 모노스페이스 | Typewriter | 48-64px |
| Storytelling | Serif | Slow fade | 44-56px |
| Social | 라운드 플레이풀 | Bounce | 56-80px |
Audio-Reactive Mapping
오디오와 비주얼을 반응시킬 때 권장되는 매핑입니다.
- Bass → scale: 비트 펄스
- Treble → glow: 시머 효과
- Amplitude → opacity: 호흡
- Mids → shape: 모핑
권장 강도는 텍스트 3-6%, 배경 10-30%입니다. 사용자는 감정을 말하고, 프레임워크가 기술을 번역합니다.
꼭 지켜야 할 7가지 기술 규칙
공식 문서가 명시하는 "깨뜨리면 안 되는 규칙" 일곱 가지입니다. 에이전트가 이 규칙들을 자동으로 지키도록 skill이 설계되어 있습니다.
- 모든 타임라인을
window.__timelines에 등록하라. 렌더러가 알 수 없는 애니메이션은 시크(seek)가 불가능합니다. - 비디오 요소는 반드시
muted. 오디오는<audio>태그로 분리합니다. Math.random()금지. 결정성이 깨집니다. 필요하면 mulberry32 같은 seeded PRNG를 사용하세요.- GSAP 타임라인 구성은 동기입니다.
async/await/fetch를 타임라인 안에 쓰지 마세요. - 타임드 엘리먼트에
class="clip"필수. 빠뜨리면 엘리먼트가 항상 보이고 타이밍이 무시됩니다. - 모든 씬에 진입 애니메이션을 추가. 기본값으로 적용되지만, 이유 있을 때만 오버라이드하세요.
- 씬 사이에 전환을 추가. 점프 컷은 영상에서 의도적이지 않게 보이기 쉽습니다.
Common Mistakes: 실전 디버깅 체크리스트
공식 문서의 "자주 하는 실수" 섹션은 디버깅 교과서입니다. 실제 렌더링 실패 시 가장 먼저 확인할 항목들입니다.
- 비디오 요소 자체에 width/height 애니메이션 금지. 브라우저가 프레임 렌더링을 멈춥니다. wrapper
<div>를 애니메이션하세요. - 스크립트에서 미디어 제어 금지.
video.play(),audio.currentTime직접 호출 금지. 프레임워크 동기화와 충돌합니다. - 타임라인 길이 < 비디오 길이 문제.
tl.set({}, {}, 283)같은 제로듀레이션 트윈으로 타임라인을 연장합니다. class="clip"누락. 타이밍이 무시되고 엘리먼트가 항상 보입니다.- 과대 해상도 이미지(7000×5000 등). 140MB 디코딩으로 렌더가 느려집니다. 캔버스 2배 이하로 리사이즈하세요.
- backdrop-filter 스택. 16레이어 blur를 매 프레임 계산하면 렌더가 무너집니다. 2-3레이어로 제한하세요.
- timeline key 불일치.
data-composition-id와window.__timelines키가 정확히 일치해야 합니다.
패키지 아키텍처로 본 확장성
HyperFrames는 모노레포 형태로 패키지가 깔끔히 분리되어 있습니다.
| 패키지 | 역할 |
|---|---|
hyperframes | CLI (create, preview, lint, render) |
@hyperframes/core | 타입, 파서, 제너레이터, 린터, 런타임, frame adapter |
@hyperframes/engine | 페이지 → 영상 캡처 (Puppeteer + FFmpeg) |
@hyperframes/producer | 풀 파이프라인 (캡처 + 인코딩 + 오디오 믹스) |
@hyperframes/studio | 브라우저 기반 Composition 에디터 UI |
@hyperframes/player | 임베더블 <hyperframes-player> 웹 컴포넌트 |
@hyperframes/shader-transitions | WebGL 셰이더 전환 |
특히 주목할 개념이 Frame Adapter 패턴입니다. GSAP, Lottie, CSS 애니메이션, Three.js 같은 다양한 애니메이션 런타임을 가져와 쓸 수 있습니다. 생태계 확장의 핵심 장치이자, 누가 먼저 Lottie 어댑터나 Three.js 어댑터를 공개하느냐에 따라 커뮤니티가 빠르게 움직일 영역입니다.
TTS와 50+ 컴포넌트 카탈로그
HyperFrames는 나레이션까지 내장합니다. Kokoro라는 로컬 TTS 모델이 기본 포함되어 API 키 없이 작동합니다.
- 제품 데모: af_heart, af_nova
- 튜토리얼: am_adam, bf_emma
- 마케팅: af_sky, am_michael
컴포넌트 카탈로그도 풍부합니다. 50개 이상의 블록이 등록되어 있고, 한 줄로 설치됩니다.
npx hyperframes add flash-through-white
npx hyperframes add instagram-follow
npx hyperframes add data-chart
소셜 오버레이, 셰이더 전환, 데이터 시각화, 시네마틱 이펙트까지 카테고리별로 정리되어 있습니다.
권장 워크플로우
공식 문서가 안내하는 실전 순서입니다.
npx hyperframes init my-video— skill까지 자동 설치됩니다.- Claude Code, Cursor, Codex, Gemini CLI 중 하나로 프로젝트를 엽니다.
/hyperframes슬래시 커맨드로 cold/warm start 프롬프트를 던집니다.npx hyperframes preview로 브라우저 라이브 리로드 상태에서 확인합니다.- 작고 타겟된 반복이 원칙입니다. "제목 2배 크게", "끝에 페이드아웃 추가" 같은 미세 수정이 전체 재프롬프트보다 효과적입니다.
npx hyperframes render --output final.mp4로 최종 렌더링합니다.
요구사항은 Node.js 22 이상과 FFmpeg뿐입니다.
안티패턴: 하지 말아야 할 것들
프롬프트 가이드가 명시하는 안티패턴도 중요합니다.
- React/Vue 컴포넌트 요청: 번역 과정이 추가됩니다. HTML로 직접 요청하세요.
- 4K/60fps 요청: 1920×1080 30fps이면 충분하고, 훨씬 빠릅니다.
- 슬래시 커맨드 생략: 일반 HTML 비디오 관습으로 에이전트가 추측하게 됩니다. 반드시
/hyperframes를 호출하세요.
FAQ
Q. Remotion과 뭐가 다른가요?
Remotion은 React 기반 프레임워크입니다. HyperFrames는 순수 HTML 기반이고, 설계 철학이 "사람이 아닌 AI 에이전트가 주로 다룰 코드"라는 점에서 근본적으로 다릅니다. 에이전트 주도 자동화가 목적이면 HyperFrames가 유리합니다.
Q. 상용 사용이 가능한가요?
Apache 2.0 라이선스로 공개되어 있습니다. 상용 프로덕션에도 제약 없이 사용 가능합니다.
Q. 학습 곡선은 어떤가요?
HTML과 CSS를 안다면 진입이 매우 빠릅니다. GSAP 지식이 있으면 더 좋지만, skill이 GSAP 레퍼런스까지 제공하므로 에이전트가 대신 작성합니다.
Q. 에이전트 없이도 쓸 수 있나요?
네. Composition 에디터(@hyperframes/studio)가 브라우저에서 직접 영상을 저작할 수 있게 해 줍니다. 다만 설계의 강점은 에이전트 협업에서 나옵니다.
Q. 오디오는 어떻게 처리하나요?
<audio> 태그와 Kokoro TTS가 내장되어 있습니다. BGM, 효과음, 나레이션을 모두 트랙 기반으로 다룰 수 있습니다.
결론: 콘텐츠 자동화의 마지막 퍼즐
콘텐츠 자동화에서 리서치, 글쓰기, 이미지 생성은 이미 에이전트의 영역이 되었습니다. 남은 하나가 영상이었습니다. HyperFrames는 그 마지막 조각을 HTML이라는 가장 오래되고 검증된 방식으로 풀어냈습니다.
프로젝트 이름이 암시하듯 "hyper frames" — 에이전트 시대의 영상 프레임입니다. 요구사항은 Node.js 22와 FFmpeg뿐이고, 설치는 한 줄입니다. 콘텐츠 자동화 파이프라인을 고민한다면 지금 한 번 돌려볼 가치가 충분합니다.
출처
- HyperFrames 공식 홈페이지: https://hyperframes.heygen.com/
- 프롬프트 가이드: https://hyperframes.heygen.com/guides/prompting
- Compositions 개념: https://hyperframes.heygen.com/concepts/compositions
- Common Mistakes: https://hyperframes.heygen.com/guides/common-mistakes
- GitHub 리포: https://github.com/heygen-com/hyperframes
