Communitygithub.com

GanQiao1990/skills_2026

HyperFrames HTML을 사용하여 비디오 컴포지션, 애니메이션, 타이틀 카드, 오버레이, 자막, 음성 해설, 오디오 반응형 비주얼 및 장면 전환을 생성합니다. HTML 기반 비디오 콘텐츠 제작, 오디오와 동기화된 자막/캡션 추가, 텍스트 음성 변환 내레이션 생성, 음악 기반 반응형 애니메이션(비트 싱크, 글로우, 펄스), 애니메이션 텍스트 강조(마커 스윕, 손그린 원, 버스트 라인, 스크리블, 스케치아웃) 및 장면 간 전환(크로스페이드, 와이프, 리빌, 셰이더 전환)이 필요할 때 사용하세요. 컴포지션 작성, 타이밍, 미디어 및 전체 비디오 제작 워크플로우를 다룹니다. CLI 명령어(init, lint, preview, render, transcribe, tts)는 hyperframes-cli 스킬을 참조하세요.

skills_2026란 무엇인가요?

이 스킬은 HTML을 비디오 제작의 단일 진리 소스(source of truth)로 사용하는 HyperFrames 프레임워크의 포괄적인 가이드입니다. 개발자는 이 스킬을 통해 HTML 파일에 `data-*` 속성으로 타이밍을 지정하고, GSAP 타임라인으로 애니메이션을 제어하며, CSS로 시각적 스타일을 정의함으로써 전체 비디오 제작 워크플로우를 실행할 수 있습니다. 이 스킬은 클립 가시성, 미디어 재생, 타임라인 동기화를 처리하여 복잡한 장면 전환, 오디오 반응형 비주얼, 동기화된 자막 및 텍스트 음성 변환을 지원합니다. 특히, 시각적 아이덴티티 게이트(Visual Identity Gate)를 통해 모든 컴포지션이 명확한 색상, 타이포그래피 및 모션 규칙을 따르도록 강제하며, 레이아웃 우선 접근법을 통해 애니메이션 전에 정적 최종 상태를 먼저 구축함으로써 의도하지 않은 레이아웃 충돌을 방지합니다. 또한 다중 장면 구성, 오디오 처리 및 비동기 타임라인 구축 금지 등 엄격한 규칙을 제공하여 안정적이고 예측 가능한 비디오 렌더링을 보장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanQiao1990/skills_2026/tree/HEAD/openclaw-imports/hyperframes

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

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

미리보기

스킬 README에서

문서

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.md
  • references/hyperframes-workflow.md

접근 방식

HTML을 작성하기 전에 높은 수준에서 생각하세요:

  1. 무엇을 — 시청자가 무엇을 경험해야 합니까? 내러티브 아크, 핵심 순간 및 감정적 비트를 식별하세요.
  2. 구조 — 얼마나 많은 컴포지션이 있으며, 어떤 것이 하위 컴포지션이고 인라인이며, 어떤 트랙이 무엇을 전달합니까(비디오, 오디오, 오버레이, 자막).
  3. 타이밍 — 어떤 클립이 지속 시간을 결정하며, 전환이 어디에 위치하고, 페이싱은 무엇입니까?
  4. 레이아웃 — 먼저 최종 상태를 구축하세요. 아래 "애니메이션 전 레이아웃"을 참조하세요.
  5. 애니메이션 — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.

작은 편집(색상 수정, 타이밍 조정, 요소 하나 추가)의 경우 바로 규칙으로 건너뛰세요.

시각적 아이덴티티 게이트

다음 순서로 확인하세요:

  1. 프로젝트에 DESIGN.md가 있습니까? → 읽으세요. 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것" 제약 조건을 사용하세요.
  2. visual-style.md가 있습니까? → 읽으세요. style_prompt_full 및 구조화된 필드를 적용하세요. (참고: visual-style.md는 프로젝트별 파일입니다. visual-styles.md는 8개의 명명된 프리셋이 있는 스타일 라이브러리입니다 — 다른 파일입니다.)
  3. 사용자가 스타일을 지정했습니까? (예: "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개의 안티 패턴).
  4. 위의 어느 것도 해당되지 않습니까? → HTML을 작성하기 전에 3가지 질문을 하세요:
    • 분위기는 무엇입니까? (폭발적인 / 영화 같은 / 유동적인 / 기술적인 / 혼란스러운 / 따뜻한)
    • 밝은 캔버스입니까, 어두운 캔버스입니까?
    • 특정 브랜드 색상, 글꼴 또는 시각적 참조가 있습니까? 그런 다음 답변에서 최소한의 DESIGN.md를 생성하세요.

모든 컴포지션은 팔레트와 타이포그래피를 DESIGN.md, visual-style.md 또는 명시적인 사용자 지시로 추적해야 합니다. #333, #3b82f6 또는 Roboto에 도달하고 있다면 이 단계를 건너뛴 것입니다.

모션 기본값, 크기 조정, 진입 패턴 및 이징에 대해서는 house-style.md를 따르세요. 하우스 스타일은 사물이 어떻게 움직이는지를 처리합니다. DESIGN.md는 사물이 어떻게 보이는지를 처리합니다.

애니메이션 전 레이아웃

모든 요소를 가장 잘 보이는 순간 — 완전히 진입하고, 올바르게 배치되었으며, 아직 종료되지 않은 프레임 — 에 있어야 할 위치에 배치하세요. 이것을 먼저 정적 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 위치는 기본 진실입니다. 트윈은 그곳에 도달하는 여정을 설명합니다.
  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-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을 동기식으로 읽습니다. 글꼴은 컴파일러에 의해 포함되므로 즉시 사용 가능합니다 — 글꼴 로딩을 기다릴 필요가 없습니다.

절대 하지 말아야 할 것:

  1. window.__timelines 등록을 잊지 마세요.
  2. 오디오에 비디오를 사용하지 마세요 — 항상 음소거된 비디오 + 별도의 <audio>
  3. 비디오를 타이밍이 있는 div 내부에 중첩하지 마세요 — 타이밍이 없는 래퍼를 사용하세요.
  4. data-layer (data-track-index 사용) 또는 data-end (data-duration 사용)를 사용하지 마세요.
  5. 비디오 요소 치수를 애니메이션하지 마세요 — 래퍼 div를 애니메이션하세요.
  6. 미디어에서 play/pause/seek을 호출하지 마세요 — 프레임워크가 재생을 소유합니다.
  7. data-composition-id 없이 최상위 컨테이너를 만들지 마세요.
  8. 어떤 타임라인 또는 트윈에서도 repeat: -1을 사용하지 마세요 — 항상 유한한 반복.
  9. 타임라인을 비동기식 (async, setTimeout, Promise 내부)으로 구성하지 마세요.
  10. 이후 장면의 클립 요소에 대해 gsap.set()을 사용하지 마세요 — 페이지 로드 시 DOM에 존재하지 않습니다. 대신 타임라인 내에서 클립의 data-start 시간에 또는 그 이후에 tl.set(selector, vars, timePosition)을 사용하세요.
  11. 콘텐츠 텍스트에 <br>을 사용하지 마세요 — 강제 줄 바꿈은 실제 렌더링된 글꼴 너비를 고려하지 않습니다. 자연스럽게 줄 바꿈되는 텍스트 + <br>은 원치 않는 추가 줄 바꿈을 생성하여 중첩을 유발합니다. 대신 max-width를 통해 텍스트를 줄 바꿈하세요. 예외: 각 단어가 의도적으로 자체 라인에 있는 짧은 표시 제목 (예: 130px의 "THE\nIMMORTAL\nGAME")

장면 전환 (협상 불가)

모든 다중 장면 컴포지션은 다음 규칙을 모두 따라야 합니다. 하나라도 위반하면 깨진 컴포지션입니다.

  1. 항상 장면 간에 전환을 사용하세요. 점프 컷은 금지됩니다. 예외 없음.
  2. 항상 모든 장면에 진입 애니메이션을 사용하세요. 모든 요소는 gsap.from()을 통해 진입 애니메이션됩니다. 어떤 요소도 완전히 형성된 상태로 나타나서는 안 됩니다. 장면이

…

[번역을 위해 잘렸습니다]

관련 스킬