remotion-to-hyperframes

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) ユーザーが、似た Remotion 動画を持っている、または A/B テストしている場合でも、新しい HyperFrames コンポジションを作成している。
• (b) ユーザーが移行を依頼せずに、会話の中で Remotion に言及している。
• (c) ユーザーが変換を依頼せず、参考資料として Remotion コードを共有している。
• (d) ユーザーが移行元の変更を明示的に依頼せず、「自分の Remotion の動画と同じ動画」を求めている。この場合は、新規の HyperFrames 制作として扱ってください。

判断に迷う場合は、代わりに 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。

ブロッカーが 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 ../hf-src && npx hyperframes render --output ../hf.mp4

# SSIM diff
../../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 のランタイム相互運用パターンです。このスキルの 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	エスケープハッチ（lint ケース 8 件）	8/8 合格	該当なし