Hyperframes

• Hyperframes는 HTML을 프레임 단위로 캡처하여 결정론적 MP4 비디오로 변환하는 오픈소스 프레임워크 (Apache 2.0)
• 웹 페이지를 만드는 방식으로 비디오를 정의하는 HTML-native 비디오 저작 도구
• AI 코딩 에이전트가 HTML을 직접 작성하여 비디오를 생성할 수 있도록 설계된 에이전트 친화적 렌더링 엔진

해당 개념이 필요한 이유

• 기존 비디오 편집 도구(Premiere, After Effects)는 GUI 기반이라 자동화·스크립팅이 어렵다
• Remotion은 React 기반이라 빌드 스텝이 필요하고, 에이전트가 JSX를 정확히 생성하기 어렵다
• Hyperframes는 plain HTML만으로 비디오를 정의하므로, 코딩 에이전트든 사람이든 진입 장벽이 낮다
• 동일 입력 → 동일 출력(결정론적 렌더링)이 보장되어 CI/CD, 회귀 테스트, 자동화 파이프라인에 적합하다

AS-IS

sequenceDiagram
    autonumber
    participant 사용자
    participant GUI편집기 as GUI 비디오 편집기
    participant 출력 as MP4 출력

    사용자->>GUI편집기: 수동으로 타임라인 조작
    GUI편집기->>GUI편집기: 프로젝트 파일 저장 (.prproj 등)
    사용자->>GUI편집기: 내보내기 버튼 클릭
    GUI편집기->>출력: 렌더링 (실행 환경에 따라 결과 다를 수 있음)
    Note over GUI편집기,출력: 자동화 불가, 에이전트 접근 불가

TO-BE

sequenceDiagram
    autonumber
    participant Agent as AI 에이전트 / 사용자
    participant HTML as index.html (Composition)
    participant CLI as Hyperframes CLI
    participant Chrome as Headless Chrome
    participant FFmpeg
    participant 출력 as MP4 출력

    Agent->>HTML: HTML + data attributes 작성
    Agent->>CLI: npx hyperframes render
    CLI->>Chrome: 프레임별 seekFrame(N) 호출
    Chrome->>Chrome: beginFrame API로 결정론적 캡처
    Chrome->>FFmpeg: PNG 프레임 스트림 전달
    FFmpeg->>출력: x264 인코딩 → MP4
    Note over Chrome,출력: 동일 입력 = 동일 출력 (결정론적)

아키텍처 — 6개 패키지 구조

Hyperframes는 모노레포 구조로, 각 패키지가 명확한 역할을 담당한다:

패키지	역할
@hyperframes/core	타입 시스템, HTML 파서/제너레이터, 린터, 런타임, Frame Adapter
@hyperframes/engine	Puppeteer 기반 Headless Chrome 프레임 캡처 엔진
@hyperframes/producer	캡처 + FFmpeg 인코딩 + 오디오 믹싱 통합 파이프라인
@hyperframes/studio	브라우저 기반 비주얼 에디터 UI
@hyperframes/player	임베드 가능한 <hyperframes-player> 웹 컴포넌트
hyperframes (CLI)	init, preview, lint, render 등 CLI 명령어

패키지 의존 관계:

CLI → Producer → Engine → Core
Studio → Core
Player → Core

Composition — 비디오의 단위

Composition은 Hyperframes 비디오의 기본 단위로, 하나의 HTML 파일이 하나의 비디오(또는 비디오 내 장면)를 정의한다. 별도의 프로젝트 파일 포맷이 아니라 plain HTML 자체가 비디오의 단위이며, data-* 속성으로 타이밍과 레이어링 정보를 추가한 것이다.

필수 구조

<div id="root" data-composition-id="my-video"
     data-start="0" data-width="1920" data-height="1080">
 
  <!-- 타이밍이 지정된 클립 요소 -->
  <h1 id="title" class="clip"
      data-start="0" data-duration="5" data-track-index="0">
    Hello!
  </h1>
</div>

3가지 핵심 규칙

1. 루트 요소에 data-composition-id, data-width, data-height 필수
2. 타이밍 요소에 data-start, data-duration, data-track-index, class="clip" 필수
3. GSAP 타임라인은 { paused: true }로 생성하고 window.__timelines에 등록

클립 타입 4가지

타입	HTML 요소	용도
Video	<video>	B-roll, A-roll 영상
Image	<img>	정적 오버레이, 그래픽
Audio	<audio>	배경음악, 효과음
Nested Composition	<div data-composition-src="...">	서브 씬, 재사용 가능한 애니메이션

2-Layer 아키텍처

Composition은 두 레이어로 분리된다:

• HTML Layer (Primitives): 무엇이 언제 어떤 트랙에서 재생되는지 선언 — data-* 속성으로 제어
• Script Layer (Effects): 애니메이션, 트랜지션, 동적 DOM 조작 — GSAP 타임라인으로 구현

스크립트에서 클립의 표시/숨김이나 미디어 재생을 직접 제어하면 안 된다. 이는 프레임워크가 자동으로 관리한다.

Frame Adapter — 애니메이션 런타임 추상화

Frame Adapter는 “프레임 N에서 화면이 어떻게 보여야 하는가?”라는 질문에 답하는 인터페이스다. 다양한 애니메이션 런타임(GSAP, Lottie, Three.js 등)을 통일된 방식으로 통합한다.

type FrameAdapter = {
  id: string;
  init?: (ctx: FrameAdapterContext) => Promise<void> | void;
  getDurationFrames: () => number;       // 총 프레임 수 반환
  seekFrame: (frame: number) => Promise<void> | void;  // 해당 프레임으로 이동
  destroy?: () => Promise<void> | void;
};

결정론(Determinism) 계약

• 정규 시계: t = frame / fps
• Date.now() 같은 wall-clock 의존 금지
• 시드 없는 랜덤 금지
• 렌더링 중 네트워크 요청 금지
• seekFrame()은 멱등(idempotent) — 같은 프레임 입력이면 항상 동일한 출력

지원 런타임 6종

런타임	Seek 방식
GSAP	timeline.totalTime(seconds)
Anime.js	instance.seek(timeMs)
CSS Keyframes	Animation.currentTime
Lottie	goToAndStop(timeMs, false)
Three.js/WebGL	hf-seek 이벤트 + window.__hfThreeTime
WAAPI	animation.currentTime

렌더링 파이프라인 — 프레임 캡처에서 MP4까지

핵심 공식

frame = floor(time × fps)

렌더링 흐름

1. CLI가 Producer를 호출
2. Producer가 Engine을 통해 Headless Chrome 인스턴스 생성
3. Composition HTML을 Chrome에 로드
4. 각 프레임에 대해:
   • Frame Adapter의 seekFrame(N) 호출
   • Chrome beginFrame API로 해당 프레임 캡처 (PNG)
5. 캡처된 프레임 시퀀스를 FFmpeg에 파이프
6. FFmpeg가 x264로 인코딩 → MP4 출력

렌더링 모드 2가지

모드	특성
Local	시스템 Chrome + FFmpeg 사용, 빠름, GPU 가속 가능
Docker	고정된 Chrome/FFmpeg/폰트, 플랫폼 무관 동일 출력, CI/CD용

Quality 프리셋

프리셋	CRF	속도	용도
Draft	28	ultrafast	반복 작업용 빠른 미리보기
Standard	18	medium	기본값, 1080p에서 시각적 무손실
High	15	slow	최종 납품용

GSAP 타임라인 — 애니메이션의 핵심 패턴

Hyperframes에서 GSAP 타임라인은 반드시 paused 상태로 생성하고, 프레임워크가 프로그래매틱하게 스크러빙한다:

// 1. paused 타임라인 생성
const tl = gsap.timeline({ paused: true });
 
// 2. 절대 위치 파라미터로 애니메이션 배치
tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);   // 0초부터
tl.to("#subtitle", { opacity: 1, duration: 0.5 }, 1.5);       // 1.5초부터
 
// 3. composition-id와 매칭하여 등록
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = tl;

Composition의 duration = GSAP 타임라인의 duration. 비디오가 30초인데 애니메이션이 8초에 끝나면 비디오도 8초에서 잘린다. 빈 tween으로 연장:

tl.set({}, {}, 30);  // 타임라인을 30초로 확장

개발 워크플로우

# 1. 프로젝트 생성
npx hyperframes init my-video
 
# 2. 브라우저에서 실시간 미리보기
npx hyperframes preview
 
# 3. HTML 편집 (에이전트 또는 직접)
# index.html 수정 → 자동 핫 리로드
 
# 4. 린트 검사
npx hyperframes lint
 
# 5. MP4 렌더링
npx hyperframes render --output output.mp4

Hyperframes vs Remotion

	Hyperframes	Remotion
저작 방식	HTML + CSS + seekable 애니메이션	React 컴포넌트
빌드 스텝	없음 — index.html이 곧 플레이 가능	번들러 필수
에이전트 핸드오프	Plain HTML 파일	JSX / React 프로젝트
라이선스	Apache 2.0	Remotion License (source-available)
분산 렌더링	Local + AWS Lambda	Remotion Lambda

참고 문서

• Official Introduction
• Quickstart
• Compositions Concept
• Frame Adapters Concept
• GSAP Animation Guide
• Rendering Guide
• GitHub Repository