HyperFrames
HTML이 비디오의 진리 소스(source of truth)입니다. 컴포지션은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외형을 위한 CSS를 갖춘 HTML 파일입니다. 프레임워크는 클립 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.
포괄 범위 및 흡수된 좁은 워크플로우
이 스킬은 HyperFrames 저작을 위한 클래스 수준의 포괄 스킬입니다. 컴포지션 구조, 타이밍, 애니메이션, 시각적 아이덴티티, 자막, 오디오 반응형 비주얼 및 프로덕션 품질의 장면 구성을 다룹니다. 명령어 참조는 hyperframes-cli 스킬을 사용하고, 소스 자료가 기존 웹사이트인 경우 website-to-hyperframes를 사용하세요. 단일 세션 프로덕션/디버깅 노트는 여기서 지원 참조로 전환되었습니다.
하위 섹션: 프로덕션 워크플로우 함정
과거 프로덕션 노트는 여전히 유용한 몇 가지 환경 함정을 강조했습니다:
- 렌더링 시 ASCII 전용 프로젝트/출력 경로를 선호하세요. 비-ASCII 경로는 headless Chrome 또는 렌더러 하위 프로세스를 손상시킬 수 있습니다.
- Conda FFmpeg에서 MP4 인코딩이 실패하는 경우,
export PATH=/usr/bin:$PATH로 시스템 FFmpeg를 강제로 사용하거나, 대체로 WebM을 렌더링하세요. - GSAP 대신 사용자 정의 타임라인 객체를 사용하는 경우, GSAP 호환
duration(),pause()및seek(time)메서드를 노출해야 합니다. - 최종 비디오가 검게 보이거나 빈 것처럼 보이면, 먼저 타이밍이 적용된
.clip컨테이너가 숨겨져 있고 그 자식만 애니메이션되었는지 확인하세요. 장면 래퍼에.hidden { display: none; }과 같은 유틸리티 클래스를 사용하면 전형적인 실패 모드가 발생합니다: 오디오는 렌더링되고, 배경은 렌더링되지만, 부모 장면이 레이아웃/페인트에 진입하지 않았기 때문에 텍스트/카드가 절대 나타나지 않습니다. 타이밍이 적용된 장면 래퍼의 경우,display: none대신opacity: 0또는 타임라인 제어 불투명도를 사용하여 숨기세요. - GSAP과 같은 중요한 런타임 JS의 경우, 렌더링 중 실시간 CDN 가져오기에 의존하기보다 프로젝트에 로컬 복사본(예:
assets/gsap.min.js)을 제공하는 것을 선호하세요. - 프로젝트에 파비콘이 없을 때 headless 브라우저의 파비콘 404 노이즈를 억제하려면 독립 실행형 컴포지션에
<link rel="icon" href="data:,">를 추가하세요. - 성공적인 렌더링 종료 코드만 신뢰하지 말고, FFmpeg로 프레임을 추출하고 스크린샷을 검사하여 시각적으로 확인하세요.
강등된 지원 참조
references/hyperframes-video-production.mdreferences/hyperframes-workflow.md
접근 방식
HTML을 작성하기 전에 높은 수준에서 생각하세요:
- 무엇을 — 시청자가 무엇을 경험해야 합니까? 내러티브 아크, 핵심 순간 및 감정적 비트를 식별하세요.
- 구조 — 얼마나 많은 컴포지션이 있으며, 어떤 것이 하위 컴포지션이고 인라인이며, 어떤 트랙이 무엇을 전달합니까(비디오, 오디오, 오버레이, 자막).
- 타이밍 — 어떤 클립이 지속 시간을 결정하며, 전환이 어디에 위치하고, 페이싱은 무엇입니까?
- 레이아웃 — 먼저 최종 상태를 구축하세요. 아래 "애니메이션 전 레이아웃"을 참조하세요.
- 애니메이션 — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.
작은 편집(색상 수정, 타이밍 조정, 요소 하나 추가)의 경우 바로 규칙으로 건너뛰세요.
시각적 아이덴티티 게이트
다음 순서로 확인하세요:
- 프로젝트에 DESIGN.md가 있습니까? → 읽으세요. 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것" 제약 조건을 사용하세요.
- visual-style.md가 있습니까? → 읽으세요.
style_prompt_full및 구조화된 필드를 적용하세요. (참고:visual-style.md는 프로젝트별 파일입니다.visual-styles.md는 8개의 명명된 프리셋이 있는 스타일 라이브러리입니다 — 다른 파일입니다.) - 사용자가 스타일을 지정했습니까? (예: "Swiss Pulse", "dark and techy", "럭셔리 브랜드") → 8개의 명명된 프리셋에 대해 visual-styles.md를 읽으세요. 최소한의 DESIGN.md를 생성하세요:
## Style Prompt(한 문단),## Colors(역할이 포함된 3-5개의 16진수 값),## Typography(1-2개의 글꼴 모음),## What NOT to Do(3-5개의 안티 패턴). - 위의 어느 것도 해당되지 않습니까? → HTML을 작성하기 전에 3가지 질문을 하세요:
- 분위기는 무엇입니까? (폭발적인 / 영화 같은 / 유동적인 / 기술적인 / 혼란스러운 / 따뜻한)
- 밝은 캔버스입니까, 어두운 캔버스입니까?
- 특정 브랜드 색상, 글꼴 또는 시각적 참조가 있습니까? 그런 다음 답변에서 최소한의 DESIGN.md를 생성하세요.
모든 컴포지션은 팔레트와 타이포그래피를 DESIGN.md, visual-style.md 또는 명시적인 사용자 지시로 추적해야 합니다. #333, #3b82f6 또는 Roboto에 도달하고 있다면 이 단계를 건너뛴 것입니다.
모션 기본값, 크기 조정, 진입 패턴 및 이징에 대해서는 house-style.md를 따르세요. 하우스 스타일은 사물이 어떻게 움직이는지를 처리합니다. DESIGN.md는 사물이 어떻게 보이는지를 처리합니다.
애니메이션 전 레이아웃
모든 요소를 가장 잘 보이는 순간 — 완전히 진입하고, 올바르게 배치되었으며, 아직 종료되지 않은 프레임 — 에 있어야 할 위치에 배치하세요. 이것을 먼저 정적 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 위치는 기본 진실입니다. 트윈은 그곳에 도달하는 여정을 설명합니다.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단계: 해당 위치로 애니메이션 진입
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-composition-src를 통해 로드된 하위 컴포지션은 <template> 래퍼를 사용합니다. 독립 실행형 컴포지션 (메인 index.html)은 <template>을 사용하지 않습니다 — <body>에 직접 data-composition-id div를 넣습니다. 독립 실행형 파일에 <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>
비디오 및 오디오
비디오는 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() 또는 시간 기반 논리를 사용하지 마세요. 의사 난수 값 (예: mulberry32)이 필요한 경우 시드된 PRNG를 사용하세요.
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")
장면 전환 (협상 불가)
모든 다중 장면 컴포지션은 다음 규칙을 모두 따라야 합니다. 하나라도 위반하면 깨진 컴포지션입니다.
- 항상 장면 간에 전환을 사용하세요. 점프 컷은 금지됩니다. 예외 없음.
- 항상 모든 장면에 진입 애니메이션을 사용하세요. 모든 요소는
gsap.from()을 통해 진입 애니메이션됩니다. 어떤 요소도 완전히 형성된 상태로 나타나서는 안 됩니다. 장면이
…
[번역을 위해 잘렸습니다]