Communitygithub.com

HyperFrames 핵심 설정

HyperFrames 구성 계약 — 하나의 렌더링 가능한 프로젝트를 구축합니다. 구성 구조, `data-*` 타이밍 속성, `class="clip"`, 트랙, 하위 구성, 변수, 프레임워크 소유 미디어 재생, 결정론적 렌더링 규칙 및 유효성 검사에 사용됩니다. 구성 HTML을 작성하기 전에 읽으십시오.

HyperFrames 핵심 설정란 무엇인가요?

HyperFrames Core는 HTML 기반 비디오 렌더링 프레임워크의 핵심 기술 계약을 정의합니다. 이 설정은 단일 HyperFrames 구성(메인 index.html 또는 하위 구성)을 구축하는 방법을 설명하며, DOM 요소에 `data-*` 속성을 사용하여 타이밍을 선언하고 GSAP 타임라인을 통해 애니메이션을 구동합니다. 주요 특징으로는 프레임워크가 미디어 재생을 독점적으로 소유하고, 결정론적 렌더링을 보장하며(랜덤, 네트워크 요청, 무한 반복 금지), 클립, 트랙, 변수, 하위 구성을 체계적으로 관리합니다. 이 설정은 Claude Code, Cursor, Codex, Copilot, Windsurf 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, SKILL.md 기반으로 구성 지침과 참조 파일(예: `references/minimal-composition.md`, `references/determinism-rules.md` 등)을 제공합니다. 개발자는 이 계약을 준수하여 예측 가능하고 확장 가능한 비디오 구성을 생성할 수 있습니다.

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

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

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

문서

HyperFrames 핵심

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

이 설정은 기술 계약입니다 — 하나의 하이퍼프레임 프로젝트를 구축하는 방법에 대한 내용입니다. 아래 본문은 빌드 가이드이며, 주제별 세부 정보는 references/(색인은 다음)에 있으며 필요 시 읽으십시오. 다른 관심사는 형제 도메인 설정(hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry)에 있습니다. /hyperframes의 기능 맵은 각각이 다루는 내용을 설명합니다.

참조

파일읽는 목적
references/minimal-composition.md가장 작은 렌더링 가능한 구성 골격부터 시작
references/composition-patterns.md모놀리식 vs 모듈식 선택, 모듈식 index.html 구조화, 하위 구성 아키타입 선택
references/data-attributes.mddata-*(루트 / 클립 / 하위 구성 호스트 / 레거시 별칭) 조회, class="clip" 사용
references/tracks-and-clips.mddata-track-index 선택, 같은 트랙 겹침 / z-인덱스 처리, 다른 클립에 상대적으로 클립 시간 지정
references/sub-compositions.md하위 구성 연결(호스트 속성, <template>, 인스턴스별 변수) 및 내부 애니메이션
references/variables-and-media.md변수 선언, <video>/<audio> 배치, 볼륨 설정, 트림
references/determinism-rules.md탐색 가능한 타임라인 구축, 결정론 금지 사항, 애니메이션 가능 속성 허용 목록, 레이아웃 / 텍스트 맞춤
references/full-screen-motion.md공유 배경으로 전체 프레임 모션 작성
references/storyboard-format.mdSTORYBOARD.md 계획 작성 (+ 구문 분석된 매니페스트)
references/script-format.md선택적 SCRIPT.md 잠금 내레이션 작성
references/subagent-dispatch.md하위 에이전트 디스패치 동사(병렬 팬아웃 / 백그라운드 / 대기)를 사용자 환경에 매핑
references/tailwind.mdTailwind v4 프로젝트에서 작업 (init --tailwind, 런타임 계약이 Studio의 v3와 다름)

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

구성 빌드

두 가지 루트 형태(상호 교환 불가)

  • 독립형 (최상위 index.html) — 루트 <div data-composition-id="…">가 <body> 안에 직접 위치하며, <template> 래퍼 없음 (래핑하면 모든 내용이 숨겨지고 렌더링이 깨짐).
  • 하위 구성 (data-composition-src를 통해 로드됨) — 루트 반드시 <template>으로 래핑되어야 함.

⚠ 전송 규칙: 런타임은 <template> 내용만 복제하며, 그 외(<head> 스타일/스크립트 포함)의 모든 것은 폐기됨 — <style>/<script>는 템플릿 내부에 넣으십시오. ⚠ 호스트 ID 규칙: 호스트 슬롯의 data-composition-id는 내부 템플릿의 data-composition-id 및 window.__timelines["<id>"] 키와 정확히 일치해야 함 — -mount/-slot/-host 접미사 없음.

파일 형태, 호스트 연결 및 사전 렌더링 체크리스트 → references/sub-compositions.md.

루트는 크기가 명시되어야 함(무음 레이아웃 버그)

독립형 루트는 명시적인 크기 상자(width/height px 단위)가 필요하며, height:100% 요소까지의 모든 상위 요소는 해결된 높이가 있어야 함 — 그렇지 않으면 flex/100% 자식이 ~0으로 축소되고 내용이 왼쪽 상단 모서리로 쌓임. lint/validate/inspect는 이를 감지하지 않음. 골격 → references/minimal-composition.md.

하나의 일시 정지된 타임라인

각 구성은 페이지 로드 시 동기적으로 빌드된 window.__timelines["<id>"](키 = 루트 data-composition-id)에 정확히 하나의 gsap.timeline({ paused: true })를 등록하며, 렌더링 지속 시간 = 루트 data-duration, 타임라인 길이가 아님. 호스트에 수동으로 하위 타임라인을 중첩하지 마십시오. 전체 계약(GSAP 외 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.

양도할 수 없는 규칙(lint/validate/inspect가 감지하지 못하는 무음 버그)

여기에 표시됨, 전체 근거는 연결된 참조에 있음. 위반하지 마십시오:

  • 렌더링 시간 시계 / 시드되지 않은 Math.random / 네트워크 / 입력 상태 없음; repeat: -1 없음(유한 횟수 사용). → determinism-rules.md
  • 시각적 속성 허용 목록만 애니메이션; display/visibility 절대 안 됨; 나중 장면 클립에 gsap.set 없음. → determinism-rules.md
  • 본문 텍스트에 <br> 없음; 변환된 요소는 블록 레벨 + 크기 지정되어야 함; 맥동 절대 장식 요소는 피크 여유 공간 필요. → determinism-rules.md
  • <video>/<audio>는 호스트 루트의 직접 자식이어야 함(절대 하위 구성 <template>/래퍼 내부에 있지 않음); 프레임워크가 재생을 소유함. → variables-and-media.md
  • 모든 id는 조립된 페이지 전체에서 고유해야 함; 하위 구성 내에서는 ID 앞에 구성 ID를 접두사로 붙임(#<id>-hero). 중복된 <video>/<img> ID는 빈 화면을 렌더링함 — 프로듀서가 getElementById로 프레임을 삽입하며, 파일 간 중복은 lint를 통과함. → composition-patterns.md
  • 전체 화면 장면 채우기는 전체 여백 자식(position:absolute; inset:0)에 적용되어야 하며, 구성 루트 자체에는 절대 안 됨 — 프로듀서의 프레임 합성에서 루트 요소 자체의 background가 제거될 수 있음(프레임이 검정색으로 렌더링됨) 미리보기/snapshot에서는 올바르게 표시되더라도. → composition-patterns.md

기존 구성 편집

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

유효성 검사

명령어 세부 사항은 hyperframes-cli 사용

  • npx hyperframes lint 통과 (오류 0개)
  • npx hyperframes validate 통과 (콘솔 오류 0개)
  • npx hyperframes inspect 통과 (오류 0개)
  • 하위 구성이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 실행 후 각 프레임을 눈으로 확인
  • npx hyperframes preview로 검토 (사용자는 Studio의 타임라인에서 무엇이든 편집 가능)
  • 사용자 승인 후에만 npx hyperframes render 실행

Individual skills in this repo

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

1345AbhishekKumar/starter-supabase

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.

1345AbhishekKumar/starter-supabase

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-supabase

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.

1345AbhishekKumar/starter-supabase

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`).

1345AbhishekKumar/starter-supabase

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

1345AbhishekKumar/starter-supabase

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-supabase

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

1345AbhishekKumar/starter-supabase

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-supabase

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-supabase

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-supabase

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-supabase

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.

1345AbhishekKumar/starter-supabase

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.

관련 스킬