HyperFrames
HTML이 비디오의 소스 코드(진실 공급원)입니다. 합성(composition)은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 모양을 위한 CSS가 있는 HTML 파일입니다. 프레임워크가 클립 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.
속성 API, 합성/템플릿 구조, 변수 및 미디어 규칙: references/authoring.md. 세션에서 첫 번째 합성 HTML을 작성하기 전에 반드시 읽으십시오.
접근 방식
발견 (탐색적 요청에만 해당)
사용자가 방향을 정하지 않은 열린 요청("제품 출시 비디오를 만들어 줘")의 경우, 색상을 선택하기 전에 의도를 파악하십시오: 대상 청중, 플랫폼, 우선순위(움직임 품질 vs 정확성 vs 속도), 그리고 변형(variations)을 원하는지 여부. 변형을 원한다면 속도나 구조가 다른 2-3가지 옵션을 제공하십시오 - 하나는 안전한 것, 하나는 야심 찬 것 - 색상 변경이 아닙니다.
특정 요청("타이틀 카드 추가", "장면 3 타이밍 수정")의 경우, 발견 단계를 건너뜁니다.
1단계: 디자인 시스템
design.md 또는 DESIGN.md 파일이 있으면 먼저 읽으십시오(두 대소문자 모두 - Linux에서는 다른 파일입니다). 브랜드 색상, 글꼴 및 제약 조건의 진실 공급원이며, 정확한 값을 사용하십시오. 글꼴 이름을 지정했지만 fonts/에 .woff2 파일이 없고 내장된 일치 항목도 없으면, HTML을 작성하기 전에 사용자에게 경고하십시오.
design.md가 없으면 선택지를 제공하십시오:
- 사용자가 스타일이나 분위기를 지정했습니까? visual-styles.md (8개의 명명된 프리셋)를 읽고 가장 가까운 것을 선택하십시오.
- 시각적으로 탐색하시겠습니까? 디자인 선택기를 실행하십시오 - references/design-picker.md.
- 빠르게 진행하시겠습니까? 분위기, 밝음/어두움, 브랜드 색상/글꼴을 물어보고 house-style.md에서 팔레트를 선택하십시오.
design.md는 브랜드를 정의하는 것이지 비디오 합성 규칙이 아닙니다. 비디오 합성 규칙은 references/video-composition.md와 house-style.md에서 제공됩니다. 웹 UI 불투명도가 아닌 비디오 크기의 브랜드 색상입니다.
2단계: 프롬프트 확장
단일 장면 구성 및 사소한 편집을 제외한 모든 구성에서 실행합니다. design.md/house-style.md에 대해 의도를 일관된 중간 표현으로 근거합니다. 프로세스 및 형식: references/prompt-expansion.md.
3단계: 계획
- 무엇 - 내러티브 아크, 주요 순간, 감정적 비트.
- 구조 - 몇 개의 구성, 하위 구성 vs 인라인, 어떤 트랙이 무엇을 담당하는지.
- 리듬 - 구현 전에 장면 리듬을 선언하십시오 (빠름-빠름-느림-빠름-셰이더-유지). 템플릿: references/beat-direction.md.
- 타이밍 - 어떤 클립이 지속 시간을 결정하고, 전환이 어디에 위치하는지.
- 레이아웃 - 먼저 최종 상태를 구축하십시오 (다음 섹션).
- 애니메이션 - 그런 다음 움직임을 추가하십시오.
요청된 것을 만드십시오. "타이틀 카드"는 "타이틀 카드 + 3개의 지원 장면 + 음악 + 자막"이 아닙니다. 추가 기능을 제안할 수는 있지만 추가하지 마십시오.
작은 편집의 경우, 바로 규칙으로 건너뜁니다.
<하드-게이트>
어떤 합성 HTML을 작성하기 전에 - 1단계에서 시각적 정체성을 확인했는지 검증하십시오. #333, #3b82f6, 또는 Roboto를 사용하고 있다면 건너뛴 것입니다.
</하드-게이트>
애니메이션 전 레이아웃
각 요소를 가장 눈에 띄는 순간에 있어야 할 위치에 배치하십시오 - 완전히 진입하고, 올바르게 배치되었으며, 아직 종료되지 않은 상태. 먼저 정적 HTML+CSS로 작성하십시오. 아직 GSAP는 사용하지 마십시오.
이유: 애니메이션 시작 상태(오프스크린, 불투명도 0)에 요소를 배치하고 도착할 것이라고 생각하는 위치로 트윈하면 최종 레이아웃을 추측하는 것이며, 오버랩은 렌더링될 때까지 보이지 않습니다. 먼저 최종 상태를 구축하면 움직임이 존재하기 전에 레이아웃 버그가 표시됩니다.
- 장면당 히어로 프레임을 식별하십시오 - 대부분의 요소가 동시에 보이는 순간. 해당 레이아웃을 구축하십시오.
- 그에 대한 정적 CSS를 작성하십시오.
.scene-content는 장면을 채워야 합니다:width: 100%; height: 100%; padding: Npx;와display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. 패딩은 콘텐츠를 안쪽으로 밀어냅니다 - 콘텐츠 컨테이너에position: absolute; top: Npx를 절대 사용하지 마십시오(콘텐츠가 커지면 넘칩니다). 절대 위치 지정은 장식 요소용으로 예약하십시오. gsap.from()을 사용한 진입 - 오프스크린에서 CSS 위치로 애니메이션합니다. CSS가 근본 진실입니다; 트윈은 여정입니다. (data-composition-src를 통해 로드된 하위 구성 요소:gsap.fromTo()선호 - references/motion-principles.md 참조).- 마지막 장면만:
gsap.to()를 사용한 종료. 다른 모든 장면은 완전히 보이는 상태로 끝납니다 - 전환 자체가 종료입니다 (아래 전환 규칙 3).
요소 A가 동일한 영역에서 요소 B가 진입하기 전에 종료되면, 둘 다 자체 히어로 프레임에 대한 올바른 CSS 위치를 제공하십시오 - 타임라인이 공존하지 않도록 하고, 레이아웃 단계가 타이밍 오류로 인한 우발적 중복을 잡아냅니다. 의도적인 레이어링(텍스트 뒤의 광선, 카드 스택)은 괜찮습니다; 이 단계는 의도하지 않은 중복(두 개의 헤드라인이 충돌, 통계가 레이블을 덮음, 콘텐츠가 프레임 밖으로 나감)을 잡기 위해 존재합니다.
타임라인 계약
- 모든 타임라인은
{ paused: true }로 시작합니다. 플레이어가 재생을 제어합니다. - 모든 타임라인을 등록합니다:
window.__timelines["<composition-id>"] = tl - 프레임워크가 하위 타임라인을 자동으로 중첩합니다. 수동으로 추가하지 마십시오.
- 지속 시간은 GSAP 타임라인 길이가 아닌
data-duration에서 가져옵니다. - 지속 시간을 설정하기 위해 빈 트윈을 만들지 마십시오.
규칙 (절대 타협 불가)
결정론적: Math.random(), Date.now() 또는 시간 기반 로직을 사용하지 마십시오. 의사 난수에는 시드된 PRNG(예: mulberry32)를 사용하십시오.
GSAP: 시각적 속성(opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, 변환)만 애니메이션하십시오. visibility나 display를 절대 애니메이션하지 마십시오; video.play()/audio.play()를 절대 호출하지 마십시오.
애니메이션 충돌: 여러 타임라인에서 동일한 요소의 동일한 속성을 동시에 애니메이션하지 마십시오.
repeat: -1 금지: 무한 반복은 캡처 엔진을 손상시킵니다. repeat: Math.ceil(duration / cycleDuration) - 1로 계산하십시오.
동기식 타임라인 구축: async/await, setTimeout 또는 Promise 내에서 타임라인을 구축하지 마십시오. 캡처 엔진은 로드 후 window.__timelines를 동기식으로 읽습니다. 글꼴은 컴파일러에 의해 포함되므로 글꼴 로드를 기다리지 마십시오.
절대 하지 말아야 할 것:
window.__timelines등록을 잊지 마십시오.- 오디오에 비디오를 사용하지 마십시오. 항상 음소거된 비디오 + 별도의
<audio>를 사용하십시오. - 비디오를 시간 제한 div 안에 중첩하지 마십시오. 시간 제한이 없는 래퍼를 사용하십시오.
data-layer대신data-track-index를,data-end대신data-duration을 사용하십시오.- 비디오 요소 크기를 애니메이션하지 마십시오. 래퍼 div를 애니메이션하십시오.
- 미디어에서 play/pause/seek을 호출하지 마십시오. 프레임워크가 재생을 소유합니다.
data-composition-id없이 최상위 컨테이너를 만들지 마십시오.- 모든 타임라인 또는 트윈에서
repeat: -1을 사용하지 마십시오. - 타임라인을 비동기식으로 구축하지 마십시오.
- 이후 장면의 클립 요소에
gsap.set()을 사용하지 마십시오. 페이지 로드 시 DOM에 존재하지 않습니다. 클립의data-start이후 또는 그 시점에tl.set(selector, vars, timePosition)을 사용하십시오. - 콘텐츠 텍스트에
<br>을 사용하지 마십시오. 자연스러운 줄 바꿈과 겹쳐서 중복을 유발합니다. 대신max-width를 사용하십시오. 예외: 한 줄에 한 단어씩 의도적으로 배치된 짧은 표시 제목.
장면 전환 (절대 타협 불가)
모든 다중 장면 구성은 다음 네 가지를 모두 따라야 합니다. 하나라도 위반하면 잘못된 구성입니다.
- 항상 장면 사이에 전환을 사용하십시오. 점프 컷은 금지입니다.
- 항상
gsap.from()을 사용하여 모든 요소를 진입 애니메이션하십시오. 완전히 형성된 상태로 나타나는 것은 없습니다. 다섯 요소는 다섯 개의 진입 트윈을 의미합니다. - 마지막 장면을 제외하고는 종료 애니메이션을 절대 사용하지 마십시오. 전환 전에 불투명도를 페이드 아웃하거나, 오프스크린으로 이동하거나, 0으로 축소하는
gsap.to()는 금지입니다. 전환 자체가 종료이며, 발동될 때 나가는 장면이 완전히 보여야 합니다. 전환 전의 종료 트윈은 전환에 빈 프레임을 넘깁니다. - 마지막 장면만 요소를 페이드 아웃할 수 있습니다.
전환 선택 및 구현: references/transitions.md.
애니메이션 가드레일
- 첫 번째 애니메이션을 0.1-0.3초 오프셋하십시오 (t=0 금지).
- 이징을 다양하게 사용하십시오 - 장면당 최소 3가지 다른 이즈, 장면 내 반복되는 진입 패턴 금지.
- 어두운 배경에 전체 화면 선형 그래디언트를 피하십시오 (H.264 밴딩) - 방사형 또는 단색 + 국소 광선 사용.
- 60px+ 헤드라인, 20px+ 본문, 16px+ 데이터 레이블.
- 숫자 열에
font-variant-numeric: tabular-nums사용.
기존 구성 편집
- 실제 파일을 읽고 추측하지 마십시오. 구성이 곧 명세입니다. 소스에서 정확한 16진수 코드, 글꼴 및 이징 패턴을 추출하십시오. 기억에 의존하지 마십시오.
- 요청된 것만 변경하십시오. 관련 없는 클립의 타이밍은 유지하십시오.
출력 체크리스트
빠름 (즉시 실행, 결과 차단):
-
npx hyperframes lint와npx hyperframes validate가 모두 통과하는지 확인 - design.md가 존재하는 경우 디자인 준수 여부 확인
느림 (미리보기를 제시하는 동안 병렬로 실행):
-
npx hyperframes inspect통과 또는 보고된 모든 오버플로가 의도적으로 표시되었는지 확인 - 대비 경고 해결
- 애니메이션 안무 확인 (애니메이션 맵 스크립트)
각 검사를 실행하고 수정하는 방법: references/quality-checks.md.
참조 색인
새로운 구성에 대해 항상 읽으십시오:
| 파일 | 다루는 내용 |
|---|---|
| references/authoring.md | 데이터 속성, 템플릿 구조, 변수, 비디오/오디오, 글꼴/에셋 |
| references/video-composition.md | 비디오 매체 규칙 - 웹 본능을 재정의합니다 |
| references/typography.md | 글꼴 페어링, OpenType, 어두운 배경 조정 |
| references/motion-principles.md | 모션 디자인, 이미지 모션, 중요한 GSAP 규칙 |
다중 장면 구성의 경우 항상 읽으십시오:
| 파일 | 다루는 내용 |
|---|---|
| references/beat-direction.md | 리듬 템플릿, 안무 동사, 깊이 레이어 |
| references/transitions.md | 전환 선택; 카탈로그는 구현으로 연결됩니다; 셰이더 전환은 @hyperframes/shader-transitions npm 패키지에 있습니다 (node_modules에서 소스 읽기) |
작업이 요구할 때 읽으십시오:
| 파일 | 읽어야 할 때 |
|---|---|
| references/quality-checks.md | inspect/contrast/design/animation-map 검사 실행 시 |
| references/cli.md | 모든 CLI 명령; 빌드/렌더 문제 해결 |
| references/captions.md | 오디오 타이밍과 동기화된 텍스트 |
| references/transcript-guide.md | 자막 측 대본 처리 (CLI 호출은 media.md에 있음) |
| references/dynamic-techniques.md | 동적 자막 애니메이션 (가라오케, 슬램, 스캐터) |
| references/audio-reactive.md | 음악/음성에 반응하는 비주얼 |
| references/css-patterns.md | 마커 강조 (하이라이트, 원, 버스트, 스크리블) |
| references/techniques.md | 비트별 계획 기술 (코드 포함 11가지 패턴) |
| references/narration.md | 음성 해설/TTS 속도 및 스크립트 구조 |
| references/media.md | TTS (Kokoro), 전사 (Whisper), 배경 제거 |
| references/prompt-expansion.md | 접근 방식의 2단계 |
| references/design-picker.md | 시각적으로 design.md 생성 |
| references/from-website.md | 웹사이트를 비디오로 변환 |
| references/registry.md | 레지스트리 블록 설치/기여 (hyperframes add) |
| visual-styles.md | 사용자가 스타일을 지정할 때; design.md 생성 |
| house-style.md | design.md가 없을 때 미적 기본값 |
| patterns.md | PiP, 타이틀 카드, 슬라이드 쇼 |
| data-in-motion.md | 데이터, 통계, 인포그래픽 |
런타임 어댑터 (구성이 GSAP 대신 해당 런타임을 사용할 때 읽으십시오): waapi, lottie, three, animejs, css-animations, typegpu.