Communitygithub.com

Hyperframes 브릿지

HTML 구성을 MP4 비디오로 렌더링하는 외부 Hyperframes 모노레포 브릿지입니다. 'render HTML as video', 'HTML to MP4' 등 특정 트리거에 반응합니다.

Hyperframes 브릿지란 무엇인가요?

Hyperframes 브릿지는 외부 Hyperframes 모노레포(`external/hyperframes/`)를 셸 명령으로 호출하여 HTML 구성을 MP4 동영상으로 렌더링하는 기술 스킬입니다. 이 스킬은 HTML 파일이나 프로젝트 디렉터리를 입력으로 받아, lint(린트), validate(검증), inspect(검사), render(렌더링)의 필수 사전 렌더링 게이트를 순차적으로 실행한 후 `npx hyperframes render --output <mp4>` 명령을 통해 최종 MP4 파일을 생성합니다. Claude Code, Cursor, Codex 등 모든 에이전트가 이 SKILL.md를 읽고 자율적으로 사용할 수 있도록 설계되었으며, Main-agent 모드 Phase B의 마지막 단계로 동작합니다. Node.js >= 22, git, Bun, FFmpeg가 필요하며, Chrome은 Hyperframes 자체에서 관리합니다. 이 스킬은 Hyperframes의 파이프라인을 재구현하지 않고 오직 외부 모노레포를 셸 호출 방식으로 사용하는 데 중점을 둡니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Hyperframes 브릿지은(는) 무엇을 하나요?

오케스트레이션: SKILL. 외부 종속성 래퍼. 실제 Hyperframes 모노레포는 ../../external/hyperframes/ 에 있습니다 (사용자가 선택한 경우 /amw-init 6단계에서 클론되거나, 또는 이 스킬이 첫 렌더링 시 대체 방식으로 클론합니다). 이 스킬은 셸 호출 패턴을 문서화하며, 모노레포를 직접 포함하지 않습니다.

개요

외부 Hyperframes 모노레포(external/hyperframes/)를 셸 호출하여 HTML 구성을 MP4 비디오로 렌더링합니다. 단일 HTML 장면 파일 또는 전체 Hyperframes 프로젝트 디렉터리를 허용합니다. npx hyperframes render --output <mp4>를 호출하기 전에 필수 사전 렌더링 게이트(lint → validate → inspect → render)를 실행합니다. MP4 경로와 작업 완료 보고서를 반환합니다. 플러그인 내부에서 Hyperframes 파이프라인을 재구현하지 않으며, 셸 호출만 수행합니다.

지침

  1. 두 가지 검사로 외부 저장소를 확인합니다: external/hyperframes/package.json이 존재해야 하며, npx hyperframes render --help가 응답해야 합니다. 둘 중 하나라도 실패하면 즉시 중단합니다.
  2. 프로젝트 디렉터리를 확인합니다: project_dir이 제공되면 그것을 사용하고, html_scene_path가 제공되면 임시 프로젝트를 생성합니다. 둘 다 제공되지 않으면 즉시 실패합니다.
  3. 사전 렌더링 게이트 시퀀스를 순서대로 실행합니다: lint → validate → inspect → render (단계가 0이 아닌 종료 코드를 반환하면 중단).
  4. cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>를 실행하고 출력 경로를 수집합니다.
  5. MP4 파일이 존재하고 비어 있지 않은지 확인하고, 출력 경로와 inspect 경고를 보고합니다.
  6. 권위 있는 실행 단계는 아래 ## 호출 패턴 섹션을 참조하세요.

활성화

전용 슬래시 명령어가 없습니다. 이 스킬에는 일치하는 /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_pathstring (선택 사항)단일 HTML 파일의 절대 경로. 브릿지는 mktemp -d -t hf-XXXXXX (POSIX 호환)를 통해 임시 hyperframes 프로젝트 디렉터리를 생성하고, HTML을 index.html로 작성한 후 렌더링하고 보고서가 작성된 후 정리합니다.
project_dirstring (선택 사항)기존 hyperframes 프로젝트 디렉터리의 절대 경로 (index.html 및 선택적으로 compositions/, assets/ 포함). 브릿지는 바로 cd하여 이동합니다 — 스캐폴딩하지 않습니다. 하위 구성, 오디오 및 외부 자산을 지원합니다.

둘 다 제공되면 project_dir이 우선합니다. 둘 다 제공되지 않으면 즉시 실패합니다.

호출 패턴

  1. 외부 저장소 확인 — 두 가지 검사 필요:

    # 검사 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 실행"
    

    둘 중 하나라도 실패하면 즉시 중단하세요. 진행하지 마세요.

  2. 프로젝트 디렉터리 확인.

    • 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"
      
    • 그 외의 경우: 즉시 실패합니다.
  3. 사전 렌더링 게이트 시퀀스 실행: 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(개발자 루프 기본 요소)를 제거했습니다.

  1. 렌더링. 확인된 프로젝트 디렉터리 내에서:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <abs-mp4-path>
    
    필요에 따라 추가 플래그 (--fps, --quality, --format, --hdr 등) — TECH-hyperframes-cli-render 참조.

[TECH-hyperframes-cli-render.md] 기능 · 사용 시기 · 작동 방식 · 플래그 · 품질 지침 · 투명 비디오 · 최소 예제 · 작업자 튜닝 · 주의 사항 · 상호 참조

  1. 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에 있습니다. 두 가지 출력이 필수입니다:

  1. 아티팩트 — hyperframes 프로젝트 폴더 + 렌더링된 MP4. 경로는 프로젝트에서 추론됩니다 (사용자 경로 → 프레임워크 규칙 → ./design/<subtype>/ → 폴백 ./design/videos/).
  2. 작업 완료 보고서 $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 속성 구문 분석 오류, 비디오 인코딩 실패, 오래된 클론.

관련 스킬