Communitygithub.com

samyakiasonline-ctrl/hyperframe

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

hyperframe란 무엇인가요?

이 스킬은 Remotion(React 기반) 비디오 컴포지션을 HyperFrames(HTML + GSAP) 컴포지션으로 변환하는 전문 번역기입니다. 대부분의 Remotion 관용구는 HyperFrames에 직접적인 대응 관계가 있어 일반적인 컴포지션의 약 80%를 기계적으로 번역할 수 있습니다. 이 스킬은 변환 매핑을 인코딩하고, HyperFrames의 seek 기반 모델에 맞지 않는 패턴(refuse + recommend interop)은 거부하고, PR #214의 런타임 인터롭 패턴을 권장함으로써 손실이 발생할 수 있는 나머지 20%를 방어합니다. 계층화된 테스트 코퍼스(T1–T4, 총 4개 픽스처)를 통해 번역 결과를 측정된 SSIM 임계값과 비교하여 평가하며, 변환을 수행하기 전에 반드시 평가를 실행해야 합니다. Claude Code, Cursor 등 AI 에이전트에서 Remotion → HyperFrames 마이그레이션을 자동화하는 데 사용됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/remotion-to-hyperframes

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

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

문서

플러그인 설치: 설정 또는 최신 상태 유지 명령 전에, 이 스킬이 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, async 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을 실행하세요. 검색에는 설치된 것이 전혀 필요하지 않습니다: 프로젝트 없음, 사전 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}). 모든 Remotion useCurrentFrame() 파생 값은 해당 장면 내 오프셋에서 타임라인의 트윈이 됩니다.
  • 각 장면 파일에 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.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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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`.

samyakiasonline-ctrl/hyperframe

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, history, clean, 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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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`.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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).

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and 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`.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

관련 스킬