플러그인 설치: 설정 또는 새로고침 명령 전에, 이 스킬이 HyperFrames 플러그인 내에 있을 경우 플러그인 실행 규칙을 따르세요. 독립 실행형 설치의 경우 아래 업데이트 지침을 유지합니다.
HyperFrames Keyframes
키프레임은 포즈 계약입니다: 가시적 상태, 연속적인 피사체 정체성, 탐색-안전 런타임, 검증된 픽셀.
광범위한 장면 레시피에는 hyperframes-animation을 사용하세요. 전체 명령어 문서에는 hyperframes-cli를 사용하세요. 구현 메커니즘(시각적 스타일이 아닌)을 선택할 때만 references/keyframe-patterns.md를 사용하세요.
크리에이터 편집 경계
키프레임은 시각적 움직임을 담당하고, 클립 조립은 담당하지 않습니다. 소스 범위 하드 컷, 트림, 스플라이스, 재정렬은 /hyperframes-core에 속합니다: 유지된 범위당 하나의 미디어 요소를 작성하고, data-start와 data-duration으로 배치하며, data-media-start로 소스 오프셋을 선택하세요. 인접한 범위는 하드 컷을 만듭니다. 크로스페이드는 다른 트랙의 겹치는 클립과 시각적 불투명도 키프레임을 사용하고, 사운드 페이드는 /hyperframes-audio를 사용합니다.
| 크리에이터 요청 | 진실된 메커니즘 |
|---|---|
| 펀치인 / 펀치아웃 | 클립 내 비-시간적 시각적/크롭 래퍼에서 scale과 x/y 또는 백분율 변환을 키프레임으로 지정합니다. 하드 펀치에는 set/짧은 트윈을 사용하고 부드러운 이동에는 트윈을 사용합니다. |
| 부드러운 다중 상태 줌 또는 리프레임 | 하나의 피사체 래퍼를 유지하고 여러 개의 줌/리프레임 상태를 세그먼트별 이징을 사용하는 포즈 사다리(pose ladder)로 작성합니다. |
| 팬, 리프레임, 또는 켄 번스 카메라 이동 | 래퍼 변환 + 스케일을 애니메이션합니다. 지오메트리는 작성됩니다; 이것은 얼굴 추적 또는 자동 의미론적 리프레임이 아닙니다. |
| 체인 카메라 이동 | 하나의 등록된 seek-safe 타임라인에서 레이블이 지정된 변환 비트를 연결합니다. |
| 매치 컷 또는 휩 팬 | /hyperframes-animation이 시각적 핸드오프를 담당하고, /hyperframes-registry가 프리미티브를 제공합니다; 키프레임은 작성된 지오메트리, 방향, 속도를 유지합니다. 자동 매칭 프레임 발견은 없습니다. |
| 크롭 및 마스크 리프레임 | 소스 시간을 변경하지 않고 크롭/리프레임하기 위해 내부 시각적 래퍼에서 clip-path 또는 마스크를 보간합니다. 다각형 키프레임은 다각형/마스크 전환을 형성할 수 있습니다. |
| 방향성 와이프 컷 또는 아이리스/리빌 컷 | 겹치는 시각적 클립 경계에서 마스크/클립 경계를 애니메이션합니다; /hyperframes-animation이 핸드오프 안무를 담당합니다. |
| 분할 화면 핸드오프 | core가 배치한 두 시각적 클립을 유지한 다음, 내부 크롭/마스크 래퍼와 디바이더 지오메트리를 키프레임으로 지정합니다. |
| 일정한 소스 리타임 | /hyperframes-core가 렌더-세이프 픽처와 피치-보존 사운드를 위한 정규화된 data-playback-rate (0.1..10)를 소유합니다. 전체 미디어 요소에 대해 일정합니다. |
| 소스 속도 램프 | <video>/<audio>의 data-automation에 있는 rate 레인 (클립 초 단위의 t, 0.1..10의 v, 로그 보간); 일정한 속도보다 우선합니다. |
| 프리즈 / 홀드 | 시각적 포즈, 최종 소스 프레임, 또는 완성된 하위 컴포지션은 홀드될 수 있습니다. 임의의 중간 소스 프리즈는 지원되지 않습니다; 정지/파생 세그먼트를 사전 처리하고, 자체 클립으로 배치한 후 다른 소스 범위로 재개합니다. |
화면과 사운드를 함께 편집할 때는 /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)인 경우에만 크로스페이드합니다.
- 읽을 수 있거나 의미론적 상태를 충분히 오래 유지합니다.
- 최종 프레임은 애니메이션의 일부이며, 정리가 아닙니다.
- 요청되지 않는 한 휴식 상태로 재설정하지 않습니다.
- 요청되지 않는 한 검은색으로 끝나지 않습니다.
- 시작 장면을 편집하는 경우 재설계를 요청하지 않는 한 레이아웃, 복사본, 에셋, 색상, 최종 상태를 유지합니다.
런타임 규칙
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 생성, 피사체 움직임을 수행하는 헬퍼 오버레이.
가시성 변경에는 등록된 seekable GSAP 타임라인에서 autoAlpha를 사용하거나 명시적 경계에서 지속 시간이 0인 tl.set()을 사용하세요. 클립이 아닌 요소 또는 클립 내 래퍼만 대상으로 하세요; 절대로 .clip 자체를 대상으로 하지 마세요. 절대로 원시 visibility를 지속 시간 트윈하지 말고, display를 트윈하지 마세요.
메커니즘 선택
프롬프트를 증명하는 가장 작은 메커니즘을 선택하세요:
| 필요 사항 | 메커니즘 |
|---|---|
| 동일 피사체가 박스 또는 계층 변경 | 공유 요소 / FLIP |
| 피사체가 보이는 경로 이동 | 경로 이동 |
| 선이 자라거나 따라 그림 | 선 그리기 |
| 한 형태가 다른 형태로 변함 | 형태 보간 |
| 리빌 경계가 보임 | 클립, 마스크, 또는 셰이더 유니폼 |
| 많은 항목이 순서대로 움직임 | 스태거 / 인덱스 지연 |
| 텍스트 자체가 움직임 | 줄, 단어, 문자, 또는 밴드 세분화 |
| 표면이 휘거나, 늘어나거나, 크롭됨 | 부모/자식 역변환 |
| UI에 상태가 있음 | 명시적 상태 머신 |
| 장면에 깊이가 있음 | DOM 3D, Three.js, 또는 WebGL 카메라/객체 키프레임 |
메커니즘은 결합될 수 있지만, 각각은 아이디어를 명확히 해야 합니다. 장식은 증명이 아닙니다.
타이밍
- 인과관계나 방향을 명확히 할 때만 예비 동작(anticipation)을 사용합니다.
- 가속은 정지 상태를 떠납니다.
- 피크 증명은 메커니즘을 명백하게 보여줍니다.
- 후속 동작(follow-through)은 에너지와 방향을 전달합니다.
- 피사체가 탄력적이거나 촉각적으로 느껴져야 할 때만 오버슈트를 사용합니다.
- 일정 속도 경로 이동은 일반적으로
ease: "none"이 필요합니다. - 개별 UI 상태는 일반적으로 날카로운 ease-out이 필요합니다.
- 반복 요소는 동일한 타이밍이 아닌 순서가 있는 오프셋이 필요합니다.
- 최종 잠금(lockup)은 전환 포즈보다 더 긴 유지 시간이 필요합니다.
- 부드러움은 동일한 피사체에서 연속적인 속도를 의미합니다.
- 동일한 변환 속성을 쓰는 트윈을 겹치지 않도록 합니다(의도적이고 검증된 경우 제외).
- 주요 표면이 동시에 스케일링되거나 이동하는 동안 큰
clip-path/마스크 변경을 애니메이션하지 않습니다; 주요 이동이 안정된 후 중첩된 리빌을 사용합니다.
텍스트
라인 박스, 단어 간격, 가독성, 최종 맞춤을 유지합니다. 텍스트가 내부적으로 이동하는 경우 텍스트 주변의 장식뿐만 아니라 글리프 또는 마스킹된 밴드를 이동합니다. 읽을 수 있는 프레임을 스냅샷합니다.
SVG
선 성장에는 DrawSVGPlugin을 선호하고, 그 다음으로 stroke-dasharray/stroke-dashoffset을 선호합니다. 형태 보간에는 MorphSVGPlugin을 선호합니다; 필요할 때 기본형을 경로로 변환하고 복잡한 실루엣을 더 간단한 부분으로 분할합니다.
3D
단독 스케일은 가짜 깊이입니다. 안정적인 부모의 원근, 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 | 마스크, 텍스트 가독성, 전체 상태, 최종 잠금, 검은색/재설정 꼬리 |
선택자 증명이 잘못 보이거나 부족해 보이면, 항상 키프레임 대상을 확인하고 대상 너비를 올바른 애니메이션 래퍼로 제한하세요. 줄무늬 레이아웃 증명에서 겹치는 가장자리가 누락되었거나 애니메이션된 항목이 선택자 외부에 있으면 --selector를 조정하세요. 단일 선택자로 충분하지 않으면 별도의 명령을 사용하세요. 고스트 증명에서 캔버스/WebGL 모션이 보이지 않으면 모션을 HyperFrames 시간 소스에 연결했는지 확인하세요.