Hyperframes 브릿지은(는) 무엇을 하나요?
오케스트레이션: SKILL. 외부 종속성 래퍼. 실제 Hyperframes 모노레포는
../../external/hyperframes/에 있습니다 (사용자가 선택한 경우/amw-init6단계에서 클론되거나, 또는 이 스킬이 첫 렌더링 시 대체 방식으로 클론합니다). 이 스킬은 셸 호출 패턴을 문서화하며, 모노레포를 직접 포함하지 않습니다.
개요
외부 Hyperframes 모노레포(external/hyperframes/)를 셸 호출하여 HTML 구성을 MP4 비디오로 렌더링합니다. 단일 HTML 장면 파일 또는 전체 Hyperframes 프로젝트 디렉터리를 허용합니다. npx hyperframes render --output <mp4>를 호출하기 전에 필수 사전 렌더링 게이트(lint → validate → inspect → render)를 실행합니다. MP4 경로와 작업 완료 보고서를 반환합니다. 플러그인 내부에서 Hyperframes 파이프라인을 재구현하지 않으며, 셸 호출만 수행합니다.
지침
- 두 가지 검사로 외부 저장소를 확인합니다:
external/hyperframes/package.json이 존재해야 하며,npx hyperframes render --help가 응답해야 합니다. 둘 중 하나라도 실패하면 즉시 중단합니다. - 프로젝트 디렉터리를 확인합니다:
project_dir이 제공되면 그것을 사용하고,html_scene_path가 제공되면 임시 프로젝트를 생성합니다. 둘 다 제공되지 않으면 즉시 실패합니다. - 사전 렌더링 게이트 시퀀스를 순서대로 실행합니다:
lint → validate → inspect → render(단계가 0이 아닌 종료 코드를 반환하면 중단). cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>를 실행하고 출력 경로를 수집합니다.- MP4 파일이 존재하고 비어 있지 않은지 확인하고, 출력 경로와
inspect경고를 보고합니다. - 권위 있는 실행 단계는 아래
## 호출 패턴섹션을 참조하세요.
활성화
전용 슬래시 명령어가 없습니다. 이 스킬에는 일치하는 /amw-* 바로 가기가 없습니다. 승인된 디자인이 MP4 비디오 출력을 필요로 할 때 Main-agent 모드의 최종 Phase B 단계로 design-principles 오케스트레이터에 의해 호출됩니다. 오케스트레이터는 명령 계층 제한 없이 이 스킬의 전체 Hyperframes 셸 호출 파이프라인 및 구성 기술을 적용할 수 있습니다.
이 스킬은 자율적이고 자체 포함되어 있습니다. 모든 에이전트(메인 에이전트, 하위 에이전트 또는 외부 오케스트레이터)는 이 SKILL.md와 그 참조를 읽어 사용할 수 있습니다. 이 스킬의 기술은 일치하는 명령어가 무엇인지에 국한되지 않습니다.
흐름 내 위치
출력(Phase B — 종료). HTML을 MP4 비디오로 렌더링하는 파이프라인입니다. 사용자가 HTML 구성을 비디오 파일로 래스터화하기를 명시적으로 원할 때만 트리거됩니다. 구성 작성이 완료된 후 마지막으로 실행됩니다.
트리거 조건
요청이 다음 중 하나와 일치하는 경우에만 이 스킬을 호출하세요:
- "이 HTML을 비디오로 렌더링" / "MP4로 렌더링"
- "HTML을 MP4로" / "웹사이트를 비디오로" / "페이지를 비디오로"
- "이 HTML 구성에서 비디오 생성"
- "구성을 비디오로 래스터화"
- Hyperframes /
hyperframes render/.hf.html명시적 언급
일반적인 "애니메이션", "모션", "비디오 재생" 또는 "애니메이션 컴포넌트" 언급에는 호출하지 마세요. 해당 사항은 다음에 속합니다:
../amw-design-principles/starter-components/animations.html(브라우저 내 Stage + Sprite 타임라인)../amw-pretext/(타이포그래픽 모션 —pretext-art/는 더 이상 사용되지 않는 리디렉션)- 사용자 자체 파이프라인
전제 조건
-
runtime_binaries (시스템 전제 조건): Node.js >= 22, git
-
runtime_binaries (
/amw-init으로 설치): Bun (Hyperframes의 패키지 관리자), FFmpeg. Chrome은 Hyperframes 자체에서hyperframes browser ensure를 통해 관리합니다 (내부적으로 Puppeteer +@puppeteer/browsers사용 — Playwright 아님). -
외부 소스:
../../external/hyperframes/—https://github.com/heygen-com/hyperframes에서 클론한 Hyperframes 모노레포.inspect,--hdr,data-variable-values지원을 위해 v0.4.30 이상으로 고정하세요. 폴더가 없으면/amw-init또는 이 스킬이 진행 전에 반드시 클론해야 합니다:git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes cd external/hyperframes && bun install
입력 계약
브릿지는 상호 배타적인 두 가지 입력을 허용합니다. 정확히 하나를 제공하세요:
| 필드 | 유형 | 설명 |
|---|---|---|
html_scene_path | string (선택 사항) | 단일 HTML 파일의 절대 경로. 브릿지는 mktemp -d -t hf-XXXXXX (POSIX 호환)를 통해 임시 hyperframes 프로젝트 디렉터리를 생성하고, HTML을 index.html로 작성한 후 렌더링하고 보고서가 작성된 후 정리합니다. |
project_dir | string (선택 사항) | 기존 hyperframes 프로젝트 디렉터리의 절대 경로 (index.html 및 선택적으로 compositions/, assets/ 포함). 브릿지는 바로 cd하여 이동합니다 — 스캐폴딩하지 않습니다. 하위 구성, 오디오 및 외부 자산을 지원합니다. |
둘 다 제공되면 project_dir이 우선합니다. 둘 다 제공되지 않으면 즉시 실패합니다.
호출 패턴
-
외부 저장소 확인 — 두 가지 검사 필요:
# 검사 1 — package.json 존재 (모노레포 클론됨) test -f "external/hyperframes/package.json" || exit-fail "모노레포를 찾을 수 없음" # 검사 2 — CLI 응답 (설치가 정상임) # @hyperframes/cli는 npm에 게시되지 않음 — 모노레포 워크스페이스 내에서 실행해야 함 (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "hyperframes CLI가 작동하지 않음 — external/hyperframes/ 내부에서 bun install 실행"둘 중 하나라도 실패하면 즉시 중단하세요. 진행하지 마세요.
-
프로젝트 디렉터리 확인.
project_dir이 제공된 경우: 직접 사용합니다.HF_PROJ_DIR="$project_dir"로 설정합니다.html_scene_path가 제공된 경우: 임시 프로젝트를 생성합니다:HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)" cp "$html_scene_path" "$HF_PROJ_DIR/index.html"- 그 외의 경우: 즉시 실패합니다.
-
사전 렌더링 게이트 시퀀스 실행:
lint → validate → inspect → render.cd "$HF_PROJ_DIR" npx hyperframes lint npx hyperframes validate npx hyperframes inspect --json # 오류가 있으면 중단 (--strict와 함께 0이 아닌 종료)TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect 참조.
[TECH-hyperframes-cli-inspect.md] 기능 · 사용 시기 · 작동 방식 · 플래그 · 출력 (JSON 모드) · 최소 예제 · 옵트아웃 속성 · 주의 사항 · 상호 참조 [TECH-hyperframes-cli-validate.md] 기능 · 사용 시기 · 작동 방식 · 출력 · 경고가 나타나는 경우 · 최소 예제 · 주의 사항 · 상호 참조 [TECH-hyperframes-cli-lint.md] 기능 · 사용 시기 · 작동 방식 · 최소 예제 · 주의 사항 · 상호 참조
게이트 시퀀스 참고: 브릿지의 시퀀스 (
lint → validate → inspect → render)는 의도적으로 상위 시퀀스 (lint → inspect → preview → render— 포함된external/hyperframes/모노레포 내부의 상위 Hyperframes CLI SKILL.md 참조)를 확장하여 무인 Phase B 파이프라인을 위해validate를 추가하고preview(개발자 루프 기본 요소)를 제거했습니다.
- 렌더링. 확인된 프로젝트 디렉터리 내에서:
필요에 따라 추가 플래그 (cd "$HF_PROJ_DIR" npx hyperframes render --output <abs-mp4-path>--fps,--quality,--format,--hdr등) — TECH-hyperframes-cli-render 참조.
[TECH-hyperframes-cli-render.md] 기능 · 사용 시기 · 작동 방식 · 플래그 · 품질 지침 · 투명 비디오 · 최소 예제 · 작업자 튜닝 · 주의 사항 · 상호 참조
- MP4 경로 반환 호출자에게. 프로젝트 디렉터리가 임시 스캐폴드(
html_scene_path경로)인 경우 보고서가 작성된 후 제거합니다.
HTML 구성 규칙 (Hyperframes 특화)
구성은 #stage 루트와 그 자식(트랙/클립/오버레이)에 data-* 타임라인 속성이 있는 일반 HTML을 사용합니다. 이는 ../amw-design-principles/starter-components/animations.html과 동일한 Stage + Sprite 정신 모델입니다. Hyperframes는 다중 트랙 오디오/비디오 믹싱 및 오프스크린 결정적 렌더링으로 확장합니다.
주요 속성 (공식 스키마는 클론되면 external/hyperframes/packages/core/에 있습니다):
data-composition-id— 스테이지 수준 식별자data-start,data-duration— 초 단위, 클립별data-track-index— 레이어 순서 (비디오/오버레이/오디오 트랙)data-width,data-height— 스테이지 수준 캔버스 크기
Framer Motion, GSAP-종속성 또는 기타 타사 애니메이션 런타임을 브릿지에 도입하지 마세요. Hyperframes에는 자체 프레임 어댑터 패턴이 있습니다. 사용자가 구성 내에서 GSAP을 원한다면 이는 브릿지의 문제가 아니라 Hyperframes의 문제입니다.
참조
전체 참조 인덱스: INDEX.md — Capture 파이프라인(7단계), CLI 명령어(12개), 구성 작성(7개), 레지스트리(4개)로 그룹화된 32개의 TECH-*.md 파일. 각 파일에는 자체 목차가 있습니다. 필요한 파일만 로드하세요.
예제
단계별 참조 파일 ./references/TECH-hyperframes-capture-step-*.md (7단계 웹사이트-투-비디오 파이프라인) 및 구성 작성 가이드 TECH-hyperframes-composition-core에서 실제 예제를 참조하세요.
[TECH-hyperframes-composition-core.md] 기능 · 사용 시기 · 작동 방식 · 접근 방식 (내러티브 순서) · 단일 파일 기본 구조 · 시각적 ID 게이트 (필수 — HTML 작성 전) · 주의 사항 · 상호 참조
출력
렌더링된 MP4 비디오 파일과 작업 완료 보고서입니다. MP4는 확인된 프로젝트 디렉터리에서 npx hyperframes render --output <mp4>에 의해 생성됩니다. 브릿지는 성공을 보고하기 전에 파일이 존재하고 비어 있지 않은지 확인합니다. 전체 계약은 아래를 참조하세요.
출력 및 완료 체크리스트
전체 출력 계약(아티팩트 경로 추론 규칙, 작업 완료 보고서 형식, 필수 체크리스트)은 TECH-output-contract에 있습니다. 두 가지 출력이 필수입니다:
- 아티팩트 — hyperframes 프로젝트 폴더 + 렌더링된 MP4. 경로는 프로젝트에서 추론됩니다 (사용자 경로 → 프레임워크 규칙 →
./design/<subtype>/→ 폴백./design/videos/). - 작업 완료 보고서
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md에 모든 아티팩트와 항목별 체크리스트 결과를 나열합니다.
완료를 보고하기 전에: TECH-output-contract의 모든 체크리스트 항목은 반드시 PASS 또는 N/A여야 합니다. FAIL이 있으면 수정 루프가 트리거됩니다.
리소스
../amw-design-principles/starter-components/animations.html— 브라우저 내 미리보기에 사용되는 약 50줄의 Stage + Sprite 타임라인 엔진; Hyperframes도 동일한 리듬을 공유합니다.../../bin/amw-html-export.py— 대체가 아닙니다.html-export는 단일 프레임을 PNG/PDF로 렌더링합니다. Hyperframes는 Puppeteer + Chrome (hyperframes browser ensure로 관리) + FFmpeg을 사용하여 다중 프레임 MP4를 렌더링합니다.../amw-dev-browser/— 대체가 아닙니다.dev-browser는 입력/자동화용입니다. Hyperframes는 출력 래스터라이저입니다./amw-init— Bun, FFmpeg을 설치하고 첫 사용 시external/hyperframes/를 클론합니다. 렌더링용 Chrome은 Hyperframes 자체에서hyperframes browser ensure를 통해 프로비저닝합니다.- 외부 저장소:
https://github.com/heygen-com/hyperframes
불가침 조항
- 외부 모노레포를 셸 호출을 통해 사용하세요. 플러그인 내부에서 파이프라인을 재구현하지 마세요.
- Hyperframes 소스를
skills/에 포함하지 마세요. 500개 이상의 파일은 스킬에 부적절한 범위입니다. dev-browser를 Hyperframes 대신 사용하지 마세요. 두 도구는 반대 문제를 해결합니다 (입력 vs. 출력).html-export.py를 대신 사용하지 마세요. 단일 프레임 PNG는 비디오가 아닙니다.- 사용자는 첫 사용 전에
/amw-init을 실행하여 Bun + FFmpeg을 설치하고 외부 저장소를 클론해야 합니다. Chrome은 클론 후(cd external/hyperframes && npx hyperframes browser ensure)를 한 번 실행하여 프로비저닝됩니다.
오류 처리
일반적인 실패 모드 및 수정 단계는 TECH-error-handling에 있습니다. 다음을 다룹니다: 외부 저장소 누락, Bun / FFmpeg / Chrome 프로비저닝, HTML 속성 구문 분석 오류, 비디오 인코딩 실패, 오래된 클론.