Communitygithub.com

Remotion → HyperFrames 포팅

기존 Remotion (React) 컴포지션의 소스 코드를 HyperFrames HTML로 포팅합니다. 명시적인 포팅/변환/마이그레이션 요청이 있을 때만 사용하세요. 단방향, Remotion 전용입니다. 단순한 언급, 참조 코드, 또는 'Remotion 비디오처럼 만들어 줘'는 새로운 빌드(/general-video)로 처리합니다. 불확실한 경우 → /hyperframes.

Remotion → HyperFrames 포팅란 무엇인가요?

이 스킬은 기존 Remotion (React 기반) 비디오 컴포지션을 HyperFrames (HTML + GSAP) 컴포지션으로 정확하게 변환하는 방법을 제공합니다. 대부분의 Remotion API는 HyperFrames에서 직접적으로 대응되며, 변환은 일반적인 컴포지션의 약 80%에 대해 기계적으로 수행됩니다. 나머지 20%는 HyperFrames의 seek 기반 모델에 맞지 않는 패턴(예: React state machine 기반 애니메이션, useEffect에 의존하는 비결정적 동작)을 거부하고, 대신 PR #214의 런타임 인터롭 패턴을 권장합니다. 이 스킬은 CLI 도구(예: `npx hyperframes`)와 함께 작동하며, Remotion 소스 린트, API 맵을 통한 변환 계획 수립, `index.html` 및 서브 컴포지션 생성, 그리고 SSIM 기반의 정량적 검증(render_diff.sh 스크립트)을 포함한 5단계 워크플로우를 통해 변환의 정확성을 보장합니다. Claude Code, Cursor, Codex, GitHub Copilot 등 다양한 AI 에이전트 플랫폼에서 사용 가능하도록 설계되었습니다. 변환할 수 없는 요소는 `TRANSLATION_NOTES.md`에 기록하여 투명성을 유지합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/remotion-to-hyperframes

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

먼저, 이 스킬을 최신 상태로 유지하세요 — 실행 전에 사용자에게 확인: npx hyperframes skills update remotion-to-hyperframes. 모든 것이 최신 상태이면 빠르게 아무 작업도 하지 않습니다. 그렇지 않으면 이 스킬과 이 스킬이 의존하는 핵심 도메인 스킬을 새로 고칩니다.

Remotion → HyperFrames

진입점은 /hyperframes입니다. 이 스킬은 기존 Remotion (React) 컴포지션의 소스 코드를 HyperFrames로 단방향 포팅하는 경우에만 사용합니다. 새로운 컴포지션 작성, Remotion이 아닌 소스(After Effects, Framer Motion, 일반 React/CSS — 번역할 Remotion 소스가 없음)에서 재생성, 단순한 Remotion 언급, 또는 불확실한 경우 → 먼저 /hyperframes를 읽으세요: 의도 레이어가 모든 경로 결정을 담당합니다.

개요

Remotion (React 기반) 비디오 컴포지션을 HyperFrames (HTML + GSAP) 컴포지션으로 변환합니다. 대부분의 Remotion 관용구는 HyperFrames에 직접적으로 대응되며, 일반적인 컴포지션의 약 80%에 대해 변환은 기계적으로 수행됩니다. 이 스킬은 매핑을 인코딩하고, HyperFrames의 seek 기반 모델에 맞지 않는 패턴을 변환하지 않음으로써 손실되는 20%를 방어하며, 대신 PR #214의 런타임 인터롭 패턴을 권장합니다.

이 스킬은 계층화된 테스트 코퍼스(T1–T4, 총 4개의 fixture)와 함께 제공되며, 측정된 SSIM 임계값에 대해 변환을 평가합니다. 변환을 실행하기 전에 반드시 평가를 실행하세요 — "눈에 맞게" 보이지만 검증된 기준보다 0.05 SSIM만큼 낮게 렌더링되는 변환은 조용히 잘못된 것입니다.

사용 시기

사용자가 명시적으로 Remotion에서 마이그레이션을 요청할 때만 이 스킬을 사용하세요. 예시 트리거 문구:

  • "내 Remotion 프로젝트를 HyperFrames로 포트해 줘"
  • "이 Remotion 코드를 HyperFrames로 변환해 줘"
  • "Remotion에서 마이그레이션"
  • "이 Remotion 컴포지션을 번역해 줘"
  • "이걸 HyperFrames HTML로 다시 작성해 줘"

다음과 같은 경우에는 이 스킬을 사용하지 마세요:

  • (가) 사용자가 유사한 Remotion 비디오를 가지고 있거나 A/B 테스트 중이더라도 새로운 HyperFrames 컴포지션을 작성하는 경우.
  • (나) 사용자가 마이그레이션을 요청하지 않고 Remotion을 단순히 언급하는 경우.
  • (다) 사용자가 변환을 요청하지 않고 Remotion 코드를 참조 자료로 공유하는 경우.
  • (라) 사용자가 "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와 이에 해당하는 HF 항목 또는 주제별 참조의 인덱스입니다. 소스에서 사용하는 내용에 따라 필요한 주제 참조를 식별하세요:

소스에 포함된 내용로드할 참조
Composition, defaultProps, schema, calculateMetadataparameters.md
Sequence, Series, Loop, AbsoluteFill, Freezesequencing.md
useCurrentFrame, interpolate, spring, Easing, interpolateColorstiming.md
Audio, Video, Img, IFrame, staticFile, delayRendermedia.md
TransitionSeries, @remotion/transitionstransitions.md
@remotion/lottielottie.md
@remotion/google-fonts/<Family>, Font.loadFont, @font-facefonts.md

모든 것을 로드하지 마세요 — 특정 소스에 필요한 것만 로드하세요.

표에 매핑되지 않은 시각적 효과가 있는 경우 라이브 카탈로그를 검색하세요. 소스가 HF API에 해당하는 항목이 없는 룩(스캔라인/CRT 오버레이, 글리치 또는 색수차 패스, 셰이더 와이프, 필름 그레인 처리)을 그리는 경우, GSAP으로 직접 작성하기 전에 npx hyperframes catalog --query "<효과를 평범한 영어로>" --json을 실행하세요. 검색에는 아무것도 설치할 필요가 없습니다: 프로젝트, 사전 추가, 계정이 필요 없습니다. 모든 디렉토리에서 호스팅된 전체 레지스트리(~400개의 블록 및 컴포넌트)를 순위화하며, transitions.md는 이미 npx hyperframes add sdf-iris를 통해 clockWipe() / 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}). 모든 Remotion useCurrentFrame() 파생은 해당 타임라인에서 장면 내 오프셋의 트윈이 됩니다.
  • 각 장면 파일에 window.__timelines["<scene-id>"] = tl;, 그리고 루트 자체의 (비어 있을 수 있는) 타임라인에 대한 window.__timelines["<composition-id>"].

사용자 정의 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 --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의 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.9740.95
T2다중 장면 + spring + 오디오 + 이미지0.9850.95
T3데이터 기반, 사용자 정의 서브 컴포넌트, 카운트업0.9530.90
T4이스케이프 해치 (8개의 린트 케이스)8/8 통과해당 없음

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

1999AZZAR/designer-mcp

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

1999AZZAR/designer-mcp

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

1999AZZAR/designer-mcp

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

1999AZZAR/designer-mcp

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

1999AZZAR/designer-mcp

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

1999AZZAR/designer-mcp

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1999AZZAR/designer-mcp

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1999AZZAR/designer-mcp

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

1999AZZAR/designer-mcp

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1999AZZAR/designer-mcp

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

1999AZZAR/designer-mcp

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

1999AZZAR/designer-mcp

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

1999AZZAR/designer-mcp

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

1999AZZAR/designer-mcp

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

관련 스킬