HyperFrames CLI은(는) 무엇을 하나요?
모든 명령은 npx hyperframes를 통해 실행됩니다. Node.js >= 22와 FFmpeg가 필요합니다.
워크플로우
- 스캐폴드 —
npx hyperframes init my-video - 작성 — HTML 컴포지션 작성 (
hyperframes스킬 참조) - 린트 —
npx hyperframes lint - 시각적 검사 —
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를 사용할 때는 클래스나 테마 토큰을 수정하기 전에 tailwind 스킬을 호출하세요. 스캐폴드는 Studio의 Tailwind v3 설정이 아닌 브라우저 런타임을 통한 Tailwind v4.2를 사용합니다.
린팅
npx hyperframes lint # 현재 디렉토리
npx hyperframes lint ./my-project # 특정 프로젝트
npx hyperframes lint --verbose # 정보 수준 결과 표시
npx hyperframes lint --json # 기계 판독 가능 형식
index.html과 compositions/ 디렉토리의 모든 파일을 린트합니다. 오류(반드시 수정), 경고(수정 권장), 정보(--verbose로 표시)를 보고합니다.
시각적 검사
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 # 명시적 히어로 프레임 타임스탬프
린트와 유효성 검사 후에 사용하세요. 특히 말풍선, 카드, 자막, 또는 빡빡한 타이포그래피가 있는 컴포지션에 유용합니다. 다음을 보고합니다:
- 텍스트가 가장 가까운 시각적 컨테이너나 버블 밖으로 확장됨
- 텍스트가 자신의 고정 너비/고정 높이 박스에 의해 잘림
- 텍스트가 컴포지션 캔버스 밖으로 확장됨
- 자식 요소가 클리핑 컨테이너를 이탈함
오류는 렌더링 전에 수정해야 합니다. 경고는 에이전트 검토를 위해 표시됩니다. --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 . # 렌더링 성능 벤치마크