비디오 엔진 (Hyperframes v0.8.77 & Brag)
HyperFrames는 HTML에서 비디오를 렌더링합니다. 컴포지션은 data-* 속성(data-start, data-duration)으로 DOM의 타이밍을 선언하는 HTML 문서이며, 애니메이션 런타임은 시커블(seekable)하고 미디어 재생은 프레임워크가 소유합니다.
1. 프로젝트 상태 감지
작업을 수행하기 전에 다음 순서로 프로젝트 상태를 평가합니다:
| 상태 | 작업 |
|---|---|
| Remotion을 HyperFrames로 포팅 | workflows/remotion-to-hyperframes/SKILL.md를 읽고 직접 실행합니다. 의도 레이어를 건너뜁니다. |
| 검사, 진단, 미리보기 또는 렌더링 | 해당 CLI 명령어(npx hyperframes check, preview, render)를 실행합니다. 인테이크를 다시 실행하지 않습니다. |
| 기존 프로젝트 편집 | npx hyperframes timeline [--json]을 실행하여 트랙, 클립 및 타이밍을 검사하고, 대상 편집을 수행합니다. |
BRIEF.md가 존재함 | 브리프에서 workflow와 flow를 읽고 즉시 해당 워크플로우를 실행합니다. |
hyperframes.json 또는 STORYBOARD.md가 존재함 | 기존 프로젝트 파일과 기록된 기본 설정에서 재개합니다. |
| 새로운 생성 요청 | 의도 인테이크를 실행하고 아래 라우팅 매트릭스를 사용하여 라우팅합니다. |
CLI 버전 관리
package.json에 고정된 의존성이 있는 기존 프로젝트를 재개할 때:
npx hyperframes@latest upgrade --project . --check
업데이트가 확인되고 검증되면 npx hyperframes@latest upgrade --project .를 적용하고 npx hyperframes check를 실행합니다.
2. 의도 라우팅 매트릭스
새로운 생성 요청을 일치하는 첫 번째 워크플로우로 라우팅합니다:
| 우선순위 | 요청 유형 | 대상 워크플로우 |
|---|---|---|
| 1 | Remotion 코드의 명시적 포팅 | workflows/remotion-to-hyperframes |
| 2 | 프레젠테이션, 피치 덱 또는 인터랙티브 슬라이드 덱 | workflows/slideshow |
| 3 | 푸티지에 대한 일반 단어 기반 자막 또는 캡션 | workflows/embedded-captions |
| 4 | 헤드토크, 인터뷰 또는 팟캐스트의 그래픽 오버레이 | workflows/talking-head-recut |
| 5 | 음악 트랙에 의해 구동되는 비트 동기 모션 (음성 없음) | workflows/music-to-video |
| 6 | 짧고 모션 중심의 운동성 비주얼 (<10초) | workflows/motion-graphics |
| 7 | GitHub 풀 리퀘스트 또는 코드 변경 설명 영상 | workflows/pr-to-video |
| 8 | 제품 런칭, 웹사이트 쇼케이스, SaaS 프로모션, /brag | workflows/product-launch-video (또는 모드 1) |
| 9 | 개념적 주제 또는 문서 설명 영상 | workflows/faceless-explainer |
| 10 | 기타 맞춤형 비디오 또는 다중 트랙 컴포지션 | workflows/general-video |
3. 운영 모드
모드 1: 제품 런칭 및 쇼케이스 (/brag 및 product-launch-video)
웹사이트 런칭, 제품 쇼케이스, SaaS 프로모션 및 /brag에 사용됩니다.
- 인테이크 및 검사:
- 옵션 파싱:
--tone(기본값, polished, yc-parody, chaotic, cinematic, deadpan, app-store (references/brag/tones.md)),--format(16:9, 9:16, 1:1),--duration(15–25초). - URL이 제공된 경우 라이브 사이트 자산 캡처:
npx hyperframes capture "<URL>" -o ./capture --json
- 옵션 파싱:
- 디자인 시스템 및 프리셋:
references/creative/frame-presets/에서 디자인 프리셋 선택 (capsule, cobalt-grid, daisy-days 등)하고 브랜드 토큰 리믹스:node workflows/product-launch-video/scripts/build-frame.mjs --preset <preset-name> --hyperframes .
- 스토리보드 및 오디오 믹스:
STORYBOARD.md및SCRIPT.md작성.- 오디오:
assets/music/에서 배경 음악 선택 또는/media-use를 사용하여 트랙 및 TTS 음성 해설 확인 (references/audio/). - 비트 큐 분석 실행:
python3 scripts/analyze_music_cues.py --audio <path> --output audio_cues.json.
- 검증 및 출력:
- 레이아웃 및 타이밍 확인:
npx hyperframes check. - 최종 비디오 컴파일:
npx hyperframes render --output brag.mp4. - 포스터 프레임 0을
brag.jpg로 저장하고 릴리스 사본을share-copy.txt로 저장.
- 레이아웃 및 타이밍 확인:
모드 2: 내러티브 및 기술 설명 영상 (faceless-explainer, pr-to-video)
코드 차이, 엔지니어링 문서 또는 복잡한 주제를 명확한 비디오 내러티브로 전환하는 데 사용됩니다.
- 스토리 스파인:
references/creative/references/story-spine.md참조 (훅, 문제 설명, 아키텍처/해결책, 영향). - 샷 형태:
references/animation/blueprints-index.md에서 청사진 선택 (code-editor, split-comparison, stat-callout, flow-diagram). - 프레임 워커 패킷:
workflows/faceless-explainer/scripts/frame-packets.mjs를 사용하여 경계가 있는 하위 에이전트 패킷 생성. 각 프레임은 격리되어 빌드됩니다 (compositions/frames/NN-*.html). - 조립 및 오디오: 프레임을 루트
index.html에 연결하고, 덕킹 엔벨로프로 음성 해설 트랙을 믹스한 후 렌더링합니다.
모드 3: 운동성 모션 그래픽 및 런타임 (motion-graphics, music-to-video)
독립형 모션 그래픽, 애니메이션 UI 컴포넌트, 비트 그리드 및 루프에 사용됩니다.
- 런타임 어댑터 (
references/animation/adapters/):- GSAP: 정밀 다중 속성 트윈 및 시크 안전 타임라인.
- Three.js: 3D 공간 뷰포트, 파티클 시스템 및 모델 (
references/animation/adapters/three.md). - Lottie: 벡터 애니메이션 플레이어 (
references/animation/adapters/lottie.md). - Anime.js / WAAPI: 간결한 DOM 모프 및 키프레임.
- CSS 키프레임: 하드웨어 가속 변환.
- 카메라 전환 및 모프 (
references/keyframes/):- Ken Burns 팬, 펀치인 줌, SVG 경로 모프 및 깊이 효과.
- 레지스트리 블록 및 셰이더 (
references/registry/):- 사전 구축된 효과 블록 검색 및 설치 (CRT 스캔라인, 글리치, 필름 그레인, 샤이머 스위프, 컨페티).
모드 4: 맞춤형 컴포지션 및 다중 트랙 편집 (general-video, slideshow)
인터랙티브 피치 덱, 다중 트랙 타임라인 편집 및 맞춤형 HTML 비디오에 사용됩니다.
- 스튜디오 규칙 (
references/studio/studio-conventions.md):- 모든 장면은 하위 컴포지션입니다 (
data-composition-src). - 하나의 캡션 트랙 (
data-track-kind="captions"). - 트랙당 하나의 요소 종류 (비디오, 그래픽, 캡션, 오디오).
- 안전 영역 준수 (Premiere 타이틀/액션 안전 상자).
- 모든 장면은 하위 컴포지션입니다 (
- 도메인 간 크리에이터 레시피:
- 트림 및 컷:
data-start,data-duration및data-media-start업데이트 (references/core/tracks-and-clips.md). - 부드러운 줌: 클립 타이밍을 고정하면서 CSS/GSAP으로 내부 크롭 래퍼 애니메이션 (
references/keyframes/). - 오디오 게인 및 덕킹: 볼륨 엔벨로프 및 버스 압축 적용 (
references/audio/).
- 트림 및 컷:
4. 검증 및 CLI 도구 체인
전달 전에 항상 검증 게이트를 실행하세요:
# 워크플로우 스캐폴드로 새 Hyperframes 프로젝트 초기화
npx hyperframes init "videos/<project>" --skill=<워크플로우-이름>
# 라이브 웹 자산, 스크린샷 및 브랜드 토큰 캡처
npx hyperframes capture "<URL>" -o ./capture --json
# 컴포지션 타임라인, 트랙 및 클립 검사
npx hyperframes timeline [--json]
# 타이밍 속성, 안전 영역 및 누락된 자산 검증
npx hyperframes check
# 인터랙티브 로컬 플레이어 실행
npx hyperframes preview
# 최종 MP4 출력 렌더링
npx hyperframes render --output output.mp4
5. 디렉토리 맵
| 경로 | 목적 |
|---|---|
workflows/ | 11개의 모든 업스트림 워크플로우 (product-launch-video, faceless-explainer, pr-to-video, motion-graphics 등) |
engine/ | 정식 Hyperframes v0.8.77 업스트림 패키지 제품군 |
references/core/ | 타이밍 속성, 결정론 규칙, 트랙 모델, 하위 컴포지션 |
references/animation/ | GSAP, Three.js, Lottie, Anime.js, CSS 어댑터, 청사진, 모션 블러 |
references/keyframes/ | 2D/3D 카메라 전환, 줌, SVG 모프, 깊이 효과 |
references/audio/ | EQ, 덕킹, 압축, 서브믹스 버스 자동화 엔벨로프 |
references/creative/ | 디자인 사양, 타이포그래피, 팔레트, 프레임 프리셋, 스토리 스파인 |
references/registry/ | 비주얼 블록, 셰이더 컴포넌트, 설치 및 배선 |
references/studio/ | 스튜디오 타임라인 레이아웃, 캡션 트랙, 안전 영역 |
references/brag/ | 큐레이팅된 /brag 단계별 가이드, 톤 및 음악 큐 |
assets/music/ | 시네마틱, 하이프, 인디, 캄 장르의 큐레이팅된 배경 음악 |
scripts/ | analyze_music_cues.py, 프레임 패킷 코어 및 오디오 추출기 |