[Claude Code 플러그인] hyperframes, HTML로 쓰면 MP4가 되는 영상 만들기
HTML로 장면을 쓰면 MP4로 렌더해 주는 HeyGen의 오픈소스 프레임워크와 Claude Code 플러그인입니다. 설치와 사용 순서를 정리하고, 이 블로그의 실제 화면 위에 모션 그래픽을 얹은 영상을 직접 만들어 글 안에 넣었습니다.
제품 소개 화면에 넣을 짧은 모션 그래픽이 필요할 때, 영상 편집 프로그램을 열기에는 한 번 쓰고 말 작업이 아깝고 애니메이션 코드를 짜서 화면을 녹화하기에는 번거롭습니다. 이 글에서는 HTML로 장면을 쓰면 영상 파일로 만들어 주는 HyperFrames와, 이를 Claude Code에서 쓰게 해 주는 hyperframes 플러그인을 다룹니다. 앞선 hairline-create 글처럼 이번에도 직접 만든 예시를 글 안에 넣었습니다.
1. 어떤 플러그인인가
HyperFrames는 HTML, CSS, 미디어, 그리고 시간 축을 되감을 수 있는 애니메이션을 결정적인(deterministic) MP4로 바꿔 주는 오픈소스 프레임워크입니다. 같은 입력이면 같은 영상이 나온다는 뜻입니다. 렌더러는 헤드리스 Chrome으로 프레임을 한 장씩 찍어서 FFmpeg로 이어 붙입니다.
이 프레임워크를 AI 에이전트가 쓰도록 가르치는 것이 플러그인에 들어 있는 스킬입니다. 공식 설명으로는 스킬이 21개이고, /hyperframes가 "무엇을 만들어 달라"는 요청이 오면 영상, 슬라이드, 모션 그래픽 같은 작업 종류에 맞는 하위 워크플로를 골라 주는 입구 역할을 합니다. 에이전트가 따르는 기본 순서는 계획하고, 유효한 HTML을 쓰고, 되감을 수 있는 애니메이션을 연결하고, 미디어를 넣고, 검사하고, 미리 보고, 렌더하는 것입니다.
2. 출처
| 항목 | 내용 |
|---|---|
| AI 도구 | Claude Code (공식 설명에 Codex, Cursor, Gemini CLI 등도 지원한다고 나와 있습니다) |
| 종류 | 플러그인 (스킬 21개 포함) |
| 만든 곳 | HeyGen |
| 공식 문서 | https://hyperframes.heygen.com |
| 저장소 | https://github.com/heygen-com/hyperframes |
| 설치 경로 | claude plugin marketplace add heygen-com/hyperframes 후 claude plugin install hyperframes@hyperframes (스킬만 따로 받으려면 npx skills add heygen-com/hyperframes) |
| 확인한 버전 | 0.8.140 (제 설치본의 plugin.json 기준, 2026년 10월 8일 확인) |
| 라이선스 | Apache License 2.0 |
| 요구 사항 | Node.js 22 이상, FFmpeg |
3. 언제 쓰면 좋은가
- 제품 소개, 타이틀 카드, 숫자가 올라가는 장면처럼 짧은 모션 그래픽이 필요할 때
- 실제 웹 화면을 캡처하고 그 위에 강조 표시, 확대, 커서 같은 안내 모션을 얹어 사용법 영상을 만들 때
- 같은 장면의 문구나 색만 바꿔 여러 번 뽑아야 할 때(코드라서 고쳐서 다시 렌더하면 됩니다)
- 영상 편집 프로그램 없이 에이전트에게 맡겨 초안을 빨리 보고 싶을 때
실사 촬영 영상을 세밀하게 편집하는 용도에는 맞지 않습니다.
4. 사용법
플러그인은 터미널에서 두 줄로 설치합니다. 공식 안내는 자동 업데이트를 Claude Code의 /plugin 메뉴에서 hyperframes 마켓플레이스에 켜 두라고 권합니다.
claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes
설치하고 나면 세션에서 스킬 목록에 hyperframes, hyperframes-core, hyperframes-cli, motion-graphics 같은 이름이 나타납니다. 이후에는 만들고 싶은 영상을 말로 설명하면 됩니다. 공식 문서가 예로 드는 요청은 이렇습니다.
Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.
영상 한 편은 하나의 프로젝트 폴더입니다. 스킬이 안내하는 주요 명령은 이렇습니다.
npx hyperframes init videos/이름 --non-interactive --example=blank # 프로젝트 만들기
npx hyperframes capture https://주소 # 웹페이지를 캡처해 소재로 쓰기(선택)
npx hyperframes check . # 구조, 레이아웃, 대비 검사
npx hyperframes snapshot --at 0.4,2,4,7 # 지정한 시각의 프레임 확인
npx hyperframes preview # 브라우저로 미리 보기
npx hyperframes render . -q high -o ./renders/video.mp4 # MP4로 렌더
장면을 이루는 규칙은 단순합니다. 가장 바깥 요소에 data-composition-id, data-width, data-height, data-duration을 적고, 시간이 있는 요소에는 data-start와 data-duration을 적습니다. 애니메이션은 일시정지 상태의 GSAP 타임라인으로 만들어 window.__timelines에 등록합니다. 렌더러가 시간을 마음대로 옮겨 가며 프레임을 찍기 때문에, 타이머나 requestAnimationFrame처럼 시간에 의존하는 코드는 쓰지 않아야 합니다.
5. 적용 예시
이 도구가 빛나는 곳은 빈 화면에 글자를 띄우는 영상보다, 실제 화면 위에 안내 그래픽을 얹는 영상입니다. 처음에는 이 블로그 이름으로 글자만 나오는 소개 영상을 만들었다가, 그래서는 HyperFrames의 장점이 안 드러난다고 보고 다시 만들었습니다. 이 블로그의 실제 AI 툴킷 화면을 캡처하고, 그 위에 스포트라이트와 말풍선, 커서를 얹은 11.5초짜리 영상입니다. 목적별 카드를 비추고, 종류와 AI 도구 칩을 비추고, 커서가 "작업 환경" 카드를 누르면 화면이 그 구역으로 내려가 카드 세 장을 비춥니다.
만든 과정은 이렇습니다.
npx hyperframes capture http://localhost:3001/tools로 실제 페이지를 캡처했습니다. 전체 페이지를 한 장으로 찍은 PNG(1909x2477)와 페이지의 HTML, 글꼴 정보가 함께 나옵니다. 배포 전 화면이라 로컬 서버 주소로 찍었습니다.- 그 PNG를 바닥 층으로 깔고, 안내 그래픽은 같은 층 안에 페이지 좌표로 얹었습니다. 그래야 화면이 스크롤될 때 스포트라이트도 같이 따라 움직입니다.
- 스포트라이트는 대상 영역에 테두리를 두르고 사방으로 아주 큰 그림자를 퍼뜨려 나머지 화면을 어둡게 합니다. 처음에는 옆으로 쓸어 켜는 효과를 줬더니 그림자까지 잘려서 화면이 어두워지지 않았습니다. 그래서 살짝 큰 상태에서 제자리로 줄어들며 켜지게 바꿨습니다.
- 커서는 화면 좌표로 움직이고, 클릭하는 순간 동그란 물결이 퍼지게 했습니다.
<div id="stage" class="clip" data-start="0" data-duration="11.5">
<div id="page">
<img id="shot" src="assets/page.png" alt="" />
<div id="spot1" class="spot" style="left:373px; top:320px; width:1172px; height:214px;"></div>
<div id="tag1" class="tag" style="left:373px; top:556px;">어떤 도움이 필요한지 먼저 고르고</div>
</div>
<svg id="cursor" viewBox="0 0 64 64">...</svg>
</div>
<script>
const tl = gsap.timeline({ paused: true });
const spotOn = (id, tag, at) => {
tl.to(id, { opacity: 1, scale: 1, duration: 0.5, ease: "power3.out" }, at);
tl.to(tag, { opacity: 1, y: 0, scale: 1, duration: 0.4, ease: "back.out(1.6)" }, at + 0.45);
};
spotOn("#spot1", "#tag1", 1.0);
// 커서 이동, 클릭 물결, 페이지 스크롤은 같은 타임라인에 시각만 달리해서 이어 붙입니다
window.__timelines["main"] = tl;
</script>확인은 check와 snapshot으로 했습니다. 오류는 0개였습니다. 스크롤 때문에 페이지 층이 화면 밖으로 나간다는 레이아웃 경고는 의도한 동작이라 data-layout-allow-overflow로 허용했고, 장면을 하위 컴포지션 파일로 나누라는 구조 권고 하나는 그대로 두었습니다. 장면이 하나뿐이기 때문입니다. 렌더한 원본은 4.3MB였는데, 정지 화면이 대부분이라 FFmpeg로 다시 인코딩해서 1.1MB로 줄였습니다.
스킬이 설명하는 전체 워크플로는 이번에도 그대로 따르지 않았습니다. 기획과 설계를 맡는 하위 에이전트와 렌더 전 사람의 승인 단계를 건너뛰고, 캡처, 작성, 검사, 스냅샷, 렌더만 직접 돌렸습니다. 웹페이지를 움직이게 하는 방식(스크롤, 스포트라이트, 커서 클릭, 말풍선)은 플러그인 안의 motion-graphics 스킬에 적힌 구성을 참고했습니다. 캡처가 시각 정보를 AI로 설명하는 단계는 API 키가 없어 건너뛰었고, 이번 영상에는 영향이 없었습니다.
6. 써 본 소감
영상을 코드로 쓴다는 발상이 짧은 모션 그래픽과 잘 맞았습니다. 문구나 색을 바꾸고 render만 다시 돌리면 되고, 되감아도 같은 결과가 나오게 만들어야 한다는 제약이 처음에는 낯설지만 check가 위반을 알려 줘서 따라가기 쉬웠습니다. 짧은 타이틀이나 숫자 장면에 특히 잘 맞았습니다. 렌더에 Chrome과 FFmpeg가 필요하다는 점, 그리고 이번처럼 스킬의 전체 순서를 생략해도 되는 경우와 아닌 경우를 구분해야 한다는 점은 기억해 둘 부분입니다.
Comments (0)