HyperFrames CLI
마케팅 엔진 파이프라인을 위한 npx hyperframes 래퍼입니다. Node.js >= 22와 PATH에 FFmpeg가 필요합니다(npx hyperframes doctor로 확인). 모든 명령은 기본적으로 DRY_RUN-safe 모드로 실행됩니다. lint/inspect 단계는 외부 호출이 없으며, render만 MP4를 작성합니다.
호출 시기
hyperframes-prompt-builder가outputs/<client>/<date>/<piece-id>/아래에 프로젝트를 생성한 직후- 컴포지션을 게시하기 전에 유효성 검사가 필요할 때(
lint+inspect) - 작업을 반복하면서 로컬 미리보기가 필요할 때(
preview) - 게시 단계에서 사용할 최종 아티팩트를 생성하는 렌더링(
render) - 렌더링 실패 시 환경 문제 해결(
doctor,browser,info)
입력값
project_path: 문자열. HyperFrames 프로젝트 경로(index.html과composition.json을 반드시 포함).mode:"lint" | "inspect" | "preview" | "render" | "doctor".render_opts: 객체, 선택 사항,mode = "render"일 때만 사용. 인식하는 키:fps: 24 | 30 | 60 (기본값 30).quality:"draft" | "standard" | "high"(기본값"standard"; 반복 작업 중에는"draft"사용).format:"mp4" | "webm"(기본값"mp4").variables: 객체. 변수 ID를 키로 하는 JSON 객체로,data-composition-variables기본값을 재정의합니다.strict: 불리언.--strict에 매핑. 파이프라인에서 기본값true— lint 오류가 있으면 렌더링 실패.strict_variables: 불리언.--strict-variables에 매핑. 조각 실행 시 기본값true.workers: 1-8 사이의 정수 또는"auto". 기본값"auto".output: 문자열.outputs/<client>/<date>/<piece-id>/내부의 출력 파일 경로.
프로세스
- 환경 확인 (세션 첫 실행 시):
npx hyperframes doctor. FFmpeg 또는 Chrome이 없으면 하드 블록으로 표시 — 렌더링을 시도하지 않음. - Lint.
npx hyperframes lint <project_path> --json. 모든error수준의 결과를 차단 요인으로 처리. 경고는 오케스트레이터에 전달하여 운영자가 결정. - Inspect.
npx hyperframes inspect <project_path> --json. 렌더링 전에 텍스트 오버플로우나 캔버스 이스케이프 문제를 해결. 오버플로우가 의도적인(진입/퇴장 애니메이션) 경우, 요소에data-layout-allow-overflow를 추가하거나(장식 요소의 경우 상위 요소에data-layout-ignore사용) — 전역적으로 규칙을 무음 처리하지 않음. - Preview (운영자 전용).
npx hyperframes preview <project_path> --port <port>. 스튜디오 프로젝트 URL(http://localhost:<port>/#project/<project-name>)을 반환하며, 소스index.html경로는 반환하지 않음. - Render.
render_opts에서 해석된 플래그를 사용하여npx hyperframes render <project_path>실행.render_opts.variables에서--variables인수를 한 줄 JSON 문자열로 구성. 조각 실행 시 항상--strict와--strict-variables를 전달. - 출력 확인. 렌더링 후 MP4 파일이 존재하고 크기가 0이 아닌지 확인.
{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }형식으로data/video-usage.jsonl에 로그.
출력값
lint:{ pass: boolean, errors: [...], warnings: [...] }.inspect:{ pass: boolean, findings: [...] }.render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.preview:{ url: string }.
명령어 치트 시트
npx hyperframes init <name> # 스캐폴드 (프롬프트 빌더가 각 조각에 대해 한 번 사용)
npx hyperframes lint <path> # 마크업 검증
npx hyperframes inspect <path> # 레이아웃/오버플로우 감사
npx hyperframes preview <path> --port 3017 # 로컬 개발
npx hyperframes render <path> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor # 환경 확인
npx hyperframes info # 버전/환경 세부 정보
변경 불가 규칙
- lint 및 inspect 단계를 통과하지 않고 렌더링하지 않음. 파이프라인에 잘못된 컴포지션을 복구할 경로가 없음.
- lint 또는 inspect 결과를 전역적으로 무음 처리하지 않음 — 마크업을 수정하거나 특정 요소를
data-layout-allow-overflow/data-layout-ignore로 허용 목록에 추가. - 선언된 변수가 있는 조각의 경우 항상
--strict-variables를 전달. 변수 ID 오타는 조용히 기본값으로 넘어가지 않고 반드시 실패해야 함. - 최종 전달 렌더링의 경우
--quality high. 반복 루프의 경우--quality draft를 사용하여 컴퓨팅 리소스 절약. - 자산 전처리(
tts,transcribe,remove-background)는 이 스킬의 범위를 벗어남 — 여기에 인라인으로 작성하지 말고 향후hyperframes-media스킬을 통해 호출.
실패 모드
doctor가 FFmpeg 또는 Chrome 누락을 보고: 프로젝트의 설정 지침에 따라 설치; 우회하지 않음.render가unknown variable오류로 실패:--variables를 통해 전달된 키가data-composition-variables에 선언되지 않음. 마크업을 수정하거나 재정의를 제거.render가 벽시계 시간 예산 초과:--quality를standard로 낮추거나, 컴포지션을 하위 컴포지션으로 분할하고--workers를 통해 병렬화.- 출력 MP4 크기가 0바이트:
doctor를 다시 실행; 거의 항상 Chrome이 캡처 중에 충돌한 경우.
관련 스킬
hyperframes: 컴포지션 작성 규칙; 이 스킬이 검증하고 렌더링할 프로젝트를 생성.hyperframes-prompt-builder: 브리프 → 컴포지션 스펙; 이 스킬보다 먼저 실행.qa-tech-specs: 렌더링된 MP4를 검증하여 플랫폼 사양을 확인; 이 스킬 이후에 실행.
상위 참조
전체 상위 스킬(모든 플래그, 문제 해결 매트릭스, 매개변수화된 렌더링): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli