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%に対しては、HFのシーク駆動モデルに適合しないパターンの変換を拒否し、代わりに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 設定は標準的な警告ケースです: スキルはインポートと 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 を以下の内容で出力します:
- ルート
<div id="stage">に、コンポジションのdata-composition-id、data-start="0"、data-duration(秒単位)、data-fps、data-width、data-height、およびスカラープロップごとに1つのdata-*を付与 data-start/data-duration/data-track-indexを持つシーンdivのフラットリスト- レイアウト用のインライン
<style>。CSSはすべてのアニメーションプロパティのfrom状態を設定 - 下部に1つの
<script>タグ。その中に1つのポーズされたgsap.timeline({paused: true})を含む。すべてのRemotionuseCurrentFrame()派生は、このタイムライン上の適切なオフセットでのトゥイーンになります window.__timelines["<composition-id>"] = tl;でタイムラインをHFランタイムに登録
カスタムReactサブコンポーネントは、プロップインターフェースをテンプレートとして使用して、インラインで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") を設定してください — そうしないと、差分は変換の忠実度ではなくエンコーダーの違い(SSIMで約0.05の低下)を測定します。
ステップ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.974 | 0.95 |
| T2 | マルチシーン + スプリング + オーディオ + 画像 | 0.985 | 0.95 |
| T3 | データ駆動、カスタムサブコンポーネント、カウントアップ | 0.953 | 0.90 |
| T4 | エスケープハッチ(8リントケース) | 8/8合格 | n/a |