플러그인 설치: 설정 또는 최신 상태 유지 명령 전에, 이 스킬이 HyperFrames 플러그인 내부에 있을 경우 plugin execution rules를 따르세요. 독립형 설치는 아래 업데이트 지침을 유지합니다.
먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자와 확인 후 실행:
npx hyperframes skills update remotion-to-hyperframes. 모든 것이 최신 상태이면 빠른 no-op이며, 그렇지 않으면 이 스킬과 해당 스킬이 의존하는 핵심 도메인 스킬을 새로 고친 후 의존합니다.
Remotion → HyperFrames
진입점은
/hyperframes입니다. 이 스킬은 기존 Remotion (React) 컴포지션의 소스를 HyperFrames로 포팅하는 용도로만 사용하세요. 단방향입니다. 새로운 컴포지션 제작, Remotion이 아닌 소스(After Effects, Framer Motion, 일반 React/CSS — 변환할 Remotion 소스가 없음)로 재창조, 단순한 Remotion 언급, 또는 불확실한 경우 → 먼저/hyperframes를 읽으세요: 의도 레이어가 모든 경로 결정을 소유합니다.
개요
Remotion (React 기반) 비디오 컴포지션을 HyperFrames (HTML + GSAP) 컴포지션으로 변환합니다. 대부분의 Remotion 관용구는 직접적인 HyperFrames 대응 관계가 있습니다 — 일반적인 컴포지션의 약 80%는 변환이 기계적으로 이루어집니다. 이 스킬은 매핑을 인코딩하고, HF의 seek 기반 모델에 맞지 않는 패턴을 변환하지 못하게 하여 손실이 발생하는 20%를 방어하며, 대신 PR #214의 런타임 인터롭 패턴을 권장합니다.
이 스킬은 계층화된 테스트 코퍼스(T1–T4, 총 4개 픽스처)와 함께 제공되며, 측정된 SSIM 임계값에 대해 번역을 평가합니다. 평가를 실행하지 않고 번역하지 마세요 — "올바르게 보이는" 번역이 검증된 기준선보다 0.05 SSIM 낮게 렌더링되면 조용히 잘못된 것입니다.
사용 시기
사용자가 명시적으로 Remotion에서 마이그레이션을 요청할 때만 이 스킬을 사용하세요. 트리거 문구 예시:
- "내 Remotion 프로젝트를 HyperFrames로 포트해 줘"
- "이 Remotion 코드를 HyperFrames로 변환해 줘"
- "Remotion에서 마이그레이션"
- "이 Remotion 컴포지션을 번역해 줘"
- "이것을 HyperFrames HTML로 다시 작성해 줘"
다음과 같은 경우에는 이 스킬을 사용하지 마세요:
- (a) 사용자가 새로운 HyperFrames 컴포지션을 제작 중인 경우, 비슷한 Remotion 비디오를 가지고 있거나 A/B 테스트 중이더라도.
- (b) 사용자가 마이그레이션을 요청하지 않고 Remotion을 언급만 하는 경우.
- (c) 사용자가 번역을 요청하지 않고 참조 자료로 Remotion 코드를 공유하는 경우.
- (d) 사용자가 소스 마이그레이션을 명시적으로 요청하지 않고 "내 Remotion 비디오와 같은 비디오"를 요청하는 경우 — 새로운 HyperFrames 빌드로 처리합니다.
지원되지 않음 (거부 — 이 스킬이 하는 일이 아닙니다):
- 역방향. HyperFrames 컴포지션을 다시 Remotion(또는 다른 프레임워크)으로 내보내는 것은 워크플로가 아닙니다 — 변환은 Remotion → HyperFrames 단방향입니다. 명확히 말씀드리세요.
- Remotion이 아닌 소스. After Effects 프로젝트(
.aep), Framer Motion / 일반 React / CSS 애니메이션 또는 다른 도구의 소스는 Remotion 컴포지션이 아닙니다 — 변환할 Remotion 소스가 없습니다./general-video를 통해 기본적으로 재생성하거나, HyperFrames가 표현할 수 없으면 거절하세요.
의심스러우면 /hyperframes로 돌아가세요; 의도 레이어가 경로를 선택합니다.
워크플로
1단계: 소스 린트
Remotion 소스 디렉토리에서 scripts/lint_source.py를 실행하세요. 린트는 깨끗하게 변환할 수 없는 패턴을 감지합니다:
- 블로커 (거부 + 인터롭 권장):
useState,useReducer, 비어 있지 않은 deps를 가진useEffect/useLayoutEffect, asynccalculateMetadata, 타사 React UI 라이브러리(MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - 경고 (구조물을 제거한 후 변환):
@remotion/lambda설정,delayRender,useCallback,useMemo, 사용자 정의 훅. - 정보 (참고 사항과 함께 변환):
staticFile,interpolateColors.
블로커가 발생하면 중단하세요. references/escape-hatch.md를 읽고 권장 메시지를 표시하세요. 경고는 변환을 중단하지 않습니다 — 3단계에서 문제가 되는 구조를 제거하고 TRANSLATION_NOTES.md에 차이를 기록하세요. @remotion/lambda 설정은 표준 경고 사례입니다: 스킬은 import + renderMediaOnLambda(...) 호출을 제거하지만 나머지 컴포지션은 변환합니다.
2단계: 변환 계획
references/api-map.md를 읽으세요 — 모든 Remotion API와 해당 HF 대응 관계 또는 주제별 참조의 색인입니다. 소스에서 사용하는 내용에 따라 필요한 주제 참조를 식별하세요:
| 소스에 포함된 내용 | 참조 로드 |
|---|---|
Composition, defaultProps, schema, calculateMetadata | parameters.md |
Sequence, Series, Loop, AbsoluteFill, Freeze | sequencing.md |
useCurrentFrame, interpolate, spring, Easing, interpolateColors | timing.md |
Audio, Video, Img, IFrame, staticFile, delayRender | media.md |
TransitionSeries, @remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>, Font.loadFont, @font-face | fonts.md |
모두 로드하지 마세요 — 특정 소스에 필요한 것만 로드하세요.
테이블에 매핑되지 않은 시각 효과가 있으면 라이브 카탈로그를 검색하세요. 소스가 HF API에 해당하는 효과가 없는 모양을 칠하는 경우 — 스캔라인/CRT 오버레이, 글리치 또는 색수차 패스, 셰이더 와이프, 필름 그레인 처리 — GSAP으로 직접 작성하기 전에 npx hyperframes catalog --query "<효과, 일반 영어로>" --json을 실행하세요. 검색에는 설치된 것이 전혀 필요하지 않습니다: 프로젝트 없음, 사전 add 없음, 계정 없음. 모든 디렉토리에서 호스팅된 전체 레지스트리(~400 블록 및 구성 요소)의 순위를 매기며, transitions.md는 이미 clockWipe() / iris()에 대해 npx hyperframes add sdf-iris를 통해 이 경로를 사용합니다. 실제 구성 요소는 수동 근사치보다 소스에 더 가깝기 때문에 일반적으로 SSIM을 낮추기보다는 높이지만, 4단계의 렌더 차이가 여전히 중재자입니다. 검색 결과에 맞는 것이 없으면 효과를 직접 작성하고, 어느 쪽이든 TRANSLATION_NOTES.md에 대체를 기록하세요.
3단계: HF 컴포지션 생성
다음과 함께 index.html을 생성하세요:
- 컴포지션의
data-composition-id,data-start="0",data-duration(초),data-fps,data-width,data-height및 스칼라 prop당 하나의data-*를 전달하는 루트<div id="stage">. data-composition-src="compositions/<scene>.html"및data-start/data-duration/data-track-index를 가진 장면당 하나의 호스트<div>. 루트에는 중첩 레이아웃이 없습니다.- 장면당 하나의
compositions/<scene>.html(<template>서브 컴포지션): 레이아웃을 위한 인라인<style>(CSS는 모든 애니메이션 속성의from상태를 설정함), 마크업, 장면 로컬 시간에 하나의 일시 중지된gsap.timeline({paused: true}). 모든 RemotionuseCurrentFrame()파생 값은 해당 장면 내 오프셋에서 타임라인의 트윈이 됩니다. - 각 장면 파일에
window.__timelines["<scene-id>"] = tl;및 루트 자체의 (비어 있을 수 있는) 타임라인에 대한window.__timelines["<composition-id>"].
사용자 정의 React 하위 구성 요소는 prop 인터페이스를 템플릿으로 사용하여 인라인 반복 HTML로 변환합니다 (인스턴스별 data-* 패턴은 parameters.md 참조).
4단계: 검증
평가 도구를 실행하세요 — 전체 가이드는 references/eval.md를 참조하세요. 빠른 경로:
# Remotion 기준 렌더링 (픽스처에서 npm install 후)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# HF 변환 렌더링
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
# SSIM 차이
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
임계값: 소스 복잡성 계층의 p05보다 약 0.02 낮음 (eval.md의 검증된 임계값 테이블 참조). 차이가 발생하면 scripts/frame_strip.sh를 실행하여 어떤 프레임이 달라졌는지 확인한 다음, 관련 타이밍/시퀀싱/미디어 참조를 다시 읽으세요.
중요: 두 렌더 모두 일치하는 픽셀 형식을 사용해야 합니다. Remotion 소스의 remotion.config.ts에서 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")를 설정하세요 — 그렇지 않으면 diff가 변환 충실도가 아닌 인코더 차이(~0.05 SSIM 손실)를 측정합니다.
5단계: 차이점 문서화
깨끗하게 변환되지 않은 모든 것 (드롭된 볼륨 램프, 근사화된 사용자 정의 프레젠테이션, 대체된 글꼴)은 HF 출력 옆에 TRANSLATION_NOTES.md로 작성됩니다. 형식은 references/limitations.md를 참조하세요.
이 스킬이 명시적으로 하지 않는 일
- React 상태 머신 변환.
useState+useEffect를 통해 애니메이션을 구동하는 컴포지션은 HyperFrames의 seek 기반 모델에서 결정적 프레임 캡처 대상이 아닙니다. 런타임 인터롭 패턴을 권장합니다. - HyperFrames와 함께 Remotion의 렌더 파이프라인 실행. 이는 PR #214의 런타임 인터롭 패턴입니다 — 이 스킬의 린트를 통과하지 못하는 컴포지션을 위한 별도 솔루션입니다.
(@remotion/lambda는 블로커가 아닙니다 — Lambda 설정은 애니메이션이 아닌 배포입니다. 스킬은 이를 경고로 제거하고 나머지를 변환합니다. references/escape-hatch.md 참조.)
자신의 번역을 평가하는 방법
테스트 코퍼스 오케스트레이터를 실행하세요:
./assets/test-corpus/run.sh
T1, T2, T3 (렌더 + diff) 및 T4 (린트 검증)을 실행하고, 계층별 통과/실패 테이블을 출력하며, 집계 JSON 보고서를 생성합니다. 이를 사용하여 깨끗한 체크아웃에서 스킬이 종단 간 작동하는지 확인하고, 참조를 편집한 후 회귀 검사로 사용하세요.
검증된 기준선 (2026-04-27 기준):
| 계층 | 컴포지션 형태 | 평균 SSIM | 임계값 |
|---|---|---|---|
| T1 | 단일 요소 페이드 인 | 0.974 | 0.95 |
| T2 | 다중 장면 + spring + 오디오 + 이미지 | 0.985 | 0.95 |
| T3 | 데이터 기반, 사용자 정의 하위 구성 요소, 카운트 업 | 0.953 | 0.90 |
| T4 | 이스케이프 해치 (8개 린트 케이스) | 8/8 통과 | 해당 없음 |