Communitygithub.com

zengbaocheng/hermes-tech-hub

HTML을 기반으로 MP4/WebM 비디오를 제작합니다. 애니메이션 타이틀 카드, 소셜 오버레이, 자막이 포함된 토킹헤드 영상, 오디오 반응형 시각 효과, 셰이더 전환 등을 HyperFrames 엔진으로 렌더링합니다.

hermes-tech-hub란 무엇인가요?

이 기술은 HTML을 비디오의 진실 공급원(source of truth)으로 삼아, 웹 기술만으로 고품질 MP4/WebM 영상을 제작할 수 있게 해주는 AI 에이전트 스킬입니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용 가능하며, 사용자가 "텍스트로 영상을 만들어줘", "웹사이트를 영상으로 변환해줘", "오디오에 맞춘 자막 영상이 필요해" 같은 요청을 할 때 자동으로 이 스킬을 호출합니다. HyperFrames 엔진은 HTML 파일에 `data-*` 속성으로 타이밍을 정의하고, GSAP으로 애니메이션을 작성하며, CSS로 스타일을 지정한 다음, Chrome headless 모드로 프레임을 캡처하고 FFmpeg로 인코딩합니다. 수학/기하학 설명 영상은 `manim-video` 스킬이 담당하며, 이 스킬은 모션 그래픽, 토킹헤드, 제품 투어, 소셜 미디어 오버레이, 셰이더 전환, 오디오 반응형 비주얼 등 실제 미디어가 필요한 작업에 특화되어 있습니다. 작업 절차는 계획 → 디자인 시스템 정의(DESIGN.md) → 스캐폴딩 → 레이아웃(hero frame 우선) → GSAP 애니메이션 → 전환 효과 → 오디오/자막/TTS → 린트/검증/프리뷰/렌더링 순으로 진행됩니다. 특히 `DESIGN.md`를 통한 시각적 정체성 정의가 모든 컴포지션 작성 전에 강제되며(HARD-GATE), `repeat: -1` 금지, 비동기 타임라인 금지 등 여러 규칙을 준수해야 합니다. 렌더링 전후로 `lint`, `validate`, `inspect`를 실행하여 구조적 문제, 명암비, 레이아웃 오버플로우 등을 자동 검증합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zengbaocheng/hermes-tech-hub/tree/HEAD/creative/hyperframes

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HyperFrames

HTML은 비디오의 진실 공급원(source of truth)입니다. 컴포지션은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외관을 위한 CSS가 포함된 HTML 파일입니다. HyperFrames 엔진은 페이지를 프레임별로 캡처하고 FFmpeg로 MP4/WebM으로 인코딩합니다.

manim-video와의 차이점: 수학/기하학 설명 영상(방정식, 3B1B 스타일)은 manim-video를 사용하세요. 모션 그래픽, 토킹헤드(자막 포함), 제품 투어, 소셜 오버레이, 셰이더 전환, 실제 비디오/오디오 미디어가 필요한 모든 작업은 hyperframes를 사용하세요.

사용 시기

  • 사용자가 텍스트, 스크립트 또는 웹사이트에서 렌더링된 비디오를 요청하는 경우
  • 애니메이션 타이틀 카드, 하단 써드(lower thirds), 타이포그래피 인트로
  • 자막이 포함된 나레이션 비디오(TTS + 파형에 동기화된 자막)
  • 오디오 반응형 시각 효과(비트 동기화, 스펙트럼 막대, 펄싱 글로우)
  • 장면 간 전환(크로스페이드, 와이프, 셰이더 워프, 화이트 플래시)
  • 소셜 오버레이(Instagram/TikTok/YouTube 스타일)
  • 웹사이트-투-비디오 파이프라인(URL 캡처, 프로모션 영상 제작)
  • 비디오 파일로 결정적으로(deterministically) 렌더링되어야 하는 모든 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.

설정 (최초 1회)

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

스크립트는 다음을 수행합니다:

  1. Node.js >= 22 및 FFmpeg 설치 여부를 확인합니다 (미설치 시 수정 지침 출력).
  2. hyperframes CLI를 전역으로 설치합니다 (npm install -g hyperframes@>=0.4.2).
  3. Puppeteer를 통해 chrome-headless-shell을 사전 캐시합니다 — Chrome의 HeadlessExperimental.beginFrame 캡처 경로를 통한 최고 품질 렌더링에 필수입니다.
  4. npx hyperframes doctor를 실행하고 결과를 보고합니다.

설정이 실패하면 references/troubleshooting.md를 참조하세요.

절차

1. HTML을 작성하기 전에 계획하기

코드를 건드리기 전에, 높은 수준에서 다음을 명확히 하세요:

  • 무엇 — 내러티브 아크, 핵심 순간, 감정적 비트
  • 구조 — 컴포지션, 트랙(비디오/오디오/오버레이), 지속 시간
  • 시각적 정체성 — 색상, 글꼴, 모션 특성(폭발적 / 영화적 / 유동적 / 기술적)
  • 히어로 프레임(hero frame) — 각 장면에서 가장 많은 요소가 동시에 보이는 순간. 이것이 먼저 구축할 정적 레이아웃입니다.

시각적 정체성 게이트(HARD-GATE). 컴포지션 HTML을 작성하기 전에 시각적 정체성이 정의되어야 합니다. 기본값이나 일반적인 색상(#333, #3b82f6, Roboto는 이 단계가 생략되었음을 암시함)으로 컴포지션을 작성하지 마세요. 다음 순서로 확인하세요:

  1. 프로젝트 루트에 DESIGN.md가 있는가? → 해당 파일의 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것" 제약 조건을 사용하세요.

  2. 사용자가 스타일을 언급했는가? (예: "Swiss Pulse", "어둡고 테크니컬한", "럭셔리 브랜드") → 최소한의 DESIGN.md를 생성하세요: ## Style Prompt, ## Colors (역할이 포함된 3-5개의 16진수), ## Typography (1-2개 패밀리), ## What NOT to Do (3-5개의 안티패턴).

  3. 위 어느 것도 해당되지 않는가? → 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 <이름>으로 선택하거나, --video clip.mp4 또는 --audio track.mp3로 미디어를 시드할 수 있습니다.

3. 애니메이션 전에 레이아웃 먼저

히어로 프레임(hero frame)부터 정적 HTML+CSS를 작성하세요 — 아직 GSAP은 사용하지 마세요. .scene-content 컨테이너는 display:flex + gap과 함께 장면을 채워야 합니다(width:100%; height:100%; padding:Npx). 패딩을 사용하여 콘텐츠를 안쪽으로 밀어 넣으세요 — 콘텐츠 컨테이너에 position: absolute; top: Npx를 절대 사용하지 마세요(콘텐츠가 남은 공간보다 높을 때 넘칩니다).

히어로 프레임이 올바르게 보인 후에만, gsap.from() 엔트리(요소를 CSS 위치로 애니메이션)와 gsap.to() 엑시트(그 위치에서 애니메이션 아웃)를 추가하세요.

전체 data-attribute 스키마와 컴포지션 규칙은 references/composition.md를 참조하세요.

4. GSAP으로 애니메이션

모든 컴포지션은 다음을 충족해야 합니다:

  • 타임라인 등록: window.__timelines["<컴포지션-id>"] = tl
  • 일시 정지된 상태로 시작: gsap.timeline({ paused: true }) — 플레이어가 재생을 제어합니다
  • 유한한 repeat 값 사용 (repeat: -1 사용 금지 — 캡처 엔진이 손상됨). 계산: repeat: Math.ceil(지속시간 / 주기지속시간) - 1.
  • 결정적(deterministic)이어야 함 — Math.random(), Date.now(), 벽시계 로직 사용 금지. 의사 난수가 필요하면 시드된 PRNG를 사용하세요.
  • 동기식으로 구축 — 타임라인 구성 주변에 async/await, setTimeout 또는 Promise 사용 금지.

핵심 GSAP API(트윈, 이즈, 스태거, 타임라인)는 references/gsap.md를 참조하세요.

5. 장면 간 전환

멀티 장면 컴포지션에는 전환이 필요합니다. 규칙:

  1. 항상 장면 사이에 전환을 사용하세요 — 점프 컷 금지.
  2. 모든 장면 요소에 항상 엔트리 애니메이션을 사용하세요 (gsap.from(...)).
  3. 마지막 장면을 제외하고는 엑시트 애니메이션을 절대 사용하지 마세요 — 전환이 곧 엑시트입니다.
  4. 마지막 장면은 페이드 아웃될 수 있습니다.

셰이더 전환(flash-through-white, liquid-wipe 등)을 설치하려면 npx hyperframes add <전환-이름>을 사용하세요. 전체 목록: 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 → 단어 수준 전사. 전사 결과의 톤(열광 / 기업 / 튜토리얼 / 스토리텔링 / 소셜 — references/features.md의 표 참조)에서 스타일을 선택하세요. 언어 규칙: 오디오가 영어임이 확인되지 않는 한 .en whisper 모델을 절대 사용하지 마세요 — .en은 비영어 오디오를 전사하지 않고 번역합니다. 모든 자막 그룹은 엑시트 트윈 이후에 반드시 하드 tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) 킬(kill)을 가져야 합니다 — 그렇지 않으면 그룹이 이후 그룹으로 새어 나가 보입니다.
  • 오디오 반응형 시각 효과: 오디오 밴드(베이스/미드/트레블)를 미리 추출하고, 타임라인 내에서 tl.call(draw, [], f / fps)를 사용한 for 루프로 프레임별로 샘플링하세요 — 단일 긴 트윈은 오디오에 반응하지 않습니다. 베이스 → 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' wasn't found — 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>를 사용하세요.

검증

렌더링 전후:

  1. 린트 + 검증 + 검사 통과: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (린트는 구조적 문제, 검증은 대비, 검사는 시각적 레이아웃/오버플로우 문제를 잡습니다 — 경고가 나타나면 troubleshooting.md 참조).
  2. 애니메이션 안무 — 새 컴포지션이나 중요한 애니메이션 변경 시 애니메이션 맵을 실행하세요. npx hyperframes init은 스킬 스크립트를 프로젝트에 복사하므로 경로는 프로젝트 로컬입니다:
    node skills/hyperframes/scripts/animation-map.mjs <컴포지션-디렉토리> \
      --out <컴포지션-디렉토리>/.hyperframes/anim-map
    
    트윈별 요약, ASCII 간트 타임라인, 스태거 감지, 데드 존(1초 이상 애니메이션 없음), 요소 수명 주기 및 플래그(offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s)가 포함된 단일 animation-map.json을 출력합니다. 요약 및 플래그를 스캔하고 — 각각을 수정하거나 정당화하세요. 작은 편집에서는 건너뛰세요.
  3. 파일이 존재하고 0이 아님: ls -lh final.mp4.
  4. 지속 시간이 data-duration과 일치: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. 시각적 확인: 중간 컴포지션 프레임 추출: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. 예상되는 경우 오디오 존재: 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 — data 속성, 타임라인 계약, 불가결 규칙, 타이포그래피/에셋 규칙
  • 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 수정, 환경 변수, 일반적인 렌더 오류

관련 스킬