HyperFrames Keyframes은(는) 무엇을 하나요?
키프레임은 포즈 계약(pose contract)입니다: 가시적인 상태, 연속적인 피사체 정체성, seek-safe 런타임, 검증된 픽셀.
광범위한 씬 레시피에는 hyperframes-animation을 사용하세요. 전체 명령어 문서에는 hyperframes-cli를 사용하세요. 시각적 스타일이 아닌 구현 메커니즘을 선택할 때만 references/keyframe-patterns.md를 사용하세요.
창작자 편집 경계
키프레임은 시각적 모션을 소유하며, 클립 어셈블리는 소유하지 않습니다. 소스-범위 하드 컷, 트림, 스플라이스, 재정렬은 /hyperframes-core에 속합니다: 유지된 범위당 하나의 미디어 요소를 작성하고, data-start와 data-duration으로 배치하며, data-media-start로 소스 오프셋을 선택합니다. 인접한 범위는 하드 컷을 만듭니다. 크로스페이드는 다른 트랙의 오버랩되는 클립과 시각적 불투명도 키프레임을 사용합니다; 사운드 페이드는 /hyperframes-audio를 사용합니다.
| 창작자 요청 | 실제 메커니즘 |
|---|---|
| 펀치-인 / 펀치-아웃 | 클립 내부의 비-시간적 시각적/크롭 래퍼에서 x/y 또는 백분율 변환을 사용한 키프레임 scale. 하드 펀치에는 set/숏 트윈을, 부드러운 무브에는 트윈을 사용하세요. |
| 부드러운 다중 상태 확대/축소 또는 재프레이밍 | 하나의 피사체 래퍼를 유지하고 여러 확대/축소/재프레이밍 상태를 세그먼트별 이징이 있는 포즈 사다리(pose ladder)로 작성합니다. |
| 팬, 재프레이밍 또는 Ken Burns 카메라 무브 | 래퍼 변환에 스케일을 더해 애니메이션합니다. 지오메트리가 작성됩니다; 이것은 얼굴 추적 또는 자동 의미론적 재프레이밍이 아닙니다. |
| 체인 카메라 무브 | 하나의 등록된 seek-safe 타임라인에 레이블이 지정된 변환 비트를 체인합니다. |
| 매치 컷 또는 휩 팬 | /hyperframes-animation이 시각적 핸드오프를 소유합니다; /hyperframes-registry가 프리미티브를 제공합니다; 키프레임은 작성된 지오메트리, 방향, 속도를 보존합니다. 자동 매칭-프레임 발견은 없습니다. |
| 크롭 및 마스크 재프레이밍 | 소스 시간을 변경하지 않고 크롭/재프레이밍하기 위해 내부 시각적 래퍼에서 clip-path 또는 마스크를 보간합니다. 폴리곤 키프레임이 폴리곤/마스크 전환을 형성할 수 있습니다. |
| 방향성 와이프 컷 또는 아이리스/리빌 컷 | 오버랩되는 시각적 클립 경계를 가로질러 마스크/클립 경계를 애니메이션합니다; /hyperframes-animation이 핸드오프 안무를 소유합니다. |
| 분할 화면 핸드오프 | 두 시각적 클립을 코어가 배치한 상태로 유지한 다음, 내부 크롭/마스크 래퍼와 분할선 지오메트리를 키프레임합니다. |
| 일정한 소스 리타임 | /hyperframes-core가 렌더-세이프 픽처와 피치-보존 사운드를 위해 정규화된 data-playback-rate (0.1..10)을 소유합니다. 전체 미디어 요소에 대해 일정합니다. |
| 소스 속도 램프 | <video>/<audio>의 data-automation에 있는 rate 레인 (클립 초 단위 t, v 0.1..10, 로그 보간); 일정한 속도보다 우선합니다. |
| 프리즈 / 홀드 | 시각적 포즈, 최종 소스 프레임, 또는 완성된 하위-컴포지션이 홀드될 수 있습니다. 임의의 중간-소스 프리즈는 지원되지 않습니다; 스틸/파생 세그먼트를 전처리하여 자체 클립으로 배치한 다음, 다른 소스 범위로 재개합니다. |
화면과 사운드를 함께 편집할 때는 /hyperframes-core, 이 스킬(시각적 모션), 그리고 배치된 트랙의 페이드, 크로스페이드, 볼륨 자동화, 덕킹/카빙 또는 효과를 위한 /hyperframes-audio를 로드합니다.
시각적 전환 또는 크롭 처리 방식은 시간적 소스 트림 또는 스플라이스가 아닙니다. /hyperframes-core가 타임라인, 클립 타이밍, 소스 범위를 소유합니다; 키프레임은 해당 클립 내부의 래퍼에서 가시적인 핸드오프 또는 크롭만 애니메이션합니다. 복사 가능한 결합 화면/사운드 레시피는 /hyperframes-core → references/creator-editing-recipes.md를 사용하세요.
절차
- 애니메이션 대상, 가시적인 상태, 최종 상태 및 런타임을 식별합니다.
- 프롬프트를 증명하는 가장 작은 메커니즘을 선택합니다. 메커니즘이 명확하지 않은 경우에만
references/keyframe-patterns.md를 읽습니다. - 선언된 런타임 내에서 seek-safe 키프레임을 작성합니다. 동기적으로 빌드하고 런타임 인스턴스를 등록합니다.
hyperframes lint,hyperframes check,hyperframes keyframes, 하나의 포커스된--shot, 그리고 증명 시점의 스냅샷으로 검증합니다.- 증명에 실패하면 소스 키프레임을 수정하고 렌더링하기 전에 가장 작은 실패 진단을 다시 실행합니다.
계약
- 움직이는 대상을 명명합니다.
- 의도된 모션을 증명하는 데 필요한 포즈(최종 상태 포함)를 명명합니다.
- 숨겨진 헬퍼 상태가 아닌 가시적인 채널을 키프레임합니다.
- 연속성이 중요할 때 객체 정체성을 보존합니다.
- 의도된 모션이 대체 또는 용해(dissolve)인 경우에만 크로스페이드합니다.
- 읽을 수 있거나 의미 있는 상태를 충분히 오래 유지합니다.
- 최종 프레임은 애니메이션의 일부이며, 정리(cleanup)가 아닙니다.
- 요청되지 않는 한 정지 상태(rest)로 재설정하지 않습니다.
- 요청되지 않는 한 검은색으로 끝내지 않습니다.
- 스타터 씬을 편집하는 경우, 재설계를 요청하지 않는 한 레이아웃, 카피, 에셋, 색상 및 최종 상태를 보존합니다.
런타임 규칙
GSAP:
- 페이지 로드 시 동기적으로 빌드합니다.
gsap.timeline({ paused: true })을 사용합니다.window.__timelines[compositionId]로 등록합니다.- 레지스트리 키는
data-composition-id와 일치해야 합니다. - 렌더-크리티컬 모션에 대해
tl.play()를 호출하지 마십시오. - 반복 횟수를 유한하게 유지합니다.
CSS 키프레임:
- 유한한 지속 시간과 반복 횟수.
- 결정적인 지연.
animation-fill-mode: both.- 타이밍이 클립에 속하는 경우
data-start를 사용합니다.
Anime.js:
- 동기적으로 생성합니다.
autoplay: false.- 유한한 지속 시간과 루프.
- 모든 인스턴스를
window.__hfAnime에 푸시합니다.
WAAPI:
- 유한한
duration. fill: "both".- 결정적인 구성.
- 텍스트 표면에는 WAAPI가 나열되지 않습니다;
--shot으로 검증하세요 (WAAPI를 seek함).
렌더-크리티컬 모션에 절대 사용하지 마세요:
Date.now()performance.now()- 시드되지 않은
Math.random() - 호버/스크롤 트리거
- 타이머
- 비동기 생성된 타임라인
- 등록되지 않은
requestAnimationFrame - 무한 루프
GSAP 스켈레톤
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
의미론적 상태에는 레이블을 사용하세요. 체인된 지연 대신 위치 매개변수를 사용하세요. 동일한 속성을 건드리는 이후의 from()/fromTo() 트윈에 대해서는 immediateRender: false를 사용하세요.
키프레임 형식
- 배열 키프레임: 단계별 지속 시간/이징이 있는 포즈 사다리.
- 백분율 키프레임: 하나의 트윈 내 정확한 타이밍.
- 속성 배열: 간결한 다중 중지 변경.
- 각 중지가 자체 이징을 가질 때 부모에
ease: "none". - 모든 세그먼트가 동일한 느낌을 공유해야 할 때
easeEach.
예제에서 숫자 거리나 타이밍을 복사하지 마십시오. 실제 컴포지션 지오메트리와 지속 시간에서 파생하세요.
두 상자 사이를 이동하는 하나의 대상에 대해서는 하나의 연속 변환 트윈 또는 FLIP을 선호하세요. 뷰어가 별개의 비트를 느껴야 할 때만 x/y/scale을 여러 개의 이징된 키프레임으로 분할하세요; 모든 세그먼트가 속도를 변경하며 덜컥거림(hitch)으로 읽힐 수 있습니다.
채널
컴포지터/시각적 채널 선호: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, 마스크, CSS 변수, SVG 패스/대시 값, 카메라 변환, 셰이더 유니폼.
레이아웃/수명 주기 채널 회피: top/left/right/bottom, width/height, margin/padding, display, visibility, 늦은 DOM 생성, 대상 모션을 수행하는 헬퍼 오버레이.
가시성 변경에는 등록된 seek 가능한 GSAP 타임라인의 autoAlpha 또는 명시적 경계에서의 지속 시간이 0인 tl.set()을 사용하세요. 클립이 아닌 요소 또는 클립 내부의 래퍼만 타겟팅하세요; .clip 자체는 절대 타겟팅하지 마세요. 절대 지속 시간을 가진 원시 visibility를 트윈하지 말고, display를 절대 트윈하지 마세요.
메커니즘 선택
프롬프트를 증명하는 가장 작은 메커니즘을 선택하세요:
| 필요 | 메커니즘 |
|---|---|
| 동일 대상이 박스나 계층을 변경함 | 공유 요소 / FLIP |
| 대상이 보이는 경로를 따라 이동함 | 경로 이동 |
| 획이 자라거나 따라 그림 | 획 그리기 |
| 한 도형이 다른 도형이 됨 | 도형 보간 |
| 리빌 경계가 보임 | 클립, 마스크 또는 셰이더 유니폼 |
| 많은 항목이 순서대로 움직임 | 스태거 / 인덱스 지연 |
| 텍스트 자체가 움직임 | 라인, 단어, 문자 또는 밴드 세분화 |
| 표면이 구부러지거나 늘어나거나 크롭됨 | 부모/자식 카운터-변환 |
| UI에 상태가 있음 | 명시적 상태 머신 |
| 씬에 깊이가 있음 | DOM 3D, Three.js 또는 WebGL 카메라/객체 키프레임 |
메커니즘은 결합될 수 있지만, 각각은 아이디어를 명확히 해야 합니다. 장식은 증명이 아닙니다.
타이밍
- 원인이나 방향을 명확히 할 때만 예측(anticipation).
- 가속은 정지 상태에서 시작합니다.
- 최고 증명(peak proof)은 메커니즘을 틀림없이 보여줍니다.
- 후속 동작(follow-through)은 에너지와 방향을 전달합니다.
- 대상이 탄력적이거나 촉각적으로 느껴져야 할 때만 오버슈트.
- 일정한 속도의 경로 이동은 일반적으로
ease: "none"이 필요합니다. - 이산적인 UI 상태는 일반적으로 날카로운 이즈-아웃이 필요합니다.
- 반복되는 요소는 동일한 타이밍이 아닌 정렬된 오프셋이 필요합니다.
- 최종 고정(lockup)은 전환 포즈보다 더 긴 홀드가 필요합니다.
- 부드러움은 동일한 대상에서 연속적인 속도를 의미합니다.
- 의도적이고 검증된 경우가 아니라면 동일한 변환 속성을 쓰는 트윈을 겹치지 마십시오.
- 동일한 히어로 표면이 확장되거나 이동하는 동안 큰
clip-path/마스크 변경을 애니메이션하지 마십시오; 주요 이동이 안정된 후 중첩된 리빌을 사용하세요.
텍스트
라인 박스, 단어 간격, 가독성 및 최종 맞춤(fit)을 보존하세요. 텍스트가 내부적으로 이동하는 경우, 텍스트 주변의 장식이 아닌 글리프 또는 마스킹된 밴드를 이동하세요. 읽을 수 있는 프레임을 스냅샷하세요.
SVG
획 성장에는 DrawSVGPlugin을 선호하고, 그 다음으로 stroke-dasharray/stroke-dashoffset을 선호합니다. 도형 보간에는 MorphSVGPlugin을 선호하세요; 필요할 때 프리미티브를 패스로 변환하고 복잡한 실루엣을 더 간단한 부분으로 분할하세요.
3D
스케일만으로는 가짜 깊이입니다. 안정적인 부모에 원근(perspective), transform-style: preserve-3d, z 이동, 회전, 카메라/월드 모션, 폐색(occlusion), 객체가 교차할 때 레이어 순서를 사용하세요.
깊이 관계를 드러내는 하나 또는 두 개의 진단 각도를 사용하세요. 각진 증명이 깊이 교차를 보여주지 않으면 z/카메라/폐색을 개선하세요.
캔버스 / WebGL
결정적 상태를 통해 카메라 위치, 카메라 대상, 객체 변환, 재질 불투명도, 셰이더 유니폼, 후처리 강도를 키프레임하세요. HyperFrames 시간에서 렌더링하세요. 마커 박스가 내부 캔버스 모션을 볼 수 없기 때문에 --ghost를 사용하세요.
CLI 증명
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
실제 애니메이션 대상에 대해 <selector>를 선택하세요. 첫 번째 프레임, 증명 포즈, 최종-마이너스-홀드, 정확한 최종에 대해 <times>를 선택하세요. 깊이가 입증되어야 할 때만 <angle>을 선택하세요.
| 도구 | 입증 내용 |
|---|---|
keyframes | 대상, 명시적 중지, 패스, 트레이스, 합성된 부모/자식 모션, CSS 중지, Anime 등록 |
--shot | 고스트, 경로 모양, 시간 간격, DOM 3D 투영, 포커스된 선택자 증명 |
--layout strip | 제자리 모션, 오버랩, 접촉, 미묘한 스케일/불투명도, 텍스트 웨이브 |
--ghost | 캔버스, WebGL, 셰이더 모션, 렌더링된 3D |
snapshot --at | 마스크, 텍스트 가독성, 전체 상태, 최종 고정, 검은색/재설정 테일 |
선택자 증명이 잘못된 것 같으면:
--json을 다시 실행하세요.- 실제 애니메이션 대상을 찾으세요.
- 해당 대상을 촬영하세요.
- 전체 프레임을 스냅샷하세요.
- 로그보다 페인팅된 픽셀을 신뢰하세요.
진단 읽기
flat은 명시적인 중간 포즈가 없음을 의미합니다. keyframes는 명시적인 중지가 있음을 의미합니다. `m