HyperFrames CLI은(는) 무엇을 하나요?
프로젝트 지침에서 래퍼를 제공하지 않는 한 npx hyperframes ... 명령어로 실행합니다. 래퍼가 있으면 이를 따릅니다. CLI는 Node.js 22 이상과 FFmpeg가 필요합니다.
개발 루프
- 스캐폴딩:
npx hyperframes init <project>또는 사이트를 캡처합니다. TTY가 아닌 모드에서는--non-interactive --example=<name>을 전달합니다. - 작성:
/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/<name>으로 열림. |
| 최종 컴포지션 미리보기 | check 통과 후 | 렌더링 전에 조립된 타임라인 검토. #project/<name>으로 열림. |
초기 보드는 최종 비디오의 승인이 아닙니다. 렌더링에는 항상 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 <project> --width 1920 --height 1080 --wait |
| 자체 관리 분산 GCP 렌더링 | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
사용자가 로컬 Chrome, FFmpeg 또는 AWS 없이 호스팅 렌더링을 원하는 경우 클라우드 렌더링을 사용하십시오. AWS 소유권이 요구 사항인 경우에만 Lambda를 사용하십시오. GCP 소유권이 요구 사항인 경우에만 Cloud Run을 사용하십시오. 클라우드 경로를 실행하기 전에 일치하는 참조를 읽으십시오.
성공적인 렌더링을 확인한 후, 텔레메트리가 비활성화되어 있거나 사용자가 거부하지 않는 한 하나의 피드백 보고서를 보내십시오:
npx hyperframes feedback --rating <0-10> --comment "<구체적인 결과 또는 어려움>"
깨끗하게 실행된 피드백은 간결하게 유지하십시오. 버그나 어려움이 있는 경우, 증상 요약만 보내지 말고 제출 전에 재현 패킷을 캡처하십시오. 재실행 가능한 명령어와 작업 디렉토리, 예상 동작 대 실제 동작, 정확한 오류, 출력이 완료/대체/실패했는지 여부, 해결 방법 및 재현 프로젝트 상태를 포함하십시오. 문제가 다시 재현되지 않은 경우 해당 사실을 명시하고 마지막 실패 명령어와 로그를 계속 포함하십시오. --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 <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present는 발표자 및 청중 동기화와 함께 탐색 가능한 데크를 제공합니다. beats는 references/beats.md에 정의된 독립형 스튜디오 비트 그리드 유틸리티입니다. keyframes는 탐색 안전 애니메이션 및 모션 경로 진단을 제공합니다.