Remotion에서 HyperFrames로 변환
빌드 전에 경로를 확인하세요. 이 기술은 오직 기존 Remotion (React) 컴포지션의 소스 코드를 HyperFrames로 변환할 때만 사용하세요. 새로운 컴포지션을 작성하는 경우(Remotion 비디오에서 영감을 받은 경우라도) → 생성 워크플로우
/general-video를 사용하세요. 범위 외 (단방향, Remotion 전용): 역방향 내보내기(HyperFrames → Remotion 또는 다른 프레임워크)는 지원되지 않으며, 비-Remotion 소스(After Effects, Framer Motion, 일반 React/CSS)는 번역할 Remotion 소스가 없으므로/general-video를 통해 새로 만들어야 합니다. 확실하지 않거나, 단순히 Remotion을 언급한 것뿐이라면? 먼저/hyperframes문서를 읽으세요.
개요
Remotion (React 기반) 비디오 컴포지션을 HyperFrames (HTML + GSAP) 컴포지션으로 변환합니다. 대부분의 Remotion 관용구는 HyperFrames에 직접적인 대응 관계가 있어, 일반적인 컴포지션의 약 80%는 기계적으로 번역할 수 있습니다. 이 기술은 이러한 매핑을 인코딩하고, 손실이 발생할 수 있는 20%의 패턴에 대해서는 번역을 거부하고 대신 PR #214의 런타임 상호 운용 패턴을 권장합니다.
이 기술은 계층화된 테스트 말뭉치(T1–T4, 총 4개 픽스처)를 제공하며, 측정된 SSIM 임계값에 대해 번역을 평가합니다. 평가 없이 번역하지 마세요 — "괜찮아 보이는" 번역이 검증된 기준선보다 SSIM이 0.05 낮으면 조용히 오류가 있는 것입니다.
사용 시기
사용자가 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로 표현할 수 없으면 거절하세요.
의심스러운 경우, 대신 /general-video (일반 HyperFrames 작성 흐름)을 사용하여 기본 HyperFrames 컴포지션을 작성하는 것이 기본값입니다.
워크플로우
1단계: 소스 검사
Remotion 소스 디렉토리에서 scripts/lint_source.py를 실행하세요. 린터는 깔끔하게 번역할 수 없는 패턴을 감지합니다:
- 블로커 (거부 + 상호 운용 권장):
useState,useReducer,useEffect/useLayoutEffect(비어 있지 않은 의존성 배열 포함), 비동기calculateMetadata, 서드파티 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와 그에 해당하는 HyperFrames 대응 또는 주제별 참조의 색인입니다. 소스에서 사용하는 항목을 기반으로 필요한 주제 참조를 식별하세요:
| 소스에 포함된 내용 | 로드할 참조 문서 |
|---|---|
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 |
모든 문서를 로드하지 마세요 — 특정 소스에 필요한 것만 로드하세요.
3단계: HF 컴포지션 생성
다음 내용을 포함하는 index.html을 생성하세요:
- 컴포지션의
data-composition-id,data-start="0",data-duration(초 단위),data-fps,data-width,data-height, 그리고 스칼라 prop당 하나의data-*속성을 가진 루트<div id="stage">. data-start/data-duration/data-track-index속성을 가진 평평한 씬 div 목록.- 레이아웃을 위한 인라인
<style>; CSS는 모든 애니메이션 속성의from상태를 설정합니다. - 하단에 일시 중지된
gsap.timeline({paused: true})을 포함하는 하나의<script>태그. 모든 RemotionuseCurrentFrame()파생은 올바른 오프셋에서 이 타임라인의 트윈이 됩니다. window.__timelines["<composition-id>"] = tl;는 타임라인을 HF의 런타임에 등록합니다.
커스텀 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")를 설정하세요 — 그렇지 않으면 차이 비교가 인코더 차이(약 0.05 SSIM 영향)를 측정하게 되어 번역 충실도가 아닙니다.
5단계: 차이점 문서화
깔끔하게 번역되지 않은 모든 항목 (볼륨 램프 제거, 커스텀 프레젠테이션 근사화, 폰트 대체)은 HF 출력 옆에 TRANSLATION_NOTES.md 파일로 작성됩니다. 형식은 references/limitations.md를 참조하세요.
이 기술이 명시적으로 하지 않는 일
- React 상태 머신 번역.
useState+useEffect를 통해 애니메이션을 구동하는 컴포지션은 HyperFrames의 탐색 기반 모델에서 결정적 프레임 캡처 대상이 아닙니다. 런타임 상호 운용 패턴을 권장하세요. - Remotion의 렌더 파이프라인을 HyperFrames와 함께 실행. 이는 PR #214의 런타임 상호 운용 패턴에 해당합니다 — 이 기술의 린트 검사를 통과하지 못하는 컴포지션을 위한 별도의 솔루션입니다.
(@remotion/lambda는 블로커가 아닙니다 — Lambda 설정은 애니메이션이 아닌 배포와 관련된 것입니다. 이 기술은 경고로 처리하여 제거하고 나머지는 번역합니다. references/escape-hatch.md 참조.)
자신의 번역을 평가하는 방법
테스트 말뭉치 오케스트레이터를 실행하세요:
./assets/test-corpus/run.sh
T1, T2, T3 (렌더 + 차이 비교) 및 T4 (린트 검증)을 실행하고, 계층별 통과/실패 테이블을 출력하며, 집계 JSON 보고서를 생성합니다. 이를 사용하여 클린 체크아웃에서 기술이 엔드투엔드로 작동하는지 확인하고, 참조 문서를 편집한 후 회귀 테스트로 사용하세요.
검증된 기준선 (2026-04-27 기준):
| 계층 | 컴포지션 형태 | 평균 SSIM | 임계값 |
|---|---|---|---|
| T1 | 단일 요소 페이드인 | 0.974 | 0.95 |
| T2 | 다중 씬 + 스프링 + 오디오 + 이미지 | 0.985 | 0.95 |
| T3 | 데이터 기반, 커스텀 서브컴포넌트, 카운트업 | 0.953 | 0.90 |
| T4 | 이스케이프 해치 (8개 린트 케이스) | 8/8 통과 | n/a |