HyperFrames은(는) 무엇을 하나요?
HTML이 비디오의 진실 공급원입니다. 컴포지션은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 외관을 위한 CSS가 포함된 HTML 파일입니다. HyperFrames 엔진은 페이지를 프레임별로 캡처하여 FFmpeg로 MP4/WebM으로 인코딩합니다.
manim-video와의 보완 관계: 수학/기하학적 설명(방정식, 3B1B 스타일)에는 manim-video를 사용하세요. 모션 그래픽, 캡션이 있는 토킹 헤드, 제품 투어, 소셜 오버레이, 셰이더 전환, 그리고 실제 비디오/오디오 미디어로 구동되는 모든 것에는 hyperframes를 사용하세요.
사용 시기
- 사용자가 텍스트, 스크립트 또는 웹사이트에서 렌더링된 비디오를 요청하는 경우
- 애니메이션 타이틀 카드, 로우더 서드, 또는 타이포그래피 인트로
- 캡션이 있는 내레이션 비디오 (TTS + 파형에 동기화된 캡션)
- 오디오 반응형 비주얼 (비트 동기화, 스펙트럼 막대, 펄스 글로우)
- 장면 간 전환 (크로스페이드, 와이프, 셰이더 왜곡, 흰색 플래시)
- 소셜 오버레이 (Instagram/TikTok/YouTube 스타일)
- 웹사이트-투-비디오 파이프라인 (URL 캡처, 프로모션 제작)
- 비디오 파일로 결정론적으로 렌더링되어야 하는 모든 HTML/CSS/JS 애니메이션
다음에는 이 스킬을 사용하지 마십시오:
- 순수 수학/방정식 애니메이션 (→
manim-video) - 이미지 생성 또는 밈 (→
meme-generation, 이미지 모델) - 라이브 화상 회의 또는 스트리밍
빠른 참조
npx hyperframes init my-video # 프로젝트 스캐폴딩
cd my-video
npx hyperframes lint # 미리보기/렌더링 전 검증
npx hyperframes preview # 라이브 리로드 브라우저 미리보기 (포트 3002)
npx hyperframes render --output final.mp4 # MP4로 렌더링
npx hyperframes doctor # 환경 문제 진단
렌더링 플래그: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (재현 가능) · --strict.
전체 CLI 참조: references/cli.md.
설정 (일회성)
bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
스크립트는 다음을 수행합니다:
- Node.js >= 22 및 FFmpeg가 설치되어 있는지 확인합니다 (설치되지 않은 경우 수정 지침을 출력합니다).
hyperframesCLI를 전역적으로 설치합니다 (npm install -g hyperframes@>=0.4.2).- Puppeteer를 통해
chrome-headless-shell을 사전 캐시합니다 — Chrome의HeadlessExperimental.beginFrame캡처 경로를 통해 최고 품질 렌더링에 필수입니다. npx hyperframes doctor를 실행하고 결과를 보고합니다.
설정이 실패하면 references/troubleshooting.md를 참조하세요.
절차
1. HTML 작성 전 계획
코드를 건드리기 전에, 높은 수준에서 다음을 명확히 하세요:
- 무엇을 — 내러티브 아크, 주요 순간, 감정적 비트
- 구조 — 컴포지션, 트랙 (비디오/오디오/오버레이), 지속 시간
- 시각적 아이덴티티 — 색상, 글꼴, 모션 특성 (폭발적 / 영화적 / 유동적 / 기술적)
- 히어로 프레임 — 각 장면에 대해, 가장 많은 요소가 동시에 보이는 순간. 이것이 먼저 구축할 정적 레이아웃입니다.
시각적 아이덴티티 게이트 (하드 게이트). 컴포지션 HTML을 작성하기 전에 시각적 아이덴티티가 정의되어야 합니다. 기본 또는 일반 색상 (#333, #3b82f6, Roboto는 이 단계를 건너뛰었음을 나타냄)으로 컴포지션을 작성하지 마세요. 다음 순서로 확인하세요:
-
프로젝트 루트에
DESIGN.md가 있는가? → 정확한 색상, 글꼴, 모션 규칙, 그리고 "하지 말아야 할 것" 제약 조건을 사용하세요. -
사용자가 스타일을 지정했는가 (예: "Swiss Pulse", "어둡고 기술적인", "럭셔리 브랜드")? →
## Style Prompt,## Colors(역할이 있는 3-5개의 헥스),## Typography(1-2개 패밀리),## What NOT to Do(3-5개의 안티패턴)으로 최소한의DESIGN.md를 생성하세요. -
위 중 어느 것도 해당하지 않는가? → HTML을 작성하기 전에 3가지 질문을 하세요:
- 분위기는? (폭발적 / 영화적 / 유동적 / 기술적 / 혼돈적 / 따뜻함)
- 밝은 캔버스인가 어두운 캔버스인가?
- 브랜드 색상, 글꼴 또는 시각적 참고 자료가 있는가?
그런 다음 답변에서
DESIGN.md를 생성하세요. 모든 컴포지션은 색상 팔레트와 타이포그래피를DESIGN.md또는 명시적인 사용자 지시로 추적해야 합니다.
2. 스캐폴딩
npx hyperframes init my-video --non-interactive
템플릿: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. 하나를 선택하려면 --example <name>을, 미디어로 시드하려면 --video clip.mp4 또는 --audio track.mp3를 전달하세요.
3. 애니메이션 전 레이아웃
먼저 히어로 프레임에 대한 정적 HTML+CSS를 작성하세요 — 아직 GSAP 없이. .scene-content 컨테이너는 display:flex + gap으로 장면을 채워야 합니다 (width:100%; height:100%; padding:Npx). 패딩을 사용하여 콘텐츠를 안쪽으로 밀어 넣으세요 — 콘텐츠 컨테이너에 position: absolute; top: Npx를 절대 사용하지 마세요 (콘텐츠가 남은 공간보다 높을 때 오버플로됩니다).
히어로 프레임이 올바르게 보인 후에만, gsap.from() 진입 (CSS 위치로 애니메이션)과 gsap.to() 퇴장 (그 위치에서 애니메이션)을 추가하세요.
전체 데이터 속성 스키마와 컴포지션 규칙은 references/composition.md를 참조하세요.
4. GSAP으로 애니메이션
모든 컴포지션은 다음을 수행해야 합니다:
- 타임라인 등록:
window.__timelines["<composition-id>"] = tl - 일시 중지된 상태로 시작:
gsap.timeline({ paused: true })— 플레이어가 재생을 제어합니다. - 유한한
repeat값 사용 (repeat: -1없음 — 캡처 엔진이 손상됨). 계산:repeat: Math.ceil(duration / cycleDuration) - 1. - 결정론적이어야 함 —
Math.random(),Date.now()또는 벽시계 로직 없음. 의사 난수가 필요하면 시드된 PRNG를 사용하세요. - 동기적으로 빌드 — 타임라인 구성 주변에
async/await,setTimeout또는 Promise가 없어야 함.
핵심 GSAP API (트윈, 이징, 스태거, 타임라인)는 references/gsap.md를 참조하세요.
5. 장면 간 전환
다중 장면 컴포지션은 전환이 필요합니다. 규칙:
- 장면 사이에는 항상 전환을 사용하세요 — 점프 컷 없음.
- 모든 장면 요소에 항상 진입 애니메이션을 사용하세요 (
gsap.from(...)). - 마지막 장면을 제외하고는 퇴장 애니메이션을 사용하지 마세요 — 전환이 퇴장입니다.
- 마지막 장면은 페이드 아웃될 수 있습니다.
셰이더 전환 (flash-through-white, liquid-wipe 등)을 설치하려면 npx hyperframes add <transition-name>을 사용하세요. 전체 목록: npx hyperframes add --list.
6. 오디오, 캡션, TTS, 오디오 반응형, 하이라이팅
- 오디오: 항상 별도의
<audio>요소 (비디오는muted playsinline). - TTS:
npx hyperframes tts "스크립트 텍스트" --voice af_nova --output narration.wav.--list로 음성 목록을 확인하세요. 음성 ID의 첫 글자는 언어를 인코딩합니다 (a/b=영어,e=스페인어,f=프랑스어,j=일본어,z=중국어 등) — CLI가 음소화기 로케일을 자동으로 추론합니다. 재정의하려면--lang만 전달하세요. 영어 이외의 음소화는 시스템 차원에espeak-ng가 설치되어 있어야 합니다. - 캡션:
npx hyperframes transcribe narration.wav→ 단어 수준 전사. 전사 톤에서 스타일을 선택하세요 (hype / corporate / tutorial / storytelling / social —references/features.md의 표 참조). 언어 규칙: 오디오가 영어로 확인되지 않는 한.enwhisper 모델을 사용하지 마세요 —.en은 영어 이외의 오디오를 전사하는 대신 번역합니다. 모든 캡션 그룹은 퇴장 트윈 후에tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)하드 킬이 있어야 합니다 — 그렇지 않으면 그룹이 나중 그룹에 표시된 상태로 누출됩니다. - 오디오 반응형 비주얼: 오디오 대역 (베이스 / 미드 / 트레블)을 사전 추출하고 타임라인 내에서
for루프로tl.call(draw, [], f / fps)를 사용하여 프레임별로 샘플링하세요 — 단일 긴 트윈은 오디오에 반응하지 않습니다. 베이스 →scale(펄스), 트레블 →textShadow/boxShadow(글로우), 전체 진폭 →opacity/y/backgroundColor에 매핑하세요. 이퀄라이저 막대 클리셰는 피하고, 콘텐츠가 비주얼을 안내하고 오디오가 그 동작을 구동하도록 하세요. - 마커 스타일 하이라이팅: 텍스트 강조를 위한 하이라이트, 원, 버스트, 스크리블, 스케치아웃 효과는 결정론적 CSS+GSAP입니다 —
references/features.md#marker-highlighting을 참조하세요. 완전히 탐색 가능하며, 애니메이션 SVG 필터가 없습니다. - 장면 전환: 모든 다중 장면 컴포지션은 전환을 사용해야 합니다 (점프 컷 없음). CSS 기본 요소 (푸시 슬라이드, 블러 크로스페이드, 줌 스루, 스태거드 블록) 또는 셰이더 전환 (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-split등) 중에서 선택하세요 (npx hyperframes add사용). 분위기와 에너지 표는references/features.md#transitions에 있습니다. 동일한 컴포지션에서 CSS와 셰이더 전환을 혼합하지 마세요.
7. 린트, 검증, 검사, 미리보기, 렌더링
npx hyperframes lint # 누락된 data-composition-id, 겹치는 트랙, 등록되지 않은 타임라인을 잡아냄
npx hyperframes validate # 5개의 타임스탬프에서 WCAG 대비 감사
npx hyperframes inspect # 시각적 레이아웃 감사 — 오버플로, 프레임 밖 요소, 가려진 텍스트
npx hyperframes preview # 라이브 브라우저 미리보기
npx hyperframes render --quality draft --output draft.mp4 # 빠른 반복
npx hyperframes render --quality high --output final.mp4 # 최종 전달
hyperframes validate는 모든 텍스트 요소 뒤의 배경 픽셀을 샘플링하고 4.5:1 미만(또는 큰 텍스트의 경우 3:1 미만)의 대비 비율에 대해 경고합니다. hyperframes inspect는 레이아웃 측면의 동반자입니다 — 여러 타임스탬프에서 페이지를 실행하고 정적 린트가 볼 수 없는 문제를 플래그합니다 (4.5초에만 안전 영역을 넘는 캡션, 제목이 가장 긴 변형일 때 오버플로되는 카드, 전환 셰이더 뒤에 위치하게 되는 요소). 말풍선, 카드, 캡션 또는 타이트한 타이포그래피가 있는 컴포지션에서 특히 inspect를 실행하세요.
8. 웹사이트-투-비디오 (사용자가 URL을 제공하는 경우)
references/website-to-video.md의 7단계 캡처-투-비디오 워크플로우를 사용하세요: 캡처 → DESIGN.md → SCRIPT.md → 스토리보드 → 컴포지션 → 렌더링 → 전달.
함정
HeadlessExperimental.beginFrame'을 찾을 수 없음— Chromium 147+에서 이 프로토콜이 제거되었습니다.hyperframes@>=0.4.2(자동 감지 및 스크린샷 모드로 폴백)를 사용하고 있는지 확인하세요. 탈출구:export PRODUCER_FORCE_SCREENSHOT=true. hyperframes#294 및 references/troubleshooting.md를 참조하세요.- 시스템 Chrome (
chrome-headless-shell이 아님) — 렌더링이 120초 동안 중단된 후 타임아웃됩니다.npx puppeteer browsers install chrome-headless-shell를 실행하세요 (setup.sh가 이 작업을 수행합니다).hyperframes doctor는 사용될 바이너리를 보고합니다. - 어디에서든
repeat: -1— 캡처 엔진이 손상됩니다. 항상 유한한 반복 횟수를 계산하세요. - 나중에 들어오는 클립 요소에 대한
gsap.set()— 요소가 페이지 로드 시 존재하지 않습니다. 대신 타임라인 내에서 클립의data-start이후 또는 그 시점에tl.set(selector, vars, timePosition)을 사용하세요. - 콘텐츠 텍스트 내
<br>— 강제 줄바꿈은 렌더링된 글꼴 너비를 알지 못하므로 자연 줄바꿈 +<br>이 이중 줄바꿈을 발생시킵니다.max-width를 사용하여 텍스트가 줄바꿈되도록 하세요. 예외: 각 단어가 의도적으로 자체 줄에 있는 짧은 표시 제목. visibility또는display애니메이션 — GSAP은 이를 트윈할 수 없습니다.autoAlpha를 사용하세요 (visibility와 opacity를 모두 처리).video.play()또는audio.play()호출 — 프레임워크가 재생을 소유합니다. 직접 호출하지 마세요.- 비동기적으로 타임라인 구축 — 캡처 엔진은 페이지 로드 후 동기적으로
window.__timelines을 읽습니다. 타임라인 구성을async,setTimeout또는 Promise로 감싸지 마세요. <template>으로 감싸진 독립형index.html— 모든 콘텐츠를 브라우저에서 숨깁니다.data-composition-src를 통해 로드된 서브 컴포지션만<template>을 사용합니다.- 오디오에 비디오 사용 — 항상 음소거된
<video>+ 별도의<audio>.
검증
렌더링 전후:
- 린트 + 검증 + 검사 통과:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(린트는 구조적 문제를, 검증은 대비를, 검사는 시각적 레이아웃/오버플로 문제를 잡음 — 경고가 나타나면 troubleshooting.md 참조). - 애니메이션 안무 — 새로운 컴포지션 또는 중요한 애니메이션 변경의 경우, 애니메이션 맵을 실행하세요.
npx hyperframes init이 스킬 스크립트를 프로젝트에 복사하므로 경로는 프로젝트 로컬입니다:
트윈별 요약, ASCII 간트 타임라인, 스태거 감지, 데드 존 (>1초 동안 애니메이션 없음), 요소 수명 주기 및 플래그 (node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.hyperframes/anim-mapoffscreen,collision,invisible,paced-fast<0.2s,paced-slow>2s)가 포함된 단일animation-map.json을 출력합니다. 요약과 플래그를 스캔하고 수정하거나 각각을 정당화하세요. 작은 편집에서는 건너뜁니다. - 파일이 존재하고 크기가 0이 아님:
ls -lh final.mp4. - 지속 시간이
data-duration과 일치함:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4. - 시각적 확인: 중간 컴포지션 프레임 추출:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - 예상되는 경우 오디오 존재:
ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.
hyperframes render가 실패하면 npx hyperframes doctor를 실행하고 보고 시 그 출력을 첨부하세요.
참조
- composition.md — 데이터 속성, 타임라인 계약, 불가결 규칙, 타이포그래피/에셋 규칙
- cli.md — 모든 CLI 명령어 (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
- gsap.md — HyperFrames용 GSAP 핵심 API (트윈, 이징, 스태거, 타임라인, matchMedia)
- features.md — 캡션, TTS, 오디오 반응형, 마커 하이라이팅, 전환 (필요 시 로드)
- website-to-video.md — 7단계 캡처-투-비디오 워크플로우
- troubleshooting.md — OpenClaw 수정, 환경 변수, 일반적인 렌더링 오류