HyperFrames CLI
모든 것은 npx hyperframes를 통해 실행됩니다. Node.js >= 22와 FFmpeg가 필요합니다.
워크플로우
- 스캐폴드(Scaffold) —
npx hyperframes init my-video - 작성(Write) — HTML 컴포지션 작성 (
hyperframesSkill 참조) - 린트(Lint) —
npx hyperframes lint - 프리뷰(Preview) —
npx hyperframes preview - 렌더링(Render) —
npx hyperframes render
프리뷰 전에 반드시 린트를 실행하세요. 누락된 data-composition-id, 중복 트랙, 등록되지 않은 타임라인 등을 잡아냅니다.
스캐폴딩
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 --non-interactive # 프롬프트 건너뛰기 (CI/에이전트)
템플릿: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init 명령어는 올바른 파일 구조를 생성하고, 미디어를 복사하며, Whisper로 오디오를 전사하고, AI 코딩 Skill을 설치합니다. 수동으로 파일을 생성하는 대신 이 명령어를 사용하세요.
린팅
npx hyperframes lint # 현재 디렉토리
npx hyperframes lint ./my-project # 특정 프로젝트
npx hyperframes lint --verbose # 정보 수준 결과 표시
npx hyperframes lint --json # 기계 판독 가능 형식
index.html과 compositions/ 디렉토리 내 모든 파일을 린트합니다. 오류(반드시 수정), 경고(수정 권장), 정보(--verbose 사용 시)를 보고합니다.
프리뷰
npx hyperframes preview # 현재 디렉토리 서빙
npx hyperframes preview --port 4567 # 사용자 지정 포트 (기본값 3002)
파일 변경 시 핫 리로드됩니다. 브라우저에서 자동으로 스튜디오를 엽니다.
렌더링
npx hyperframes render # 표준 MP4 (자동으로 renders/에 출력)
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/이름_타임스탬프.mp4 | 출력 경로 |
--fps | 24, 30, 60 | 30 | 60fps는 렌더링 시간 2배 |
--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 | 오류 및 경고 시 실패 |
품질 가이드라인: 반복 작업 시 draft, 검토 시 standard, 최종 배포 시 high를 사용하세요.
전사
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # 기존 자막 가져오기
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
텍스트 음성 변환
npx hyperframes tts "텍스트를 여기에 입력" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # 모든 음성 목록 보기
문제 해결
npx hyperframes doctor # 환경 확인 (Chrome, FFmpeg, Node, 메모리)
npx hyperframes browser # 번들된 Chrome 관리
npx hyperframes info # 버전 및 환경 정보
npx hyperframes upgrade # 업데이트 확인
렌더링이 실패하면 doctor를 먼저 실행하세요. 일반적인 문제: FFmpeg 누락, Chrome 누락, 메모리 부족.
주의사항
--out 경로는 디렉토리여야 하며 파일명이 아니어야 합니다.
npx hyperframes render --out renders/output.mp4 → ✗ 오류: "디렉토리가 아닙니다"
npx hyperframes render → ✅ 자동으로 renders/이름_타임스탬프.mp4에 출력
파일 경로를 지정하려면 --out 대신 --output을 사용하세요.
index.html의 루트 타임라인이 서브 컴포지션의 data-composition-id와 일치해야 합니다.
index.html에 data-composition-src 참조만 있고 인라인 콘텐츠가 없는 경우에도 실제 data-composition-id와 일치하는 window.__timelines 등록이 필요합니다. 가장 좋은 방법은 window.__timelines['<서브-컴포지션-아이디>'] = gsap.timeline({paused:true})를 등록하는 것입니다. 그러나 서브 컴포지션이 자체 타임라인을 등록하므로, index.html 스크립트 블록은 린트 통과를 위해서만 필요합니다. 'root' 대신 서브 컴포지션의 ID를 사용하세요.
서브 컴포지션 <div>에는 data-start="0"과 data-duration이 필요합니다.
<template> 내부의 <div data-composition-id="...">에는 data-start="0"과 data-duration="N"이 있어야 합니다. 그렇지 않으면 린트가 경고를 표시하고 재생이 시작되지 않을 수 있습니다.
기타
npx hyperframes compositions # 프로젝트의 컴포지션 목록
npx hyperframes docs # 문서 열기
npx hyperframes benchmark . # 렌더링 성능 벤치마크