HyperFrames 입문: Claude Code에 한 문장 부탁하여 HTML로 MP4 영상 만들기 (수정 및 효과음까지)

HyperFrames는 HeyGen이 공개한 오픈소스(Apache 2.0) 비디오 도구입니다. HTML로 작성된 화면을 헤드리스 Chrome으로 프레임 단위로 캡처하고, FFmpeg로 MP4 파일로 만듭니다.

본문에서는 Claude Code에 한 문장 부탁하여 20초 분량의 3개 장면 홍보 영상을 MP4로 추출하는 과정과, 같은 대화의 연장선상에서 색 보정 및 효과음 추가까지 요청한 과정을 제가 시도한 절차대로 재현합니다.

결론부터 말하자면, 한 문장의 요청만으로 MP4 파일이 생성되었고, 수정이나 음향 효과까지 텍스트로 요청할 수 있었습니다. 다만 요청하지 않은 부분이 움직일 때가 있으므로, 추출된 영상은 같은 시점의 프레임을 나란히 놓고 확인해야 합니다.

영상 편집 소프트웨어를 사용하지 않고, git과 AI 코딩 에이전트로 짧은 영상을 만들고 싶은 개발자에게 적합한 글입니다.

전체 개요: 비디오는 HTML 한 장, 추출은 내 손의 HyperFrames

AI가 작성하는 것은 왼쪽의 HTML까지입니다. 오른쪽 2단은 제가 가진 HyperFrames가 담당합니다 (공식 README를 기반으로 제작 · 2026-09-24 취득)

HyperFrames에서는 비디오 한 편이 하나의 HTML 파일입니다. '언제, 무엇을, 어떻게 움직일지'를 그 안에 작성하면, HyperFrames가 브라우저에서 프레임 단위로 캡처하여 MP4로 만듭니다. 공식 README의 제목은 다음과 같습니다.

Write HTML. Render video. Built for agents.

(HTML을 작성한다. 비디오를 렌더링한다. 에이전트를 위해 만들어졌다)

애초부터 AI 코딩 에이전트가 HTML을 작성한다는 전제하에 설계된 도구입니다. 역할은 다음 세 가지로 나뉩니다.

AI가 작성한 HTML 예시

실제로 AI가 작성한 index.html에서, 2번째 장면(GitHub 별 개수 카운트업) 부분을 발췌했습니다. data-start와 data-duration은 해당 장면을 몇 초부터 얼마나 오랫동안 보여줄지 지정하는 값입니다.

<div id=

설정하지 않은 채 끝까지 진행했습니다. 로그인이나 키를 요구하는 장면은 한 번도 없었습니다. HyperFrames 자체는 무료이며, AI에게 작성하도록 하는 부분의 이용료는 별도로 발생합니다.

### 준비물

- **Node.js 22 이상**과 **FFmpeg**(2026-10-05 시점 README의 Requirements 항목)
- **출력용 Chrome**. 가지고 있지 않다면 `npx hyperframes browser ensure`로 찾거나 가져옵니다.
- **Claude Code**

환경은 `npx hyperframes doctor`로 점검할 수 있습니다. Node, FFmpeg, FFprobe, Chrome 등이 목록으로 나열됩니다.

## 단계 0: 틀을 만들고 git에 넣기

npx hyperframes init teaser
cd teaser
git init && git add -A && git commit -m init

git에 넣는 이유는, 나중에 수정을 부탁할 때 무엇이 어떻게 바뀌었는지 차이점(diff)으로 읽기 위함입니다.

`init` 직후의 틀을 `npx hyperframes render`로 출력하면, 내용은 'Title' 글자만 있는 백지 상태입니다. 그래도 1920×1080・30fps・10초짜리 MP4가 되며, 출력은 20~30초 정도 걸렸습니다. 브라우저에서 확인하려면 `npx hyperframes preview`를 사용합니다(제 환경에서는 localhost:3002에서 열렸습니다).

2026-10-05 시점 README에는 Claude Code 전용 플러그인으로 넣는 방법도 나와 있습니다(`claude plugin marketplace add heygen-com/hyperframes` → `claude plugin install hyperframes@hyperframes`). 저는 `init`에 포함된 스킬로 시도했고, 플러그인을 통한 방식은 시도하지 않았습니다.

## 단계 1: Claude Code를 실행하고 명령어 허용 여부를 결정하기

AI는 출력 도중에 `npx hyperframes …`나 `npm run …`을 스스로 입력합니다. 대화 모드인 `claude`로 부탁할 경우, 명령어마다 허가를 요청하므로 내용을 보고 허가합니다.

저는 기록을 남기기 위해 비대화형(`claude -p`)으로 부탁했습니다. 허용할 도구를 미리 `--allowedTools`로 전달하는 방식입니다. 아래는 실제로 사용한 형태에서 제 환경만의 항목을 제외하고 정리한 것입니다.

claude -p --model sonnet --permission-mode acceptEdits
--allowedTools

실제로 사용한 문구를 그대로 넣었습니다. '이 채널'은 제 YouTube 채널에 대한 것이므로, 자신의 공지 내용으로 바꿔서 사용할 수 있습니다.

처음에 시도했던 10초짜리 간단한 버전은 글자와 움직임만 있는 소박한 결과물이었습니다. 저에게는 부족했기 때문에, 장면을 3개로 늘리고 전환과 공식 부품도 요청한 것이 이 문구입니다. 중간에 입은 한 번도 내지 않았습니다. 약 6분 기다려서 renders/teaser.mp4

(1920×1080・H.264・20.0초)가 나왔습니다.

위에서 4.0초・10.0초・19.0초의 프레임입니다. 요청한 3가지 장면(단말기・카운트업・구독 마감)이 갖춰져 있습니다.

첫 번째 장면의 단말기 진행 상황은 영상 속 연출이며, 실제 쓰기 로그는 아닙니다. AI에게 의존하지 않고 직접 쓰기를 다시 할 때도 npx hyperframes render

한 줄이면 충분합니다. 20초짜리 영상에 약 35초가 걸렸습니다.

최소의 예 (10초짜리 간단한 버전)

템플릿 상태에서 다음 한 문구만으로, 10초 정도의 공지(renders/announce.mp4

)가 약 2분 만에 나왔습니다. 우선 작게 시도해 보고 싶다면 여기가 간편합니다.

이 프로젝트로 '터미널 도구의 신작 영상, 공개했습니다'라는 10초 정도의 공지 영상을 만들어서 renders/announce.mp4에 쓰기해주세요

AI는 무엇을 했나

기록을 보니, AI가 갑자기 HTML을 쓰기 시작한 것은 아닙니다. 다음 순서로 진행했습니다.

• 설명서를 읽기: :init

이 넣어준 스킬(~/.claude/skills/hyperframes)을 읽음 -
부품 찾고 조합하기: :npx hyperframes catalog --query …

로 공식 부품(블록)을 검색하고, :npx hyperframes add …

으로 5개를 조합함 -
검사 및 샘플: :npm run check

을 거쳐서, :npx hyperframes snapshot --at …

으로 지정한 시점의 프레임을 찍어 확인함 -
쓰기: :npm run render -- --output renders/teaser.mp4

add

한 5개의 부품이 각각 영상의 어느 부분에 해당되는지 대응표입니다 (AI가 친 명령어 기록에서 발췌・2026-09-25)

조합된 것은 code-terminal-run
・count-up
・yt-lower-third
・grain-overlay
・organic-light-leak-overlay

의 5가지입니다. 그대로 사용한 것이 아니라, yt-lower-third

의 아바타 이미지나 채널명・구독자 수를 빼고 문구를 일본어로 교체했습니다 (AI 보고에 따름).

그렇다면 AI에게 FFmpeg 스크립트를 쓰게 하는 방법과 무엇이 다를까요. 차이는, 부품의 카탈로그・설명서・검사・프레임 샘플이 도구 쪽에 갖춰져 있다는 점입니다. AI는 그것을 손잡이 삼아 진행했습니다.

단계 3: 같은 대화의 연장선으로 수정 요청하기

단계 1에서 기록한 session_id

를 --resume

에 전달하여, 같은 대화의 연속으로 요청합니다 (다른 옵션은 단계 1과 동일). 대화 모드라면, 같은 화면에서 계속 입력만 하면 됩니다.

claude -p --resume <session_id> --model sonnet --permission-mode acceptEdits
--allowedTools "（手順1과 동일）"
-- "전체 색상을 채널의 파란색(#2F6DB5)으로 통일하고, 2장면의 숫자를 더 크게 눈에 띄게 해줘"

약 1분 반 만에 다시 작성되었고, 전체가 파란 계열로, 숫자는 화면 폭 가득하게 되었습니다.

같은 10초 지점의 프레임에서 색상과 숫자 크기만 바뀌었음을 확인해 보세요 (추출된 영상의 프레임・2026-09-25)

템플릿을 git에 넣어두었기 때문에, 변경된 줄은 git diff로 읽을 수 있습니다. 수정된 것은 삽입한 부품을 포함하여 5개의 파일이었습니다.

색상 값, 글자 위치, 숫자 크기의 3가지 종류의 변경으로 나뉩니다 (수정 전 → 수정 후 git diff・2026-09-25)

숫자에 맞춰 상하의 글자도 움직이고 있습니다. 이것은 요청하지 않은 변경입니다. 이번에는 그 이동이 AI의 보고서에 적혀 있었습니다. 보고서 본문은 다음과 같습니다.

레이블과의 조화를 위해, 'GITHUB STARS'를 조금 위로, '2026년 9월 기준'을 조금 아래로 움직였습니다.

단계4: 소리도 문장으로 요청하기

같은 대화의 연장선에서 소리를 요청했습니다 (--resume 형식은 단계3과 동일).

落ち着いたBGMを敷いて、場面の切り替えと数字が止まるところに効果音を入れて、最後に『チャンネル登録よろしくなのだ』を日本語の声で読み上げて付けて

'~なのだ'는 제 채널 캐릭터의 말투입니다. 본인의 영상이라면, 마무리 한마디로 대체해 주세요.

결과는 다음과 같습니다:

• 효과음: HyperFrames에 포함된 효과음 중에서 선택되어, 장면 전환 2곳과 52,700이 도달하는 지점에 삽입되었습니다 -
• BGM: 사인인하지 않았기 때문에 기성곡 카탈로그를 사용할 수 없어, AI가 ffmpeg로 사인파의 화음을 쌓아 calm-pad.wav를 직접 제작했습니다 -
• 영상: 변함없이 HTML의 차이점은 <audio> 주변 5줄뿐이었습니다 -
• 음성: 후술했듯이, 저는 채택하지 않았습니다.

추출된 영상은 같은 시각의 프레임을 나열하여 확인하기

여기서 이 도구를 사용할 때 가장 주의해야 할 점입니다. 처음에 시도했던 10초짜리 간단한 버전에서 '색상을 파란색으로 하고, 마지막에 한마디를 추가해줘'라고 요청했을 때는, 보고서에는 없는데 제목 위치가 어긋나 있었습니다.

분홍색 점선에 대해, 오른쪽 제목인 '터미널 도구의'만 위로 어긋나 있습니다 (추출된 영상의 프레임・2026-09-24)

추가한 한마디의 틀이 중앙 정렬 블록에 추가되면서, 제목이 약 100px 위로 밀려 올라가 있었습니다. 변경은 index.html 1개 파일, 약 30줄에서 차이점도 읽을 수 있습니다. 그럼에도 불구하고 차이점 단계에서는 이 어긋남을 알아차릴 수 없었고, 프레임을 나열해 보고서야 알게 되었습니다.

같은 시각의 1프레임은 ffmpeg로 추출합니다. 수정 전 MP4를 다른 이름으로 남겨두고, 수정한 후와 같은 초 단위로 추출하여 나란히 놓습니다.

cp renders/announce.mp4 before.mp4 # 수정을 요청하기 전에 남기기
ffmpeg -ss 7.5 -i before.mp4 -frames:v 1 before_t7.5.png
ffmpeg -ss 7.5 -i renders/announce.mp4 -frames:v 1 after_t7.5.png

단계3의 수정처럼 보고서에 전부 적혀 있는 경우도 있고, 적혀 있지 않은 경우도 있습니다. 차이점과 보고서를 읽은 후에는, 마지막으로 추출된 것을 자신의 눈과 귀로 확인해 주세요.

걸림돌

추출을 위해서는 외부 통신이 필요함

템플릿은 추출할 때 애니메이션 부품(GSAP)을 CDN에서 불러오고, 폰트도 외부에서 불러옵니다. 외부 배포처에 도달하지 않는 환경에서는 추출이 실패했습니다. 저는 npm i gsap로 로컬에 넣고, index.html의 읽기 방식을 다음과 같이 수정하여 통과시켰습니다.

<!-- 변경 전 -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<!-- 변경 후 -->
...

공식 부품에도 CDN 로딩이 포함되어 있으므로, 이 점을 프로젝트의 CLAUDE.md에 한 줄 적어주세요. 사내 네트워크 등 외부 통신이 제한된 환경에서는 같은 조치가 필요합니다.

목소리는 준비한 음성 파일을 전달한다

CLI에는 로컬 모델(Kokoro-82M)로 목소리를 만드는 tts가 있습니다. 하지만 Python 부품(kokoro-onnx, soundfile)과 일본어 발음을 위해서는 espeak-ng가 별도로 필요하며, 제 환경에서는 모델을 포함하여 약 420MB가 되었습니다. 제가 만들게 한 일본어 목소리를 들어보니 일본어로 알아들을 수 없어 채택하지 않았습니다. 내레이션을 넣으려면 직접 준비한 음성 파일을 전달해서 구성하게 하는 것이 확실합니다. AI는 소리를 <audio> 요소에 시간을 지정하여 포함하므로, 파일만 있다면 배치와 타이밍을 요청할 수 있습니다.

효과음・BGM의 라이선스를 확인한다

첨부된 효과음은 HeyGen 측 신고에 따르면 Pixabay Content License입니다. 로그인 없이 곡을 만드는 경로 중 하나인 MusicGen은 모델 가중치가 CC-BY-NC 4.0(비상업적)입니다. 이번 BGM은 AI가 ffmpeg로 합성한 것이므로 이 문제는 없었습니다. 상용 영상에 사용할 경우, 어느 경로의 소리인지 확인해 주세요.

Linux arm64에서 추출용 Chrome을 준비할 수 없었다

제가 시도한 Linux arm64에서는 npx hyperframes browser ensure가 'not available for Linux ARM64'를 표시하며 Chrome을 가져올 수 없었습니다. 따로 준비한 헤드리스 Chrome(Playwright에 포함된 headless_shell)을 환경 변수 HYPERFRAMES_BROWSER_PATH로 지정하여 사용했습니다. 이 변수는 공식 리포지토리의 소스와 주간 업데이트 기록에서 추출용 브라우저를 지정하는 공식 명칭으로 취급되고 있습니다 (2026-10-05 확인). x86_64 Linux나 macOS에서 browser ensure가 작동할지는 시험해 보지 않았습니다.

적합한 상황 / 부적합한 상황

적합한 상황

• 텍스트와 움직임이 중심인 짧은 영상: 공지, 기능 소개, 데이터 그래프, 코드 차분 설명, 자막付き의 세로형 쇼츠 등. 저는 마찬가지로 한 문장씩 요청하여 그래프・세로형 쇼츠・코드 차분 설명을 각각 1개씩 만들었습니다 (이 3개는 공식 부품을 사용하지 않았습니다)
• 같은 유형의 영상을 문구나 숫자만 바꿔서 여러 개 만들고 싶은 경우. 영상이 텍스트이기 때문에, 수정이나 교체는 글로 요청할 수 있고, 차이점을 추적할 수 있습니다.

부적합한 상황・다른 도구와 결합하는 상황

• 실사 영상이나 사람이 말하는 아바타 영상 그 자체. 공식 가이드에서는 촬영된 영상이나 HeyGen 측에서 만든 아바타 클립을 소재로 가져와, 그 주변의 텍스트나 움직임을 HyperFrames로 구성하는 방식을 안내하고 있습니다.
• 요청한 것 외에 일절 바뀌어서는 안 되는 작업을 확인 없이 반복하고 싶은 경우. 요청하지 않은 부분이 움직일 수 있으므로, 보고 확인하는 수고는 남아 있습니다.
• 외부 통신이 불가능한 환경 (초안은 추출 시점에 외부에서 로딩합니다)

요약

제가 가장 전하고 싶은 것은, 영상을 쉽게 만들 수 있다는 점입니다.

시도해 보면서 제가 가치를 느낀 부분은, 영상 편집 소프트웨어를 한 번도 열지 않고, 요청하기・보기・수정하기・음악을 추가하는 과정 전체를 텍스트만으로 처리할 수 있었다는 점입니다. 공지처럼 텍스트와 움직임이 중심인 짧은 영상은 이 도구에 맡길 수 있다고 판단했습니다. 그 대신, 추출된 것을 보고 확인하는 작업은 사람에게 남습니다.

• HyperFrames는 HTML로 작성한 영상을 로컬 헤드리스 Chrome과 FFmpeg으로 MP4에 추출하는 도구입니다. AI가 작성하는 것은 HTML까지이고, 영상을 만드는 것은 HyperFrames입니다.
• Claude Code에 한 문장을 요청하자, 공식 부품을 찾아 구성하고, 검사 및 프레임 샘플로 확인한 후, 20초・3 장면의 공지 영상을 추출했습니다.
• 수정이나 음악도 같은 대화의 연속에 텍스트로 요청할 수 있었습니다. 바뀐 부분은 git의 차이점과 AI의 보고서에서 읽을 수 있습니다.
• 요청하지 않은 부분이 움직이고, 보고서에도 없는 것이 있었습니다. 추출된 것은 같은 시간대의 프레임을 나열하여 확인해야 합니다.

init
은 홈 디렉터리 하위에 스킬을 넣습니다. 추출에는 외부 통신이 필요합니다. 이 2가지는 시도하기 전에 알아두세요.
먼저 npx hyperframes init

템플릿을 만들고 git에 넣은 다음, 한 문장으로 공지 영상을 요청해 보세요.

이 글의 내용은 영상에서도 설명하고 있습니다 → 【HyperFrames 입문】영상 편집 소프트웨어 없이, 요청만으로 영상 제작 가능

참고 링크 (1차 정보)

• heygen-com/hyperframes (공식 리포지토리)
• README (HTML 작성. 비디오 렌더링. 에이전트를 위해 구축됨.・원리・요구사항・Claude Code 플러그인)
• CLI 레퍼런스 (init・render・preview・doctor・browser・skills・tts)
• 인증 및 API 키 (계정 없이 로컬에서 제작 가능・사인인 시 추가되는 항목)
• 아바타 발표자 추가 (실사 또는 아바타와 결합하는 방법)
• 주간 업데이트 기록 (HYPERFRAMES_BROWSER_PATH 기재됨)
• 릴리스 목록
• heygen-com/heygen-cli (HeyGen의 커맨드라인 도구. HeyGen 서비스 범위)
• facebookresearch/audiocraft (MusicGen 라이선스)

토론