remotion-to-hyperframes

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 個のフィクスチャ）が付属しています。評価を実行せずに翻訳しないでください。「見た目は正しい」翻訳でも、検証済みのベースラインより 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。

ブロッカーが 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 --skill=remotion-to-hyperframes --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 合格	該当なし