HyperFrames
HyperFrames는 HTML → MP4 렌더러(Apache 2.0)입니다. 컴포지션은 data-start, data-duration, data-track-index 속성을 가진 일반 HTML 파일입니다. 렌더러는 헤드리스 Chrome을 타임라인에 따라 프레임 정확도로 구동하고, 프레임을 FFmpeg로 전달합니다. hyperframes-prompt-builder 스킬이 마케팅 엔진 디스패처 진입점이며, 이 스킬은 저작 규칙을 담당합니다.
호출 시점
- 라우팅(
PROVIDERS.md또는 프론트매터의provider_override.video: hyperframes통해) 결과 HyperFrames 제공자로 할당된 경우. - 작업이
motion-typography,data-viz-reel,programmatic-short이거나, 선언된 변수로부터 결정적 출력이 필요한 컴포지션(예: 새로운 숫자로 재렌더링해도 동일한 주간 KPI 릴)인 경우. - 승인된 정적 이미지(인용 카드, 캐러셀 슬라이드)를 타이포그래피 시스템 변경 없이 짧은 모션 작품으로 업그레이드해야 하는 경우.
- 오케스트레이터가 재렌더링 가능한 아티팩트(동일 컴포지션, 다른
--variables, 바이트 단위로 동일한 기준선)를 필요로 하는 경우.
입력
composition_id: 문자열. 프로젝트 디렉토리 및data-composition-id에 사용되는 짧은 슬러그.aspect:9:16|1:1|16:9|4:5.duration_seconds: 정수. 전체 컴포지션 길이.scenes: 배열. 각 항목:{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.design_tokens: 객체. 브랜드 색상, 기본/보조 서체군, 간격 척도. 존재하는 경우clients/<slug>/design.md에서 가져옵니다.variables: 배열, 선택 사항. 호출자가 렌더 시 재정의할 수 있는 선언된 매개변수:{ id, type, label, default }.assets: 객체, 선택 사항.{ video?, audio?, images[] }— 프로젝트 하위의 로컬 경로.output_dir: 문자열. 렌더러가 MP4를 기록하는 경로(기본값:outputs/<client>/<date>/<piece-id>/).
프로세스
- 먼저 브랜드 컨텍스트를 읽습니다.
clients/<active-client>/design.md(또는 전달된 디자인 토큰)를 로드합니다. 토큰을 알기 전까지 HTML 작성을 거부합니다. — 클라이언트에 디자인 파일이 없는 경우에만 저장소 기본값으로 대체합니다. - 내러티브 아크를 명시적으로 계획합니다(장면, 리듬, 트랜지션, 비트). 마크업을 작성하기 전에 수행합니다. Hook은 처음 1.5초, 본문(body), CTA는 마지막에 배치합니다.
- 애니메이션 전에 레이아웃을 먼저 작성합니다. 최종 화면 레이아웃을 먼저 작성합니다 — 요소가 최종 위치에 배치됩니다.
gsap.from()을 사용하여 해당 위치로 애니메이션합니다. 마지막 장면만gsap.to()퇴장을 사용할 수 있습니다. - HTML을 구성합니다. 루트
<html>은data-composition-id,data-width,data-height를 포함합니다. 각 클립은id,data-start,data-duration,data-track-index를 포함합니다.<html>의data-composition-variables(JSON 배열)로 매개변수화합니다. 런타임에window.__hyperframes.getVariables()로 읽습니다. - 모든 타임라인을
paused상태로 등록합니다.const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;— 프레임워크가 재생을 제어합니다. 무한 반복,Math.random(), 시간 기반 로직, 비동기 타임라인 구성은 금지됩니다. - 모든 장면 사이에 트랜지션을 적용합니다. 절단(cut)은 없습니다. 업스트림
references/transitions.md에 나열된 트랜지션(페이드, 와이프, 마스크, 셰이더)을 사용합니다. - 비디오 및 오디오.
<video>는 음소거되어야 합니다. 오디오는 별도의<audio>요소에 자체 트랙으로 존재합니다. - 로컬에서 검증합니다:
npx hyperframes lint를 실행한 후npx hyperframes inspect(텍스트 오버플로우, 컨테이너 클리핑)를 실행합니다. 두 검사가 모두 통과한 경우에만 렌더링합니다.hyperframes-cli스킬에 위임됩니다. - 매니페스트를 생성합니다. MP4 옆에
manifest.json을 작성합니다:{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }.CLAUDE.md의 완료 조건(Definition of Done)에 필요합니다.
출력
project_path: 문자열. HyperFrames 프로젝트 디렉토리 경로.composition_html: 문자열. 작성된index.html콘텐츠(또는project_path아래의 경로).render_args: 객체.npx hyperframes render에 전달할 플래그(--fps,--quality,--variables,--strict).expected_artifact: 문자열. 렌더 후output_dir아래에 생성될 MP4 경로.cost_estimate_usd: 숫자. 로컬 렌더 — 컴퓨팅 시간만; DRY_RUN인 경우 0으로 보고, 그렇지 않으면--workers× duration에서 추정.
불가침 규칙
- 모든 요소는 진입 애니메이션(
gsap.from())이 있어야 합니다. - 모든 타임라인은
paused상태로 시작하며window.__timelines에 등록됩니다. - 컴포지션 로직에
Math.random(),Date.now(), setTimeout 기반 애니메이션은 금지됩니다. - 비디오 트랙은 음소거;
<video>에 오디오를 내장하지 마십시오. - 클라이언트 카피가 변수일 수 있는 경우 마크업에 직접 포함하지 마십시오 —
data-composition-variables에 선언하여 동일한 컴포지션을 새 작품에 재렌더링할 수 있도록 합니다. outputs/아래의 렌더링된 MP4를 편집하지 마십시오. 대신hyperframes render를 다시 실행하십시오.
예제
예제 1: 주간 KPI 릴 (programmatic-short)
입력: { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
출력: outputs/<client>/<date>/kpi-weekly-w21/ 아래의 프로젝트. index.html이 두 숫자 변수를 읽고 애니메이션합니다. render_args.--variables가 각 작품에 대해 변수를 해석합니다.
예제 2: 모션 인용 카드 (motion-typography)
입력: { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
출력: 활성 클라이언트의 타이포그래피 페어링을 준수하는 키네틱 타이포그래피 컴포지션. 마스크된 텍스트 진입과 마지막 프레임에서 부드럽게 유지됩니다.
실패 모드
design.md가 없고 디자인 토큰이 전달되지 않은 경우: 중단하고 질문합니다. 팔레트를 임의로 생성하지 마십시오.npx hyperframes lint에서 오류 보고(data-composition-id누락, 트랙 중첩, 등록되지 않은 타임라인): 수정될 때까지 렌더링 차단.npx hyperframes inspect에서 장면 텍스트 오버플로우 보고: 시스템 최소값 이하로 서체 축소보다는 레이아웃 재배치를 선호합니다.- 오디오 트랙이 컴포지션
duration_seconds보다 긴 경우: 오디오를 자르고,duration_seconds를 늘리지 마십시오. - 컴포지션이
Math.random()또는 벽시계 시간을 사용하는 경우: 선언된 변수 또는 시드 기반 결정적 생성기로 리팩터링한 후 렌더링합니다.
관련 스킬
hyperframes-cli: lint, inspect, preview, render 명령어. 저작 후 항상 호출됩니다.hyperframes-prompt-builder: 마케팅 엔진 전문 스킬. 작품 브리프를 이 스킬이 기대하는 입력 형태로 변환하며, 매트릭스가hyperframes로 확인될 때video-prompt-builder가 호출합니다.video-prompt-builder: 일반 디스패처.qa-tech-specs: 렌더링된 MP4를 플랫폼 사양(종횡비, 길이, 안전 영역)에 대해 검증합니다.compliance-<active client>: 렌더 후, 렌더링된 아티팩트와 변수에서 해석된 화면 카피에 대해 실행합니다.
업스트림 참고
전체 업스트림 스킬(컴포지션 패턴, 트랜지션 카탈로그, 오디오 반응형, 캡션, 데이터 인 모션): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes