Communitygithub.com

ZardLi1115/zedclaw

HTML 기반 비디오 합성, 애니메이션 타이틀 카드, 소셜 오버레이, 자막이 포함된 토킹헤드 영상, 오디오 반응형 시각 효과, 쉐이더 전환을 HyperFrames를 사용하여 제작합니다. HTML이 비디오의 진실 공급원(source of truth)입니다. 사용자가 HTML 합성에서 렌더링된 MP4/WebM을 원할 때, 미디어 위에 텍스트/로고/차트를 애니메이션화하려 할 때, 오디오와 동기화된 자막이 필요할 때, TTS 내레이션을 원할 때, 또는 웹사이트를 비디오로 변환하려 할 때 사용하세요.

zedclaw란 무엇인가요?

이 스킬은 HyperFrames 엔진을 기반으로 HTML/CSS/JS 애니메이션을 결정론적으로 MP4/WebM 비디오로 렌더링하는 역량을 제공합니다. HTML 파일이 비디오의 진실 공급원 역할을 하며, `data-*` 속성으로 타이밍을 제어하고 GSAP 타임라인으로 애니메이션을 구성합니다. 주로 모션 그래픽스, 토킹헤드 자막 영상, 제품 투어, 소셜 미디어 오버레이, 쉐이더 전환 및 오디오 반응형 시각 효과 등에 적합하며, 순수 수학/기하학 애니메이션(`manim-video`)이나 이미지 생성과는 구분됩니다. CLI 도구(`npx hyperframes`)를 통해 프로젝트 스캐폴딩, 미리보기, 린트/검증, 렌더링을 지원하며, Chrome Headless Shell과 FFmpeg를 사용하여 프레임별 캡처 및 인코딩을 수행합니다. 또한 TTS, 자동 자막 생성, 웹사이트-비디오 파이프라인, 시각적 디자인 검증(DESIGN.md 기반) 등 고급 기능을 포함하고 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ZardLi1115/zedclaw/tree/HEAD/optional-skills/creative/hyperframes
원본 보기→모든 스킬 둘러보기

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

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

HyperFrames

HTML이 비디오의 진실 공급원(source of truth)입니다. 합성은 타이밍을 위한 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.

설정 (최초 1회)

bash "$(dirname "$(find ~/.zedclaw/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 작성 전 계획

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

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

시각적 아이덴티티 게이트 (HARD-GATE). 합성 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 <이름>을 전달하여 선택하고, --video clip.mp4 또는 --audio track.mp3를 전달하여 미디어로 시드합니다.

3. 애니메이션 전 레이아웃

히어로 프레임에 대한 정적 HTML+CSS를 먼저 작성하세요 — 아직 GSAP은 사용하지 마세요. .scene-content 컨테이너는 씬을 채워야 합니다 (width:100%; height:100%; padding:Npx) display:flex + gap을 사용하세요. 패딩을 사용하여 콘텐츠를 안쪽으로 밀어 넣으세요 — 콘텐츠 컨테이너에 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 → 단어 수준 전사. 전사 톤( hype / corporate / tutorial / storytelling / social — 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 기본 요소(푸시 슬라이드, 블러 크로스페이드, 확대 통과, 스태거드 블록) 또는 쉐이더 전환(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 <composition-dir> \
  --out <composition-dir>/.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 — 데이터 속성, 타임라인 계약, 불가결한 규칙, 타이포그래피/에셋 규칙
  • 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 수정, 환경 변수, 일반적인 렌더링 오류

관련 스킬

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community