Communitygithub.com

nastechresearch/nastech-agent

HTML 구성에서 MP4/WebM 비디오를 렌더링합니다.

nastech-agent란 무엇인가요?

이 스킬은 HTML, CSS, JavaScript(GSAP)로 작성된 구성을 프레임별로 캡처하여 MP4 또는 WebM 형식의 비디오로 인코딩하는 도구인 HyperFrames를 기반으로 합니다. 사용자가 텍스트, 스크립트 또는 웹사이트 URL에서 비디오를 요청할 때 사용되며, 모션 그래픽, 내레이터 캡션, 제품 투어, 소셜 미디어 오버레이 등 다양한 유형의 콘텐츠 제작에 적합합니다. 수학적/기하학적 설명이 필요한 경우 `manim-video`와 함께 보완적으로 사용할 수 있습니다. 주요 기능으로는 GSAP를 사용한 결정론적 애니메이션, 오디오 반응형 비주얼, TTS를 통한 음성 내레이션 및 자막 생성, 셰이더 전환 효과, 웹사이트 캡처 기반 비디오 제작 등이 있습니다. `npx hyperframes` CLI를 통해 프로젝트 스캐폴딩, 미리보기, 렌더링을 지원하며, Chrome Headless Shell을 사용하여 고품질 렌더링을 수행합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/hyperframes

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

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

문서

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                      # 환경 문제 진단

preview는 Chrome 렌더링 작업자를 열어두는 장기 실행 Next.js 서버입니다. 완료되면 항상 중지하십시오(정리 참조) — 잊어버린 미리보기는 GPU가 없는 호스트(WSL, 컨테이너, CI)에서 소프트웨어 WebGL(swiftshader)을 통해 각각 CPU 코어를 무기한 소모하는 유휴 chrome-headless-shell 작업자를 유지합니다.

렌더링 플래그: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(재현 가능) · --strict.

전체 CLI 참조: references/cli.md.

설정(1회)

bash "$(dirname "$(find ~/.nastech/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을 작성하기 전에 계획

코드를 작성하기 전에 높은 수준에서 다음을 명확히 하십시오:

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

시각적 아이덴티티 게이트(강제). 어떤 구성 HTML을 작성하기 전에 시각적 아이덴티티를 정의해야 합니다. 기본값이나 일반적인 색상(#333, #3b82f6, Roboto는 이 단계를 건너뛰었다는 신호임)으로 구성을 작성하지 마십시오. 다음 순서로 확인하십시오:

  1. 프로젝트 루트에 DESIGN.md가 있습니까? → 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것" 제약 조건을 사용합니다.

  2. 사용자가 스타일을 지정했습니까?(예: "Swiss Pulse", "어둡고 기술적인", "럭셔리 브랜드") → ## Style Prompt, ## Colors(역할이 있는 3-5가지 16진수), ## Typography(1-2개 패밀리), ## What NOT to Do(3-5개의 안티패턴)와 함께 최소한의 DESIGN.md를 생성합니다.

  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 <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() 종료(CSS 위치 에서 애니메이션)를 추가합니다.

전체 데이터 속성 스키마 및 구성 규칙은 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. 장면 간 전환

다중 장면 구성에는 전환이 필요합니다. 규칙:

  1. 장면 간에 항상 전환 사용 — 점프 컷 금지.
  2. 모든 장면 요소에 항상 진입 애니메이션 사용 (gsap.from(...)).
  3. 마지막 장면을 제외하고 종료 애니메이션을 절대 사용하지 않음 — 전환 자체가 종료입니다.
  4. 마지막 장면은 페이드 아웃될 수 있습니다.

셰이더 전환(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 → 단어 수준 전사. 기록 톤(과대광고 / 기업 / 튜토리얼 / 스토리텔링 / 소셜 — references/features.md의 표 참조)에서 스타일을 선택하십시오. 언어 규칙: 오디오가 영어로 확인되지 않은 한 .en whisper 모델을 절대 사용하지 마십시오 — .en는 영어 이외의 오디오를 기록하지 않고 번역합니다. 모든 캡션 그룹은 종료 트윈 후에 하드 tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) 킬이 있어야 합니다. 그렇지 않으면 그룹이 나중에 보이는 것으로 누출됩니다.
  • 오디오 반응형 비주얼: 오디오 대역(베이스 / 미드 / 트레블)을 미리 추출하고 타임라인 내에서 tl.call(draw, [], f / fps)의 for 루프로 프레임별로 샘플링합니다 — 단일 긴 트윈은 오디오에 반응하지 않습니다. 베이스 → scale(펄스), 트레블 → textShadow/boxShadow(글로우), 전체 진폭 → opacity/y/backgroundColor에 매핑합니다. 이퀄라이저 막대 클리셰를 피하십시오 — 콘텐츠가 시각을 안내하고 오디오가 그 행동을 구동하게 하십시오.
  • 마커 스타일 하이라이팅: 텍스트 강조를 위한 하이라이트, 원, 버스트, 낙서, 스케치아웃 효과는 결정론적 CSS+GSAP입니다 — references/features.md#marker-highlighting 참조. 완전히 탐색 가능하며, 애니메이션 SVG 필터가 없습니다.
  • 장면 전환: 모든 다중 장면 구성은 전환을 사용해야 합니다(점프 컷 금지). CSS 기본 요소(푸시 슬라이드, 블러 크로스페이드, 줌 스루, 스태거 블록) 또는 npx hyperframes add를 통한 셰이더 전환(flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split 등) 중에서 선택합니다. 분위기 및 에너지 테이블은 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 → 스토리보드 → 구성 → 렌더링 → 전달.

정리

render는 일회성입니다(작업자가 완료되면 종료됨). preview는 그렇지 않습니다 — 중지할 때까지 Chrome 작업자를 상주 상태로 유지하는 백그라운드 Next.js 서버를 실행합니다. 실행 중인 상태로 두지 마십시오: GPU가 없는 호스트에서 각 유휴 작업자의 swiftshader 프로세스는 CPU 코어를 고정하며, 며칠 동안 열려 있는 미리보기는 여러 개를 쌓아 올립니다.

사용자가 검토를 마쳤을 때(또는 새 미리보기를 시작하기 전에) 미리보기를 중지하십시오:

pkill -f "hyperframes.*preview"     # Studio 서버(포트 3002 해제)
pkill -f chrome-headless-shell      # 해당 렌더링 작업자; 다른 도구가 사용하지 않는 경우에만 안전

다른 도구가 chrome-headless-shell을 사용하는지 확실하지 않은 경우 먼저 확인하십시오: pgrep -af chrome-headless-shell. 같은 방식으로 멈춘 호스트(많은 유휴 작업자가 CPU를 회전시키는)를 복구하십시오 — references/troubleshooting.md를 참조하십시오.

함정

  • preview를 실행 중인 상태로 두는 것 — Chrome 작업자를 보유하는 장기 실행 서버입니다. WSL/컨테이너/CI에서 해당 유휴 작업자는 각각 CPU 코어를 회전시킵니다(소프트웨어 WebGL). 완료되면 중지하십시오 — 정리 참조.

  • 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>.

검증

렌더링 전후:

  1. Lint + validate + inspect 통과: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint는 구조적 문제, validate는 대비, inspect는 시각적 레이아웃/오버플로 문제를 잡습니다 — 경고가 나타나면 troubleshooting.md 참조).
  2. 애니메이션 choreography — 새 구성 또는 중요한 애니메이션 변경의 경우 애니메이션 맵을 실행합니다. npx hyperframes init는 스킬 스크립트를 프로젝트에 복사하므로 경로는 프로젝트 로컬입니다:
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    
    트윈별 요약, ASCII Gantt 타임라인, 스테거 감지, 데드 존(애니메이션 없이 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 csv=p=0 final.mp4 — 구성의 data-duration과 비교하십시오. ±1프레임 이내여야 합니다.
  5. 시각적 검토 — 재생하고 전체를 시청하십시오. 타이밍이 맞지 않는 요소, 애니메이션 결함, 깜박임, 렌더링 아티팩트를 찾으십시오. --quality draft로 인한 압축 아티팩트는 --quality high로 최종 렌더링하기 전까지 무시하십시오.

참조

파일내용
references/cli.md모든 CLI 명령 및 플래그 참조
references/composition.md데이터 속성 스키마, 트랙 규칙, 구성 구조
references/gsap.mdGSAP API 사용법트윈, 이징, 스테거, 타임라인
references/features.md캡션 스타일, 마커 하이라이팅, 전환 표, 오디오 반응
references/troubleshooting.md환경 문제, 미리보기 정리, 렌더링 타임아웃, GPU 문제
references/website-to-video.mdURL 캡처 워크플로우

관련 스킬