HyperFrames
HTML은 비디오의 진실 공급원(source of truth)입니다. 합성물(composition)은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외형을 위한 CSS가 포함된 HTML 파일입니다. 프레임워크는 클립의 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.
Open Design 통합 (이 표면의 핵심)
이 스킬이 Open Design 내에서 실행될 때(즉, $OD_PROJECT_DIR이 설정된 경우), 출력 흐름은 고정됩니다. 렌더링된 .mp4 파일만 프로젝트 루트에 배치되어야 합니다. 합성물 소스 파일(hyperframes.json, meta.json, index.html, 에셋)은 사용자의 FileViewer나 채팅의 "생성된 파일" 칩을 복잡하게 만들지 않도록 숨김 캐시 디렉토리 안에 속합니다.
OD 내부의 렌더링 워크플로우 — 빠른 경로(Fast Path):
대부분의 OD 요청("테스트 비디오", "5초 제품 소개", "데모 클립")에 대해 합성물 HTML을 처음부터 작성하지 마십시오. HyperFrames의 내장 스캐폴드(scaffold)를 사용하고 프롬프트가 실제로 변경하는 부분만 편집하십시오. "처음부터 작성" 경로는 모델 출력과 조용한 채팅 도구 시간을 분 단위로 소모하지만, 스캐폴드 경로는 몇 초면 끝납니다.
# 1. 숨김 캐시 슬롯을 선택합니다. 점 접두사 → OD의 프로젝트 파일
# 목록에서 이를 건너뛰므로 소스 파일이 채팅을 복잡하게 만들지 않습니다.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. 즉시 렌더링 가능한 스캐폴드(hyperframes.json,
# meta.json, GSAP CDN + window.__timelines.main이
# 이미 등록된 index.html)를 가져옵니다. 이 명령은 셸에서 실행되며,
# 순수 파일 복사이므로 Chrome, npx 캐시 외의 네트워크가 필요하지 않습니다.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. $COMP/index.html 만 편집합니다. 기본 길이가 아닌 경우 루트의
# `data-duration`을 변경하고, <style>에서 자리 표시자 팔레트를 교체하고,
# 텍스트/이미지를 위한 1~3개의 클립 <div>를 추가하고, 기존의
# `window.__timelines["main"] = gsap.timeline({paused:true})` 블록 내에
# 해당 GSAP 트윈(tween)을 추가합니다.
# 편집을 최소한으로 유지하십시오. 스캐폴드는 이미 유효한 HF입니다.
# 4. OD 데몬을 통해 렌더링을 디스패치합니다. 이 셸에서 `npx hyperframes
# render`를 실행하지 마십시오. 데몬이 샌드박스 없는 프로세스에서 대신 실행합니다.
# (특히 Claude Code와 같은 많은 에이전트 CLI는 Bash를 macOS sandbox-exec으로
# 래핑하는데, 이 아래에서 puppeteer의 Chrome 하위 프로세스가 프레임 캡처 도중
# 중단됩니다. 데몬 프로세스는 샌드박스가 없으므로 렌더링이 안정적으로 완료됩니다.)
#
# 디스패처는 ~1초 이내에 {taskId}를 반환합니다. 렌더링 완료까지
# `od media wait <taskId>` 호출을 반복하여 구동합니다.
# 각 호출은 최대 25초 동안 롱 폴링(long-poll)하며(셸 도구의 기본 30초 제한
# 미만), 종료 코드 0/2/5로 완료/실행 중/실패를 알립니다.
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<descriptive-name>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
각 generate 호출과 wait 호출은 최대 ~25초 동안 지속되므로 에이전트 셸 도구의 기본 ~30초 제한이 절대 발생하지 않습니다. HF의 진행 줄(Capturing frame N/M)은 루프 전체에 걸쳐 stderr로 실시간 스트리밍됩니다. 렌더링이 완료되면 마지막 stdout 줄은 {"file": { "name": "<출력>", "size": …, "kind": "video", … }}입니다. 생성된 파일을 사용자에게 알리기 위해 응답에서 file.name을 인용하십시오.
OD 내에서 시각적 정체성 게이트를 건너뜁니다. 아래("접근 방식" 아래)의 HARD-GATE 섹션은 합성물을 작성하기 전에 DESIGN.md / visual-style.md를 읽거나 중단하고 3가지 분위기 질문을 하라고 알려줍니다. 이 게이트는 독립형 HF 프로젝트를 위한 것입니다. OD 프로젝트에는 이미 자체 디자인 시스템 레이어가 있습니다 — 사용자는 프로젝트 생성 시 시각적 방향을 선택했습니다. OD 테스트 렌더링의 경우 다음을 기본값으로 사용하십시오: 어두운 캔버스(#0b0b0f), 하나의 따뜻한 강조 색상(#ffb76b), 하나의 차가운 강조 색상(#7da4ff), 절제된 모션. 사용자의 프롬프트가 주제조차 고르기에 너무 모호한 경우에만(매우 드묾) 스타일 입력을 요청하십시오.
처음부터 작성해야 하는 경우: 사용자가 빈 템플릿이 명확히 제공할 수 없는 것을 명시적으로 요청하는 경우에만 해당합니다(예: 다중 합성 타임라인, 오디오 반응형 오버레이, 이미 생성한 TTS 트랙과 동기화된 자막). 그 외 모든 경우에는 초기화 + 편집이 기본 경로입니다.
자체 셸에서 실행할 수 있는 가벼운 HF 하위 명령(Chrome을 실행할 필요 없음):
npx hyperframes lint "$COMP"— 디스패치 전 합성물 검증npx hyperframes transcribe <audio>— 자막 생성npx hyperframes tts <text>— 내레이션 생성
render/inspect/preview(Chrome에 의존하는 모든 것)에는 데몬 디스패치를 사용하십시오.
od media generate --model hyperframes-html을 호출하지 마십시오 — 해당 디스패처 경로는 의도적으로 400(AGENT_RENDERED)을 반환합니다. HyperFrames는 npx를 통해 사용자가 직접 렌더링합니다.
hyperframes.json / meta.json / index.html을 프로젝트 루트에 넣지 마십시오. OD의 파일 목록이 재귀적으로 스캔하여 사용자 채팅에 관련 없는 파일 세 개가 나타나게 됩니다.
render 외의 CLI 옵션(lint, preview, transcribe, tts, inspect, benchmark)은 작업이 필요할 때 셸 도구에서 직접 호출하십시오(예: 합성물에서 참조하기 전에 캐시에 TTS 오디오 생성).
접근 방식
HTML을 작성하기 전에 높은 수준에서 생각하십시오:
- 무엇을 — 시청자가 무엇을 경험해야 합니까? 내러티브 아크, 핵심 순간 및 감정적 비트를 식별하십시오.
- 구조 — 얼마나 많은 합성물, 어떤 것이 하위 합성물 또는 인라인인지, 어떤 트랙이 무엇을 전달하는지(비디오, 오디오, 오버레이, 자막).
- 타이밍 — 어떤 클립이 지속 시간을 결정하는지, 전환이 어디에 위치하는지, 페이싱은 어떠한지.
- 레이아웃 — 최종 상태를 먼저 구축하십시오. 아래의 "애니메이션 전 레이아웃"을 참조하십시오.
- 애니메이션 — 그런 다음 아래 규칙을 사용하여 모션을 추가하십시오.
작은 편집(색상 수정, 타이밍 조정, 요소 하나 추가)의 경우 바로 규칙으로 건너뛰십시오.
시각적 정체성 게이트
다음 순서로 확인하십시오:
- 프로젝트에 DESIGN.md가 있습니까? → 읽으십시오. 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것" 제약 조건을 사용하십시오.
- visual-style.md가 있습니까? → 읽으십시오.
style_prompt_full및 구조화된 필드를 적용하십시오. (참고:visual-style.md는 프로젝트별 파일입니다.visual-styles.md는 8개의 명명된 프리셋이 있는 스타일 라이브러리입니다 — 다른 파일입니다.) - 사용자가 스타일을 언급했습니까? (예: "Swiss Pulse", "어둡고 기술적인", "럭셔리 브랜드") → 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를 사용하려고 한다면 이 단계를 건너뛴 것입니다.
모션 기본값, 크기 조정, 진입 패턴 및 이징(easing)에 대해서는 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: 해당 위치로 애니메이션
ll.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: 해당 위치에서 애니메이션
ll.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>를 사용하지 않습니다 — 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>
비디오
…
[번역을 위해 잘렸습니다]