heygen-com/hyperframes

플러그인 설치: 설정 또는 새로 고침 명령을 실행하기 전에 이 스킬이 HyperFrames 플러그인 내부에 있을 경우 플러그인 실행 규칙을 따르세요. 독립형 설치는 아래 업데이트 지침을 유지합니다.

HyperFrames 코어

에이전트 함정 (먼저 읽으세요):

• transform: translate(-50%,-50%) CSS를 GSAP의 x/y로 트윈할 노드에 적용하지 말고 flex/inset으로 중앙 정렬하세요. 린트: gsap_css_transform_conflict. fromTo 또는 xPercent/yPercent를 사용하세요.
• 씬 종료 시 tl.set(..., {visibility:"hidden"})을 추가하지 마세요. 런타임은 이미 타이밍된 클립을 숨깁니다. 내부 노드의 불투명도 페이드(또는 .clip의 opacity)면 충분합니다. 캡션 하드 킬은 다른 규칙입니다.
• window.__timelines["id"]는 루트 data-composition-id와 일치해야 합니다.
• render 후 요약의 두 번째 줄을 읽으세요: beginframe vs screenshot, GPU 모드, 스테이지 타이밍. Linux에서 screenshot + software gpu는 느린 경로입니다.

HyperFrames는 HTML에서 비디오를 렌더링합니다. 컴포지션은 data-* 속성으로 타이밍을 선언하는 DOM을 가진 HTML 파일이며, 해당 애니메이션 런타임은 시크 가능하고 미디어 재생은 프레임워크가 소유합니다.

이 스킬은 기술 계약입니다 — 하나의 hyperframes 프로젝트를 구축하는 방법에 대한 것입니다. 아래 본문은 빌드 가이드입니다. 주제별 세부 정보는 references/ (인덱스 참조)에 있으며 필요할 때 읽으세요. 프로세스 문서 (브리프, 스토리보드, 리뷰, 프로덕션, 디스패치, 프레임 워커)는 /hyperframes → references/에 있습니다. 다른 관심사는 형제 도메인 스킬(hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry)에 있습니다. /hyperframes의 기능 맵에서 각 스킬이 다루는 내용을 확인할 수 있습니다.

참조

파일	읽는 목적
references/minimal-composition.md	가장 작은 렌더링 가능한 컴포지션 스켈레톤부터 시작하기
references/composition-patterns.md	모놀리식 vs 모듈식 선택; 모듈식 index.html 구조화; 서브 컴포지션 아키타입 선택
references/data-attributes.md	모든 data-* (루트 / 클립 / 서브 컴포지션 호스트 / 레거시 별칭) 조회; class="clip" 사용
references/tracks-and-clips.md	data-track-index가 제어하는 것과 제어하지 않는 것, z-index, 다른 클립을 기준으로 클립 타이밍 이해; npx hyperframes timeline으로 모든 트랙과 클립 나열
references/creator-editing-recipes.md	진실된 잘라내기/자르기/재정렬/재타이밍/고정/카메라/마스크/크로스페이드/오디오 편집 레시피와 그 한계 복사
references/sub-compositions.md	서브 컴포지션 연결 (호스트 속성, <template>, 인스턴스별 변수) 및 내부 애니메이션
references/variables-and-media.md	변수 선언; <video>/<audio> 배치, 볼륨 설정, 자르기
references/determinism-rules.md	시크 가능한 타임라인 구축; 결정론 금지 사항; 레이아웃 / 텍스트 맞춤
references/full-screen-motion.md	공유 배경으로 전체 프레임 모션 제작
references/tailwind.md	Tailwind v4 프로젝트에서 작업 (init --tailwind; 런타임 계약이 Studio의 v3와 다름)

애니메이션 런타임별 세부 정보(GSAP API, Lottie, Three.js 등)는 hyperframes-animation → adapters/<runtime>.md를 참조하세요.

컴포지션 빌드

두 가지 루트 형태 (상호 교환 불가)

• 독립형 (최상위 index.html): 루트 <div data-composition-id="…">가 <body>에 직접 위치하며 <template> 래퍼가 없습니다. 독립형 루트를 래핑하면 모든 콘텐츠가 숨겨지고 lint가 이를 거부합니다(standalone_composition_wrapped_in_template, 오류).
• 서브 컴포지션 (data-composition-src를 통해 로드됨): 루트를 <template>으로 감쌉니다. 이것이 작성해야 할 형태입니다. 로더는 일반 전체 문서도 허용하고 <body>로 대체하지만, 템플릿 형식이 예제와 도구에서 가정하는 형태입니다.

⚠ 전송 규칙: 템플릿화된 서브 컴포지션의 경우 어셈블러는 파일 자체의 <head> <style>/<script>를 삭제합니다(packages/core/src/compiler/compositionAssembly.ts의 hasTemplate 게이트). 따라서 <style>/<script>는 템플릿 내부에 배치하세요. <link>는 어떤 방식으로든 호이스트됩니다. ⚠ 호스트 ID 규칙: 호스트 슬롯, 내부 템플릿, window.__timelines["<id>"] 키에 동일한 id를 부여하세요. 다른 로컬 id도 지원되지만(어셈블러가 파일의 첫 번째 루트로 대체) 불일치는 조용히 넘어가므로, 특별한 이유가 없다면 일치시키세요.

파일 형태, 호스트 연결 및 사전 렌더링 체크리스트 → references/sub-compositions.md.

루트는 크기가 지정되어야 함 (조용한 레이아웃 버그)

독립형 루트는 width/height: 100%를 사용합니다. 캔버스 크기는 data-width/data-height입니다. 런타임은 해당 픽셀을 컴포지션 루트에 스탬프합니다. #root에 1920px/1080px을 하드코딩하지 마세요. 스켈레톤 → references/minimal-composition.md.

하나의 일시 중지된 타임라인

각 컴포지션은 window.__timelines["<id>"] (키 = 루트 data-composition-id)에 정확히 하나의 gsap.timeline({ paused: true })을 등록합니다. 비동기 콜백(document.fonts.ready) 내에서 빌드하는 것은 지원되지만, 중요한 것은 빌드 완료 후에만 등록해야 한다는 점입니다. 렌더링 길이는 타임라인 길이가 아닌 루트의 data-duration입니다: 타임라인이 더 길면 잘리고, 더 일찍 끝나면 마지막 프레임을 유지합니다. 루트 data-duration을 생략하면 길이가 대신 추론됩니다(타임라인, 미디어 윈도우 또는 어댑터). window.__timelines = window.__timelines || {}가 필요하지 않습니다. 런타임이 인라인 스크립트가 실행되기 전에 레지스트리를 생성하고 lint가 더 이상 요구하지 않습니다. 서브 타임라인을 수동으로 호스트에 중첩하지 마세요. 런타임이 등록된 자식 타임라인을 자동으로 중첩합니다. 전체 계약 (GSAP 이외의 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.

첫 번째 패스 린트 함정 (보장된 첫 번째 빌드 실패)

lint가 확실히 잡지만 이후에만 잡는 규칙들입니다. 처음부터 올바르게 작성하세요:

• CSS 초기 transform을 동일한 속성에 대한 GSAP 트윈과 절대 쌍으로 사용하지 마세요. CSS 값과 트윈의 시작이 충돌하여 lint가 gsap_css_transform_conflict로 거부합니다. gsap.fromTo(el, { x: -40 }, { x: 0 })와 같이 트윈 내부에서 초기 상태를 설정하고 CSS transform: translateX(-40px)를 사용하지 마세요.
• <video>/<audio>에 crossorigin을 절대 넣지 마세요. lint는 media_crossorigin_breaks_preview (오류)로 무조건 거부하며, canvas/WebGL/WebAudio 읽기용도 포함됩니다. 억제할 수 없습니다.
• <video data-start>에 data-start도 있는 조상을 절대 제공하지 마세요. lint는 video_nested_in_timed_element (오류)로 거부합니다. 래퍼 또는 비디오 중 하나에만 타이밍을 지정하세요. 둘 다 하지 마세요.
• 모든 <audio>에는 id가 필요합니다. lint는 media_missing_id로 거부하며, id가 없는 <audio>는 믹서가 절대 선택하지 않아 렌더링이 무음이 됩니다.
• autoAlpha 또는 visibility로 .clip을 절대 트윈하지 마세요. lint는 gsap_animates_clip_element로 거부합니다. 대신 자식을 애니메이션하세요.
• 명명된 CSS font-family는 제공된 로컬 파일에 대한 in-file @font-face가 필요합니다. 그렇지 않으면 lint가 font_family_without_font_face를 발생시킵니다.
• 서브 컴포지션 #root는 width/height: 100% (또는 inset: 0)를 사용하며, 하드코딩된 1920px/1080px을 사용하지 않습니다. 캔버스 크기는 data-width/data-height입니다.

린트 오류는 레이아웃 및 대비 감사도 비활성화합니다. check는 0 sample(s) 및 0/0 text checks를 보고하는데, 이는 깨끗한 파일처럼 보이지만 아무것도 실행되지 않았음을 의미합니다. 해당 숫자를 신뢰하기 전에 린트 오류를 먼저 해결하세요.

양보할 수 없는 규칙 (자동 게이트가 놓칠 수 있는 조용한 버그)

여기에 나열됨; 전체 근거는 연결된 참조에 있습니다. 위반하지 마세요:

• 렌더링 시간 시계 / 시드되지 않은 Math.random / 네트워크 / 입력 상태 없음; repeat: -1 없음 (유한 횟수 사용). → determinism-rules.md
• .clip 요소에서 display, visibility 또는 autoAlpha를 절대 트윈하지 마세요. 프레임워크가 클립 가시성을 소유하며, lint가 거부합니다(gsap_animates_clip_element). 대신 자식을 애니메이션하세요. → determinism-rules.md
• 본문 텍스트에 <br> 없음; 변환된 요소는 블록 레벨이면서 크기가 지정되어야 함; 펄싱 절대 장식 요소는 피크 클리어런스가 필요함. → determinism-rules.md
• <video>/<audio>는 플랫 문서 쿼리로 찾기 때문에, 프레임워크는 모든 중첩 깊이에서 이를 시크하고 디코딩합니다(서브 컴포지션 <template> 또는 래퍼 내부 포함). 하나의 하드 제한: data-start가 있는 <video>가 data-start도 있는 다른 일반 요소 내부에 있으면 lint 오류가 발생하며, 실패는 실제입니다(잘못된 소스 프레임, 클립이 슬롯 중간에 사라짐). 따라서 타이밍을 래퍼 또는 비디오 중 하나에만 지정하고 둘 다 하지 마세요. 서브 컴포지션 호스트는 예외입니다. 서브 컴포지션 내부의 미디어는 올바르게 렌더링됩니다. 다른 주의 사항은 타임라인과 관련이 있으며 배치와는 관련이 없습니다. 서브 컴포지션 타임라인은 호스트 루트 요소를 애니메이션할 수 없습니다. → variables-and-media.md
• 조립된 페이지 전체에서 모든 id를 고유하게 유지하세요(서브 컴포지션 id 앞에 컴포지션 id를 붙임, #<id>-hero). 그러면 자체 #id CSS 및 getElementById 호출이 해결됩니다. 프레임 주입은 더 이상 이에 의존하지 않습니다. 컴파일러는 모든 video[src]/audio[src]/img[src]에 문서 고유의 data-hf-render-id를 스탬프합니다. src 속성 대신 <source> 자식을 사용하는 미디어는 스탬프되지 않으므로 여전히 고유한 id가 중요합니다. → composition-patterns.md
• 컴포지션 루트의 전체 화면 채우기는 일반 렌더링에서는 괜찮습니다. 계층적 합성 경로(HDR 콘텐츠 또는 셰이더 전환을 사용하는 컴포지션)에서만 삭제되며, 엔진이 모든 컴포지션 루트를 투명하게 강제하여 아래 레이어가 보이도록 합니다. 컴포지션이 셰이더 전환이나 HDR 미디어를 사용하는 경우 전체 블리드 자식에 채우기를 넣으세요(position:absolute; inset:0). → composition-patterns.md

기존 컴포지션 편집

• 먼저 파일을 읽으세요. 관련 없는 타이밍, 트랙, ID, 변수, 미디어 경로를 보존하세요.
• 프로젝트의 타임라인(트랙, 클립, 시작, 종료, 재생되는 항목)을 알려면 index.html 및 모든 서브 컴포지션 파일을 읽는 대신 npx hyperframes timeline [--json]을 실행하세요.
• 기존 컴포지션 ID 및 타임라인 키와 일치시키세요.
• 클립 추가: 주변 클립을 고려하여 data-start/data-duration을 의도적으로 설정하세요. data-track-index는 Studio 표시 레인일 뿐 타이밍 제약 조건이 아니므로 비어 있을 필요가 없습니다.
• 루트 data-duration 이후에 끝나는 클립은 잘립니다. 동일한 편집에서 루트 data-duration을 클립의 끝까지 연장하세요(lint가 clip_ends_past_root_duration 경고).
• 모든 컴포지션 요소의 data-hidden은 미리보기와 렌더링 모두에서 요소를 숨기며 시간 창을 재정의합니다. 이는 비파괴적/되돌릴 수 있으며 Studio의 타임라인 눈 아이콘으로 토글됩니다.
• 서브 컴포지션 추가: 호스트를 연결하기 전에 내부 data-composition-id를 확인하세요.

검증

명령어 세부 사항은 hyperframes-cli 사용

• npx hyperframes check 통과 (린트, 런타임, 레이아웃, 모션, 대비에서 0건의 발견)
• 서브 컴포지션이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 실행 및 각 프레임 육안 검사
• 리뷰를 위한 npx hyperframes preview --background (사용자는 Studio의 타임라인에서 무엇이든 편집할 수 있으며 서버는 호출 명령이 종료된 후에도 유지됨)
• 사용자 승인 후에만 npx hyperframes render 실행