HyperFrames — 먼저 읽으세요
모든 HyperFrames 작업을 시작하기 전에 여기서 시작하세요 — 특히 프로젝트 에이전트 설정(CLAUDE.md / AGENTS.md / .cursorrules)이 없는 경우. 기능 맵 + 비디오 라우터는 아래에 있습니다.
기능 맵 — 어떤 의도에 어떤 스킬
| 원하는 작업… | 이동할 위치 |
|---|---|
| 동영상 만들기 (URL, 브리프, 주제, GitHub PR, 기존 영상, 또는 애니메이션할 단일 요소로부터) | 아래 비디오 라우터 (§ 비디오 라우팅) |
HTML 컴포지션 작성/편집 — data-* 계약, 클립, 트랙, 서브 컴포지션, 변수 | /hyperframes-core |
| 애니메이션 — 원자 모션 규칙, 씬 청사진, 전환, 런타임 어댑터 (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | /hyperframes-animation |
크리에이티브 방향 — design.md, 팔레트, 타이포그래피, 내레이션, 비트 계획, 오디오 반응 | /hyperframes-creative |
| 미디어 전처리 — TTS 음성 해설, 배경 음악, 전사, 배경 제거, 캡션 | /hyperframes-media |
| CLI 개발 루프 — 초기화, 린트, 검증, 검사, 미리보기, 렌더링, 게시, 닥터 | /hyperframes-cli |
레지스트리 블록/컴포넌트 설치 (hyperframes add) | /hyperframes-registry |
작성 계약(모든 시간 요소는
data-start/data-duration/data-track-index가 필요함; 시간 요소는class="clip"필요; GSAP 타임라인은 일시 중지되고window.__timelines에 등록됨; 결정론적 로직만 —Date.now()/Math.random()/ 네트워크 없음)은 여기에 중복되지 않습니다 —/hyperframes-core에 있습니다. 컴포지션 HTML을 작성하기 전에 먼저 읽으세요.
HyperFrames가 할 수 없는 것 — 먼저 확인하세요
HyperFrames는 HTML 컴포지션을 작성하고 코드로부터 MP4로 렌더링합니다. 그 모델에는 명확한 외부 경계가 있습니다. 이 경계를 넘는 요청은 라우팅 선택이 아니라 범위를 벗어납니다 — 따라서 워크플로우를 찾는 대신 거절하거나 올바른 도구를 가리키세요. 이는 단일 요청이 아닌 아키텍처에서 비롯됩니다:
- 렌더링은 결정론적이고 자체 포함됩니다. 모든 값, 자산, 텍스트는 작성할 때 고정됩니다; 렌더링은 네트워크 호출이나 실시간/렌더링 시점 데이터 풀을 수행하지 않습니다(핵심 규칙:
Date.now()/Math.random()/ 네트워크 없음). "렌더링 시점에 숫자를 실시간으로 새로고침"은 불가능합니다 — 작성 시점에 데이터를 한 번 가져와 고정시키거나 거절하세요. - 기존 비디오는 오버레이만 되고 편집되지 않습니다. HyperFrames는 소스 클립 위에 프레임을 구성합니다 —
/embedded-captions는 캡션 레이어를 추가하고,/graphic-overlays는 디자인된 그래픽 카드(하단 3분할, 데이터 콜아웃, 제목)를 추가합니다 — 클립은 아래에서 변경되지 않고 재생되지만, 인코딩된 비디오 스트림을 후처리하지는 않습니다. 영상 자체(타이밍, 색상, 프레이밍, 순서, 오디오)를 변경하는 것은 NLE 스타일 편집이며 범위를 벗어납니다. - Remotion 가져오기는 단방향입니다.
/remotion-to-hyperframes는 Remotion 프레임워크 소스를 HyperFrames로 변환합니다. 역방향(HyperFrames → Remotion 또는 다른 프레임워크)은 없습니다 — 범위를 벗어납니다. 그리고 비-Remotion React/웹 애니메이션 소스는 변환할 Remotion 소스가 없습니다 —/general-video를 통해 다시 만드세요. - 가지고 있지 않은 입력을 생성할 수 없습니다. 화면/세션 녹화, 카메라 캡처, AI 토킹헤드/립싱크 아바타 생성이 없습니다. 영상이나 자산이 아직 존재하지 않으면 HyperFrames가 이를 conjure할 수 없습니다 — 사용자에게 제공하거나 올바른 캡처 도구를 사용하도록 요청하세요.
그 외의 모든 것 — URL, 브리프, 주제, PR, 주석을 달 영상, 또는 애니메이션할 단일 요소로부터의 비디오 — 는 범위 내에 있으며 아래에서 라우팅하세요.
비디오 라우팅
이 섹션은 최상위 워크플로우만 알고 있습니다. 워크플로우 내부 단계, 도메인 스킬(hyperframes-* — 위의 기능 맵 참조) 또는 기술 참조를 로드하지 않습니다.
결정 테이블
INPUT 유형(의도)이 기본 축입니다; OUTPUT 길이는 한계일 뿐 게이트가 아닙니다. 일치하는 입력에 대해 전문 워크플로우는 최대 ~3분까지 처리합니다 — 어떤 워크플로우에 들어갈지는 의도(입력 유형, 그리고 텍스트의 경우 주제)에 의해 결정되며 길이에 의해 결정되지 않습니다. 길이는 상단에서만 중요합니다: 진정으로 더 긴 작품(3-5분 튜토리얼, 5분 이상 딥 다이브)은 다른 레지스터이며 /general-video로 라우팅됩니다. ≤~3분 대역 내에서 세 번째 축이 두 개의 텍스트 기반 워크플로우를 나눕니다 — 주제: _마케팅_되는 제품 vs _설명_되는 주제(아래 단계 3의 명확화 규칙 참조).
| 길이 / 입력 | 제품 출시 (URL / 브리프 / 스크립트) | 일반 웹사이트 / URL | GitHub PR / 코드 변경 | 주제 / 문서 / 노트 (제품 없음, URL 없음) | 기존 영상 (토킹헤드) † |
|---|---|---|---|---|---|
| ≤ ~3분 | /product-launch-video | /website-to-video | /pr-to-video | /faceless-explainer | /embedded-captions · /graphic-overlays † |
| 3-5분 튜토리얼 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 5분 이상 딥 다이브 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 정적 / 루프 | /general-video | /general-video | /general-video | /general-video | /general-video |
현재 적용 범위: ≤ ~3분 대역에는 제품 출시 / 일반 웹사이트 / GitHub-PR / 주제 입력을 위한 전용 워크플로우가 있으며(URL은 종류 다음 _의도_로 분할됨 — 단계 3 참조), 기존 영상 열은 모든 길이에서 /embedded-captions(캡션/자막) 또는 /graphic-overlays(디자인된 그래픽 오버레이)로 커버되며, 의도에 따라 분할됩니다(단계 2 참조). 다른 모든 셀은 /general-video — 일반 HTML 컴포지션 작성 흐름(입력 및 길이 불가지): ~3분보다 긴 모든 것(3-5분 / 5분 이상 행)과 모든 정적 / 루프 형식. 라우터는 만들 수 있는 비디오에서 막다른 길에 도달하지 않습니다; 유일한 진정한 "일반/없음" 응답은 HyperFrames 자체 외부의 요청입니다(예: 완성된 비디오 파일의 NLE 스타일 편집 — 재타이밍, 재색상화, 재프레이밍, 재정렬, 오디오).
† 기존 영상은 길이가 아닌 의도에 따라 분할됩니다. 캡션/자막 → /embedded-captions; 디자인된 그래픽 오버레이/패키징 — 하단 3분할, 데이터 콜아웃, 제목이 있는 카드, 풀 인용구 — → /graphic-overlays. 둘 다 클립 위에 오버레이되며, 클립은 아래에서 변경되지 않고 재생됩니다; 어느 것도 영상 자체를 편집하지 않습니다.
장르 단축(테이블보다 우선). 짧은(~10초 미만), 내레이션 없는, 디자인 중심 모션 그래픽 — 운동 타이포그래피, 통계/차트 히트, 로고 스팅, 하단 3분할/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트 — 는 입력에 관계없이 /motion-graphics로 라우팅됩니다. 이는 INPUT 유형이 아닌 OUTPUT 장르이므로, 요청이 명확히 모션 우선이고 내레이션이 없을 때(단계 2 참조) 위의 입력 유형 테이블보다 우선합니다. 더 길거나 내레이션이 있는 처리는 입력 유형에 따라 라우팅되거나 /general-video로 라우팅됩니다.
기존 컴포지션 마이그레이션(특수 케이스)
위 테이블은 입력으로부터 비디오를 생성하기 위한 것입니다. 하나의 워크플로우는 이 밖에 있습니다: 사용자가 명시적으로 기존 Remotion(React) 컴포지션을 HyperFrames로 포팅/변환/마이그레이션하도록 요청하는 경우 → /remotion-to-hyperframes. 이는 소스 변환이지 입력으로부터의 생성이 아니므로 INPUT × LENGTH 셀이 없습니다. Remotion에 대한 명시적인 마이그레이션 언어("내 Remotion 프로젝트 포팅", "이 Remotion 컴포지션 변환", "이것을 HyperFrames로 다시 작성")가 있을 때만 여기로 라우팅하세요 — Remotion을 지나치게 언급하는 것은 트리거가 아닙니다; 생성 테이블 또는 /hyperframes-core로 기본 설정하세요.
라우팅 절차
- INPUT 유형 + 대상 길이 결정. 라우팅은 비디오가 무엇에 관한 것인지 — 주제와 입력을 알아야 합니다. 주제 자체가 지정되지 않은 경우(예: URL, 명명된 제품, 주제 또는 작업할 자산 없이 "우리 것에 대한 비디오 만들기"), 또는 입력 유형을 알 수 없는 경우, 워크플로우에 들어가기 전에 물어보세요 — 먼저 명확히 하세요; 워크플로우 스킬을 호출한 다음 묻지 마세요. 워크플로우에 들어가는 것이 그 자체로 라우팅 결정이기 때문입니다. 최대 2개의 명확화 질문:
- "입력이 무엇인가요 — 제품(URL 또는 브리프), 일반 웹사이트/URL, GitHub PR/코드 변경, 설명할 주제나 문서, 또는 캡션을 추가할 기존 토킹헤드 비디오?"
- "대상 길이 — 약 3분 이하, 또는 더 길게(3-5분 튜토리얼 / 5분 이상 딥 다이브)?"
- 사양 기본값 — 묻지 말고 명시하세요 (이는 경로에 영향을 주지 않으므로 라우팅을 차단하지 마세요): 종횡비 16:9(엔진은 9:16 세로도 지원 — 사용자가 TikTok/Reels/Shorts 같은 세로 목적지를 언급할 때만 전환); 내레이션/캡션 언어 = 사용자의 언어. 사용자가 반발할 때만 확인; 선택한 워크플로우는 0단계에서 자체 세부 사항을 다시 확인합니다.
- 먼저 INPUT 유형(의도)으로 선택; 길이는 한계일 뿐 게이트가 아닙니다.
- 짧은 디자인 중심 모션 그래픽(장르 단축, 입력 테이블보다 우선) — 모션 자체가 메시지: 운동 타이포그래피, 통계/숫자 카운트업, 차트 히트, 로고 스팅, 하단 3분할/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트; 일반적으로 ~10초 미만, 내레이션/음성 해설 없음 →
/motion-graphics. 이는 INPUT 유형이 아닌 OUTPUT 장르입니다 — 요청이 명확히 빠르고, 내레이션이 없으며, 디자인 중심의 모션 작품일 때 입력에 관계없이 여기로 라우팅하세요. 동일한 재료의 더 길거나 내레이션이 있는 처리는 이것이 아닙니다(입력 유형에 따라 라우팅하거나/general-video로). - 기존 토킹헤드 비디오(사용자가 클립을 가지고 있고 그 위에 무언가를 추가하려는 경우) → 의도에 따라 분할, 모든 길이(입력 유형이 길이보다 우선): 캡션/자막(말하는 단어를 읽을 수 있는 텍스트로) →
/embedded-captions; 디자인된 그래픽 오버레이 — 하단 3분할, 데이터 콜아웃, 제목이 있는 정보 카드, 풀 인용구, 그래픽 패키지 편집 →/graphic-overlays. (영상 자체를 _편집_하는 것 — 재타이밍, 재색상화, 재프레이밍, 재정렬, 오디오 — 은 NLE 스타일이며 범위를 벗어납니다; § HyperFrames가 할 수 없는 것 참조.) - GitHub PR / 코드 변경(
github.com/<소유자>/<저장소>/pull/<N>링크,소유자/저장소#N참조, 또는 "이 PR") →/pr-to-video(최대 ~3분). - 그 외(제품 URL / 브리프 / 주제 텍스트): 의도가 단계 3을 통해 워크플로우를 선택하며, 최대 ~3분까지 처리합니다 — 짧은 15-30초 프로모션과 ~100초 설명 영상 모두 길이가 아닌 의도에 따라 라우팅됩니다. 대상이 명확히 ~3분보다 긴 경우에만(3-5분 튜토리얼, 5분 이상 딥 다이브)
/general-video(길이 불가지 대체 — 단계 4 참조)로 라우팅하세요. 진정히 긴 작품을 ≤~3분 워크플로우에 강제로 넣지 마세요 — 의도가 대역 내에서 결정하고/general-video가 나머지를 커버합니다.
- 짧은 디자인 중심 모션 그래픽(장르 단축, 입력 테이블보다 우선) — 모션 자체가 메시지: 운동 타이포그래피, 통계/숫자 카운트업, 차트 히트, 로고 스팅, 하단 3분할/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트; 일반적으로 ~10초 미만, 내레이션/음성 해설 없음 →
- ≤~3분 URL/텍스트 입력 명확화(의도 분할). 두 가지 분할:
- URL 종류 + 의도 — URL이 더 이상 PLV를 위해 자동으로 승리하지 않음; 그 종류 다음 _의도_가 결정: GitHub PR 링크(
.../pull/<N>,소유자/저장소#N, "이 PR") →/pr-to-video; 그 외 웹사이트 URL은 의도에 따라 분할 — 특정 제품 또는 SaaS 마케팅/출시/프로모션 →/product-launch-video; 일반 사이트 → 비디오(사이트 투어, 포트폴리오/블로그/랜딩 페이지 쇼케이스, 사이트 자체 비주얼의 소셜 클립, 또는 "이 사이트를 비디오로 바꾸기") →/website-to-video. 둘 다 headless Chrome으로 크롤링; PR URL은...
- URL 종류 + 의도 — URL이 더 이상 PLV를 위해 자동으로 승리하지 않음; 그 종류 다음 _의도_가 결정: GitHub PR 링크(