Communitygithub.com

DigitalRavagers/Experiment

HyperFrames HTML 구성 계약입니다. 구성 구조, 데이터 속성, 클립, 트랙, 하위 구성, 변수, 미디어 재생, 결정론적 렌더링 규칙 및 최소 렌더링 가능 프로젝트의 유효성 검사에 사용됩니다.

Experiment란 무엇인가요?

이 스킬은 HTML 기반의 동영상 합성 프레임워크인 HyperFrames의 핵심 기술 계약을 정의합니다. HyperFrames는 HTML 파일을 DOM으로 선언하여 타이밍을 구성하고, 애니메이션 런타임이 탐색 가능하며, 미디어 재생을 프레임워크가 소유하는 방식으로 동작합니다. 개발자는 이 스킬을 통해 구성 구조(data-composition-id, data-duration 등), 클립 및 트랙(data-start, data-duration, data-track-index), 하위 구성(서브 컴포지션) 연결 방법, 변수 및 미디어 선언, 그리고 결정론적 렌더링 규칙(예: Math.random 금지, repeat: -1 금지 등)에 대한 상세한 명세를 확인할 수 있습니다. 지원되는 플랫폼은 Claude Code, Cursor, Codex 등 모든 AI 에이전트 개발 환경이며, lint/validate/inspect 명령어를 통해 자동 검증이 가능하여 디버깅 시간을 크게 단축시킵니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/DigitalRavagers/Experiment/tree/HEAD/.agents/skills/hyperframes-core

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

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

문서

HyperFrames Core

HyperFrames는 HTML에서 동영상을 렌더링합니다. 구성은 data-* 속성으로 타이밍을 선언하는 DOM을 가진 HTML 파일이며, 애니메이션 런타임은 탐색 가능하고 미디어 재생은 프레임워크가 관리합니다.

이 스킬은 기술 계약입니다. 다른 관련 내용은 다음 스킬에 있습니다:

  • hyperframes-animation — 원자적 모션 규칙 + 씬 블루프린트 + 각 런타임별 어댑터(GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)
  • hyperframes-creative — 팔레트, 타이포그래피, 나레이션, 비트 계획, 오디오 반응형
  • hyperframes-media — TTS, Whisper 전사, 배경 제거, 자막
  • hyperframes-registry — 블록 및 컴포넌트 설치(hyperframes add)
  • hyperframes-cli — 개발 루프 명령어(lint / validate / preview / render)

Tailwind v4 프로젝트(hyperframes init --tailwind)의 경우 references/tailwind.md를 참조하세요. 브라우저 런타임 계약은 Studio의 Tailwind v3 설정과 다릅니다.

라우팅

원하는 작업읽을 파일
최소 렌더링 가능 구성 보기references/minimal-composition.md
모놀리식 단일 파일과 모듈식 하위 구성 아키텍처 중에서 결정references/composition-patterns.md
모듈식 index.html 구성(조정자 + 슬롯 + 루트 오디오)references/composition-patterns.md
하위 구성 아키텍처 선택(콘텐츠 / 드라이버 전용 / 다중 씬 병합 / 오디오 반응형)references/composition-patterns.md
data-* 속성 조회(루트, 클립, 하위 구성 호스트, 레거시 별칭)references/data-attributes.md
class="clip" 올바르게 사용하기references/data-attributes.md
data-track-index 선택; 동일 트랙 중첩; 트랙 인덱스 vs CSS z-indexreferences/tracks-and-clips.md
다른 클립에 상대적인 시간 지정(data-start="intro + 2", 크로스페이드 중첩, 체인)references/tracks-and-clips.md
하위 구성 연결(호스트 속성, <template> 래퍼, 인스턴스별 변수)references/sub-compositions.md
하위 구성 내 애니메이션(gsap.fromTo over gsap.from, 되감기 동작)references/sub-compositions.md
변수 선언(유형, 추가 옵션, 기본값, CI에서 --strict-variables)references/variables-and-media.md
<video>/<audio> 배치, 볼륨 설정, data-media-start로 트리밍references/variables-and-media.md
탐색 가능한 타임라인 구축(일시 정지, 동기 생성, gsap.set 이후 씬 트랩)references/determinism-rules.md
비결정론적 상태 방지(시계, Math.random, repeat: -1, 유한 반복 공식)references/determinism-rules.md
애니메이션 가능/불가능한 것(시각적 속성 허용 목록; display/visibility 불가)references/determinism-rules.md
텍스트 맞춤 및 오버플로 방지(fitTextFontSize 시그니처, <br> 규칙, 레이아웃 계약)references/determinism-rules.md
공유 배경으로 전체 프레임 모션 작성references/full-screen-motion.md
Tailwind v4 프로젝트에서 작업(init --tailwind)references/tailwind.md

애니메이션 런타임 세부 정보(GSAP API, Lottie, Three.js 등)는 hyperframes-animation → adapters/<runtime>.md를 참조하세요.

구성 구조

두 가지 루트 형식이 있습니다. 상호 교환할 수 없습니다.

  • 독립형(최상위 index.html) — 루트 <div data-composition-id="…">가 <body>에 직접 위치합니다. <template> 래퍼 없음. 독립형 루트를 <template>으로 감싸면 모든 콘텐츠가 브라우저에서 숨겨져 렌더링이 중단됩니다.
  • 하위 구성(data-composition-src를 통해 로드되는 파일) — 루트 <div data-composition-id="…"> 반드시 <template>으로 감싸야 합니다. 래퍼가 없으면 런타임이 이를 추출하고 마운트할 수 없습니다.

⚠ 하위 구성 전송 규칙: 런타임은 <template> 콘텐츠만 라이브 DOM에 복제합니다. 템플릿 외부의 모든 것 — <head>와 <head> 내의 <style>/<script>/<link> — 은 폐기됩니다. <style> 및 <script> 블록을 <head>가 아닌 <template> 내부에 배치하세요.

⚠ 호스트 ID 규칙: 호스트 파일에서 슬롯의 data-composition-id는 내부 템플릿의 data-composition-id 및 window.__timelines["<id>"] 키와 정확히 일치해야 합니다. -mount / -slot / -host 접미사를 추가하지 마십시오.

파일 모양, 호스트 배선, 함정 예제 및 사전 렌더링 확인 체크리스트는 references/sub-compositions.md를 참조하세요.

루트는 크기가 지정되어야 합니다(무음 레이아웃 버그)

독립형 루트는 명시적으로 크기가 지정된 상자를 설정해야 하며, 루트와 height: 100% 요소 사이의 모든 조상은 확인된 높이를 가져야 합니다. 루트나 중간 래퍼에 높이가 없으면 flex/height:100% 콘텐츠 컨테이너가 ~0으로 축소되고 콘텐츠가 왼쪽 상단 모서리에 쌓입니다(종종 x=0에서 첫 번째 글자가 잘림). lint, validate, inspect는 이를 감지하지 못합니다 — inspect는 축소된 루트에 대해 작성된 data-width/data-height를 대체하고 "0개의 레이아웃 문제"를 보고합니다.

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- 견고하게 중앙 정렬: position:absolute + inset:0이 크기 조정된 루트를 채웁니다.
         중간 래퍼와 관계없이; 또는 상위 체인의 크기가 조정된 경우에만 flex 컨테이너를 사용하세요. -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>Title</h1>
    </section>
  </div>
</body>

중앙 정렬 컨테이너에 padding(≥80px)을 유지하세요. 큰 텍스트가 프레임 가장자리에 닿지 않도록 하는 타이틀 안전 여백입니다. references/minimal-composition.md를 참조하세요.

타임라인 계약(GSAP 기본값)

모든 구성은 정확히 하나의 GSAP 타임라인을 등록합니다.

  • gsap.timeline({ paused: true })로 생성 — 플레이어가 재생을 관리합니다.
  • window.__timelines["<composition-id>"]에 등록합니다. 키는 루트의 data-composition-id와 정확히 일치해야 합니다. 점 구문(window.__timelines.<id> = tl)은 id가 유효한 식별자일 때 동일합니다. id에 -가 포함된 경우 대괄호를 사용하세요.
  • 페이지 로드 중 동기식으로 타임라인을 구축하세요. async, setTimeout, Promise 또는 이벤트 핸들러 내부가 아닙니다. 렌더러는 페이지 로드 완료 후 샘플링합니다. 지연된 타임라인 구축은 샘플을 놓칩니다.
  • 렌더링 기간은 루트의 data-duration에서 비롯되며, GSAP 타임라인 길이에서 비롯되지 않습니다. 기간을 설정하기 위해 빈 트윈으로 타임라인을 채우지 마십시오.
  • 하위 구성의 경우 호스트(master.add(sub))에 하위 타임라인을 수동으로 중첩하지 마십시오. 프레임워크가 이를 독립적으로 구동합니다.

GSAP이 아닌 런타임(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU)의 경우 해당 계약은 hyperframes-animation/adapters/<runtime>.md에 있습니다. 런타임 간 애니메이션 런타임 계약은 references/determinism-rules.md를 참조하세요.

불가침 규칙

다음은 렌더러를 중단시키거나 — lint/validate/inspect가 감지하지 못하는 무음 시각적 버그를 생성합니다(규칙 3, 7-8). (동기 타임라인 구축은 위의 타임라인 계약에서 다룹니다.)

  1. 시각적 요소에 Math.random() / Date.now() / performance.now() 사용 금지 — 시드 기반 PRNG를 사용하세요.
  2. repeat: -1 금지. repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) 사용 — floor, ceil 아님(ceil은 data-duration을 초과하여 gsap_repeat_ceil_overshoot 린트를 유발합니다. max(0, …)는 음수 반복 = 무한을 방지합니다).
  3. <video>/<audio>는 호스트 루트(index.html)의 직접적인 자식이어야 합니다. 하위 구성 <template> 내부나 래퍼 <div> 내부에 절대 배치하지 마십시오. 그렇지 않으면 디코딩되지 않고 빈/검은색으로 렌더링됩니다(무음). 프레임워크가 재생을 관리합니다. video.play() / audio.play() / currentTime = … 사용 금지. 하위 구성은 호스트 요소를 구동할 수 없으므로(선택자 또는 querySelector) 호스트 미디어는 메인 타임라인에서 글로벌 시간으로 애니메이션 처리하세요. references/variables-and-media.md를 참조하세요.
  4. 이후 씬의 클립 요소에 gsap.set() 사용 금지(아직 DOM에 없음). 클립의 data-start 시점 또는 이후에 tl.set(selector, vars, time)을 사용하세요.
  5. display / visibility 애니메이션 금지. opacity / 변환을 애니메이션 처리하세요. 클립 수명 주기가 표시/숨김을 처리합니다.
  6. 본문 텍스트에 <br> 사용 금지. max-width를 통해 텍스트가 줄바꿈되도록 하세요.
  7. 변환된 요소는 블록 수준이어야 하며 크기가 지정되어야 합니다. transform/scaleX/scaleY는 인라인 <span>에서 작동하지 않으며, 자동 너비(0px) 요소를 스케일링하면 아무것도 표시되지 않습니다 → 보이지 않는 막대/채우기. display: block/inline-block/flex-item 및 실제 width/height(예: 크기 조정된 부모 내에서 width: 100%)를 지정하세요.
  8. 절대 위치 지정 장식 요소(배지, 알약, 태그)가 맥동하거나 오버슈트하는 경우(yoyo 스케일, back.out) 최대 크기에서 여유 공간이 필요하며 overflow: hidden 가장자리와 겹치지 않아야 합니다. 그렇지 않으면 이웃과 겹치거나 잘립니다. 정지 상태가 아닌 가장 큰 프레임에 대해 위치를 지정하세요.

기존 구성 편집

  • 편집하기 전에 실제 파일을 읽으세요.
  • 관련 없는 타이밍, 트랙, ID, 변수 및 미디어 경로를 보존하세요.
  • 기존 구성 ID 및 타임라인 레지스트리 키와 일치시키세요.
  • 클립을 추가할 때는 겹치지 않는 data-track-index를 선택하거나 의도적으로 주변 타이밍을 조정하세요.
  • 하위 구성을 추가할 때는 호스트를 연결하기 전에 내부 data-composition-id를 확인하세요.

유효성 검사

명령어 세부 정보는 hyperframes-cli를 사용하세요.

  • npx hyperframes lint 통과(오류 0개)
  • npx hyperframes validate 통과(콘솔 오류 0개)
  • npx hyperframes inspect 통과 또는 오버플로가 의도적으로 표시됨
  • 하위 구성이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 실행 후 각 프레임을 육안 검사

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

DigitalRavagers/Experiment

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

DigitalRavagers/Experiment

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

관련 스킬