coleam00/hyperframes-ai-video-generation

HyperFrames CLI

모든 명령은 npx hyperframes를 통해 실행됩니다. Node.js >= 22 및 FFmpeg가 필요합니다.

워크플로우

1. 스캐폴딩 — npx hyperframes init my-video
2. 작성 — HTML 컴포지션 작성 (hyperframes 스킬 참조)
3. 린트 — npx hyperframes lint
4. 시각적 검사 — npx hyperframes inspect
5. 미리보기 — npx hyperframes preview
6. 렌더링 — 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 --non-interactive       # 프롬프트 건너뛰기 (CI/에이전트)

템플릿: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init은 올바른 파일 구조를 생성하고, 미디어를 복사하며, Whisper로 오디오를 전사하고, AI 코딩 스킬을 설치합니다. 수동으로 파일을 만드는 대신 사용하세요.

린팅

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 # 명시적 히어로 프레임 타임스탬프

lint와 validate 이후에 사용하세요. 특히 말풍선, 카드, 캡션 또는 좁은 타이포그래피가 포함된 컴포지션에 유용합니다. 보고하는 항목:

• 가장 가까운 시각적 컨테이너 또는 말풍선 밖으로 나가는 텍스트
• 자체 고정 너비/고정 높이 상자에 의해 잘리는 텍스트
• 컴포지션 캔버스 밖으로 나가는 텍스트
• 클리핑 컨테이너를 벗어나는 하위 요소

오류는 렌더링 전에 수정되어야 합니다. 경고는 에이전트 검토를 위해 표시됩니다. 경고에서도 실패하려면 --strict를 추가하세요. 반복되는 정적 이슈는 기본적으로 접혀서 JSON 출력이 LLM 컨텍스트 윈도우에 최적화됩니다. 진입/퇴장 애니메이션을 위해 오버플로우가 의도적인 경우, 요소나 상위 요소에 data-layout-allow-overflow를 표시하세요. 장식 요소가 감사되지 않아야 하는 경우 data-layout-ignore로 표시하세요.

npx hyperframes layout은 동일한 시각적 검사 패스의 호환성 별칭으로 사용 가능합니다.

미리보기

npx hyperframes preview                   # 현재 디렉토리 서빙
npx hyperframes preview --port 4567       # 사용자 지정 포트 (기본값 3002)

파일 변경 시 핫 리로드됩니다. 브라우저에서 스튜디오가 자동으로 열립니다.

렌더링

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는 렌더링 시간 2배
--quality	draft, standard, high	standard	draft는 반복 작업용
--format	mp4, webm	mp4	WebM은 투명도 지원
--workers	1-8 or 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 누락, 낮은 메모리.

기타

npx hyperframes compositions   # 프로젝트의 컴포지션 목록
npx hyperframes docs           # 문서 열기
npx hyperframes benchmark .    # 렌더링 성능 벤치마크