HyperFrames
HTML은 비디오의 진실 공급원(source of truth)입니다. 컴포지션은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외관을 위한 CSS를 포함하는 HTML 파일입니다. 프레임워크가 클립 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.
접근 방식
탐색 (탐색적 요청에만 해당)
사용자가 방향을 정하지 않은 개방형 요청("제품 출시 비디오를 만들어 줘", "우리 브랜드를 위한 무언가를 만들어 줘")의 경우, 색상을 선택하기 전에 의도를 파악하세요.
- 대상 — 누가 이것을 보는가? 개발자? 임원? 일반 소비자?
- 플랫폼 — 어디에서 재생되는가? 소셜(15초), 웹사이트 히어로, 제품 데모, 내부용?
- 우선순위 — 무엇이 가장 중요한가? 모션 품질? 콘텐츠 정확성? 브랜드 충실도? 속도?
- 변형 — 사용자가 옵션을 원하는가, 아니면 단 하나의 최선의 결과물을 원하는가?
구체적인 요청("타이틀 카드를 추가해 줘", "씬 3의 타이밍을 수정해 줘")의 경우 탐색을 건너뜁니다.
탐색적 요청의 경우, 단순한 색상 변경이 아닌, 다른 템포, 에너지 레벨 또는 구조적 접근 방식을 가진 의미 있게 다른 2-3가지 변형을 제공하는 것을 고려하세요. 하나는 안전하고 예상되는 스타일로, 다른 하나는 야심 찬 스타일로. 이것을 의무 사항으로 강제하지 마세요. 적절할 때 사용할 수 있는 도구입니다.
1단계: 디자인 시스템
프로젝트에 design.md 또는 DESIGN.md 파일이 있으면 먼저 읽으세요(두 가지 대소문자를 모두 확인하세요. Linux에서는 서로 다른 파일입니다). 브랜드 색상, 글꼴 및 제약 조건에 대한 진실 공급원입니다. 정확한 값을 사용하세요. 색상을 만들거나 글꼴을 대체하지 마세요. 모든 형식이 작동합니다(YAML frontmatter, 산문, 표 — 값을 추출하기만 하면 됩니다).
로컬에서 찾을 수 없는 글꼴을 지정하는 경우(fonts/ 디렉토리에 .woff2 파일이 없거나 내장 글꼴이 아닌 경우), HTML을 작성하기 전에 사용자에게 경고하세요: "design.md에 [글꼴 이름]이 지정되었지만 글꼴 파일을 찾을 수 없습니다. fonts/에 .woff2 파일을 추가하거나 가장 가까운 내장 대체 글꼴로 대체하겠습니다."
design.md 파일이 없으면 사용자에게 선택권을 제공하세요.
- 사용자가 스타일이나 분위기를 지정했는가? → visual-styles.md에서 8가지 명명된 프리셋을 읽고 가장 가까운 것을 선택하세요.
- 시각적으로 옵션을 탐색하고 싶은가? → 디자인 선택기를 실행하세요: 전체 워크플로우를 위해 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을 작성하기 전에 높은 수준에서 생각하세요.
- 무엇 — 시청자는 무엇을 경험해야 하는가? 내러티브 아크, 핵심 순간 및 감정적 비트를 식별하세요.
- 구조 — 몇 개의 컴포지션, 하위 컴포지션인지 인라인인지, 어떤 트랙이 무엇을 전달하는지(비디오, 오디오, 오버레이, 캡션).
- 리듬 — 구현하기 전에 씬 리듬을 선언하세요. 어떤 씬이 빠른 히트이고, 어떤 것이 유지이며, 셰이더가 어디에 위치하고, 에너지가 어디에서 최고조에 달하는지. 패턴 이름을 지정하세요: fast-fast-SLOW-fast-SHADER-hold. 리듬 템플릿은 references/beat-direction.md를 읽으세요.
- 타이밍 — 어떤 클립이 지속 시간을 결정하고, 전환이 어디에 위치하며, 페이스는 어떠한지.
- 레이아웃 — 먼저 최종 상태를 구축하세요. 아래의 "애니메이션 전 레이아웃"을 참조하세요.
- 애니메이션 — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.
요청된 것을 구축하세요. "타이틀 카드"에 대한 요청은 "타이틀 카드 + 3개의 지원 씬 + 배경 음악 + 캡션"에 대한 요청이 아닙니다. 모든 씬, 모든 요소, 모든 트윈은 그 자리를 정당화해야 합니다. 추가 씬이나 요소가 작품을 진정으로 개선할 경우 제안하세요. 추가하지 마세요.
작은 편집(색상 수정, 타이밍 조정, 요소 하나 추가)의 경우 규칙으로 바로 건너뛰세요.
애니메이션 전 레이아웃
모든 요소를 가장 잘 보이는 순간에 배치하세요. 요소가 완전히 들어오고, 올바르게 배치되고, 아직 나가지 않는 프레임입니다. 이것을 먼저 정적 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 위치로 애니메이션을 적용합니다. CSS 위치는 진실 공급원입니다. 트윈은 그곳에 도달하는 여정을 설명합니다. (data-composition-src를 통해 로드된 하위 컴포지션에서는gsap.fromTo()를 선호합니다. references/motion-principles.md의 하중 지지 GSAP 규칙 참조).gsap.to()로 퇴장을 추가하세요. CSS 위치에서 화면 밖/보이지 않는 곳으로 애니메이션을 적용합니다.
예시
/* 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단계: 해당 위치로 애니메이션 적용
// step3: animate into those positions
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);
// step4: animate out from those positions
// 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/compositions에 필수 | 초. 비디오/오디오는 미디어 길이를 기본값으로 사용합니다. |
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-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">
<!-- content -->
<style>
[data-composition-id="my-comp"] {
/* scoped styles */
}
</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 });
// tweens...
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>
비디오 및 오디오
비디오는 muted playsinline이어야 합니다. 오디오는 항상 별도의 <audio> 요소입니다:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
타임라인 규약
- 모든 타임라인은
{ 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을 사용하지 마세요. 항상 유한 반복을 사용하세요. - 타임라인을 비동기식으로 구축하지 마세요(
async,setTimeout,Promise내부). - 이후 씬의 클립 요소에
gsap.set()을 사용하지 마세요. 페이지 로드 시 DOM에 존재하지 않습니다. 클립의data-start시간 또는 그 이후에 타임라인 내부에서tl.set(selector, vars, timePosition)을 사용하세요. - 콘텐츠 텍스트에
<br>을 사용하지 마세요. 강제 줄 바꿈은 실제 렌더링된 글꼴 너비를 고려하지 않습니다. 자연스럽게 줄바꿈되는 텍스트에<br>이 추가되면 원하지 않는 추가 줄바꿈이 발생하여 겹침이 발생합니다.max-width를 통해 텍스트를 줄바꿈하세요. 예외: 각 단어가 의도적으로 자체 줄에 있는 짧은 디스플레이 제목(예: 130px에서 "THE\nIMMORTAL\nGAME")입니다.
씬 전환 (협상 불가)
모든 멀티 씬 컴포지션은 다음 규칙을 모두 따라야 합니다. 하나라도 위반하면 컴포지션이 깨집니다.
- **
…
[번역을 위해 잘렸습니다]