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 を実行します。lint は、クリーンに翻訳できないパターンを検出します:
- ブロッカー(拒否 + 相互運用を推奨):
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、およびスカラー prop ごとに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 サブコンポーネントは、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") を設定してください。そうしないと、差分は翻訳の忠実度ではなくエンコーダの違い(約0.05 SSIM ヒット)を測定することになります。
ステップ 5: ギャップを文書化する
クリーンに翻訳されなかったもの(ドロップされたボリュームランプ、近似されたカスタムプレゼンテーション、代替されたフォント)は、HF 出力の隣に TRANSLATION_NOTES.md を書き込みます。形式については references/limitations.md を参照してください。
このスキルが明示的に行わないこと
- React ステートマシンを翻訳しません。
useState+useEffectを介してアニメーションを駆動するコンポジションは、HyperFrames のシーク駆動モデルにおける決定論的なフレームキャプチャターゲットではありません。ランタイム相互運用パターンを推奨してください。 - Remotion のレンダリングパイプラインを HyperFrames と並行して実行しません。 それは PR #214 のランタイム相互運用パターンであり、このスキルの lint に失敗するコンポジションに対する別のソリューションです。
(@remotion/lambda はブロッカーではありません。Lambda 設定はデプロイメントであり、アニメーションではありません。スキルはそれを警告として削除し、残りを翻訳します。references/escape-hatch.md を参照してください。)
自分の翻訳をグレード付けする方法
テストコーパスオーケストレーターを実行します:
./assets/test-corpus/run.sh
T1、T2、T3(レンダリング + 差分)および T4(lint 検証)を実行し、ティアごとの合格/不合格テーブルを出力し、集約 JSON レポートを生成します。これを使用して、クリーンチェックアウトでスキルがエンドツーエンドで動作することを確認し、リファレンスを編集した後の回帰チェックとしても使用します。
検証済みベースライン(2026-04-27 現在):
| ティア | コンポジション形状 | 平均 SSIM | 閾値 |
|---|---|---|---|
| T1 | 単一要素フェードイン | 0.974 | 0.95 |
| T2 | マルチシーン + spring + オーディオ + 画像 | 0.985 | 0.95 |
| T3 | データ駆動、カスタムサブコンポーネント、カウントアップ | 0.953 | 0.90 |
| T4 | エスケープハッチ(8 つの lint ケース) | 8/8 合格 | n/a |