Hyperframes 사용법, 윈도우에서 설치부터 AI로 MP4 영상 만들기까지

먼저 설치하세요: Node.js 윈도우 설치 방법, 처음 쓰는 사람을 위한 안내 FFmpeg 윈도우 설치 방법과 처음 쓰는 명령 3가지

Hyperframes는 Node.js 위에서 실행되고, 마지막에 장면을 MP4로 묶을 때 FFmpeg를 씁니다. 두 프로그램이 먼저 설치되어 있어야 합니다. 특히 Node.js 글의 스크립트 실행 허용 단계까지 마쳐서 npx --version이 되는 상태여야 합니다. 그 단계를 건너뛰면 이 글의 npx 명령이 모두 빨간 오류로 멈춥니다.

Hyperframes는 웹페이지처럼 만든 장면을 시간 순서대로 촬영해 MP4 영상으로 만들어 주는 도구입니다. HeyGen이 만들어 오픈소스(Apache 2.0)로 공개했고, 내 컴퓨터에서 렌더링하는 데에는 비용이 들지 않습니다.

비유하자면 웹페이지로 만드는 파워포인트 애니메이션입니다. 글자, 도형, 이미지, 음성을 웹페이지 한 장에 올려 두고 "1초에 제목이 나타나고 4초에 사라진다"처럼 시간을 정해 두면, Hyperframes가 그 페이지를 한 프레임씩 찍어 영상 파일로 묶습니다.

장면을 만드는 코드는 사람이 직접 쓰지 않아도 됩니다. Hyperframes는 처음부터 AI가 쓰기 좋게 설계되었고, AI에게 작업 방법을 알려 주는 설명서(스킬)도 함께 제공합니다. 사람은 원하는 영상을 말로 설명하고, 미리보기를 보며 고칠 점을 말해 주면 됩니다.

이 수업에서 하는 일

「영상 제작을 위한 AI 활용」 수업에서는 Hyperframes를 세 번 만납니다.

1) 00:20 설치 시간에 Hyperframes와 AI용 스킬을 준비합니다. 2) 01:10 모션그래픽 실습에서 10초짜리 짧은 모션그래픽을 만듭니다. 글자와 도형이 움직이며 제품 특징이나 처리 단계를 보여 주는 영상입니다. 3) 02:10 영상 제작 실습에서 준비한 화면 자료와 Whisper로 만든 시간표(타임테이블)를 넘겨 30~60초 설명 영상을 만듭니다.

작업 흐름은 늘 같습니다. ChatGPT 데스크톱 앱의 Codex에게 Hyperframes 스킬을 써서 장면을 만들어 달라고 요청합니다. Codex가 프로젝트 폴더에 장면 파일을 만들고 미리보기를 엽니다. 사람은 미리보기를 보면서 "제목을 더 크게", "두 번째 장면을 1초 늘려 줘"처럼 수정을 요청합니다. 마음에 들면 MP4로 렌더링합니다.

윈도우에서 준비하기

Hyperframes는 따로 설치 파일이 없습니다. Node.js에 들어 있는 npx라는 실행 도구가 필요할 때 Hyperframes를 내려받아 실행합니다. 그래서 이 단계에서 할 일은 선행 프로그램 확인, 작업 폴더 만들기, AI용 스킬 설치 세 가지입니다.

1) 시작 메뉴에서 PowerShell을 검색해 엽니다. Node.js나 FFmpeg를 방금 설치했다면 열려 있던 창을 닫고 새 창을 여세요. 설치 전에 열어 둔 창은 새 프로그램을 찾지 못합니다. 2) 아래 세 명령으로 선행 프로그램을 확인합니다.

node -v
npx --version
ffmpeg -version

첫 줄은 Node.js 버전을, 둘째 줄은 npx 버전을, 셋째 줄은 FFmpeg 버전을 보여 줍니다. Hyperframes는 Node.js 22 이상이 필요하므로 node -v 결과가 v22로 시작하거나 그보다 커야 합니다.

v22.12.0
10.9.0
ffmpeg version 7.1 ...

숫자는 컴퓨터마다 다릅니다. "인식되지 않습니다"라는 오류가 나오면 위의 선행 글로 돌아가 설치를 마쳐 주세요. npx --version에서만 "스크립트를 실행할 수 없으므로 npx.ps1 파일을 로드할 수 없습니다"라는 오류가 나오면 Node.js 글의 스크립트 실행 허용하기 단계를 진행합니다.

3) 실습용 폴더를 만들고 그 안으로 이동합니다.

cd $HOME
mkdir hyperframes-practice
cd hyperframes-practice

첫 줄은 내 사용자 폴더(C:\Users\내이름)로 이동하고, 둘째 줄은 hyperframes-practice라는 폴더를 만들고, 셋째 줄은 그 폴더 안으로 들어갑니다. 폴더 이름은 영어와 숫자로 짓는 편이 문제가 적습니다.

4) AI용 Hyperframes 스킬을 설치합니다.

npx hyperframes skills update

이 명령은 Hyperframes의 핵심 스킬 묶음을 내 컴퓨터의 공용 스킬 폴더(사용자 폴더 아래 .agents\skills)에 설치합니다. Codex는 이 폴더를 모든 프로젝트에서 읽습니다. 다시 실행하면 스킬을 최신으로 갱신합니다.

npx로 처음 실행하는 패키지라면 아래처럼 내려받아도 되는지 묻습니다. y를 입력하고 Enter를 누르면 됩니다.

Need to install the following packages:
hyperframes@...
Ok to proceed? (y)

5) 스킬을 설치한 뒤에는 Codex에서 새 대화(세션)를 시작해야 스킬을 알아봅니다. 이미 열어 둔 대화에서는 보이지 않을 수 있습니다.

참고로 Hyperframes에는 윈도우용 Studio 데스크톱 앱도 있습니다. 터미널 없이 AI와 미리보기를 한 창에서 쓰는 앱이지만 HeyGen 계정 로그인이 필요합니다. 이 수업은 Codex와 명령어 방식으로 진행합니다.

설치 확인

Hyperframes는 내 컴퓨터가 렌더링할 준비가 되었는지 점검하는 명령을 제공합니다.

npx hyperframes doctor

Node.js, FFmpeg, 렌더링용 크롬 브라우저 등 필요한 항목을 하나씩 확인해 결과를 보여 줍니다. 공식 문서에 실린 출력 예시는 다음과 같은 모양입니다.

hyperframes doctor

  ✓ Version          0.1.4 (latest)
  ✓ Node.js          v22.x (linux x64)
  ✓ FFmpeg            7.x
  ✓ FFprobe           7.x
  ✓ Chrome            (system or cached)
  ✓ Docker            24.x
  ✓ Docker running    Running

  ◇  All checks passed

버전 숫자와 표시 항목은 내 컴퓨터와 다를 수 있습니다. 이 수업에서 꼭 통과해야 하는 줄은 Node.js, FFmpeg, FFprobe, Chrome입니다. Docker는 이 수업에서 쓰지 않으므로 표시가 달라도 괜찮습니다.

스킬이 제대로 설치됐는지는 아래 명령으로 확인합니다. 아무것도 바꾸지 않고 상태만 알려 줍니다.

npx hyperframes skills check

처음 써 보기

예제 1은 명령어만으로 기본 프로젝트를 만들어 보는 연습입니다. Hyperframes가 어떻게 움직이는지 감을 잡는 용도이고, 실제 수업에서는 이 과정을 AI가 대신합니다.

npx hyperframes init my-video

my-video라는 새 프로젝트 폴더를 만들고 기본 장면을 넣어 줍니다. 진행 중에 몇 가지를 물어볼 수 있는데, 잘 모르겠으면 미리 선택된 항목에서 Enter를 누르면 됩니다. 질문 없이 기본값으로 만들고 싶다면 끝에 --non-interactive를 붙입니다.

cd my-video
npx hyperframes preview

첫 줄로 프로젝트 폴더에 들어가고, 둘째 줄로 미리보기를 엽니다. 브라우저에 편집 화면이 열리고 장면을 재생해 볼 수 있습니다. 장면 파일이 바뀌면 미리보기도 자동으로 새로 고쳐집니다. 미리보기를 끝내려면 PowerShell 창에서 Ctrl + C를 누릅니다.

npx hyperframes render --output final.mp4

프로젝트를 final.mp4라는 영상 파일로 렌더링합니다. --output을 빼면 프로젝트 안의 renders 폴더에 날짜와 시간이 붙은 이름으로 저장됩니다. 탐색기에서 파일을 더블클릭해 재생해 보세요.

예제 2는 Codex에게 모션그래픽을 요청하는 연습입니다. ChatGPT 데스크톱 앱에서 Codex를 열고, 작업 폴더를 앞에서 만든 hyperframes-practice로 지정한 뒤 새 대화에 아래처럼 보냅니다. Codex에서는 $hyperframes라고 쓰면 Hyperframes 스킬을 쓰라는 뜻이 됩니다.

$hyperframes 스킬을 사용해 10초짜리 1920x1080 모션그래픽을 만들어 줘.

보는 사람: 우리 제품을 처음 설치하는 고객
핵심 메시지: "설치는 세 단계면 끝납니다"
구성: 제목 등장(0~2초) → 1단계, 2단계, 3단계가 차례로 나타남(2~8초) → 마무리 문구(8~10초)
분위기: 밝고 깔끔하게, 파란색 계열
글자: 한글이 깨지지 않도록 한글 글꼴을 프로젝트에 포함해 줘

다 만들면 미리보기를 열고 프로젝트 폴더 위치를 알려 줘.

Codex가 명령을 실행하거나 인터넷을 써도 되는지 물을 수 있습니다. 스킬이 패키지를 설치하고 미리보기 서버를 띄우고 렌더링을 실행하기 때문입니다. 이 실습 폴더에서 하는 작업이라면 허용해 주세요.

미리보기를 보고 고칠 점은 같은 대화에서 이어서 말합니다. 한 번에 한두 가지씩, 몇 초에 무엇이 어떻게 바뀌어야 하는지 구체적으로 말하면 결과가 빨리 맞춰집니다.

2단계 문구가 너무 빨리 사라져. 2단계를 1초 더 보여 주고, 마무리 문구는 글자를 지금보다 크게 해 줘. 나머지는 그대로 둬.

예제 3은 Whisper로 만든 시간표를 넘겨 설명 영상을 만드는 연습입니다. 녹음 파일과 Whisper가 만든 .srt 파일, 화면 캡처 이미지를 프로젝트 폴더에 넣은 뒤 요청합니다. Whisper 사용법은 이 시리즈의 Whisper 글에서 다룹니다.

$hyperframes 스킬로 설명 영상을 만들어 줘.

자료: 폴더 안의 narration.mp3(설명 녹음), narration.srt(Whisper 자막), screen1.png~screen3.png(화면 캡처)
1) narration.srt의 시간에 맞춰 장면을 바꿔 줘. 각 구간에 맞는 화면 캡처를 보여 줘.
2) 화면 아래쪽에 자막을 넣어 줘. 자막 문구는 srt 내용을 그대로 쓰고 임의로 고치지 마.
3) 녹음을 배경 음성으로 넣어 줘.

먼저 장면 구성표를 보여 주고, 내가 확인하면 만들어 줘.

마지막 줄처럼 구성표를 먼저 받아 보면, 장면을 다 만든 뒤에 처음부터 다시 고치는 일이 줄어듭니다. 완성되면 "final.mp4로 렌더링해 줘"라고 요청하거나 프로젝트 폴더에서 직접 render 명령을 실행합니다.

자주 막히는 곳

Node.js 버전이 낮다는 메시지가 나올 때가 있습니다. Hyperframes는 Node.js 22 이상에서만 동작합니다. node -v로 버전을 확인하고, 22보다 낮으면 Node.js 글을 따라 LTS 버전을 다시 설치한 뒤 PowerShell을 새로 여세요.

렌더링 중 FFmpeg를 찾지 못한다는 오류가 나올 수 있습니다.

FFmpeg not found

FFmpeg가 설치되지 않았거나, 설치했지만 PowerShell이 위치를 모르는 상태입니다. 새 PowerShell 창에서 ffmpeg -version이 되는지 먼저 보고, 안 되면 FFmpeg 글의 설치와 PATH 안내를 따르세요. 그다음 npx hyperframes doctor를 다시 실행합니다.

npx를 입력하자마자 npx.ps1 파일을 로드할 수 없다는 빨간 오류가 나오면 PowerShell 실행 정책 문제입니다. Node.js 글의 스크립트 실행 허용하기 단계를 진행하세요. 회사 정책으로 허용이 안 되면 이 글의 npx를 모두 npx.cmd로 바꿔 입력하면 됩니다. 예를 들어 npx.cmd hyperframes doctor처럼 씁니다.

렌더링용 브라우저를 내려받지 못하는 경우도 있습니다. Hyperframes는 크롬 브라우저를 화면 없이 띄워(headless Chrome) 프레임을 찍습니다. 컴퓨터에 크롬이 있으면 그것을 쓰고, 찾지 못하면 렌더링 전용 크롬을 처음 한 번 내려받습니다. 회사망에서 이 다운로드가 막히면 렌더링이 시작되지 않습니다. 아래 명령으로 브라우저를 미리 준비해 볼 수 있습니다.

npx hyperframes browser ensure

다운로드가 중간에 끊겼다면 끝에 --force를 붙여 다시 받습니다. 그래도 안 되면 사내망 담당자에게 외부 다운로드 허용 여부를 문의하세요.

한글이 네모나 다른 글꼴로 나올 수 있습니다. 장면에 쓴 글꼴이 프로젝트 안에 포함되지 않으면 렌더링 때 기본 글꼴로 바뀝니다. Codex에게 "한글 글꼴 파일을 프로젝트에 넣고 @font-face로 선언해 줘"라고 요청하세요. npx hyperframes lint를 실행하면 글꼴 선언이 빠진 곳을 알려 줍니다.

렌더링이 느린 것은 대부분 정상입니다. 프레임을 하나씩 찍어서 묶는 방식이라, 미리보기는 바로 재생돼도 렌더링은 시간이 더 걸립니다. 영상 길이, 해상도, 효과가 많을수록 오래 걸립니다. 확인용으로 빠르게 뽑아 보고 싶을 때는 화질을 낮춥니다.

npx hyperframes render --quality draft --output draft.mp4

Codex가 스킬을 모르는 것처럼 행동하면 새 대화를 시작한 뒤 npx hyperframes skills check를 실행해 보세요. 빠졌거나 오래된 스킬이 있다고 나오면 npx hyperframes skills update를 다시 실행합니다.

회사 PC에서는 프로그램 설치 권한, 사내망 차단, 백신 경고 때문에 막히는 일이 많습니다. npx는 인터넷에서 패키지를 받아 오므로 사내망에서 막힐 수 있습니다. 수업 전에 교육 담당자와 패키지 다운로드 가능 여부를 확인해 주세요.

위에 없는 오류가 나오면 당황하지 말고 아래 세 명령을 프로젝트 폴더에서 실행한 뒤, 출력 전체를 복사해 Codex에게 보여 주세요. 무엇을 하려다 막혔는지 한 줄 덧붙이면 원인을 더 빨리 찾습니다.

npx hyperframes doctor
npx hyperframes lint
npx hyperframes check

회사 자료를 다룰 때

내 컴퓨터에서 미리보기와 렌더링을 하면 프로젝트 파일은 내 컴퓨터에 남습니다. 다만 Codex에게 보내는 요청 문장과 Codex가 읽은 파일 내용은 AI 서비스로 전송됩니다. 화면 캡처나 녹음에 고객 식별정보, 내부 인증정보, API 키가 보이지 않게 하고, 필요하면 가상의 제품이나 테스트 화면으로 바꿔서 쓰세요.

Hyperframes 명령어 도구는 명령 이름이나 렌더링 성능 같은 사용 통계를 익명으로 보냅니다. 공식 문서에 따르면 프로젝트 이름이나 영상 내용은 보내지 않습니다. 회사 정책상 끄고 싶다면 아래 명령을 실행합니다.

npx hyperframes telemetry disable

용어 풀이

HTML: 웹페이지의 뼈대를 적는 언어입니다. Hyperframes에서는 장면 하나하나가 HTML 파일입니다. CSS: 웹페이지의 색, 크기, 위치, 글꼴을 정하는 언어입니다. 컴포지션: Hyperframes에서 영상 한 편을 이루는 장면 구성입니다. 어떤 요소가 몇 초에 나타나 몇 초 동안 보이는지가 들어 있습니다. 프레임: 영상을 이루는 한 장 한 장의 그림입니다. 초당 30프레임이면 1초에 그림 30장이 지나갑니다. 렌더링: 장면 파일을 실제 영상 파일(MP4)로 만들어 내는 과정입니다. 스킬: AI에게 주는 작업 설명서입니다. Hyperframes 스킬에는 올바른 장면 파일 작성법, 미리보기와 렌더링 순서 같은 규칙이 들어 있습니다. npx: Node.js에 포함된 도구로, 프로그램을 따로 설치하지 않고 필요할 때 내려받아 실행합니다.

맥에서는

명령은 윈도우와 같습니다. 터미널 앱을 열고 node -v와 ffmpeg -version을 확인한 뒤 npx hyperframes skills update, init, preview, render를 똑같이 실행하면 됩니다. FFmpeg는 Homebrew로 설치하는 경우가 많습니다.

brew install ffmpeg

사용자 폴더로 이동할 때는 cd ~를 씁니다.

다음 글

다음 글에서는 사람과 AI가 함께 쓰는 Aside 브라우저를 설치하고 AI가 브라우저를 다룰 수 있게 연결합니다. Aside 브라우저 윈도우 설치와 aside-cli 연결, AI에게 브라우저 맡기기

시리즈 전체 목록: https://www.letscoding.kr/blog/category/tools

공식 문서 https://github.com/heygen-com/hyperframes https://hyperframes.heygen.com/quickstart https://hyperframes.heygen.com/guides/with-codex https://hyperframes.heygen.com/help

확인일: 2026-11-02