개요
Hyperframes를 사용하면 개발자가 HTML과 CSS로 비디오를 제작하고, 헤드리스 Chrome의 결정론적 렌더링을 통해 MP4로 내보낼 수 있습니다. 내장 CLI로 미리보기와 렌더링을 지원하며, 스킬 플러그인을 제공하여 AI 코딩 에이전트와 긴밀하게 통합됩니다. GSAP, Lottie 등의 애니메이션 런타임을 지원하며 프레임 어댑터 패턴을 채택합니다.
README 미리보기
\n \n \n \n \n \n\n\n\n \n \n \n \n \n\n\nWrite HTML. Render video. Built for agents.\n\n\n \n\n\nHyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents.\n\n## Quick Start\n\n### Option 1: With an AI coding agent (recommended)\n\nInstall the HyperFrames skills, then describe the video you want:\n\n```bash\nnpx skills add heygen-com/hyperframes\n```\n\nThis teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for the dev-loop commands (init, lint, preview, render), `/hyperframes-media` for asset preprocessing (TTS, transcription, background removal), `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes.\n\nFor Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).\n\nFor Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface:\n\n```bash\ncodex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse assets\n```\n\nFor Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The m
FAQ (5)
문제 해결GSAP 트윈이 hyperframes에서 1700초 이후 렌더링된 비디오에 나타나지 않는 이유는 무엇인가요?
hyperframes 0.6.52의 알려진 버그: 시작 시간이 약 1700초(절대값)를 초과하는 GSAP 트윈이 렌더링 중에 적용되지 않습니다. 해결 방법: 트윈이 시간 0에서 시작되고 duration을 사용하여 가시성을 제어하도록 애니메이션을 재구성하거나, 컴포지션을 더 짧은 세그먼트로 분할하세요. t=0에서 연속적인 트윈은 정상적으로 작동합니다. 영구적인 수정을 위해 이슈 #1107을 추적하세요.
문제 해결HyperFrames를 v0.6.11로 업그레이드한 후 렌더링된 비디오 하단에 흰색 또는 검은색 막대가 나타나는 이유는 무엇인가요?
이는 HyperFrames v0.6.11+ (최신 v0.6.31 포함)에서 알려진 회귀 문제입니다. 1080x1920 세로 구성의 처음 약 37초 동안 하단 스트립이 비디오 요소로 덮이지 않습니다. 현재 유일한 해결 방법은 올바르게 렌더링되는 v0.6.10으로 다운그레이드하는 것입니다. 다음 명령어를 사용하세요: npx --yes hyperframes@0.6.10 render --output out.mp4. 영구적인 수정을 위해 이슈 #1009를 추적하세요.
문제 해결루트 타임라인의 지속 시간이 0일 때 Hyperframes 미리보기에서 tl.set() 변경 사항이 무시되는 이유는 무엇인가요?
이 문제는 v0.8.107 이전 버전의 Hyperframes CLI에 영향을 미칩니다. set-only 루트 타임라인은 지속 시간이 0이므로, 프리뷰 런타임이 이를 일시 정지된 duration-floor 타임라인으로 감싸지만 작성자의 루트 타임라인을 잘못된 상태로 일시 정지된 채로 남겨둡니다. 따라서 시킹을 수행해도 tl.set() 값이 렌더링되지 않습니다.
해결 방법: Hyperframes CLI v0.8.107 이상으로 업그레이드하세요:
npx hyperframes@latest preview또는 수정된 릴리스로 버전을 고정하세요:
npx hyperframes@0.8.107 preview이제 duration-floor 래퍼가 유지되고 있던 루트 타임라인을 활성화하여, 기존의 nested-composition 동작과 일치하게 됩니다.
이전 버전에서의 임시 해결 방법: 시킹 전에 루트 타임라인의 일시 정지를 해제하세요. 예를 들면:
window.__timelines.main.paused(false);
__player.seek(0.5);지속 시간이 0이 아닌 트윈을 하나라도 추가해도 폴백 경로를 피할 수 있습니다.
문제 해결컴파일된 대용량 HTML 파일에서 hyperframes render를 실행할 때 "Fatal JavaScript invalid size error 268435456" 오류를 어떻게 해결하나요?
HyperFrames를 v0.8.137 이상으로 업그레이드하세요. v0.8.137 릴리스에는 HTML을 일정 크기의 청크로 나누어 처리하여 정규식 매치 배열이 V8의 2^27 슬롯 한도를 초과하지 않도록 방지하는 PR #5098이 포함되어 있습니다.
단계:
1. 업그레이드:
npm install hyperframes@latest
또는 다음 명령으로 직접 실행:
npx hyperframes@latest render --output out.mp4
2. 즉시 업그레이드할 수 없는 경우, 정상 동작이 확인된 마지막 릴리스로 고정하세요:
npx hyperframes@0.8.75 render --output out.mp4
3. 프로젝트 수준의 임시 해결 방법으로, @font-face 규칙을 모든 하위 컴포지션에서 반복해서 선언하는 대신 루트 컴포지션에서 한 번만 선언하여 컴파일된 HTML 크기를 줄이세요. 반복되는 로컬 폰트 선언은 각각 base64로 별도 인라인되어 매우 큰 index.html 파일을 만들 수 있습니다.
Node의 힙 크기를 늘려도 이 크래시는 방지되지 않습니다. V8이 내부 정규식 결과 배열을 구성하는 도중에 중단되기 때문이며, 이는 캐치할 수 있는 메모리 부족 예외가 아닙니다.
문제 해결Docker로 렌더링한 비디오는 왜 macOS 렌더링에 비해 색상이 어긋나거나 더 옅게 보이나요?
이 문제는 Debian의 FFmpeg 5.1.9가 색상을 BT.601 매트릭스로 인코딩하면서 출력을 BT.709로 태그했기 때문에 발생했습니다. Hyperframes를 v0.8.81 이상으로 업그레이드하세요. 이 수정은 v0.8.143에서 확인되었으며, 해당 버전에서는 Docker와 macOS 출력이 1–2 색상 레벨 이내로 일치합니다. 업그레이드할 수 없는 경우 Docker 이미지의 Debian FFmpeg를 8.1과 같은 최신 정적 FFmpeg 빌드로 교체하거나, 인코딩 필터에 out_color_matrix=bt709를 명시적으로 추가해 보세요. 별도로, 백그라운드 업데이터가 렌더링 중에 전역 패키지를 수정하는 경우 HYPERFRAMES_NO_UPDATE_CHECK=1과 HYPERFRAMES_NO_AUTO_INSTALL=1을 설정하세요. 해당 문제는 v0.8.83에서 수정되었습니다.