Communitygithub.com

HyperFrames Core

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

HyperFrames Core란 무엇인가요?

이 스킬은 HyperFrames 프레임워크의 핵심 기술 계약을 정의합니다. HyperFrames는 HTML, CSS, JavaScript를 사용하여 비디오를 렌더링하는 시스템으로, `data-*` 속성을 통해 DOM에 타이밍을 선언하고 애니메이션 런타임이 탐색 가능하며 미디어 재생이 프레임워크에 의해 관리됩니다. 이 스킬은 독립형(standalone) 또는 하위 구성(sub-composition)이라는 두 가지 주요 형태의 구축 방법을 설명하고, GSAP 충돌, 미디어 태그 오용, 클립 요소 애니메이션 등 주요 함정을 방지하는 린트(lint) 규칙을 제공합니다. 또한 `npx hyperframes timeline` 및 `npx hyperframes check`와 같은 CLI 도구를 사용한 검증 방법과 참조 문서 목록을 포함하여 개발자가 결정론적 렌더링을 보장하고, 일반적인 실수를 피하며, 효율적으로 프로젝트를 구축할 수 있도록 돕습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/hyperframes-core

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

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

문서

HyperFrames Core은(는) 무엇을 하나요?

Agent 함정 (먼저 읽으세요):

  • CSS transform: translate(-50%,-50%) 대신 flex/inset으로 중앙 정렬하세요. GSAP x/y로 애니메이션하는 노드에 위 변환을 사용하지 마세요. 린트: gsap_css_transform_conflict. fromTo 또는 xPercent/yPercent를 사용하세요.
  • 장면 종료 시 tl.set(..., {visibility:"hidden"})를 추가하지 마세요. 런타임이 이미 시간 제한 클립을 숨깁니다. 내부 노드(또는 .clip의 opacity)에 대한 페이드 아웃이면 충분합니다. 캡션 강제 종료는 다른 규칙입니다.
  • window.__timelines["id"]는 루트 data-composition-id와 일치해야 합니다.
  • render 후, 요약의 두 번째 줄(beginframe vs screenshot, GPU 모드, 단계 타이밍)을 읽으세요. Linux에서 screenshot + software gpu는 느린 경로입니다.

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

이 스킬은 기술 계약입니다 — 하나의 HyperFrames 프로젝트를 구축하는 방법을 설명합니다. 아래 본문은 빌드 가이드입니다. 주제별 세부 사항은 references/에 있으며 (다음 인덱스 참조), 필요할 때 읽으세요. 프로세스 문서(브리프, 스토리보드, 리뷰, 프로덕션, 디스패치, 프레임 워커)는 /hyperframes → references/에 있습니다. 다른 사항은 형제 도메인 스킬(hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry)에서 다룹니다. /hyperframes의 기능 맵은 각 스킬이 무엇을 다루는지 설명합니다.

참조

파일읽을 때…
references/minimal-composition.md가장 작은 렌더링 가능한 구성 뼈대부터 시작하려면
references/composition-patterns.md모놀리식 vs 모듈식 선택; 모듈식 index.html 구조화; 하위 구성 아키타입 선택
references/data-attributes.md모든 data-* (루트 / 클립 / 하위 구성 호스트 / 레거시 별칭) 조회; class="clip" 사용
references/tracks-and-clips.mddata-track-index가 제어하는 것(그리고 제어하지 않는 것), z-인덱스 이해, 다른 클립에 상대적인 클립 타이밍; npx hyperframes timeline으로 모든 트랙과 클립 나열
references/creator-editing-recipes.md정확한 자르기/트림/재정렬/리타임/프리즈/카메라/마스크/크로스페이드/오디오 편집 레시피와 그 한계 복사
references/sub-compositions.md하위 구성 연결 (호스트 속성, <template>, 인스턴스별 변수) 및 내부 애니메이션
references/variables-and-media.md변수 선언; <video>/<audio> 배치, 볼륨 설정, 트림
references/determinism-rules.md탐색 가능한 타임라인 구축; 결정론 금지 사항; 레이아웃 / 텍스트 맞춤
references/full-screen-motion.md공유 배경으로 전체 프레임 모션 작성
references/tailwind.mdTailwind v4 프로젝트에서 작업 (init --tailwind; 런타임 계약이 Studio의 v3와 다름)

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

구성 구축

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

  • 독립형 (Standalone) (최상위 index.html): 루트 <div data-composition-id="…">가 <body>에 직접 위치하며, <template> 래퍼가 없습니다. 독립형 루트를 래핑하면 모든 콘텐츠가 숨겨지고 lint에서 거부됩니다 (standalone_composition_wrapped_in_template, 오류).
  • 하위 구성 (Sub-composition) (data-composition-src를 통해 로드됨): 루트를 <template>으로 감쌉니다. 이것이 작성해야 할 형태입니다. 로더는 일반 전체 문서도 허용하고 <body>로 폴백하지만, 예제와 도구는 템플릿 형태를 가정합니다.

⚠ 전송 규칙: 템플릿화된 하위 구성의 경우 어셈블러는 파일 자체의 <head> <style>/<script>를 삭제합니다 (packages/core/src/compiler/compositionAssembly.ts, hasTemplate 게이트). 따라서 <style>/<script>를 템플릿 내부에 넣으세요. <link>는 어떤 경우든 호이스팅됩니다. ⚠ 호스트 ID 규칙: 호스트 슬롯, 내부 템플릿, window.__timelines["<id>"] 키에 동일한 ID를 부여하세요. 다른 로컬 ID도 지원되지만 (어셈블러가 파일의 첫 번째 루트로 폴백), 불일치는 조용히 넘어가므로 특별한 이유가 없다면 일치시키세요.

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

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

독립형 루트는 width/height: 100%를 작성합니다. 캔버스 크기는 data-width/data-height입니다. 런타임이 해당 픽셀을 구성 루트에 적용합니다. #root에 1920px/1080px을 하드코딩하지 마세요. 뼈대 → references/minimal-composition.md.

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

각 구성은 window.__timelines["<id>"] (키 = 루트 data-composition-id)에 정확히 하나의 gsap.timeline({ paused: true })를 등록합니다. 비동기 콜백(document.fonts.ready) 내에서 빌드하는 것도 지원됩니다. 중요한 것은 빌드가 완료된 후에만 등록해야 한다는 것입니다. 렌더링 길이는 루트의 data-duration이며, 타임라인의 길이가 아닙니다: 타임라인이 이를 초과하면 잘리고, 일찍 끝나면 마지막 프레임을 유지합니다. 루트 data-duration을 생략하면 길이가 대신 추론됩니다 (타임라인, 미디어 윈도우 또는 어댑터). window.__timelines = window.__timelines || {}는 필요하지 않습니다. 런타임이 인라인 스크립트가 실행되기 전에 레지스트리를 생성하며, lint는 더 이상 이를 요구하지 않습니다. 하위 타임라인을 호스트에 수동으로 중첩하지 마세요. 런타임이 등록된 하위 타임라인을 자동으로 중첩합니다. 전체 계약 (GSAP 이외의 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.

첫 번째 패스 린트 주의 사항 (보장된 첫 번째 빌드 실패)

lint가 잡아내는 규칙이지만, 사후에만 가능합니다. 처음부터 올바르게 작성하세요:

  • CSS 초기 transform을 동일한 속성의 GSAP 트윈과 절대 쌍으로 사용하지 마세요. CSS 값과 트윈의 시작 값이 충돌하여 lint에서 gsap_css_transform_conflict로 거부합니다. CSS transform: translateX(-40px) 대신 gsap.fromTo(el, { x: -40 }, { x: 0 })를 사용하여 트윈 내부에서 초기 상태를 설정하세요.
  • <video>/<audio>에 crossorigin을 절대 넣지 마세요. lint가 무조건 media_crossorigin_breaks_preview (오류)로 거부하며, canvas/WebGL/WebAudio 읽기 백에도 적용됩니다. 억제할 수 없습니다.
  • <video data-start>에 data-start도 있는 조상을 절대 제공하지 마세요. lint가 video_nested_in_timed_element (오류)로 거부합니다. 래퍼 또는 비디오 중 하나에만 타이밍을 지정하고, 둘 다에는 하지 마세요.
  • 모든 <audio>에는 id가 필요합니다. lint가 media_missing_id로 거부하며, ID가 없는 <audio>는 믹서에 의해 절대 선택되지 않으므로 렌더링이 무음이 됩니다.
  • .clip을 autoAlpha 또는 visibility로 트윈하지 마세요. lint가 gsap_animates_clip_element로 거부합니다. 대신 자식을 애니메이션하세요.
  • 명명된 CSS font-family에는 제공된 로컬 파일에 대한 @font-face가 파일 내에 필요합니다. 그렇지 않으면 lint가 font_family_without_font_face를 발생시킵니다.
  • 하위 구성 #root는 width/height: 100% (또는 inset: 0)을 사용하며, 하드코딩된 1920px/1080px이 아닙니다. 캔버스 크기는 data-width/data-height입니다.

린트 오류는 레이아웃 및 대비 감사(audit)를 비활성화합니다. check는 0 sample(s) 및 0/0 text checks를 보고하는데, 이는 깨끗한 파일처럼 보이지만 아무것도 실행되지 않았음을 의미합니다. 해당 숫자를 신뢰하기 전에 린트 오류를 해결하세요.

절대 지켜야 할 규칙 (자동 게이트가 놓칠 수 있는 무음 버그)

여기에 표시됩니다. 전체 근거는 연결된 참조에 있습니다. 위반하지 마세요:

  • 렌더링 시간 시계 / 시드되지 않은 Math.random / 네트워크 / 입력 상태 없음; repeat: -1 없음 (유한 횟수 사용). → determinism-rules.md
  • .clip 요소에서 display, visibility 또는 autoAlpha를 트윈하지 마세요. 프레임워크가 클립 가시성을 소유하며, lint가 거부합니다 (gsap_animates_clip_element). 대신 자식을 애니메이션하세요. → determinism-rules.md
  • 본문 텍스트에 <br> 없음; 변환된 요소는 블록 레벨 + 크기 지정되어야 함; 맥동하는 절대 장식 요소는 피크 여유 공간이 필요함. → determinism-rules.md
  • <video>/<audio>는 평면 문서 쿼리로 찾아지므로 프레임워크가 모든 중첩 깊이에서 (하위 구성 <template> 또는 래퍼 내부 포함) 탐색하고 디코딩합니다. 하나의 엄격한 제한: lint는 <video data-start>가 data-start도 있는 다른 일반 요소 내부에 있으면 오류를 발생시키며, 실패는 실제입니다 (잘못된 소스 프레임, 클립이 슬롯 중간에 사라짐). 따라서 래퍼 또는 비디오 중 하나에만 타이밍을 지정하고, 둘 다에는 하지 마세요. 하위 구성 호스트는 예외입니다. 하위 구성 내부의 미디어는 올바르게 렌더링됩니다. 다른 주의 사항은 타임라인 관련이지 배치 관련이 아닙니다. 하위 구성 타임라인은 호스트 루트 요소를 애니메이션할 수 없습니다. → variables-and-media.md
  • 조립된 페이지 전체에서 모든 id를 고유하게 유지하세요 (하위 구성 ID에 구성 ID 접두사 추가, #<id>-hero). 그래야 자체 #id CSS와 getElementById 호출이 해결됩니다. 프레임 삽입은 더 이상 이에 의존하지 않습니다. 컴파일러는 모든 video[src]/audio[src]/img[src]에 문서 고유의 data-hf-render-id를 스탬프합니다. src 속성 대신 <source> 자식을 사용하는 미디어는 스탬프되지 않으므로 고유 ID가 여전히 중요합니다. → composition-patterns.md
  • 구성 루트의 전체 화면 채우기는 일반 렌더링에서 괜찮습니다. 레이어드 합성 경로(HDR 콘텐츠 또는 셰이더 전환을 사용하는 구성)에서만 삭제됩니다. 이 경우 엔진은 모든 구성 루트를 투명하게 강제하여 아래 레이어가 보이도록 합니다. 구성이 셰이더 전환 또는 HDR 미디어를 사용하는 경우 채우기를 전체 블리드 자식 (position:absolute; inset:0)에 넣으세요. → composition-patterns.md

기존 구성 편집

  • 먼저 파일을 읽으세요. 관련 없는 타이밍, 트랙, ID, 변수, 미디어 경로를 보존하세요.
  • 프로젝트의 타임라인(트랙, 클립, 시작, 종료, 재생)을 확인하려면 index.html과 모든 하위 구성 파일을 읽는 대신 npx hyperframes timeline [--json]을 실행하세요.
  • 기존 구성 ID와 타임라인 키를 일치시키세요.
  • 클립 추가: 주변 클립과 의도적으로 data-start/data-duration을 설정하세요. data-track-index는 Studio 디스플레이 레인이며 타이밍 제약이 아니므로 비어 있을 필요가 없습니다.
  • 구성 요소의 data-hidden은 미리보기와 렌더링 모두에서 숨기며, 시간 윈도우를 재정의합니다. 비파괴적/가역적이며 Studio의 타임라인 눈 아이콘으로 전환됩니다.
  • 하위 구성 추가: 호스트를 연결하기 전에 내부 data-composition-id를 확인하세요.

검증

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

  • npx hyperframes check 통과 (린트, 런타임, 레이아웃, 모션 및 대비에 걸쳐 0개의 결과)
  • 하위 구성이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 및 각 프레임 육안 검사
  • npx hyperframes preview --background 리뷰용 (사용자는 Studio의 타임라인에서 무엇이든 편집 가능하며 서버는 호출 명령을 견딤)
  • 사용자 승인 후에만 npx hyperframes render

Individual skills in this repo

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

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check (aspect ratio correction), prompt engineering, avatar resolution, and voice selection. Required for any HeyGen video generation. Replaces deprecated endpoints with v3. Use when: (1) generating any HeyGen video (via API or otherwise), (2) sending a personalized video message (outreach, update, announcement, pitch, knowledge), (3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face, (4) "make a video of me saying...", "send a video to my leads", "record an update for my team", "create a video pitch", "make a loom-style message", "I want to appear in this video", "generate a HeyGen video", "make a talking head video". Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter. Returns video share URL + HeyGen session URL for iteration. Chain signal: when the user wants to create/design an avatar AND make a video in the same request, run heygen-avatar f...

Zuhair-01/claude-skills-and-systems

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). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

관련 스킬