Remotion → HyperFrames
개요
Remotion(React 기반) 비디오 구성을 HyperFrames(HTML + GSAP) 구성으로 변환합니다. 대부분의 Remotion 표현식은 직접적인 HyperFrames 대응 항목이 있습니다. 일반적인 구성의 약 80%는 기계적으로 번역됩니다. 이 스킬은 이러한 매핑을 인코딩하고, HF의 seek 기반 모델에 부합하지 않는 패턴을 번역하지 않음으로써 손실이 발생하는 20%를 방지하며, 대신 PR #214의 런타임 인터롭 패턴을 권장합니다.
이 스킬은 계층화된 테스트 코퍼스(T1–T4, 총 4개의 fixture)와 함께 제공되며, 측정된 SSIM 임계값에 대해 번역을 평가합니다. 평가를 실행하지 않고 번역하지 마십시오. "올바르게 보이는" 번역이라도 검증된 기준선보다 SSIM이 0.05 낮으면 조용히 잘못된 것입니다.
사용 시기
사용자가 명시적으로 Remotion에서 마이그레이션을 요청한 경우에만 이 스킬을 사용하세요. 예시 트리거 문구:
- "내 Remotion 프로젝트를 HyperFrames로 포팅해줘"
- "이 Remotion 코드를 HyperFrames로 변환해줘"
- "Remotion에서 마이그레이션해줘"
- "이 Remotion 구성을 번역해줘"
- "이것을 HyperFrames HTML로 재작성해줘"
다음 경우에는 이 스킬을 사용하지 마세요:
- (a) 사용자가 유사한 Remotion 비디오를 가지고 있거나 A/B 테스트 중이더라도 새로운 HyperFrames 구성을 작성하는 경우.
- (b) 사용자가 마이그레이션을 요청하지 않고 Remotion을 우연히 언급하는 경우.
- (c) 사용자가 번역을 요청하는 것이 아니라 참고 자료로 Remotion 코드를 공유하는 경우.
- (d) 사용자가 소스 마이그레이션을 명시적으로 요청하지 않고 "내 Remotion 비디오와 동일한 비디오"를 요청하는 경우 — 이는 새로운 HyperFrames 빌드로 처리합니다.
의심스러울 경우 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 |
모든 것을 로드하지 마십시오. 특정 소스에 필요한 것만 로드하십시오.
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가 있는 scene 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 기준선 렌더링 (fixture에서 npm install 후)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# HF 번역 렌더링
cd ../hf-src && npx hyperframes render --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의 seek 기반 모델에서 결정론적 프레임 캡처 대상이 아닙니다. 런타임 인터롭 패턴을 권장합니다. - HyperFrames와 함께 Remotion의 렌더 파이프라인 실행. 이것은 이 스킬의 린트에 실패하는 구성을 위한 별도의 솔루션인 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 | 다중 장면 + spring + 오디오 + 이미지 | 0.985 | 0.95 |
| T3 | 데이터 기반, 사용자 정의 하위 구성, 카운트업 | 0.953 | 0.90 |
| T4 | 이스케이프 해치(8개 린트 사례) | 8/8 통과 | 해당 없음 |