remotion-to-framevideo

Remotion から FrameVideo への移行

概要

Remotion（React ベース）の動画コンポジションを FrameVideo（HTML + GSAP）のコンポジションに変換します。Remotion の一般的なイディオムのほとんどには FrameVideo で直接対応する方法があり、一般的なコンポジションの約 80％は機械的に変換できます。このスキルでは対応関係を定義し、損失につながる残りの 20％に対処するため、HF のシーク駆動型モデルに適合しないパターンは変換せず、代わりに PR #214 のランタイム相互運用パターンを推奨します。

このスキルには、SSIM の実測しきい値に基づいて変換を評価する段階的なテストコーパス（T1～T4、合計 4 つのフィクスチャ）が含まれています。評価を実行せずに変換しないでください。「見た目は正しい」変換でも、検証済みベースラインより SSIM が 0.05 低ければ、気付かないまま誤った結果になります。

使用する場面

ユーザーが Remotion からの移行を明示的に依頼した場合にのみ、このスキルを使用してください。 該当する依頼の例：

• 「Remotion プロジェクトを FrameVideo に移植して」
• 「この Remotion コードを FrameVideo に変換して」
• 「Remotion から移行して」
• 「この Remotion コンポジションを変換して」
• 「これを FrameVideo の HTML に書き換えて」

次の場合は、このスキルを使用しないでください。

• (a) 類似した Remotion 動画を持っている、または A/B テストしている場合でも、ユーザーが新しい FrameVideo コンポジションを作成している。
• (b) ユーザーが移行を依頼せずに、Remotion に言及しているだけである。
• (c) ユーザーが変換を依頼するのではなく、参考資料として Remotion コードを共有している。
• (d) ユーザーがソースの移行を明示的に依頼せず、「Remotion の動画と同じ動画」を求めている。その場合は新規の FrameVideo 制作として扱ってください。

判断に迷った場合は、代わりに framevideo スキルを使って、FrameVideo ネイティブのコンポジションを作成してください。

ワークフロー

ステップ 1：ソースを lint する

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。

ブロッカーが 1 つでも検出された場合は、そこで停止してください。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 を持ち、スカラーの各プロパティに対応する data-* を 1 つずつ備えたルート <div id="stage">。
• data-start／data-duration／data-track-index を持つシーン div のフラットなリスト。
• レイアウト用のインライン <style>。CSS では、アニメーションする各プロパティの from 状態を設定します。
• 最下部に 1 つだけ配置する <script> タグ。ここに、1 つの一時停止状態の gsap.timeline({paused: true}) を含めます。Remotion の useCurrentFrame() による導出はすべて、適切なオフセットでこのタイムライン上のトゥイーンに変換します。
• window.__timelines["<composition-id>"] = tl; でタイムラインを HF のランタイムに登録します。

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

ステップ 4：検証する

評価ハーネスを実行します。詳しい手順は references/eval.md を参照してください。簡単な手順は次のとおりです。

# Render Remotion baseline (after npm install in the fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# Render HF translation
cd ../fv-src && npx framevideo render --output ../fv.mp4

# SSIM diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./fv.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 を使ってアニメーションを駆動するコンポジションは、FrameVideo のシーク駆動モデルでは決定的なフレームキャプチャの対象になりません。ランタイム相互運用パターンを推奨してください。
• FrameVideo と並行して Remotion のレンダリングパイプラインを実行しません。 これは 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	複数シーン＋スプリング＋オーディオ＋画像	0.985	0.95
T3	データ駆動、カスタムサブコンポーネント、カウントアップ	0.953	0.90
T4	エスケープハッチ（8 件の lint ケース）	8/8 合格	n/a