HyperFrames CLI
모든 것은 npx hyperframes를 통해 실행됩니다. Node.js >= 22 및 FFmpeg가 필요합니다.
워크플로우
- 스캐폴딩 —
npx hyperframes init my-video - 작성 — HTML 구성 요소 작성 (
hyperframes스킬 참조) - 린트 —
npx hyperframes lint - 런타임 검증 —
npx hyperframes validate - 시각적 검사 —
npx hyperframes inspect - 미리보기 —
npx hyperframes preview - 렌더링 —
npx hyperframes render
미리보기 전에 린트와 검사를 수행하세요. lint는 누락된 data-composition-id, 중복 트랙, 등록되지 않은 타임라인을 찾아냅니다. inspect는 렌더링된 구성 요소를 헤드리스 Chrome에서 열고, 타임라인을 탐색하며, 텍스트가 말풍선/컨테이너 밖으로 나가거나 캔버스 밖으로 나가는지를 보고합니다.
스캐폴딩
npx hyperframes init my-video # 대화형 마법사
npx hyperframes init my-video --example warm-grain # 예제 선택
npx hyperframes init my-video --video clip.mp4 # 비디오 파일 포함
npx hyperframes init my-video --audio track.mp3 # 오디오 파일 포함
npx hyperframes init my-video --example blank --tailwind # Tailwind v4 브라우저 런타임 포함
npx hyperframes init my-video --non-interactive # 프롬프트 건너뛰기 (CI/에이전트)
템플릿: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init은 올바른 파일 구조를 생성하고, 미디어를 복사하며, Whisper로 오디오를 전사하고, AI 코딩 스킬을 설치합니다. 파일을 수동으로 생성하는 대신 사용하세요.
--tailwind를 사용할 때는 스캐폴드가 Studio의 Tailwind v3 설정이 아닌 브라우저 런타임을 통한 Tailwind v4.2를 사용한다는 점에 유의하세요. 클래스 및 테마 토큰 문법을 편집 전 v4 문서와 확인하세요.
린팅
npx hyperframes lint # 현재 디렉토리
npx hyperframes lint ./my-project # 특정 프로젝트
npx hyperframes lint --verbose # 정보 수준 결과
npx hyperframes lint --json # 기계 판독 가능
index.html 및 compositions/ 디렉토리의 모든 파일을 린트합니다. 오류(수정 필수), 경고(수정 권장), 정보(--verbose 사용 시)를 보고합니다.
런타임 검증
npx hyperframes validate # 현재 디렉토리
npx hyperframes validate ./my-project # 특정 프로젝트
npx hyperframes validate --json # 기계 판독 가능
npx hyperframes validate --timeout 5000 # 느린 스크립트/미디어 (기본값 3000ms)
헤드리스 Chrome에서 구성 요소를 로드하고 JS 콘솔 오류, 누락된 에셋, WCAG 대비 문제를 보고합니다(--no-contrast로 대비 검사 생략 가능). lint 후, inspect 전에 실행하세요.
validate는 업스트림에서 npx hyperframes check를 위해 권장되지 않습니다. check는 하나의 브라우저 세션에서 린트, 런타임, 레이아웃, 모션, 대비 검증을 모두 실행합니다. "린트 및 검증" 체크리스트 항목을 만족합니다.
시각적 검사
npx hyperframes inspect # 타임라인에 걸쳐 렌더링된 레이아웃 검사
npx hyperframes inspect ./my-project # 특정 프로젝트
npx hyperframes inspect --json # 에이전트가 읽을 수 있는 결과
npx hyperframes inspect --samples 15 # 더 조밀한 타임라인 스윕
npx hyperframes inspect --at 1.5,4,7.25 # 명시적 히어로 프레임 타임스탬프
lint와 validate 후에 사용하세요. 특히 말풍선, 카드, 캡션 또는 타이트한 타이포그래피가 있는 구성 요소에 유용합니다. 다음을 보고합니다:
- 가장 가까운 시각적 컨테이너 또는 말풍선 외부로 확장되는 텍스트
- 고정 너비/높이 상자에 의해 잘리는 텍스트
- 구성 요소 캔버스 외부로 확장되는 텍스트
- 클리핑 컨테이너를 탈출하는 자식 요소
오류는 렌더링 전에 수정해야 합니다. 경고는 에이전트 검토를 위해 표시되며, 경고에도 실패하려면 --strict를 추가하세요. 반복되는 정적 문제는 기본적으로 축소되어 JSON 출력이 LLM 컨텍스트 창에 대해 간결하게 유지됩니다. 오버플로우가 진입/종료 애니메이션의 의도적인 경우, 요소나 상위 요소에 data-layout-allow-overflow를 표시하세요. 장식용 요소가 감사되지 않도록 하려면 data-layout-ignore로 표시하세요.
npx hyperframes layout은 동일한 시각적 검사 패스를 위한 호환성 별칭으로 남아 있습니다.
미리보기
npx hyperframes preview # 현재 디렉토리 서빙
npx hyperframes preview --port 4567 # 사용자 지정 포트 (기본값 3002)
파일 변경 시 핫 리로드됩니다. 자동으로 브라우저에서 Studio를 엽니다.
프로젝트를 사용자에게 다시 전달할 때는 소스 index.html 경로가 아닌 Studio 프로젝트 URL을 사용하세요:
http://localhost:<port>/#project/<project-name>
미리보기 출력의 실제 포트와 프로젝트 디렉토리 이름을 사용하세요. 예를 들어, codex-openai-video에서 npx hyperframes preview --port 3017 실행 후, http://localhost:3017/#project/codex-openai-video를 보고하세요.
index.html은 소스 코드 컨텍스트로만 취급하세요. 구현 파일로 링크하는 것은 괜찮지만, 프로젝트나 미리보기 표면으로 레이블을 지정하지 마세요.
렌더링
npx hyperframes render # 표준 MP4
npx hyperframes render --output final.mp4 # 이름 지정 출력
npx hyperframes render --quality draft # 빠른 반복
npx hyperframes render --fps 60 --quality high # 최종 전달
npx hyperframes render --format webm # 투명 WebM
npx hyperframes render --docker # 바이트 동일
| 플래그 | 옵션 | 기본값 | 참고 사항 |
|---|---|---|---|
--output | 경로 | renders/name_timestamp.mp4 | 출력 경로 |
--fps | 24, 30, 60 | 30 | 60fps는 렌더링 시간이 두 배로 걸립니다 |
--quality | draft, standard, high | standard | 반복 시 draft 사용 |
--format | mp4, webm | mp4 | WebM은 투명도 지원 |
--workers | 1-8 또는 auto | auto | 각 작업자가 Chrome을 실행합니다 |
--docker | 플래그 | off | 재현 가능한 출력 |
--gpu | 플래그 | off | GPU 가속 인코딩 |
--strict | 플래그 | off | 린트 오류 시 실패 |
--strict-all | 플래그 | off | 오류 및 경고 모두 실패 |
--variables | JSON 객체 | — | data-composition-variables에 선언된 변수 값 재정의 |
--variables-file | 경로 | — | 변수 값이 포함된 JSON 파일 (--variables 대안) |
--strict-variables | 플래그 | off | --variables에서 선언되지 않은 키 또는 유형 불일치 시 렌더링 실패 |
품질 가이드: 반복 시 draft, 검토 시 standard, 최종 전달 시 high.
매개변수화된 렌더링: 구성 요소는 <html> 루트에 **data-composition-variables**를 사용하여 변수를 선언합니다 — 항목당 {id, type, label, default}의 JSON 선언 배열로 스키마를 정의합니다. 내부 스크립트는 window.__hyperframes.getVariables()를 통해 해결된 값을 읽습니다. CLI **--variables '{"title":"Q4 Report"}'**는 id를 키로 하는 JSON 객체로, 한 번의 렌더링에 대해 선언된 기본값을 재정의합니다. 누락된 키는 기본값으로 대체되므로 동일한 구성 요소가 개발 프리뷰와 프로덕션에서 변경 없이 실행됩니다. (하위 컴포넌트 호스트는 인스턴스별로 **data-variable-values**를 사용하여 재정의할 수도 있습니다 — 동일한 객체 형태이며, 하위 컴포넌트의 한 마운트에 범위가 지정됩니다. 전체 패턴은 hyperframes 스킬을 참조하세요.)
에셋 전처리
npx hyperframes tts, transcribe, remove-background는 에셋(내레이션 오디오, 단어 수준 전사, 투명 비디오)을 생성하여 구성 요소에 추가합니다. 각 명령어는 첫 실행 시 자체 모델을 다운로드합니다. 음성 선택, Whisper 모델 규칙(.en이 비영어를 번역하는 주의사항), 출력 형식 선택(VP9 알파 WebM vs ProRes), TTS → 전사 → 캡션 체인에 대해서는 hyperframes-media 스킬을 호출하세요.
문제 해결
npx hyperframes doctor # 환경 확인 (Chrome, FFmpeg, Node, 메모리)
npx hyperframes browser # 번들된 Chrome 관리
npx hyperframes info # 버전 및 환경 세부 정보
npx hyperframes upgrade # 업데이트 확인
렌더링 실패 시 먼저 doctor를 실행하세요. 일반적인 문제: FFmpeg 누락, Chrome 누락, 낮은 메모리.
기타
npx hyperframes compositions # 프로젝트의 구성 요소 목록
npx hyperframes docs # 문서 열기
npx hyperframes benchmark . # 렌더 성능 벤치마크