플러그인 설치: 설정 또는 최신 명령 전에 이 스킬이 HyperFrames 플러그인 내에 있을 때 플러그인 실행 규칙을 따르십시오. 독립 실행형 설치는 아래 업데이트 지침을 유지합니다.
HyperFrames 코어
에이전트 함정 (먼저 읽으십시오):
transform: translate(-50%,-50%)CSS를 사용하지 말고 flex/inset으로 중앙 정렬하십시오. GSAPx/y를 사용하는 노드에서 이렇게 하면 린트 오류가 발생합니다:gsap_css_transform_conflict.fromTo또는xPercent/yPercent를 사용하십시오.- 장면 종료
tl.set(..., {visibility:"hidden"})을 추가하지 마십시오. 런타임은 이미 시간이 지정된 클립을 숨깁니다. 내부 노드(또는.clip에opacity)의 페이드 아웃으로 충분합니다. 캡션 하드킬은 다른 규칙입니다. window.__timelines["id"]는 루트data-composition-id와 일치해야 합니다.render후 요약의 두 번째 줄을 읽으십시오:beginframevsscreenshot, GPU 모드, 단계 타이밍. Linux에서screenshot+software gpu는 느린 경로입니다.
HyperFrames는 HTML에서 비디오를 렌더링합니다. 합성물은 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.md | data-track-index가 제어하는(그리고 제어하지 않는) 것, z-index, 다른 클립에 상대적인 클립 타이밍 이해; 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.md | Tailwind v4 프로젝트 작업 (init --tailwind; 런타임 계약은 Studio의 v3와 다름) |
애니메이션 런타임 세부 정보(GSAP API, Lottie, Three.js 등)는 hyperframes-animation → adapters/<runtime>.md로 이동하십시오.
합성물 구축
두 가지 루트 형태 (상호 교환 불가)
- 독립 실행형 (최상위
index.html): 루트<div data-composition-id="…">가<body>에 직접 위치하며,<template>래퍼가 없습니다. 독립 실행형 루트를 래핑하면 모든 콘텐츠가 숨겨지고lint에서 거부합니다(standalone_composition_wrapped_in_template, 오류). - 서브 구성 (
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로 거부합니다. CSStransform: translateX(-40px)대신gsap.fromTo(el, { x: -40 }, { x: 0 })으로 트윈 내부에서 초기 상태를 설정하십시오. <video>/<audio>에crossorigin을 절대 넣지 마십시오.lint는 캔버스/WebGL/WebAudio 읽기백을 포함하여 조건 없이media_crossorigin_breaks_preview(오류)로 거부합니다. 억제 방법이 없습니다.<video data-start>에data-start를 가진 상위 요소를 절대 제공하지 마십시오.lint는video_nested_in_timed_element(오류)로 거부합니다. 래퍼 또는 비디오 중 하나에만 타이밍을 설정하고 둘 다에 설정하지 마십시오.- 모든
<audio>에는id가 필요합니다.lint는media_missing_id로 거부하며, id가 없는<audio>는 믹서에서 절대 선택되지 않으므로 렌더링이 무음이 됩니다. autoAlpha또는visibility로.clip을 절대 트윈하지 마십시오 —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입니다.
린트 오류는 또한 레이아웃 및 대비 감사를 비활성화합니다: check는 0 sample(s) 및 0/0 text checks를 보고하며, 이는 깨끗한 파일처럼 읽히지만 아무것도 실행되지 않았음을 의미합니다. 이러한 숫자를 신뢰하기 전에 린트 오류를 해결하십시오.
양보할 수 없는 규칙 (자동 게이트가 놓칠 수 있는 무음 버그)
여기서 표면화됨; 전체 근거는 연결된 참조에 있습니다. 위반하지 마십시오:
- 렌더링 시간 시계 / 시드되지 않은
Math.random/ 네트워크 / 입력 상태 없음;repeat: -1은 유한한 루트data-duration하에서만 가능합니다(내보내기 클립이 이를 자릅니다 — 그렇지 않으면 유한 횟수를 사용하십시오). →determinism-rules.md .clip요소에서display,visibility또는autoAlpha를 절대 트윈하지 마십시오. 프레임워크가 클립 가시성을 소유하며,lint가 이를 거부합니다(gsap_animates_clip_element). 대신 하위 요소를 애니메이션화하십시오. →determinism-rules.md- 본문 텍스트에
<br>없음; 변환된 요소는 블록 레벨이면서 크기가 지정되어야 함; 펄스 절대 장식 요소는 피크 여유 공간이 필요합니다. →determinism-rules.md <video>/<audio>는 평면 문서 쿼리로 찾으므로 프레임워크는 모든 중첩 깊이(서브 구성<template>또는 래퍼 내부 포함)에서 이를 탐색하고 디코딩합니다. 하나의 엄격한 제한:<video data-start>가data-start도 가진 다른 일반 요소 내부에 있으면lint오류가 발생하며, 실패는 실제입니다(잘못된 소스 프레임, 그런 다음 클립이 슬롯 중간에 사라짐). 따라서 타이밍을 래퍼 또는 비디오 중 하나에만 설정하고 둘 다에 설정하지 마십시오. 서브 구성 호스트는 면제됩니다: 서브 구성 내부의 미디어는 올바르게 렌더링됩니다. 다른 주의 사항은 배치가 아닌 타임라인과 관련됩니다: 서브 구성 타임라인은 호스트 루트 요소를 애니메이션화할 수 없습니다. →variables-and-media.md- 조립된 페이지 전체에서 모든
id를 고유하게 유지하십시오(서브 구성 ID 앞에 구성 ID 접두사 사용,#<id>-hero). 그래야 자신의#idCSS 및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-duration을 지나 끝나는 클립은 잘립니다: 동일한 편집에서 루트data-duration을 클립 끝까지 확장하십시오(lint는clip_ends_past_root_duration경고). - 모든 구성 요소의
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