HyperFrames CLI
모든 것은 npx hyperframes를 통해 실행됩니다. (프로젝트 지침에서 로컬 래퍼를 지정하는 경우는 예외입니다.) 로컬 래퍼를 정확히 따르세요. Node.js >= 22 및 FFmpeg가 필요합니다.
워크플로
- 스캐폴드 —
npx hyperframes init my-video(또는 URL로부터capture).init은 설치된 스킬을 GitHub의 최신 버전과 비교하여 업데이트하고, 만약 오래된 것이 있으면 전역 세트를 업데이트합니다.--skip-skills플래그는 현재 중단되었습니다(임시로, skills.sh 레지스트리가 따라잡는 동안). 따라서 모든init은 이 검사를 실행하고 최신 스킬을 가져옵니다. - 작성 — HTML 컴포지션 작성 (
hyperframes-core스킬 참조) - 린트 —
npx hyperframes lint(정적, 빠름 — 반복 중에 일찍 실행) - 검사 —
npx hyperframes check(브라우저 게이트;--snapshots를 추가하면 주석이 달린 프레임 및 찾은 항목별 크롭을 얻을 수 있음) - 미리보기/편집 —
npx hyperframes preview는 스튜디오를 엽니다. 사용자가 직접 편집할 수 있는 타임라인 편집기입니다(단순히 보기만 하는 것이 아님). 거기서 검토하고, 렌더링하기 전에 물어보세요. - 렌더링 — 변형 선택:
- 반복:
npx hyperframes render --quality draft - 배포:
npx hyperframes render --quality high --output out.mp4 - CI/교차 호스트 재현:
npx hyperframes render --docker --strict --output out.mp4 - 클라우드, 제로 인프라:
npx hyperframes cloud render(HeyGen이 렌더링 호스팅; 로컬 Chrome/FFmpeg/AWS 불필요, 아래 Cloud 참조) - 클라우드, 자체 AWS:
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(아래 Lambda 참조)
- 반복:
- 피드백 보고 — 출력을 확인한 후, 작업당 한 번씩
npx hyperframes feedback --rating <1-5> --comment "..."을 실행합니다 (에이전트 규칙 참조).
preview 전에 check를 실행하세요. 먼저 린터를 실행하고(린트 오류가 있으면 브라우저를 완전히 건너뜀), 그런 다음 기존의 validate → inspect → snapshot 시퀀스가 하나의 브라우저 세션과 하나의 검색 패스에서 했던 모든 작업을 수행합니다: 런타임 콘솔 오류 및 실패한 요청, 레이아웃 결함(말풍선/컨테이너 또는 캔버스 밖으로 텍스트가 넘침, 겹침 유지, 폐색), 모션 사이드카 검증 (*.motion.json — 검색 아래 진입, 스태거 순서, 프레임 내, 활성도), 및 WCAG 대비. 대비 실패는 오류로 간주되며, 샘플링된 전경/배경 색상, 측정된 대비와 필요한 대비의 비율, 그리고 제안된 준수 색상을 포함하므로, 대부분의 대비 수정에는 스크린샷이 필요하지 않습니다. 모든 발견 사항은 선택자, data-* 식별자, 컴포지션 소스 파일, 바운딩 박스 및 샘플 시간을 포함합니다 — HTML로 바로 이동하세요. 단일 샘플 과도 상태는 정보로 격하됩니다. 샘플 간에 유지되는 발견 사항은 종료 코드를 결정합니다(--strict는 경고도 결정). validate, inspect, layout은 여전히 작동하지만, check의 일부에 대한 더 이상 사용되지 않는 별칭입니다.
모션 중심 작업의 경우, 스냅샷 기반 반복 및 *.motion.json 사이드카를 선호하세요. 규율 및 모션 검증 사양은 references/lint-validate-inspect.md를 참조하세요. 에이전트가 작성한 후보 변형을 비교하려면 npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json]을 사용하여 각 컴포지션을 자체 런타임을 통해 렌더링하고, 하나의 레이블이 지정된 시트로 조합하여 나란히 검사하고 선택합니다. 컬러 그레이드 선택을 위해, 색상별 명령어인 npx hyperframes grade-compare --for <frame> --grades grades.json (또는 --luts a.cube,b.cube)을 사용하여 각 그레이딩 후보를 실제 WebGL 그레이딩 런타임을 통해 하나의 레이블이 지정된 PNG로 렌더링한 후 승자를 선택하세요.
에이전트 규칙
모든 명령어에 적용되는 횡단 규칙:
--json은render,preview및play서버 모드를 제외한 모든 명령어에서 사용 가능합니다. 지원되는 명령어에 대한 에이전트/CI 호출에 사용하세요. 출력에는_meta봉투(CLI 버전, 최신 사용 가능 버전, 업데이트 조언)가 포함됩니다.render는 stdout + 종료 코드를 통해서만 상태를 보고합니다. 아래의 사후 렌더링 검사로 성공을 확인하세요.preview --selection --json및preview --context --json은 preview 예외입니다: 서버를 시작하지 않고 사용자의 실행 중인 Studio 세션을 쿼리하고 종료합니다.doctor --json은 환경이 손상된 경우에도 항상 0으로 종료됩니다. 페이로드의ok필드로 게이트하세요:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. 이렇게 하면 파이프라인이 CLI 릴리스 변경으로부터 보호됩니다.- 비-TTY 모드는 자동 감지됩니다.
stdout이 TTY가 아닌 경우(CI, 에이전트, 파이프 출력) CLI는 자동으로 비대화형 모드로 전환됩니다.init은 그런 다음--example이 필요합니다. TTY에서도 이 모드를 강제하려면--non-interactive를 전달하세요. - 렌더링 시 CI 게이팅:
--strict는 린트 오류 시 실패,--strict-all은 경고에도 실패,--strict-variables는 선언되지 않은--variables키에 대해 실패합니다. HYPERFRAMES_RUN_ID로 검증 루프를 연결하세요. 작업/디자인 요소별로 CLI를 구동하는 오케스트레이터는 작업 단위당 한 번 이 환경 변수를 설정해야 합니다. 모든 명령어 호출은 이를 텔레메트리에 연결하고,check는 게이트별 분석을 내보내므로 작업당 왕복 시간을 측정할 수 있습니다.--json의 경로는 수정됩니다 —$HOME은 리터럴$HOME이 되므로 출력을 버그 보고서 및 에이전트 컨텍스트에 안전하게 붙여넣을 수 있습니다.- 렌더링은 사용자가 결정합니다. 검사가 통과되었다고 해서 자동으로 렌더링하지 마세요.
preview에서 멈추고, 사용자에게 비디오가 Studio에서 편집 가능하다고 알린 후, 사용자가 승인한 경우에만 렌더링하세요. - 사용자 지시 편집에는 Studio 컨텍스트를 사용하세요. 사용자가 "이 선택된 요소", "내가 클릭한 것", "현재 선택" 등과 같은 말을 하면, Studio에서 이를 선택하도록 요청한 후
npx hyperframes preview --context --json --context-fields selection을 실행하세요. 반환된selection.target.hfId/selector,selection.sourceFile,selection.currentTime및selection.thumbnailUrl을 사용하여 편집을 고정하세요.selection이null이고errors.selection.code가no-selection이면, 사용자에게 요소를 클릭하고 다시 실행하도록 요청하세요. 스크린샷으로 추측하지 마세요. - Studio 컨텍스트를 간결하게 유지하세요.
preview --context --json은 기본적으로 간결한 선택 항목을 반환합니다. 에이전트 컨텍스트를 비대화하지 않으려면--context-fields selection,--context-fields selection,lint또는--context-fields lint를 추가하세요. 계산된 스타일, 인라인 스타일 또는 텍스트 필드 메타데이터와 같은 무거운 필드가 필요할 때만--context-detail full을 사용하세요. - 사후 렌더링 확인.
render가 종료 코드 0을 반환한 후, 출력 파일이 존재하고 그럴듯한 크기인지 확인한 후 성공을 보고하세요:[ -s "$OUTPUT" ] || echo "render produced no output". CLI는 성공 시◇ <path>를 출력합니다. 긴 렌더링의 경우ffprobe -i "$OUTPUT" -show_format -v error로 지속 시간을 확인하는 것이 좋습니다. - 성공적인 렌더링 후 피드백을 보고하세요. 출력이 확인되면, 작업당 한 번
npx hyperframes feedback --rating <1-5> --comment "..."을 실행하여 실행 결과를 보고하세요 —5는 깔끔함, 마찰이 있을 때는 낮추세요.--comment에서 발견한 버그, 해결 방법, 누락된 기능 또는 혼란스러운 동작을 모두 넣으세요. 이것이 프로젝트의 주요 신호 채널입니다. 렌더링이 조용히 넘어가면 유지 관리자는 알 수 없습니다. 텔레메트리가 비활성화되었거나 사용자가 거부한 경우에만 건너뛰세요.- 재현 가능한 버그의 경우
--file-issue를 추가하세요 — 프로젝트의 최소 재현을 공개 URL에 게시하고, 코멘트 + 환경이 미리 채워진 GitHub 이슈를 엽니다. 코멘트만으로는 유지 관리자가 재현하는 것이 거의 불가능합니다. 게시된 컴포지션이 보고서를 실행 가능하게 만듭니다. 실패한 컴포지션이 현재 디렉토리가 아닌 경우--dir <project>를 해당 프로젝트로 지정하세요. - 유지 관리자가 재현할 수 있는 버그 코멘트를 작성하세요 — 요약은 쓸모가 없습니다. CLI는 이미 os/arch/mem/ffmpeg/CLI-버전을 첨부하므로, 이를 반복하지 말고 코멘트는 당신만이 본 내용에 사용하세요. 버그의 경우, 다음 중 해당하는 모든 것을 포함하세요:
- 정확한 오류 문자열, 그대로 (요약하지 말고 복사) — 또한 렌더링이 여전히 출력 파일을 생성했는지, 자동으로 폴백했는지(
[Render] … re-rendering via screenshot/falling back로그 라인 확인), 또는 프로세스가 오류 없이 강제 종료되었는지(Killed: 9,FATAL … heap,Target closed). "어떤 타임아웃 / 어떤 실패 모드"가 가장 유용한 정보입니다. - 최소 재현: 가장 작은 컴포지션(또는 문제가 있는 요소 + 해당 CSS)을 코멘트에 인라인으로 포함하거나 파일을 명시하세요. 분리한 트리거 이름을 지정하세요(예: "텍스트 노드가
font-family: 苹方을 사용할 때만", "4K에서만", "<video>가 있을 때만"). - 실행한 정확한 명령어 + 플래그 및 설정된 모든 환경 변수(
HF_*/PRODUCER_*). - 무엇이, 어디서 잘못되었는지: 프레임 번호 또는 타임스탬프, 시각적 결함(빈 텍스트, 하단 검은 띠, 잘못된 글리프, 정지된 캔버스)과 예상한 것. 저장한 경우 스크린샷 경로.
- 가끔만 재현된다면 그렇게 말하고 발생률을 알려주세요.
- 정확한 오류 문자열, 그대로 (요약하지 말고 복사) — 또한 렌더링이 여전히 출력 파일을 생성했는지, 자동으로 폴백했는지(
- 재현 가능한 버그의 경우
라우팅
| 원하는 작업… | 읽을 문서 |
|---|---|
프로젝트 스캐폴드 (init, capture, skills) | references/init-and-scaffold.md |
정확성 확인 (lint, check, snapshot, 더 이상 사용되지 않는 validate/inspect) | references/lint-validate-inspect.md |
미리보기 또는 렌더링 (preview, play, render, publish) | references/preview-render.md |
환경 진단 (doctor, browser) | references/doctor-browser.md |
클라우드 렌더링, 제로 인프라 HeyGen 호스팅 (cloud render / list / get / delete, auth) | references/cloud.md |
자체 AWS Lambda에서 클라우드 렌더링 (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
매개변수화/템플릿 렌더링 (--variables, --variables-file, --strict-variables, --batch) | references/cloud.md + hyperframes-core (variables-and-media.md) |
기타 모든 것 (info, upgrade, compositions, docs, benchmark, telemetry, 에셋 전처리) | references/upgrade-info-misc.md |
스킬 간 연동
- Tailwind 프로젝트 (
init --tailwind) → 클래스나 테마 토큰을 편집하기 전에hyperframes-core(Tailwind 참조)를 사용하세요. - 레지스트리 블록/컴포넌트 (
hyperframes add,hyperframes catalog) → 설치 경로, 하위 컴포지션 연결, 스니펫 병합에hyperframes-registry를 사용하세요. - 에셋 전처리 (
tts,transcribe,remove-background) → 음성 선택, Whisper 모델 규칙, 캡션 및 TTS-to-캡션 체인에media-use를 사용하세요. - 매개변수화된 렌더링 (
--variables) →<html>의data-composition-variables를 통해 선언합니다. 전체 스키마는hyperframes-core를 참조하세요.
클라우드 (HeyGen 호스팅 렌더링)
hyperframes cloud render는 제로 인프라 렌더링 경로입니다. CLI가 프로젝트를 압축하고 업로드한 후 HeyGen의 클라우드에서 렌더링하여 mp4를 다운로드합니다. Chrome, FFmpeg, AWS가 필요 없으며, 크레딧당 비용을 지불합니다. 이것이 "클라우드에서 렌더링"에 대한 기본 답변입니다. Lambda는 이미 AWS를 소유하고 있고 분산/청크 렌더링이 필요한 경우에만 사용하세요.
npx hyperframes auth login # 일회성 로그인 (`heygen` CLI와 공유)
npx hyperframes cloud render # 압축, 업로드, 렌더링, renders/<id>.mp4로 다운로드
일반적인 플래그: --composition <html>, --output <path>, --quality draft|standard|high, --fps, --resolution 1080p|4k, --format mp4|webm|mov, --aspect-ratio (data-width/data-height에서 자동 감지). --no-wait + --callback-url로 파이어 앤 포겟; --idempotency-key "$(uuidgen)"로 재시도를 안전하게 만드세요. cloud list / cloud get <id> / cloud delete <id>로 작업을 관리하세요.
규범적인 템플릿 워크플로는 한 번 업로드하고 여러 번 다시 렌더링하는 것입니다: 로컬 프로젝트를 한 번 렌더링하여 asset_id를 얻은 다음, 다른 --variables로 해당 에셋에 대해 다시 제출합니다(압축 + 업로드 건너뜀). 전체 플래그 세트, 인증 모델, 웹훅 및 템플릿 루프는 references/cloud.md를 참조하세요.
변수 (매개변수화/템플릿 렌더링)
모든 렌더링(로컬, 클라우드 또는 Lambda)은 렌더링 시 선언된 템플릿 슬롯을 채울 수 있습니다. 선언은 컴포지션(data-composition-variables)에 있으며, CLI 인터페이스는 다음과 같습니다:
npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
--strict-variables는 선언되지 않은 키 또는 유형 불일치가 있을 때 렌더링을 실패시킵니다(CI에서 사용). --batch <rows.json>는 데이터 행당 하나의 출력을 {key}/{index} 경로 플레이스홀더와 함께 렌더링하고 manifest.json을 작성합니다. 전체 스키마(유형 선언, data-var-src/data-var-text 선언적 바인딩, 하위 컴포지션용 인스턴스별 data-variable-values, 및 우선 순위)는 hyperframes-core 스킬(references/variables-and-media.md)을 사용하세요. 클라우드 템플릿 루프는 references/cloud.md에 있습니다.
Lambda (클라우드 렌더링)
hyperframes lambda는 분산 렌더링을 AWS Lambda에 배포하고 랩톱 또는 CI에서 드라이브합니다. 종단 간은 세 가지 명령어로 이루어집니다:
npx hyperframes lambda deploy # SAM 스택 프로비저닝 (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # 분해 (S3 버킷 제외) -- 매월 S3에서 정리