Communitygithub.com

비디오 편집 툴킷

HyperFrames HTML을 사용하여 비디오 합성, 애니메이션, 타이틀 카드, 오버레이, 캡션, 음성 해설, 오디오 반응형 비주얼 및 장면 전환을 생성합니다.

비디오 편집 툴킷란 무엇인가요?

이 스킬은 HyperFrames HTML을 기반으로 한 전체 비디오 제작 워크플로우를 지원합니다. HTML을 비디오의 단일 진실 공급원(source of truth)으로 사용하여, 개발자는 타이밍 속성, GSAP 애니메이션 및 CSS를 통해 비디오 구성을 정의할 수 있습니다. CLI 단계(init, lint, preview, render, transcribe, tts)는 별도의 `hyperframes-cli` 스킬로 처리됩니다. 'Layout Before Animation' 원칙을 적용하여 모든 요소를 가장 잘 보이는 순간에 정확히 배치하고, `gsap.from()`으로 진입 애니메이션을 추가합니다. 다중 장면 구성 간에는 전환을 필수적으로 사용하며, 마지막 장면을 제외하고는 퇴장 애니메이션을 금지합니다. 또한, 'Visual Identity Gate'를 통해 사전 정의된 디자인 스타일(DESIGN.md, visual-style.md, 또는 사용자 질문)이 없는 경우 HTML 생성을 차단하여 일관된 시각적 정체성을 유지합니다. 이 스킬은 비디오 및 오디오 클립, 캡션, 오디오 반응형 애니메이션(비트 동기화, 글로우, 펄스), 애니메이션 텍스트 강조(마커 스윕, 손으로 그린 원, 버스트 라인, 낙서, 스케치 아웃) 및 장면 전환(크로스페이드, 와이프, 리빌, 셰이더 전환)을 포함한 포괄적인 작성을 지원합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/hyperframes

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

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

미리보기

스킬 README에서

문서

HyperFrames

HTML은 비디오의 단일 진실 공급원(source of truth)입니다. 구성(composition)은 data-* 속성(타이밍), GSAP 타임라인(애니메이션), CSS(외관)로 구성된 HTML 파일입니다. 프레임워크는 클립 가시성, 미디어 재생 및 타임라인 동기화를 처리합니다.

접근 방식

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

  1. 무엇(What) — 시청자는 무엇을 경험해야 합니까? 내러티브 아크, 주요 순간 및 감정적 비트를 식별하세요.
  2. 구조(Structure) — 얼마나 많은 구성이 있으며, 어떤 것이 하위 구성이고 어떤 것이 인라인인지, 어떤 트랙이 무엇(비디오, 오디오, 오버레이, 캡션)을 전달하는지 결정하세요.
  3. 타이밍(Timing) — 어떤 클립이 지속 시간을 결정하고, 전환이 어디에 배치되며, 페이싱은 어떠한지 계획하세요.
  4. 레이아웃(Layout) — 먼저 최종 상태를 구축하세요. 아래의 "레이아웃 우선, 애니메이션 나중"을 참조하세요.
  5. 애니메이션(Animate) — 그런 다음 아래 규칙을 사용하여 움직임을 추가하세요.

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

시각적 정체성 게이트

다음 순서로 확인하세요:

  1. 프로젝트에 DESIGN.md가 존재합니까? → 읽으세요. 정확한 색상, 글꼴, 모션 규칙 및 "하지 말아야 할 것(What NOT to Do)" 제약 조건을 사용하세요.
  2. visual-style.md가 존재합니까? → 읽으세요. style_prompt_full 및 구조화된 필드를 적용하세요. (참고: visual-style.md는 프로젝트별 파일입니다. visual-styles.md는 8개의 명명된 프리셋이 있는 스타일 라이브러리입니다 — 다른 파일입니다.)
  3. 사용자가 스타일을 지정했습니까? (예: "Swiss Pulse", "어둡고 테크니컬한", "럭셔리 브랜드") → 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)에 배치하고 도착해야 할 위치로 트윈(tween)하면, 최종 레이아웃을 추측하는 것입니다. 중첩은 비디오가 렌더링될 때까지 보이지 않습니다. 최종 상태를 먼저 구축하면 움직임을 추가하기 전에 레이아웃 문제를 보고 해결할 수 있습니다.

과정

  1. 각 장면의 히어로 프레임(hero frame) 을 식별하세요 — 대부분의 요소가 동시에 보이는 순간입니다. 이것이 당신이 구축할 레이아웃입니다.
  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 위치가 기준점(ground truth)이고, 트윈은 그곳에 도달하기 위한 여정을 설명합니다.
  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단계: 해당 위치로 애니메이션 진입
il.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/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"] {
        /* 스코프된 스타일 */
      }
    </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에서 가져옵니다
  • 지속 시간을 설정하기 위해 빈 트윈을 절대 생성하지 마세요

규칙 (협상 불가)

결정론적(Deterministic): 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를 읽습니다. 글꼴은 컴파일러에 의해 삽입되므로 즉시 사용 가능합니다 — 글꼴 로딩을 기다릴 필요가 없습니다.

절대 하지 말아야 할 것:

  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()을 통해 IN으로 애니메이션합니다. 어떤 요소도 완전히 형성된 상태로 나타날 수 없습니다. 장면에 5개의 요소가 있으면 5개의 진입 트윈이 필요합니다.
  3. 마지막 장면을 제외하고는 절대 퇴장 애니메이션을 사용하지 마세요. 즉, 전환이 실행되기 전에 투명도 0, y 화면 밖, 크기 0 등으로 애니메이션하는 gsap.to()가 없어야 합니다. 전환이 바로 퇴장입니다. 나가는 장면의 콘텐츠는 전환이 시작되는 순간 완전히 보여야 합니다.
  4. 마지막 장면만: 마지막 장면은 요소를 페이드 아웃할 수 있습니다(예: 검은색으로 페이드). 이것이 gsap.to(..., { opacity: 0 })가 허용되는 유일한 장면입니다.

잘못된 예 — 전환 전 퇴장 애니메이션:

// 금지됨 — 이것은 전환이 사용할 수 있기 전에 장면을 비웁니다
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 전환이 빈 프레임에서 실행됩니다

올바른 예 — 진입만, 전환이 퇴장을 처리:

// 장면 1 진입 애니메이션
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// 퇴장 트윈 없음 — 7.2초의 전환이 장면 변경을 처리합니다
// 장면 2 진입 애니메이션
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

애니메이션 가드레일

  • 첫 번째 애니메이션은 0.1-0.3초 오프셋(t=0 아님)
  • 진입 트윈 간에 이징을 다양화하세요 — 장면당 최소 3개의 다른 이즈 사용
  • 장면 내에서 진입 패턴을 반복하지 마세요
  • 어두운 배경에서 전체 화면 선형 그래디언트를 피하세요 (H.264 밴딩 — 방사형 또는 솔리드 + 국소 글로우 사용)
  • 렌더링된 비디오의 경우 60px+ 헤드라인, 20px+ 본문, 16px+ 데이터 레이블
  • 숫자 열에 font-variant-numeric: tabular-nums 사용

visual-style.md나 애니메이션 방향이 제공되지 않은 경우, 미적 기본값에 대해 house-style.md를 따르세요.

타이포그래피 및 자산

  • 글꼴: CSS에서 원하는 font-family를 작성하기만 하면 됩니다 — 컴파일러가 지원되는 글꼴을 자동으로 포함합니다. 글꼴이 지원되지 않으면 컴파일러가 경고합니다.
  • 외부 미디어에 crossorigin="anonymous" 추가

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

govindgoel2001/video-editing-toolkit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

관련 스킬