HyperFrames — HTML로 만드는 AI 영상

 

CLAUDE CODE PRACTICE

HyperFrames — HTML로 만드는 AI 영상
설치부터 나레이션 MP4 제출까지, 실강 완전판

FFmpeg 설치 → HyperFrames 설치 → 첫 영상 생성 → ElevenLabs 나레이션 병합 → 구글 드라이브 제출.

과정 생성형 AI 활용 마케팅 기획 업무생산성 향상 심화과정 (3일차) 주제 HyperFrames 기반 AI 영상 제작 실습 작성 한국부동산마케팅협회(KREMA) 발행일 2026-06-04

【목차】

• 01HyperFrames 개요
• 02사전 준비 — FFmpeg 설치
• 03HyperFrames 설치
• 04설치 확인 — MyVideo 폴더와 스킬 인식
• 05첫 영상 실습
• 06컴포지션의 구조 — AI가 만든 영상을 읽는 법
• 07ElevenLabs 화면 익히기 — 한국어 보이스와 Voice ID
• 08나레이션 병합 — 프롬프트 원문과 오류 대처
• 09API 키 보안 — .env 파일 원칙
• 103일 과정을 마치며 — 감, 자신감, 습관

HyperFrames(하이퍼프레임즈)는 AI 아바타 영상 서비스로 유명한 HeyGen(헤이젠)이 공개한 오픈소스 영상 렌더링 프레임워크입니다. 핵심 아이디어는 단순합니다. 웹페이지 언어인 HTML로 영상의 설계도(슬라이드 나열 + 애니메이션)를 쓰면, 그것을 실제 영상 파일(MP4)로 변환해 주는 것입니다.

FFmpeg와 HyperFrames를 설치하고, 부동산 이슈 영상을 직접 생성한 뒤, ElevenLabs(일레븐랩스) 나레이션을 입혀 MP4로 렌더링하고 구글 드라이브로 제출하는 전 과정을 실습했습니다. 코드를 한 줄도 직접 쓰지 않고 전부 Claude Code(클로드 코드)에게 한글 프롬프트로 지시해서 완성하는 것이 수업의 핵심입니다.

1. HyperFrames 개요 — HTML을 쓰면 영상이 나온다

지금까지 영상 제작은 After Effects, Premiere 같은 전문 도구의 영역이었습니다. 타임라인을 손으로 조작해야 하고, 라이선스 비용이 들고, 무엇보다 AI가 직접 만들 수 없어 사람의 개입이 필수였습니다. HyperFrames는 이 구조를 바꿉니다.

기존 영상 제작 방식

• After Effects, Premiere 등 전문 툴 학습 필요
• 타임라인과 레이어를 수동 조작 — 자동화 불가
• 라이선스 비용 + 렌더링 수수료 발생
• AI가 직접 만들 수 없음 — 사람 개입 필수

HyperFrames 방식

• HTML, CSS, JavaScript 조합으로 영상 정의 — 텍스트 파일이 곧 설계도
• AI 에이전트가 직접 영상 생성 — Claude, Cursor, Gemini 지원
• Apache 2.0 라이선스 — 완전 오픈소스, 상업적 사용 자유
• 결정론적(deterministic) 렌더링 — 같은 입력은 항상 같은 영상 출력

정체를 알면 쉽다 — "결국 HTML 슬라이드의 나열"

HyperFrames가 만드는 것은 index.html 한 장으로 구성된 슬라이드의 나열입니다. 슬라이드마다 JavaScript 애니메이션이 조금씩 들어가고, 그 화면들을 순서대로 캡처해 이어 붙여 MP4로 만드는 것뿐입니다. 그래서 이름이 "하이퍼 + 프레임즈"입니다. 그리고 이 마지막 "이어 붙여 영상으로 굽는" 작업을 뒤에서 처리해 주는 도구가 오늘 가장 먼저 설치한 FFmpeg(에프에프엠펙)입니다.

"HTML을 작성하면 영상이 나온다"는 말은 곧 "텍스트를 다루는 AI가 영상을 만들 수 있다"는 뜻입니다. AI는 영상 파일을 직접 편집하기는 어렵지만 텍스트(HTML 코드)를 쓰는 일은 가장 잘합니다. HyperFrames는 영상 제작을 텍스트 작성 문제로 바꿔놓은 프레임워크입니다. 단, 장면 하나하나를 코드로 쓰는 작업이라 AI 입장에서는 노가다성 업무이고, 토큰(사용량)을 매우 많이 소모합니다.

▶ 용어 미리 정리 (초보자용)

※ 렌더링(rendering) : 설계도(HTML)를 실제 영상 파일로 변환하는 과정. "굽는다"고 생각하면 쉽습니다.
※ FFmpeg : 영상을 자르고, 붙이고, 병합하는 멀티미디어 프레임워크. 캡컷이나 Premiere Pro가 하는 일을 까만 화면(명령어)으로 처리하는 원조 도구이며, 편집 프로그램들은 이것의 사용성을 개선한 GUI(그래픽 화면)라고 보면 됩니다.
※ 터미널 / CLI(Command Line Interface) : 명령어를 글자로 입력해 컴퓨터와 소통하는 창. Windows에서는 PowerShell(파워셸)이 이 역할을 합니다.
※ AI 에이전트 : 지시만 내리면 파일 생성, 명령 실행 등을 스스로 수행하는 AI. 이번 강의에서는 Claude Code를 사용.

2. 사전 준비 — FFmpeg 설치

설치 방법

설치 방식은 클로드에게 설치 방법을 물어보고, 알려주는 명령을 그대로 복사해 PowerShell에 붙여넣는 것뿐.

프롬프트 — 클로드 웹에서 FFmpeg가 무엇인지 설명하고 설치 방법 알려줘

• 클로드가 운영체제별 설치 방법을 안내합니다. Windows면 PowerShell을 (시작 메뉴에서 검색해) 실행하고, 안내된 설치 명령을 복사해 붙여넣은 뒤 엔터를 칩니다. 맥북이면 터미널에서 동일하게 진행합니다.
• 설치 확인 : PowerShell에 ffmpeg -version 을 입력했을 때 빨간 오류 없이 버전 정보가 줄줄이 나오면 정상입니다.

[이미지]

FFmpeg 설치 확인 화면 — PowerShell의 ffmpeg -version 출력

▶ 설치 오류가 났을 때 (실강에서 실제로 나온 대처법)

※ 확인 명령에서 빨간색 글씨가 나오면 잘못된 것입니다. 그 빨간 오류 내용을 전체 복사(또는 화면 전체 캡처)해서 클로드에 붙여넣고 "원인 분석해서 해결법 알려줘"라고 요청하세요. 터미널 내용은 전부 드래그 복사가 가능합니다.

Node.js 설치

HyperFrames는 HTML, CSS, JavaScript를 조합해 슬라이드형 애니메이션을 만드는데, 이 과정을 브라우저 바깥(내 PC)에서 실행하려면 Node.js(노드)가 필요합니다. 대부분 첫날 설치를 마쳤고, 미설치자는 검색해서 Node.js 공식 홈페이지에 들어가 운영체제에 맞는 설치 프로그램을 내려받아 기본값 그대로 설치하면 됩니다.

설치 항목	역할	설치 경로	확인 방법
FFmpeg	HTML 화면들을 이어 붙여 MP4로 굽는 백단 엔진	PowerShell(터미널)	ffmpeg -version
HyperFrames	영상 설계도(컴포지션) 프레임워크 + Claude용 스킬	Claude Code (3절 참조)	입력창에 / 입력 시 스킬 표시
Node.js	HTML/JS 애니메이션을 PC에서 구동하는 엔진	공식 홈페이지 설치 파일	node -v

이 설치들이 되어 있어야 클로드가 "내 컴퓨터에 있는" FFmpeg와 HyperFrames를 가져다 쓸 수 있습니다. 클로드 코드는 마법이 아니라, 내 PC에 설치된 도구들을 대신 조작해 주는 비서입니다. 백단에 도구가 없으면 비서도 일할 수 없습니다.

3. HyperFrames 설치

터미널 명령(npx) 방식과 그보다 더 쉬운 방법이 있습니다. GWS CLI를 설치할 때와 똑같은 패턴입니다.

STEP 1

빈 폴더 생성

오늘 작업 전용 별도 폴더

→

STEP 2

GitHub 주소 복사

HyperFrames 검색 → 깃허브

→

STEP 3

Claude Code 지시

"확인하고 이 경로에 설치해줘"

단계별 상세

• 1) 작업 폴더 생성 — 작업용 빈 폴더를 하나 새로 만듭니다.
• 2) GitHub 주소 복사 — "HyperFrames" GitHub(깃허브) 링크 주소창의 URL을 복사합니다.
• 3) Claude Code 실행 — Claude Code를 새 세션에서 방금 만든 빈 폴더를 워크스페이스로 선택합니다.
• 4) 설치 지시 — 복사한 URL을 붙여넣고 로컬에 설치를 합니다.

설치에는 수 분이 걸리며, 환경에 따라 중간에 안내 질문이 나오면 클로드의 안내를 따르면 됩니다.

▶ 왜 앞서는 웹에서 하고, 지금은 Claude Code에서 하나

웹 버전은 내 컴퓨터에 접근 권한이 없어 "방법 안내"까지만 가능합니다. 반면 HyperFrames 설치는 Claude Code(PC 버전)가 직접 수행합니다. Claude Code는 내가 지정한 폴더에 접근해 파일을 만들고 명령을 실행할 수 있기 때문입니다. 이 차이를 이해하면 어떤 작업을 어디에 시킬지 감이 잡힙니다.

4. 설치 확인 — MyVideo 폴더와 스킬 인식

설치가 끝나면 사용자 환경에 따라 결과가 케이스 바이 케이스로 다르지만 공통 원칙은 하나 — 설치 과정에서 클로드가 개별적으로 안내한 내용을 최우선으로 따른다입니다.

케이스 분기 — MyVideo 폴더가 생겼는가? 또는 샘플영상을 만들어 본다

[이미지]

설치 완료 후 작업 폴더 구조 화면

케이스	현상	대응
A. MyVideo 폴더 생성됨	설치 폴더 안에 MyVideo(마이비디오) 하위 폴더가 새로 생김	새 세션(+ New Session)을 열고 MyVideo 폴더를 선택해서 작업 시작
B. MyVideo 없음 (다수)	루트(설치한 그 폴더)에 바로 설치됨	새 세션에서 설치했던 폴더 그대로 선택해서 작업 시작 > 샘플영상을 제작해 봄

스킬 인식 확인 — 자동 완성이 뜨는가

정상 설치되면 HyperFrames가 Claude Code 안에 스킬(skill)로 내장됩니다. 스킬 목록에 하이퍼프레임 스킬이 나타나면 성공입니다.

• 스킬이 안 보일 때 — Claude를 완전히 종료했다가 다시 실행합니다. 프로그램이 재시작되어야 새로 설치된 스킬을 스캔합니다.

설치 → 새 세션 → 폴더 선택(MyVideo 또는 루트) → / 입력해 스킬 확인 → 안 되면 Claude 완전 재시작.

5. 첫 영상 실습 — 영상 만들기

세팅이 끝난 수강생들이 실제로 입력한 실습 프롬프트입니다.

실습 프롬프트 원문 최근 {**** 이슈} 한 가지를 택하고 온라인 서치하고, 하이퍼프레임즈 스킬 활용해서 해당 내용을 설명할 수 있는 다이내믹하고 지루하지 않은 영상 생성 후 브라우저로 표시해줘

영상 길이나 스타일은 각자 취향대로 바꿔도 됩니다. 핵심은 세 가지 — (1) 온라인 서치로 최신 내용을 가져오게 하고, (2) 하이퍼프레임즈 스킬을 쓰게 하고, (3) 바로 파일로 만들지 말고 브라우저로 먼저 표시하게 하는 것.

왜 "브라우저로 표시해줘"가 들어가는가

렌더링 전에 브라우저에서 결과를 슬라이드처럼 재생해 보고, 마음에 안 드는 부분을 프롬프트로 수정한 뒤에 최종 렌더링하기 위해서입니다.

단계	할 일	비고
1	실습 프롬프트 입력	리서치부터 시작하므로 생성에 꽤 오랜 시간이 걸림. 입력해 두고 기다리면 됨
2	브라우저 표시 확인	편집 화면처럼 뜨면 정상. 안 뜨면 "방금 생성한 영상을 브라우저에서 실행해줘"라고 요청
3	재생하며 검토	재생 버튼을 누르면 슬라이드가 순서대로 넘어감. 어색한 부분을 프롬프트로 지적
4	렌더링 지시	"영상 파일로 만들어줘" → MP4 생성. 저장 위치는 보통 작업 폴더 안 render 폴더

▶ 토큰(사용량) 주의 — 거듭 강조된 부분

이 작업은 장면 하나하나를 HTML/CSS 코드로 쓰는 노가다성 작업이라 토큰을 엄청나게 소모합니다. 클로드 디자인 등 다른 작업과 병행하면 더 빨리 소진되므로, 중요한 작업 전에는 사용량 여유를 확인하세요.

처음 세팅과 설치가 어렵지, 활용은 어렵지 않습니다. 프롬프트를 던져서 내가 원하는 대로 조정해 영상을 만들면 되는 것이니까요. 전문 분야가 있다면 이 기술로 양산형 영상을 만들어 보세요. AI가 만들었다는 이질감 때문에 조회수가 높지는 않아도, 시도가 없는 것보다는 낫습니다.

[영상 파일]election.mp4 (3.75MB)

[이미지]

샘플로 만들어본 지방선거 개표결과 영상

6. 컴포지션의 구조 — AI가 만든 영상을 읽는 법

컴포지션(composition)은 영상 한 편의 설계도이며, 실체는 index.html 같은 HTML 파일 하나입니다. AI가 대신 써 주더라도 구조를 알아 두면 "씬 2를 1초 늘려줘" 같은 수정 지시를 정확하게 내릴 수 있습니다.

개념	역할	비유
Composition(컴포지션)	영상 전체의 해상도, FPS(초당 프레임 수), 총 길이를 정의하는 최상위 컨테이너	영화 한 편의 기획서
Scene(씬)	장면 단위. 시작/끝 시간(밀리초, ms)으로 구간을 나누며 여러 씬이 순서대로 재생됨	영화의 장면 구분
Block(블록)	재사용 가능한 부품. 사전 제작 블록을 data-block="이름"으로 삽입	레고 부품

컴포지션 HTML 기본 구조 예시 <div data-composition data-duration="5000" <!-- 전체 길이: 5초(5000ms) --> data-fps="30" <!-- 초당 프레임 수 --> data-width="1920" data-height="1080"> <!-- 씬 1: 0초 ~ 2.5초 --> <div data-scene data-start="0" data-end="2500"> <h1 data-animate="fadeIn">안녕하세요</h1> </div> <!-- 씬 2: 2.5초 ~ 5초 --> <div data-scene data-start="2500" data-end="5000"> <p data-animate="slideUp">HyperFrames!</p> </div> </div>

data-로 시작하는 속성이 시간, 해상도, 애니메이션을 정의합니다. 1초 = 1,000ms이므로 data-start="2500"은 2.5초 지점 시작이라는 뜻입니다. fadeIn(서서히 나타남), slideUp(아래에서 올라옴) 같은 이름만 지정하면 효과가 적용됩니다.

이 HTML 파일은 더블클릭하면 브라우저에서 그냥 열립니다. 즉 "영상의 원본"이 텍스트 파일이라는 것 — 그래서 나중에 깃허브에 올려 배포할 수도, 일부 글자만 직접 고칠 수도 있는 것입니다.

7. ElevenLabs 화면 익히기 — 한국어 보이스 선택과 Voice ID

영상 생성이 돌아가는 동안 강의는 나레이션 준비로 넘어갔습니다. ElevenLabs(일레븐랩스)는 딥러닝 기반 음성 합성(TTS, Text-to-Speech) 전문 서비스로, 가입은 무료입니다. 검색해서 사이트에 들어가 가입과 로그인을 먼저 마칩니다.

화면 사용 순서 (실강 시연 그대로)

• 1) Voices 메뉴 — 좌측 메뉴의 Voices에 들어가면 음성 샘플 목록이 나옵니다. 처음에는 외국 보이스 위주로 보입니다.

[이미지]

ElevenLabs Voices 메뉴 화면

• 2) Language를 Korean으로 — 언어 필터를 한국어로 바꾸면 다양한 한국어 보이스가 나타납니다. 각 보이스에 표시된 숫자(예: 212.2K)는 그 목소리를 쓰는 사용자 수 — 높을수록 선호도가 검증된 보이스입니다.
• 3) 보이스 추가 — 마음에 드는 보이스의 플러스 버튼(Add to My Voices)을 누르면 내가 쓸 수 있는 음성으로 등록됩니다.
• 4) Text to Speech 테스트 — 좌측 중간의 Text to Speech 메뉴에서 등록한 보이스를 선택하고 텍스트를 입력해 Generate하면 음성이 생성됩니다. 무료 플랜에서도 수천 자 단위 생성이 가능합니다(실강 기준 약 5,000자 안내, 정확한 한도는 가입 시점 정책 확인 필요).
• 5) Voice ID 복사 — 보이스 우측의 점 세 개(...) 메뉴 → Copy Voice ID. 영문과 숫자가 섞인 이상한 값이 복사되는데, 이것이 핵심입니다.

음성 미세 조정 3종 슬라이더

[이미지]

음성 미세 조정 슬라이더(Speed / Stability / Similarity) 화면

설정	역할	실강 팁
Speed	말하는 속도	정보 전달 영상은 약간 빠르게 해도 자연스러움
Stability	목소리 높낮이의 안정성(다이내믹 정도)	낮추면 이상한 음성이 나옴 — 차분한 나레이션은 높게 유지가 안전
Similarity	원본 목소리와의 일관성 유지 정도	기본값 부근 권장. 전부 최대치로 올리면 쇼츠용 과장된 목소리도 가능

ElevenLabs는 수만 개의 보이스를 사람 이름이 아니라 고유한 Voice ID로 관리합니다(동명이인 문제 방지). 화면에 보이는 "Anna Kim" 같은 이름은 표시용일 뿐이고, API로 음성을 만들 때는 반드시 이 ID 값을 전달해야 합니다.

8. 나레이션 병합 — 프롬프트 원문과 오류 대처

이제 영상에 음성을 입힙니다. 사람에게 일을 시킨다고 생각하면 순서가 보입니다 — 영상은 이미 있으니, (1) 영상 내용에 맞는 스크립트를 쓰고, (2) 그 스크립트로 음성 파일을 만들고, (3) 영상과 병합하는 것. 이 워크플로 전체를 한 번에 클로드에게 지시합니다.

나레이션 병합 프롬프트 (실강 원문 구조) 이 영상에 나레이션을 넣고 싶어. 구성된 내용으로 스크립트를 먼저 작성하고, 나레이션 음성 파일 생성과 영상 병합까지 해줘.

클로드가 스크립트 작성 → ElevenLabs API 호출(MP3 생성) → FFmpeg 병합까지 알아서 처리합니다. 결과 영상 하단에 나레이션이 표시되며 음성이 입혀집니다. 이때 음성 제작을 위해서는 ElevenLabs API 키를 발급받아야 합니다.

실제 발생한 오류 — 한국어 대신 외국어 음성

한 수강생의 영상에서 스크립트와 달리 음성이 계속 외국어로 출력되는 오류가 났습니다. 원인은 클로드가 스크립트를 외국어로 짠 것. 대처 프롬프트는 다음과 같습니다.

프롬프트 — 한국어 출력 오류 대처 지금 음성이 외국어로 나오고 있어. 스크립트가 한국어로 작성됐는지 더블 체크하고, 정확하게 한국어로 다시 만들어서 음성 생성부터 다시 해줘

▶ 콘텐츠 제작의 기준 — "나레이션이 기준이다"

※ 생성형 AI 음악(Suno 등)은 1분을 요청해도 1분 30초가 나오는 등 길이가 랜덤합니다.
※ 정보 전달형 영상(카드뉴스, 쇼츠)에서는 나레이션이 중간에 끊기면 맥이 완전히 끊기므로, 나레이션 길이를 기준으로 이미지 배열과 음악의 시작/끝을 맞추는 것이 필요합니다.
※ 반대로 뮤직비디오는 음악이 가장 중요한 소스이므로 음악이 기준이 되고 이미지와 영상이 음악 길이에 맞춥니다.

▶ 한글 파일명 주의

콘텐츠 생성 작업에서 한글이 변수가 되는 경우가 종종 있습니다. 파일명과 작업 폴더명은 가급적 영어로 쓰고, 자막 등 결과물에 들어가야 하는 한글은 "콘텐츠는 한국어로"라고 명시적으로 전달하세요. 유니코드 처리가 어설프면 자막이 깨질 수 있습니다.

9. API 키 보안 — .env 파일 원칙

ElevenLabs 같은 외부 서비스를 쓰려면 API 키(사용 권한을 증명하는 비밀번호 같은 문자열)가 필요합니다. 개인 키를 쓸 때의 정석은 .env 파일(환경변수 파일)입니다.

.env 파일이 있으면 클로드가 키를 자동으로 읽어옵니다. 프롬프트에는 "키는 .env에 있어"라고만 쓰면 됩니다.

절대 하지 말 것

• API 키를 채팅창에 직접 붙여넣기 (한 번이라도 붙여넣은 키는 유출로 간주하고 즉시 재발급)
• .env 파일을 GitHub에 커밋(업로드)
• 코드 안에 키를 하드코딩(직접 써넣기)

.gitignore 필수 항목

• .env — 키 파일 자체를 버전 관리에서 제외
• *.mp3, *.mp4 — 용량 큰 산출물 제외
• render/ — 렌더링 결과 폴더 제외

10. 과정을 마치며

AI 활용 업무생산성 향상 심화과정에서 다룬 주제는 모두 11가지 — 생성형 AI와 에이전트의 개념, Claude Code · Cowork · Chat의 구분, GUI/CLI 등 컴퓨터 기초 용어, Node.js · Python · Git 개발 환경, 웹 개발 기초(프론트엔드/백엔드, HTML/CSS/JS), Git과 GitHub 배포, Vercel 배포, GWS CLI 구글 시트 연동과 VOC 대시보드, 그리고 오늘의 FFmpeg + HyperFrames 영상 제작까지입니다.

3일 만에 이 내용을 다 이해하는 것은 불가능하고, 그래야 할 필요도 없습니다. 여기서 얻어갈 것은 각 기술의 이해가 아니라 감입니다 — AI가 현재 어디까지 와 있는지, 그리고 그 수준이 생각보다 대단히 높지도, 나와 멀지도 않다는 감. 그 감이 자신감이 되고, 자주 활용하는 습관이 되면 됩니다. AI가 대중화된 것은 2022년 ChatGPT 이후 겨우 4년 — 전문성이 확립되기엔 이른, 누구나 전문가가 될 수 있는 과도기입니다. 작년과 올해의 AI 영상 품질이 완전히 다르듯, 내년에는 거의 완벽한 수준에 도달할 것입니다. 이 흐름에 대한 감을 계속 가지고 가십시오. 지식의 가치는 예전 같지 않습니다 — 찾으면 그만이고, 물어보면 그만입니다.

에이전틱 워크플로(agentic workflow) — AI 에이전트와 소통하며 작업물을 만들어가는 지금의 방식 — 가 빠르게 표준화, 범용화되고 있습니다. 이번에 만든 포트폴리오와 영상은 전부 내 자산입니다. 돌아가서 계속 수정, 보완해 이력서와 실무에 실제로 활용하는 것이 이 교육의 완성입니다.

한국부동산마케팅협회(KREMA) · HyperFrames 기반 AI 영상 제작 실습