Communitygithub.com

Remotion から HyperFrames への変換

既存の Remotion(React)コンポジションのソースを HyperFrames (HTML) に移植します。明示的な移植/変換/移行リクエストがあった場合にのみ使用し、Remotion のみを対象とします。

Remotion から HyperFrames への変換 とは?

このスキルは、Remotion(React ベース)のビデオコンポジションを HyperFrames(HTML + GSAP)のコンポジションに機械的に変換するための専用スキルです。変換は一方向(Remotion → HyperFrames)であり、逆方向はサポートされません。スキルは、変換前にソースコードをリントし、useState や useEffect などのブロッカーを特定して、変換できないパターンに対してはランタイム相互運用パターンを推奨します。変換は段階的に行われ(ソースのリント → 計画 → HF コンポジションの生成 → 検証 → ギャップの文書化)、組み込みのテストコーパス(T1~T4)と SSIM しきい値を使用して翻訳の品質を評価します。このスキルは、Claude Code、Coder、Cursor、Codex などの AI エージェントで使用するために設計されており、明示的な Remotion 移行リクエストにのみ使用する必要があります。

対応~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。すべてが最新の場合は高速な 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 のシーク駆動モデルに適合しないパターンの変換を拒否し、代わりに PR #214 のランタイム相互運用パターンを推奨することで、損失の大きい 20% を防ぎます。

このスキルには、階層化されたテストコーパス(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 で表現できない場合は拒否してください。

疑わしい場合は、デフォルトで /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 設定は標準的な警告ケースです。スキルはインポートと 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 はすでに npx hyperframes add sdf-iris を介して clockWipe() / iris() に対してこのルートを取っています。実際のコンポーネントは手書きの近似値よりもソースに近いため、通常は SSIM を下げるのではなく上げます — ただし、ステップ 4 のレンダリング差分が依然として判断基準です。検索で適切なものが見つからなかった場合は、エフェクトを手書きし、代わりに TRANSLATION_NOTES.md に置換を記録します。

ステップ 3: HF コンポジションを生成する

index.html を以下の内容で出力します:

  • ルート <div id="stage"> は、コンポジションの data-composition-id、data-start="0"、data-duration (秒単位)、data-fps、data-width、data-height、およびスカラープロパティごとに 1 つの data-* を持ちます。
  • シーンごとに 1 つのホスト <div> で、data-composition-src="compositions/<scene>.html" と data-start / data-duration / data-track-index を持ちます。ルートはネストされたレイアウトを保持しません。
  • シーンごとに 1 つの compositions/<scene>.html(<template> サブコンポジション):レイアウト用のインライン <style>(CSS はすべてのアニメーションプロパティの from 状態を設定します)、マークアップ、およびシーンのローカル時間内の 1 つの一時停止された gsap.timeline({paused: true})。すべての Remotion useCurrentFrame() の派生は、シーン内のオフセットでそのタイムライン上のトゥイーンになります。
  • 各シーンファイル内の window.__timelines["<scene-id>"] = tl;、およびルート自身の(空の可能性がある)タイムライン用の window.__timelines["<composition-id>"]。

カスタム React サブコンポーネントは、プロップインターフェースをテンプレートとして使用して(インスタンスごとの data-* パターンについては parameters.md を参照)、繰り返し HTML としてインライン化します。

ステップ 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 のシーク駆動モデルでは決定論的なフレームキャプチャターゲットではありません。ランタイム相互運用パターンを推奨します。
  • 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マルチシーン + スプリング + オーディオ + 画像0.9850.95
T3データ駆動、カスタムサブコンポーネント、カウントアップ0.9530.90
T4エスケープハッチ(8 つのリントケース)8/8 合格n/a

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.

関連スキル