Communitygithub.com

s2530786-cell/ION-DEX

비디오 합성, 애니메이션, 타이틀 카드, 오버레이, 자막, 음성 해설, 오디오 반응형 비주얼, 장면 전환을 HyperFrames HTML로 제작합니다. HTML 기반 비디오 콘텐츠 제작 요청 시 사용하세요.

ION-DEX란 무엇인가요?

이 스킬은 HyperFrames 프레임워크를 기반으로 HTML을 비디오 제작의 단일 진실 공급원(Source of Truth)으로 사용하여 전체 비디오 제작 워크플로우를 지원합니다. 디자인 시스템(design.md)부터 시작하여 브랜드 색상과 폰트를 적용하고, 프롬프트 확장(prompt-expansion)을 통해 사용자 의도를 명확히 합니다. 그런 다음 레이아웃 우선 접근법으로 정적 HTML+CSS로 최종 상태를 먼저 구성한 후 GSAP으로 진입/퇴장 애니메이션을 추가합니다. 다양한 데이터 속성(data-start, data-duration, data-track-index 등)을 통해 클립 타이밍과 오버레이를 제어하고, 변수 시스템(data-composition-variables)을 활용해 동일한 구성을 다양한 콘텐츠로 재사용할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex 등 에이전트 기반 개발 환경에서 사용되며, 여러 장면 전환(크로스페이드, 와이프, 리빌, 셰이더 전환), 자막 동기화, 오디오 반응형 애니메이션(비트 동기화, 글로우, 펄스), 애니메이션 텍스트 강조(마커 스윕, 핸드드로운 서클, 버스트 라인 등)를 지원합니다. 개발 루프 CLI 명령어(init, lint, inspect, preview, render)나 자산 전처리 명령어(tts, transcribe, remove-background)는 각각 hyperframes-cli 및 hyperframes-media 스킬에 위임합니다.

지원 대상~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/s2530786-cell/ION-DEX/tree/HEAD/.cursor/skills/hyperframes

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HyperFrames

HTML이 비디오의 단일 진실 공급원(Source of Truth)입니다. 합성(composition)은 data-* 속성으로 타이밍을 지정하고, GSAP 타임라인으로 애니메이션을, CSS로 모양을 정의하는 HTML 파일입니다. 프레임워크가 클립 가시성, 미디어 재생, 타임라인 동기화를 처리합니다.

접근법

탐색 (탐색적 요청에만 해당)

사용자가 방향을 정하지 않은 개방형 요청("제품 출시 비디오 만들어줘", "브랜드를 위한 무언가 만들어줘")의 경우, 색상을 선택하기 전에 의도를 파악하세요:

  • 대상 — 누가 시청하나요? 개발자? 임원? 일반 소비자?
  • 플랫폼 — 어디서 재생되나요? 소셜 미디어(15초), 웹사이트 히어로, 제품 데모, 내부용?
  • 우선순위 — 무엇이 가장 중요한가요? 모션 품질? 콘텐츠 정확도? 브랜드 충실도? 속도?
  • 변형 — 사용자가 여러 옵션을 원하나요, 아니면 하나의 최선의 결과물을 원하나요?

구체적인 요청("타이틀 카드 추가해줘", "장면 3 타이밍 수정해줘")의 경우 탐색 단계를 건너뜁니다.

탐색적 요청의 경우, 단순한 색상 변경이 아니라 의미 있게 다른 2-3가지 변형을 제안하는 것을 고려하세요. 예: 다른 페이스, 에너지 레벨 또는 구조적 접근법. 하나는 안전하고 예상되는 버전, 다른 하나는 야심찬 버전. 필수는 아니며, 적절할 때 사용할 수 있는 도구입니다.

1단계: 디자인 시스템

프로젝트에 design.md 또는 DESIGN.md 파일이 있으면 먼저 읽으세요 (대소문자를 모두 확인하세요 — Linux에서는 다른 파일입니다). 브랜드 색상, 폰트, 제약 조건의 단일 진실 공급원입니다. 정확한 값을 사용하세요 — 색상을 임의로 만들거나 폰트를 대체하지 마세요. 어떤 형식이든 괜찮습니다 (YAML 머리말, 산문, 테이블 — 값을 추출하기만 하면 됩니다).

로컬에서 찾을 수 없는 폰트( fonts/ 디렉토리에 .woff2 파일이 없고, 내장 폰트도 아님)를 지정하는 경우 HTML을 작성하기 전에 사용자에게 경고하세요: "design.md에 [폰트 이름]이 지정되었지만 폰트 파일을 찾을 수 없습니다. fonts/에 .woff2 파일을 추가하거나 가장 가까운 내장 대안으로 대체하겠습니다."

design.md가 없으면 사용자에게 선택권을 제공하세요:

  1. 사용자가 스타일이나 분위기를 지정했나요? → visual-styles.md에서 8개의 명명된 프리셋을 읽고 가장 가까운 것을 선택하세요.
  2. 옵션을 시각적으로 탐색하고 싶나요? → 디자인 선택기를 실행하세요: 전체 워크플로는 references/design-picker.md를 참조하세요. 시각적 선택기 페이지를 제공합니다. 사용자가 브라우저에서 분위기, 팔레트, 타이포그래피, 모션을 구성한 후 생성된 design.md를 복사하여 대화에 다시 붙여넣습니다.
  3. 건너뛰고 빠르게 진행하고 싶나요? → 분위기, 라이트/다크, 브랜드 색상/폰트를 물어보세요. 그런 다음 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을 작성하기 전에 높은 수준에서 생각하세요:

  1. 무엇 — 시청자는 무엇을 경험해야 하나요? 내러티브 아크, 핵심 순간, 감정적 비트를 식별하세요.
  2. 구조 — 합성은 몇 개이며, 서브 합성인지 인라인인지, 어떤 트랙이 무엇을 전달하는지 (비디오, 오디오, 오버레이, 자막).
  3. 리듬 — 구현하기 전에 장면 리듬을 선언하세요. 어떤 장면이 빠르고, 어떤 장면이 느리며, 셰이더는 어디에 배치되고, 에너지는 어디서 최고조에 달하는지. 패턴 이름을 지정하세요: 빠름-빠름-느림-빠름-셰이더-홀드. 리듬 템플릿은 references/beat-direction.md를 참조하세요.
  4. 타이밍 — 어떤 클립이 지속 시간을 결정하고, 전환이 어디에 배치되며, 페이싱은 어떠한지.
  5. 레이아웃 — 최종 상태를 먼저 구축하세요. 아래 "애니메이션 전 레이아웃"을 참조하세요.
  6. 애니메이션 — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.

요청된 것을 구축하세요. "타이틀 카드" 요청은 "타이틀 카드 + 3개의 지원 장면 + 배경 음악 + 자막" 요청이 아닙니다. 모든 장면, 모든 요소, 모든 트윈은 그 자리를 정당화해야 합니다. 추가 장면이나 요소가 작품을 진정으로 향상시킨다면 제안하세요 — 추가하지 마세요.

사소한 편집(색상 수정, 타이밍 조정, 요소 하나 추가)의 경우 바로 규칙으로 건너뜁니다.

<하드-게이트> 합성 HTML을 작성하기 전에 — 1단계에서 시각적 정체성을 확인했는지 검증하세요. #333, #3b82f6 또는 Roboto에 손이 간다면 건너뛴 것입니다. </하드-게이트>

애니메이션 전 레이아웃

모든 요소를 가장 잘 보이는 순간(완전히 진입하고, 올바르게 배치되고, 아직 퇴장하지 않은 프레임)에 배치하세요. 이것을 먼저 정적 HTML+CSS로 작성하세요. 아직 GSAP는 사용하지 마세요.

이것이 중요한 이유: 애니메이션 시작 상태(화면 밖, 0으로 축소, 불투명도 0)에 요소를 배치하고 도착해야 할 위치로 트윈하면 최종 레이아웃을 추측하는 것입니다. 중복은 비디오가 렌더링될 때까지 보이지 않습니다. 최종 상태를 먼저 구축하면 모션을 추가하기 전에 레이아웃 문제를 보고 수정할 수 있습니다.

프로세스

  1. 각 장면의 히어로 프레임을 식별하세요 — 대부분의 요소가 동시에 보이는 순간입니다. 이것이 구축할 레이아웃입니다.
  2. 해당 프레임에 대한 정적 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는 장식용으로만 예약하세요.
  3. gsap.from()으로 진입 추가 — 화면 밖/보이지 않음에서 CSS 위치로 애니메이션합니다. CSS 위치가 기본 진실이며, 트윈은 그곳에 도달하는 과정을 설명합니다. (data-composition-src를 통해 로드된 서브 합성에서는 gsap.fromTo()를 선호하세요 — references/motion-principles.md의 하중 지지 GSAP 규칙 참조.)
  4. 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-durationimg/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을 편집하지 않고 렌더링합니다.

3단계 패턴:

  1. 선언: 합성의 <html> 루트에 data-composition-variables로 변수를 선언합니다. 각 항목에는 id, type (string, number, color, boolean, enum 중 하나), label, default가 필요합니다. Enum 항목에는 options: [{value, label}, ...]도 필요합니다.
  2. 읽기: 합성 내부 스크립트에서 window.__hyperframes.getVariables()로 해결된 값을 읽습니다. 선언된 기본값 + 인스턴스별 재정의 + CLI 재정의의 병합된 결과를 반환합니다.
  3. 재정의: 렌더링 시 npx hyperframes render --variables '{...}' (최상위) 또는 호스트 요소의 data-variable-values='{...}' (서브 컴포넌트의 인스턴스별)로 재정의합니다.
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"제목","default":"Hello"},
  {"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>

오디오 반응형 애니메이션

분석된 오디오 데이터에 애니메이션을 연결하려면 각 프레임(1/30초)에서 오디오 스펙트럼과 주파수 대역(저음, 중음, 고음)의 배열을 제공하는 __hyperframes.getAudioFrameData(timeInSeconds)를 사용하세요. 각 프레임은 { spectrum: Float32Array, bands: { bass: number, mid: number, treble: number } }를 반환합니다. 또한 __hyperframes.getPeakTimestamps()는 타임스amps 배열을 반환합니다. 자세한 API 참조는 references/audio-reactive.md를 참조하세요.

function animateBeat() {
  const frame = __hyperframes.getAudioFrameData(tl.time());
  if (frame) {
    const bass = frame.bands.bass;
    gsap.set(".pulse-circle", { scale: 1 + bass * 2 });
    gsap.set(".glow", { opacity: 0.3 + bass * 0.7 });
  }
  requestAnimationFrame(animateBeat);
}
animateBeat();

텍스트 애니메이션 및 강조

HyperFrames는 마커 스윕, 손으로 그린 원, 버스트 라인, 낙서, 스케치아웃과 같은 텍스트 강조를 지원합니다. 이는 SVG 오버레이와 GSAP 트윈을 결합하여 구현됩니다. 참조는 references/text-animations.md를 참조하세요.

장면 전환

다음 유형의 전환을 지원합니다: 크로스페이드, 와이프(왼쪽/오른쪽/위/아래), 리빌(원형, 사각형, 다이아몬드), 셰이더 기반 전환(사용자 정의 GLSL 효과). 전환은 보통 data-duration이 겹치는 클립을 사용하여 중첩된 클립을 통해 구현됩니다. 자세한 내용은 references/transitions.md를 참조하세요.

자막 및 캡션

__hyperframes.getSubtitles()는 타임스탬프가 있는 자막 배열을 반환합니다. 클립 텍스트 요소를 업데이트하여 동기화된 캡션을 표시합니다. TTS(텍스트 음성 변환) 워크플로는 hyperframes-media 스킬을 참조하세요.

렌더링

# 단일 파일 미리보기
npx hyperframes preview

# 프로젝트 검사 (모든 합성 및 종속성 목록)
npx hyperframes inspect

# 비디오 파일로 렌더링
npx hyperframes render --output result.mp4

추가 참조

관련 스킬

  • hyperframes-cli — 개발 루프 CLI 명령어 (init, lint, inspect, preview, render)
  • hyperframes-media — 자산 전처리 명령어 (tts, transcribe, remove-background)

관련 스킬