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の実行時相互運用パターンを推奨します。
このスキルには、測定されたSSIMしきい値に対して変換を評価する階層化テストコーパス(T1~T4、合計4つのフィクスチャ)が付属しています。評価を実行せずに変換しないでください。「見た目が正しい」変換でも、検証済みのベースラインより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、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、およびスカラープロップごとに1つのdata-*を持つルート<div id="stage">。 data-start/data-duration/data-track-indexを持つシーンdivのフラットリスト。- レイアウト用のインライン
<style>。CSSは、アニメーション化されたすべてのプロパティのfrom状態を設定します。 - 一番下の単一の
<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 --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のシーク駆動モデルにおける決定論的なフレームキャプチャターゲットではありません。実行時相互運用パターンを推奨します。 - RemotionのレンダリングパイプラインをHyperFramesと一緒に実行すること。 それはPR #214の実行時相互運用パターンです — このスキルのリントに失敗するコンポジションのための別のソリューションです。
(@remotion/lambdaはブロッカーではありません。Lambda設定はデプロイメントであり、アニメーションではありません。スキルはそれを警告として削除し、残りの部分を変換します。references/escape-hatch.mdを参照。)
自分の変換を評価する方法
テストコーパスオーケストレーターを実行します:
./assets/test-corpus/run.sh
T1、T2、T3(レンダリング + 差分)とT4(リント検証)を実行し、ティアごとの合格/不合格テーブルを出力し、集約JSONレポートを出力します。これを使用して、クリーンなチェックアウトでスキルがエンドツーエンドで動作していることを確認し、リファレンスを編集した後のリグレッションチェックとして使用します。
検証済みベースライン(2026年4月27日時点):
| ティア | コンポジション形状 | 平均SSIM | しきい値 |
|---|---|---|---|
| T1 | 単一要素のフェードイン | 0.974 | 0.95 |
| T2 | マルチシーン + スプリング + オーディオ + 画像 | 0.985 | 0.95 |
| T3 | データ駆動、カスタムサブコンポーネント、カウントアップ | 0.953 | 0.90 |
| T4 | エスケープハッチ(8つのリントケース) | 8/8合格 | n/a |