한 줄 요약: heygen-com/hyperframes는 “Write HTML. Render video. Built for agents.”를 표방하는 Apache-2.0 HTML→MP4 프레임워크입니다. 컴포지션은 React가 아니라 data-* 타이밍 속성과 seekable 애니메이션(기본 GSAP)으로 작성하고, 렌더러는 wall clock을 쓰지 않고 t = frame / fps로 시크한 뒤 Chrome HeadlessExperimental.beginFrame으로 픽셀을 찍고 FFmpeg로 인코딩합니다. 오늘은 GitHub Trending TypeScript 일간 상위권(+873 스타)에 오른 이 저장소를 모노레포·렌더 파이프라인·에이전트 스킬·Remotion 비교 기준으로 해부하고, 박스에서 Node 22.20 + hyperframes@0.8.156으로 재현한 doctor·lint·check·snapshot·2초 MP4 렌더 결과를 적습니다.
왜 지금 이 저장소인가
에이전트가 영상을 “만들 수 있다”는 말과, 같은 입력을 CI에서 다시 돌려도 프레임이 안 흔들린다는 말은 다릅니다. 전자는 프롬프트 품질 문제이고, 후자는 렌더 계약 문제입니다. HyperFrames가 흥미로운 지점은 HeyGen이 자사 Studio·클라우드 렌더의 코어를 오픈소스로 풀어, 에이전트가 이미 잘 쓰는 HTML/CSS/JS 표면 위에 결정론적 캡처 계약을 얹었다는 점입니다. PPT Master가 “SVG→네이티브 PPTX”라면 HyperFrames는 “HTML→네이티브 MP4/WebM”입니다. 같은 “에이전트가 만든 산출물을 편집 가능한 프로젝트로 남긴다”는 철학이지만, 매체가 슬라이드가 아니라 타임라인입니다.
| 항목 | 확인한 값 | 해석 |
|---|---|---|
| 저장소 | heygen-com/hyperframes (TypeScript, 홈 hyperframes.dev) |
토픽: ai, animation, ffmpeg, gsap, html, mcp, puppeteer, typescript, video |
| 스타 / 포크 | 63,096 / 5,660 (2026-10-14 16:57 KST API) | 2026-03-10 생성 → 약 7개월. 열린 이슈+PR 279 |
| Trending | TypeScript 일간 상위(+873), 전체 일간에도 노출 | 오늘 아침 다룬 vercel-labs/skills·REA·VoiceStudio 등과 겹치지 않음 |
| npm / 릴리스 | hyperframes@0.8.156 (2026-10-14 13:37 KST 태그) |
하루에도 여러 패치(v0.8.152~156). engines: Node ≥22 |
| 라이선스 | Apache-2.0 | Remotion의 소스-가용(인원 제한) 라이선스와 대비되는 실무 포인트 |
| 최근 푸시 | 2026-10-14 16:39 KST | 릴리스 직후에도 활발 |
기능 지도: CLI · Studio · 스킬 · 클라우드
실무자가 만지는 표면은 네 겹입니다. (1) 로컬 CLI npx hyperframes, (2) 데스크톱/웹 Studio, (3) 코딩 에이전트용 스킬·플러그인, (4) HeyGen 클라우드 / AWS Lambda / GCP Cloud Run 분산 렌더. README는 “에이전트가 HTML을 쓰고, 사람은 Studio로 다듬고, 같은 파일이 렌더된다”는 루프를 강조합니다.
| 표면 | 대표 명령·경로 | 실무 포인트 |
|---|---|---|
| CLI | init lint check snapshot preview render doctor skills timeline |
비대화형 기본. 에이전트/CI에 맞게 설계 |
| 게이트 | check = lint + runtime + layout + motion + contrast |
lint error가 있으면 layout/contrast 샘플이 0으로 떨어져 “깨끗해 보이는” 함정 |
| 에이전트 | Claude plugin marketplace / npx skills add heygen-com/hyperframes / npx hyperframes skills update |
코어 세트 기본 설치, 생성 워크플로는 on-demand. skills.sh 레지스트리는 main보다 몇 시간 늦을 수 있음 |
| 분산 렌더 | cloud · lambda · cloudrun |
로컬 Chrome/FFmpeg 없이, 또는 워커 샤딩 |
| 부가 미디어 | tts(Kokoro) transcribe remove-background normalize-audio |
doctor에 optional로 표기. 없어도 코어 렌더는 가능 |
아키텍처: 모노레포와 렌더 데이터 흐름
루트는 Bun 워크스페이스(packages/*)입니다. npm에 올라가는 사용자 대면 바이너리는 hyperframes(packages/cli)이고, 실제 캡처·인코딩은 @hyperframes/engine → @hyperframes/producer 경로입니다. 박스에서 클론한 v0.8.156 기준 패키지 역할은 아래와 같습니다.
| 패키지 | 한 줄 역할 | 소스에서 본 규모 감각 |
|---|---|---|
@hyperframes/cli |
명령 표면, 프로젝트 스캐폴드, 스킬 설치, 클라우드 드라이버 | ~8.7MB 트리, 명령 수십 개 |
@hyperframes/core |
타입·파서·컴파일러·런타임·프레임 어댑터 | ~6.7MB. 어셈블리·변수·서브컴포지션 |
@hyperframes/engine |
브라우저 풀, BeginFrame/스크린샷 캡처, 청크·스트리밍 인코더, 오디오 믹서 | README: “Seekable web page to video (Puppeteer + FFmpeg)” |
@hyperframes/producer |
createRenderJob/executeRenderJob, HTML 로컬라이즈, 분산·패리티 하네스 |
~50MB. 회귀·PSNR·Lambda-local 테스트 레인 |
@hyperframes/sdk |
헤드리스 편집 세션(프레임워크 중립) | 에이전트/임베드용 |
studio / player |
WYSIWYG 타임라인, 임베드 플레이어 | 사람이 같은 HTML을 손으로 다듬는 경로 |
aws-lambda / gcp-cloud-run |
분산 렌더 어댑터 | Chromium 번들·S3/플랜 퍼블리셔 |
lint / parsers / shader-transitions |
정적 규칙, HTML 파싱, WebGL 전환 | 에이전트 첫 빌드 실패를 앞당기는 계층 |
한 프레임의 데이터 흐름을 문서·엔진 README 기준으로 압축하면 다음과 같습니다.
| 단계 | 담당 | 핵심 계약 |
|---|---|---|
| 1. Compile / localize | producer htmlCompiler |
원격 img/video/audio/@font-face를 same-origin 로컬 경로로 재작성. mid-render fetch 금지 |
| 2. Frame clock | engine | time = floor(frame) / fps. 시스템 시계 미사용 |
| 3. Seek | frame adapter + window.__timelines |
paused GSAP(또는 WAAPI/Lottie/Three…)를 t로 점프. play() 금지 |
| 4. Capture | screenshotService / BeginFrame |
선호 경로: chrome-headless-shell + HeadlessExperimental.beginFrame. 일반 Chrome은 screenshot 폴백 |
| 5. Encode | streamingEncoder / chunkEncoder |
프레임 파이프→FFmpeg. 오디오는 <audio>/<video> 트랙 믹스 |
| 6. Parallel (옵션) | parallelCoordinator |
프레임 범위를 워커로 분할. Lambda/Cloud Run과 동일 계약 |
컴포지션 계약: data-* 와 결정론
작성 모델의 핵심은 “프레임 번호를 React props로 계산”이 아니라 “HTML이 언제 보이는지 선언하고, 애니메이션 런타임이 seek에 응답”입니다. hyperframes-core 스킬이 강제하는 규칙을 실무 관점에서 요약합니다.
| 계약 | 규칙 | 깨지면 |
|---|---|---|
| 루트 | data-composition-id + data-width/height (+ 보통 data-duration/data-fps) |
캔버스 크기·길이가 고정되지 않음. 루트 duration은 컴파일 타임에 잠김 |
| 클립 | 가시 슬롯에 class="clip", data-start, data-duration, data-track-index |
반개구간 [start, start+duration). 끝 프레임에 도달한 애니메이션은 안 보임 |
| 타임라인 | 정확히 하나(권장)의 gsap.timeline({ paused: true })를 window.__timelines[id]에 등록 |
키 불일치·비동기 빌드 전 등록 → t=0 정지 화면 |
| 결정론 | 금지: Date.now, unseeded Math.random, mid-render fetch, hover/scroll 의존 |
CI·재렌더에서 프레임 드리프트 |
| 미디어 | <audio>는 id 필수. <video data-start>를 또 다른 timed 조상 안에 넣지 말 것. crossorigin 금지 |
무음 렌더, 잘못된 소스 프레임, preview 깨짐 |
| GSAP 함정 | 같은 노드에 CSS transform 초기값 + GSAP x/y 금지(gsap_css_transform_conflict). .clip에 autoAlpha 금지 |
lint error → check의 layout/contrast가 무력화 |
서브컴포지션은 data-composition-src로 다른 HTML을 호스트에 끼워 넣고, 템플릿 래핑 여부에 따라 <head> 스타일/스크립트 호이스팅 규칙이 달라집니다. 에이전트가 “파일 하나 더 쪼개기”를 할 때 가장 많이 밟는 지뢰입니다.
에이전트 스킬 21개: 라우터와 워크플로
이 저장소는 오늘 아침 다룬 vercel-labs/skills 설치 CLI의 소비자이기도 합니다. HyperFrames 자체는 21개 스킬을 배포하고, /hyperframes 라우터가 “만들어 줘” 요청을 워크플로로 분기합니다. 설치는 코어 세트가 기본이고, 생성 워크플로는 필요할 때 on-demand로 끌어옵니다.
| 종류 | 스킬 예 | 언제 |
|---|---|---|
| 라우터 | /hyperframes |
영상/모션/렌더 요청의 첫 진입점. 의도 확인 + 도메인 맵 |
| 생성 워크플로 | product-launch-video faceless-explainer pr-to-video motion-graphics music-to-video slideshow … |
브리프 유형별 end-to-end 루프 |
| 도메인 | hyperframes-core animation keyframes audio cli registry media-use |
계약·모션·믹스·레지스트리 블록을 원자적으로 로드 |
| 마이그레이션 | remotion-to-hyperframes |
React Remotion → HTML 단방향 포트 |
주의: npx skills add --all은 published 21개를 전부 깔고, 레포 내부 .claude/skills 6개는 기본 제외입니다. 최신 main이 필요하면 npx hyperframes skills update가 skills.sh 블롭보다 앞섭니다. 오늘 아침 글의 “설치 CLI”와 이 글의 “영상 프레임워크”는 계층이 다릅니다.
HyperFrames vs Remotion (그리고 인접 대안)
공식 가이드는 같은 3초 타이틀 카드를 React(Remotion)와 HTML(HyperFrames)로 나란히 보여 줍니다. 둘 다 headless Chrome + FFmpeg입니다. 차이는 작성·시킹·라이선스입니다.
| 축 | HyperFrames | Remotion |
|---|---|---|
| 작성 | HTML + CSS + seekable JS | React 컴포넌트 + useCurrentFrame |
| 빌드 | 없음. index.html이 곧 프로젝트 |
번들러 필요 |
| 모션 모델 | 렌더러가 애니메이션을 pause/seek | 프레임 번호→보간값을 코드가 계산 |
| 에이전트 핸드오프 | 에이전트가 이미 잘하는 HTML | JSX/프로젝트 구조 필요 |
| 분산 | 로컬 + Lambda + Cloud Run + HeyGen cloud | Remotion Lambda(성숙도 높음) |
| 라이선스 | Apache-2.0 | 자체 라이선스(소규모 무료, 유료 구간) |
| 대안 | 겹치는 문제 | HyperFrames를 고를 때 |
|---|---|---|
| Remotion | 웹 기술로 영상 | 에이전트·HTML 우선, Apache-2.0, 빌드 없는 프로젝트 |
| After Effects / Premiere 스크립트 | 모션 그래픽 자동화 | CI·헤드리스·텍스트 산출물 중심 |
| MoviePy / ffmpeg 직접 | 클립 조립 | 타이포·UI·웹 애니메이션이 본체인 경우 |
| PPT Master (슬라이드) | 에이전트 산출물→편집 가능 파일 | 매체가 타임라인/영상일 때 |
| VoiceStudio (음성) | 로컬 미디어 AI | 보이스가 아니라 HTML 모션/컴포지션이 핵심일 때 |
설치·실행·평가 루프
| 단계 | 명령 | 기대 |
|---|---|---|
| 요구사항 | Node ≥22, FFmpeg, Chrome/chromium | Node 20에서는 CLI가 즉시 거절(실측) |
| 스캐폴드 | npx hyperframes@0.8.156 init my-video |
index.html + hyperframes.json + 코어 스킬 복사 |
| 정적 게이트 | npx hyperframes lint → check |
에러 0 후에야 layout/contrast 숫자를 신뢰 |
| 시각 검증 | snapshot --at 0.5,2,4 |
에이전트/리뷰어용 PNG + contact sheet |
| 렌더 | render -o out.mp4 / --format webm |
로컬 또는 cloud render / lambda |
| 최적화 브라우저 | npx @puppeteer/browsers install chrome-headless-shell |
BeginFrame 경로. 일반 Chrome은 screenshot 폴백 |
박스 스모크 (실측, 날조 없음)
환경: Linux box, Node v22.20.0(툴체인 타르볼), 시스템 FFmpeg 7.1.5, 시스템 Google Chrome. 패키지 hyperframes@0.8.156. 워크스페이스 /workspace/mw-afternoon-opensource-1014/smoke/.
| 검사 | 결과 | 메모 |
|---|---|---|
| Node 20에서 CLI | 거절 | “HyperFrames requires Node.js >= 22 (current: 20.19.2)” |
hyperframes --help |
OK | Getting Started / Project / Deploy / AI 섹션 명령 목록 확인 |
doctor |
코어 OK, 일부 ✗ | ✓ Node/FFmpeg/FFprobe/Chrome/shm. ✗ Docker, whisper-cpp, Kokoro TTS, MusicGen(모두 optional). 일반 Chrome → BeginFrame 불가 경고 후 headless-shell 안내 |
init demo-video |
OK | blank 10s 타이틀 컴포지션 + 코어 스킬을 ~/.agents/skills·~/.claude/skills에 복사 |
lint |
0 errors, 0 warnings | 스캐폴드 HTML 기준 |
check |
passed | layout warning 1건: 정지 컴포지션(seek 시 움직임 없음) → data-no-timeline 힌트. Contrast 5/5 WCAG AA |
snapshot --at 0.5 |
OK | 0.5s + 자동 end 프레임 9.7s PNG + contact-sheet.jpg |
render (2초, fps 15) |
성공 | 30 frames, beginframe capture(렌더 경로에서 headless-shell 확보), software GPU(SwiftShader), 14.6 KB · 2.0s · wall 5.2s. capture 2.8s / encode(중첩) 2.8s / assemble 0.1s |
덧붙여, 첫 doctor 시점의 시스템 Chrome 경고와 달리, 실제 render 잡은 Puppeteer가 chrome-headless-shell을 끌어와 captureMode: beginframe으로 돌았습니다. 운영에서는 doctor 경고만 보고 screenshot 폴백이라고 단정하지 말고, 한 번 짧은 렌더로 captureMode를 확인하는 편이 안전합니다.
설계 트레이드오프와 한계
| 선택 | 이득 | 비용·주의 |
|---|---|---|
| HTML 네이티브 | 에이전트·devtools·빌드리스 | React 생태계·컴포넌트 테스트 관습을 그대로 못 가져옴 |
| Seek + BeginFrame | 느린 머신에서도 프레임 드롭 없는 결정론 | wall-clock 애니메이션·무한 루프·난수를 금지. 학습 곡선은 lint가 대신함 |
| Chrome 의존 | 웹 기술 그대로 렌더 | 헤드리스 셸·/dev/shm·GPU/SwiftShader 이슈. Docker 경로가 문서화됨 |
| 에이전트 스킬 중심 DX | 프롬프트→프로젝트 루프가 짧음 | 스킬이 stale하면 품질이 급락. skills update와 check 게이트를 파이프라인에 넣어야 함 |
| HeyGen 클라우드·계정 | 로컬 GPU/Chrome 부담 이전 | 완전 오프라인·벤더 비의존이 목표면 Lambda self-host 또는 로컬만 |
| 텔레메트리 기본 ON | 제품 개선 신호 | hyperframes telemetry disable. 로그인 시 계정 링크 가능(doctor 안내) |
저장소 테스트 파일만 *.test.ts 기준 약 1,395개, 비테스트 TS 약 1,780개 수준입니다(클론 트리 카운트). producer는 unit/integration/regression/PSNR/distributed 레인을 나눠 두었고, “프레임이 같다”를 제품 약속으로 취급합니다. 박스에서는 전체 monorepo 테스트 스위트는 돌리지 않았고(시간·의존성), 사용자 경로인 CLI 스모크와 짧은 beginframe 렌더에 집중했습니다.
도입 판단 체크리스트
| 질문 | 예라면 | 아니라면 |
|---|---|---|
| 산출물이 에이전트가 고칠 수 있는 프로젝트여야 하나? | HyperFrames HTML 프로젝트 | 블랙박스 SaaS 렌더로 충분할 수 있음 |
| 팀이 이미 React 영상 파이프라인을 갖고 있나? | Remotion 유지 + 필요 시 마이그레이션 스킬 | HTML 경로가 온보딩 비용이 낮음 |
| 라이선스가 상업 규모에서 자유로워야 하나? | Apache-2.0이 명확한 이점 | Remotion 유료 구간도 검토 |
| CI에서 프레임 회귀가 필요한가? | check + snapshot/PSNR 레인 |
일회성 마케팅 클립이면 overkill |
| Node 22·Chrome·FFmpeg를 통제할 수 있나? | 로컬/셀프호스트 | HeyGen cloud render 또는 관리형 Lambda |
정리하면, HyperFrames는 “또 하나의 영상 에디터”가 아니라 에이전트가 쓸 수 있는 결정론적 HTML 컴포지션 런타임에 가깝습니다. BeginFrame 시크, lint/check 게이트, 21개 스킬 라우터, Apache-2.0이 한 세트입니다. 오늘 박스에서 확인한 범위는 CLI·짧은 beginframe 렌더까지이고, Studio UI·Lambda 실배포·대용량 미디어 파이프라인은 별도 검증이 필요합니다. 저장소와 문서는 github.com/heygen-com/hyperframes, hyperframes.heygen.com에서 이어가면 됩니다.