HyperFrames CLI
npx hyperframes ... 명령어로 실행하세요. 프로젝트 지침에서 래퍼를 제공한다면 래퍼를 따르세요. CLI는 Node.js 22 이상과 FFmpeg을 필요로 합니다.
개발 루프
- 스캐폴딩:
npx hyperframes init <프로젝트>또는 사이트를 캡처합니다. 비-TTY 모드에서는--non-interactive --example=<이름>을 전달하세요. - 작성:
/hyperframes-core를 사용하여 컴포지션을 작성합니다. - 편집 중 빠른 피드백 얻기: 첫 번째 HTML 패스 이후 및 구조적 변경 후에
npx hyperframes lint를 실행합니다. - 최종 게이트 실행:
npx hyperframes check를 실행합니다. 이 명령어는 브라우저를 열기 전에 lint를 다시 실행합니다. 불필요한 독립 lint 호출을 앞에 추가하지 마세요. 주석이 달린 개요 프레임과 크롭 찾기를 위해--snapshots를 추가합니다. - 서브 컴포지션 검사:
index.html이data-composition-src를 마운트할 때 중간 스냅샷을 캡처하고 각 마운트된 장면을 검사합니다. - 최종 스튜디오 미리보기 열기:
npx hyperframes preview를 실행하고, 타임라인 프로젝트 URL을 사용자에게 전달한 후 수정할지 렌더링할지 물어봅니다. - 승인 후에만 렌더링: 반복 작업에는 드래프트 품질을, 최종 전달에는 고품질을 사용합니다.
- 출력 확인: 파일이 존재하고, 비어 있지 않으며, 적절한 길이인지 확인합니다.
# 빠른 반복 검사; 작성하는 동안 필요에 따라 반복합니다.
npx hyperframes lint
# 필수 최종 게이트; lint를 포함합니다.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check는 먼저 lint를 실행한 후, 하나의 브라우저 세션과 하나의 시크 패스를 사용하여 런타임 오류, 실패한 요청, 레이아웃, *.motion.json 어설션 및 WCAG 대비를 감사합니다. 지속적인 발견 사항은 종료 코드를 결정하고, 일시적인 진입 또는 종료 발견 사항은 정보 제공용입니다. 경고를 게이트하려면 --strict를 사용하세요. validate, inspect, layout은 호환성을 위해 별칭으로 남아 있지만 새 지침이나 스크립트에 사용해서는 안 됩니다.
두 가지 다른 미리보기 화면
이 상태들을 혼동하지 마세요:
| 화면 | 열릴 수 있는 시점 | 목적 |
|---|---|---|
| 스토리보드 | 컴포지션 검사 전, storyboard: yes인 경우만 | 계획 카드 및 와이어프레임 스케치 검토. ?view=storyboard#project/<이름> 열기. |
| 최종 컴포지션 미리보기 | check 통과 후 | 렌더링 전에 조립된 타임라인 검토. #project/<이름> 열기. |
초기 보드는 최종 비디오의 승인이 아닙니다. 렌더링은 항상 hyperframes-core/references/review-loop.md에 정의된 최종 승인이 필요합니다.
서브 컴포지션 스모크 테스트
정적 감사만으로는 모든 마운트 실패를 잡을 수 없습니다. 프로젝트가 서브 컴포지션을 사용하는 경우 각 호스트 슬롯에 대해 적어도 하나의 보이는 중간 지점을 캡처하세요:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
작은 스타일 없는 콘텐츠, 캔버스 크기 아이콘, 누락된 히어로 요소 또는 타임라인 등록 시간 초과를 렌더링 차단 마운트 결함으로 취급하세요. 해당 수정 사항은 hyperframes-core/references/sub-compositions.md를 참조하세요.
에이전트 규칙
-
에이전트 및 CI 호출에는
--json을 선호하세요. 서버 모드render,preview및play는 일반 JSON 출력을 제공하지 않습니다.preview --selection --json및preview --context --json은 쿼리 모드 예외입니다. -
doctor --json은 항상 0으로 종료됩니다. 페이로드를 게이트하세요:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
비-TTY 모드는 자동입니다.
init은 거기서--example이 필요합니다. TTY에서 결정적 동작을 강제하려면--non-interactive를 사용하세요. -
동일한 검증 루프의 모든 명령에 하나의
HYPERFRAMES_RUN_ID를 사용하세요. -
해당 경고, 변수 또는 CI 조건이 렌더링을 게이트해야 할 때
--strict,--strict-all및--strict-variables를 사용하세요. -
JSON 경로는 홈 디렉터리를
$HOME으로 가립니다. 역으로 가리기를 시도하지 마세요. -
검사가 통과했다고 해서 렌더링하지 마세요. 최종 미리보기에서 멈추고 승인을 기다리세요.
스튜디오 지향 편집
사용자가 "이 요소" 또는 현재 선택 항목을 언급할 때는 추측하지 말고 스튜디오를 쿼리하세요:
npx hyperframes preview --context --json --context-fields selection
가능하면 selection.target.hfId를 사용하고, 그렇지 않으면 선택자와 소스 파일을 사용하세요. 결과가 no-selection을 보고하면 사용자에게 요소를 클릭하고 다시 실행하도록 요청하세요. 필요한 컨텍스트 조각만 요청하고, 계산된 스타일이나 편집 가능한 텍스트 메타데이터에만 --context-detail full을 사용하세요. 전체 동작 및 실패 코드는 references/preview-render.md에 있습니다.
렌더링 선택
| 필요 | 명령어 |
|---|---|
| 빠른 로컬 반복 | npx hyperframes render --quality draft |
| 최종 로컬 전달 | npx hyperframes render --quality high --output out.mp4 |
| 재현 가능한 컨테이너 렌더링 | npx hyperframes render --docker --strict --output out.mp4 |
| 로컬 변수 기반 배치 렌더링 | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen 호스팅 제로 인프라 렌더링 | npx hyperframes cloud render |
| 자체 관리 분산 AWS 렌더링 | npx hyperframes lambda render <프로젝트> --width 1920 --height 1080 --wait |
| 자체 관리 분산 GCP 렌더링 | npx hyperframes cloudrun render <프로젝트> --width 1920 --height 1080 --wait |
사용자가 로컬 Chrome, FFmpeg 또는 AWS 없이 호스팅 렌더링을 원할 때 클라우드 렌더링을 사용하세요. AWS 소유권이 요구 사항인 경우에만 Lambda를 사용하세요. GCP 소유권이 요구 사항인 경우에만 Cloud Run을 사용하세요. 클라우드 경로를 실행하기 전에 해당 참조를 읽으세요.
성공적인 렌더링을 확인한 후, 텔레메트리가 비활성화되어 있거나 사용자가 거부하지 않는 한 하나의 피드백 보고서를 보내세요:
npx hyperframes feedback --rating <0-10> --comment "<구체적인 결과 또는 문제점>"
깔끔한 실행 피드백은 간결하게 유지하세요. 버그나 문제점이 있는 경우 제출하기 전에 재현 패킷을 캡처하세요. 증상 요약만 보내지 마세요. 재실행 가능한 명령과 작업 디렉터리, 예상 동작 대 실제 동작, 정확한 오류, 출력 완료/폴백/실패 여부, 해결 방법 및 재현 프로젝트 상태를 포함하세요. 시각적 결함(검은 프레임, 깜빡임, 손상된 출력, 잘못된 프레임, 빈 출력, 기타 시각적 이상)을 설명하는 평점 7 이하의 경우 COMPOSITION_STRUCTURE: 블록도 포함하세요. 이는 개인 정보를 보호하는 구조적 분석(요소 인구 조사 + 속성 존재 여부 + 타임라인 형태)으로, 유지 관리자가 컴포지션 ZIP 없이도 알려진 버그 패턴과 일치시킬 수 있도록 합니다. 에이전트는 컴포지션 인구 조사 헬퍼를 통해 자동으로 이 블록을 채웁니다. 사람이 수동으로 채울 필요는 없습니다. 문제가 다시 재현되지 않았다면 그렇게 말하고 마지막 실패 명령과 로그를 계속 포함하세요. --file-issue는 동의가 있는 경우에만 사용하세요. 이는 최소 재현을 공개 URL에 게시합니다. 필요한 패킷 형식 및 개인 정보 보호 경고는 references/preview-render.md에 있습니다.
명령어 실행 전에 해당 참조를 읽으세요
다음 참조 및 소유 스킬은 선택적 배경 읽기가 아닌 필수 명령 계약입니다. 테이블의 명령어를 실행하기 전에 해당 행을 읽으세요.
| 필요 | 참조 |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, 모션 사이드카, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, 변수 기반 render --batch | references/compare-and-batch.md |
기존 프로젝트의 스튜디오 비트 그리드용 beats | references/beats.md |
preview, play, render, publish, 스튜디오 컨텍스트, 피드백 | references/preview-render.md |
doctor, 브라우저 관리 | references/doctor-browser.md |
auth, HeyGen 호스팅 클라우드 렌더링 및 템플릿 변수 | references/cloud.md |
| AWS Lambda 배포 및 렌더링 | references/lambda.md |
| Google Cloud Run 배포 및 렌더링 | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, 텔레메트리, 미디어 전처리 | references/upgrade-info-misc.md |
컴포지션 변수의 경우 /hyperframes-core → references/variables-and-media.md도 읽으세요. hyperframes add 및 hyperframes catalog는 /hyperframes-registry를 사용하세요. hyperframes present 전에는 /slideshow를 읽고, hyperframes keyframes 전에는 /hyperframes-keyframes를 읽으세요. TTS, 전사, 자막 또는 배경 제거 선택사항은 /media-use를 사용하세요.
특수 명령어는 의도적으로 소유 워크플로우에 의해 문서화됩니다:
npx hyperframes present <프로젝트-디렉터리> --port 3004 --no-open
npx hyperframes beats <프로젝트-디렉터리> --json
npx hyperframes keyframes <프로젝트-디렉터리> --json
present는 발표자 및 청중 동기화와 함께 탐색 가능한 덱을 제공합니다. beats는 references/beats.md에 정의된 독립형 스튜디오 비트 그리드 유틸리티입니다. keyframes는 시크-세이프 애니메이션 및 모션 경로 진단을 표시합니다.