HyperFrames
HTML은 비디오의 단일 진실 공급원입니다. 컴포지션은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외관을 위한 CSS를 갖춘 HTML 파일입니다. 프레임워크는 클립 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.
접근 방식
발견 (탐색적 요청 전용)
사용자가 방향을 정하지 않은 개방형 요청(예: "제품 출시 비디오 만들어줘", "우리 브랜드용 뭔가 만들어줘")의 경우, 색상을 선택하기 전에 의도를 파악하세요:
- 대상 — 누가 시청하나요? 개발자? 임원? 일반 소비자?
- 플랫폼 — 어디서 재생되나요? 소셜 미디어(15초), 웹사이트 히어로, 제품 데모, 내부용?
- 우선순위 — 무엇이 가장 중요한가요? 모션 퀄리티? 콘텐츠 정확성? 브랜드 충실도? 속도?
- 변형 — 사용자가 여러 옵션을 원하나요, 아니면 단일 최선의 결과물을 원하나요?
구체적인 요청(예: "타이틀 카드 추가해줘", "씬 3 타이밍 수정해줘")의 경우 발견 단계를 건너뛰세요.
탐색적 요청의 경우, 단순한 색상 변경이 아닌 의미 있는 차이가 있는 2~3개의 변형을 고려해보세요 — 다른 페이스, 에너지 레벨, 또는 구조적 접근 방식. 하나는 안전하고 예상되는 스타일, 다른 하나는 야심찬 스타일로. 이것을 강제하지는 마세요 — 적절할 때 사용할 수 있는 도구일 뿐입니다.
단계 1: 디자인 시스템
프로젝트에 design.md 또는 DESIGN.md 파일이 있으면 먼저 읽으세요 (두 대소문자 모두 확인하세요 — Linux에서는 다른 파일입니다). 브랜드 색상, 글꼴 및 제약 조건의 진실 공급원입니다. 정확한 값을 사용하세요 — 색상을 임의로 만들거나 글꼴을 대체하지 마세요. 모든 형식이 가능합니다 (YAML 프론트매터, 산문, 테이블 — 값을 추출하기만 하면 됩니다).
로컬에서 찾을 수 없는 글꼴( fonts/ 디렉토리에 .woff2 파일이 없거나, 내장 글꼴이 아닌 경우)을 명시한 경우, HTML을 작성하기 전에 사용자에게 경고하세요: "design.md에 [글꼴 이름]이 명시되어 있으나 글꼴 파일을 찾을 수 없습니다. fonts/에 .woff2 파일을 추가하거나, 가장 가까운 내장 대안으로 대체하겠습니다."
design.md가 없는 경우, 사용자에게 선택지를 제공하세요:
- 사용자가 스타일이나 분위기를 언급했나요? → 8개의 명명된 프리셋을 위해 visual-styles.md를 읽으세요. 가장 가까운 것을 선택하세요.
- 시각적으로 옵션을 탐색하고 싶나요? → 디자인 피커를 실행하세요: 전체 워크플로우를 위해 references/design-picker.md를 읽으세요. 시각적 피커 페이지를 제공합니다. 사용자가 브라우저에서 분위기, 팔레트, 타이포그래피 및 모션을 구성한 다음, 생성된 design.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: 계획
HTML을 작성하기 전에, 높은 수준에서 생각하세요:
- 무엇(What) — 시청자는 무엇을 경험해야 하나요? 내러티브 아크, 핵심 순간, 감정적 비트를 식별하세요.
- 구조(Structure) — 컴포지션은 몇 개이며, 어떤 것이 서브 컴포지션이고 인라인인지, 어떤 트랙이 무엇을 전달하는지 (비디오, 오디오, 오버레이, 캡션).
- 리듬(Rhythm) — 구현하기 전에 씬 리듬을 선언하세요. 어떤 씬이 빠른 히트이고, 어떤 씬이 홀드이며, 셰이더가 어디에 위치하고, 에너지가 어디서 최고조에 달하는지. 패턴 이름을 지정하세요: fast-fast-SLOW-fast-SHADER-hold. 리듬 템플릿을 위해 references/beat-direction.md를 읽으세요.
- 타이밍(Timing) — 어떤 클립이 지속 시간을 결정하며, 전환이 어디에 위치하고, 페이스는 어떤지.
- 레이아웃(Layout) — 먼저 최종 상태를 구축하세요. 아래 "애니메이션 전 레이아웃"을 참조하세요.
- 애니메이션(Animate) — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.
요청된 것을 구축하세요. "타이틀 카드"에 대한 요청은 "타이틀 카드 + 3개의 지원 씬 + 배경 음악 + 캡션"에 대한 요청이 아닙니다. 모든 씬, 모든 요소, 모든 트윈은 그 자리를 증명해야 합니다. 추가 씬이나 요소가 작품을 진정으로 향상시킨다면 제안하세요 — 추가하지 마세요.
작은 편집의 경우 (색상 수정, 타이밍 조정, 한 요소 추가), 바로 규칙으로 건너뛰세요.
<하드 게이트>
컴포지션 HTML을 작성하기 전에 — 단계 1에서 시각적 정체성을 확인했는지 검증하세요. #333, #3b82f6 또는 Roboto를 사용하려고 한다면, 건너뛴 것입니다.
</하드 게이트>
애니메이션 전 레이아웃
각 요소를 가장 잘 보이는 순간 — 완전히 진입하고, 올바르게 배치되며, 아직 나가지 않는 프레임 — 의 위치에 배치하세요. 이것을 정적 HTML+CSS로 먼저 작성하세요. 아직 GSAP은 사용하지 마세요.
이것이 중요한 이유: 요소를 애니메이션 시작 상태 (화면 밖, 0으로 스케일, 불투명도 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를 절대 사용하지 마세요. 절대 위치 콘텐츠 컨테이너는 콘텐츠가 남은 공간보다 길 때 오버플로우됩니다.position: absolute는 장식 요소에만 사용하세요. gsap.from()으로 진입 추가 — 화면 밖/보이지 않는 상태에서 CSS 위치로 FROM 애니메이션. CSS 위치는 진실 공급원입니다. 트윈은 그곳에 도달하는 여정을 설명합니다. (data-composition-src를 통해 로드된 서브 컴포지션에서는gsap.fromTo()를 선호하세요 — references/motion-principles.md의 부하 지지 GSAP 규칙 참조.)gsap.to()로 종료 추가 — CSS 위치에서 화면 밖/보이지 않는 상태로 TO 애니메이션.
예시
/* scene-content가 씬을 채우고, 패딩이 콘텐츠 위치 지정 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* 컨테이너가 모든 씬 크기(1920x1080, 1080x1920 등)를 채웁니다.
패딩이 콘텐츠 위치 지정. Flex + gap이 간격 처리. */
잘못된 예 — 하드코딩된 치수 및 절대 위치 지정:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// 단계 3: 해당 위치로 애니메이션
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// 단계 4: 해당 위치에서 밖으로 애니메이션
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
요소가 시간에 걸쳐 공간을 공유하는 경우
요소 A가 요소 B가 같은 영역에 진입하기 전에 종료하면, 두 요소 모두 각자의 히어로 프레임에 대해 올바른 CSS 위치를 가져야 합니다. 타임라인 순서는 시각적으로 공존하지 않도록 보장합니다 — 하지만 레이아웃 단계를 건너뛰면, 타이밍 오류로 인해 실수로 겹치는 경우를 잡지 못합니다.
의도적인 겹침으로 간주되는 것
레이어 효과(텍스트 뒤의 글로우, 그림자 요소, 배경 패턴) 및 z-스택 디자인(카드 스택, 깊이 레이어)은 의도적입니다. 레이아웃 단계는 의도하지 않은 겹침을 잡기 위한 것입니다 — 두 개의 헤드라인이 서로 위에 겹쳐지거나, 통계가 레이블을 가리거나, 콘텐츠가 프레임 밖으로 나가는 경우.
데이터 속성
모든 클립
| 속성 | 필수 | 값 |
|---|---|---|
id | 예 | 고유 식별자 |
data-start | 예 | 초 또는 클립 ID 참조("el-1", "intro + 2") |
data-duration | img/div/컴포지션에 필수 | 초. 비디오/오디오는 미디어 지속 시간 기본값. |
data-track-index | 예 | 정수. 같은 트랙 클립은 겹칠 수 없음. |
data-media-start | 아니요 | 소스로의 트림 오프셋 (초) |
data-volume | 아니요 | 0-1 (기본값 1) |
data-track-index는 시각적 레이어링에 영향을 주지 않습니다 — CSS z-index를 사용하세요.
컴포지션 클립
| 속성 | 필수 | 값 |
|---|---|---|
data-composition-id | 예 | 고유 컴포지션 ID |
data-start | 예 | 시작 시간 (루트 컴포지션: "0" 사용) |
data-duration | 예 | GSAP 타임라인 지속 시간보다 우선 |
data-width / data-height | 예 | 픽셀 치수 (1920x1080 또는 1080x1920) |
data-composition-src | 아니요 | 외부 HTML 파일 경로 |
data-variable-values | 아니요 | 서브 컴포넌트 호스트에서 인스턴스별 변수 재정의의 JSON 객체 |
루트 <html> 요소:
| 속성 | 필수 | 값 |
|---|---|---|
data-composition-variables | 아니요 | 선언된 변수의 JSON 배열 (id/type/label/default) — Studio 편집 UI를 구동하고 getVariables()에 기본값 제공 |
컴포지션 구조
data-composition-src를 통해 로드된 서브 컴포지션은 <template> 래퍼를 사용합니다. 독립형 컴포지션 (메인 index.html)은 <template>을 사용하지 않습니다 — data-composition-id div를 <body>에 직접 넣습니다. 독립형 파일에서 <template>을 사용하면 모든 콘텐츠가 브라우저에서 숨겨져 렌더링이 깨집니다.
서브 컴포지션 구조:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- 콘텐츠 -->
<style>
[data-composition-id="my-comp"] {
/* 범위 스타일 */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// 트윈...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
루트에서 로드: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
변수 (매개변수화된 컴포지션)
소스 HTML을 편집하지 않고도 다른 콘텐츠(제목, 테마 색상, 가격, 캡션)로 동일한 컴포지션을 렌더링합니다.
세 단계 패턴:
- 선언
data-composition-variables로 컴포지션의<html>루트에 변수를 선언하세요. 각 항목은id,type(string,number,color,boolean,enum중 하나),label,default가 필요합니다. Enum 항목은options: [{value, label}, ...]도 필요합니다. - 읽기 컴포지션 스크립트 내에서
window.__hyperframes.getVariables()로 해결된 값을 읽으세요. 선언된 기본값 + 인스턴스별 재정의 + CLI 재정의의 병합된 결과를 반환합니다. - 재정의
npx hyperframes render --variables '{...}'(최상위) 또는 호스트 요소의data-variable-values='{...}'(서브 컴포넌트의 인스턴스별)로 렌더링 시 재정의합니다.
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"제목","default":"안녕하세요"},
{"id":"theme","type":"enum","label":"테마","default":"light","options":[
{"value":"light","label":"라이트"},
{"value":"dark","label":"다크"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# 개발 미리보기는 선언된 기본값 사용
npx hyperframes preview
# 재정의로 렌더링
npx hyperframes render --variables '{"title":"Q4 보고서","theme":"dark"}' --output q4.mp4
# 또는 JSON 파일에서
npx hyperframes render --variables-file ./vars.json
서브 컴포지션 인스턴스별 값: data-composition-src를 통해 로드된 서브 컴포넌트 내에서도 동일한 getVariables()가 작동합니다. 각 호스트 요소는 자체 값을 전달합니다:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Enterprise","price":"$99"}'
></div>
UI 편집: Studio는 선언된 변수를 기반으로 편집기를 생성합니다. 각 변수는 해당 type에 맞는 입력(문자열, 숫자, 색상 선택기, 토글, 드롭다운)을 얻습니다.
GSAP 모션 규칙
- 모든 타임라인 변수는
window.__timelines에 등록되어야 합니다. - 서브 컴포지션은
gsap.fromTo()를 사용하세요 — 각 인스턴스는data-variable-values가 다를 수 있으므로 시작 및 종료 값을 명시적으로 설정해야 합니다. - 진입은 CSS가 최종 위치를 소유한다는 전제로
from()을 사용하세요. - 종료는
to()를 사용하세요. - 중첩된 타임라인에
tl.add()를 사용하세요. - 지속 시간은 0.4-1.2초로 유지하고, 기본값은 0.6초로 합니다.
- 이징: 진입은
power2.out또는power3.out, 종료는power2.in. - 클립 지속 시간을 초과하는 경우
position: "absolute"를 사용하세요. tl.totalDuration()은data-duration과 일치해야 하며, 일치하지 않으면tl.progress(1)을 강제로 적용하세요.onStart를function()(화살표 함수 아님)으로 사용하여 로컬 변수와 충돌을 피하세요.
텍스트 페이드 방지
텍스트 클립은 정적 기간 동안 페이드하지 마세요. 타이틀 카드가 정적 상태로 유지되어야 한다면, 하나의 DOM 요소로 이를 달성하세요. 동일한 id의 요소를 복제하고 교체하는 것은 ES 브릿지 기술이며, 새로운 GSAP 애니메이션이 필요하지 않습니다.
구체적인 지속 시간
모든 지속 시간을 초 단위로 명시적으로 설정하세요 — "auto"를 사용하지 마세요. 비디오 컴포지션은 미디어에 관계없이 정확한 타이밍이 필요합니다.
반응형 오디오
references/audio-reactive.md를 읽으세요. 오디오 반응형 비주얼을 위해 AudioMotionAnalyzer를 사용하고, 웨이브폼을 위해 HyperframesAudio 및 AudioMotion 클립을 사용하세요. 오디오 트랙에는 항상 명시적인 오디오 매니페스트 항목과 data-audition-id가 필요합니다.
기본 규칙
- 항상 GSAP cdn.js 링크를 포함하세요.
- 항상
data-duration,data-track-index,data-start를 설정하세요. position: absolute를 피하세요 — 레이아웃을 위해 flexbox를 사용하세요.- 모든 요소의 길이를 수동으로 계산하세요.
- 타임라인이 모든 코드 경로에서 정의되었는지 확인하세요 — 특히 조건부 논리가 있는 경우.
window.__timelines에 타임라인을 등록하세요.- 애니메이션을 위해 항상 GSAP를 사용하세요 — CSS 트랜지션을 사용하지 마세요.
- 오디오 트랙 ID를 항상 명시적으로 설정하세요.
인덱스 파일(main.ts)
main.ts는 런타임 부트스트래퍼입니다: GSAP, HyperframesAudio, SheetRender, postRobot를 가져오고, 타임라인을 등록하고, 각 컴포지션의 로드, 언로드, 시작을 위한 브릿지 리스너를 설정합니다. data-composition-src를 통해 로드된 파일만 이 import를 필요로 합니다. 독립형 파일은 자체 <script> 태그에서 GSAP를 직접 포함합니다.
오디오 및 캡션
references/audio.md를 읽으세요. 오디오 파일은 data-media-start, data-volume 및 명시적 지속 시간이 있는 클립입니다. 텍스트 캡션의 경우 references/captions.md를 읽으세요. 캡션은 청각 장애인 접근성을 위해 선택 사항이 아닙니다. 항상 캡션을 포함하세요. 캡션 없는 비디오는 차별입니다.
성능
성능 고려 사항은 재렌더링을 방지하기 위한 신호 대기열, __plan 객체, resolve.shift()를 포함합니다.
참조
모든 참조 파일: