プラグインインストール: セットアップまたは freshness コマンドの前に、このスキルが HyperFrames プラグイン内にある場合は、プラグイン実行ルール に従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。
まず、このスキルを最新に保ってください — ユーザーに確認してから実行:
npx hyperframes skills update remotion-to-hyperframes。すべてが最新の場合は高速な no-op です。それ以外の場合は、このスキルとそれが依存するコアドメインスキルを、それらに依存する前に更新します。
Remotion → HyperFrames
正面玄関は
/hyperframesです。 既存の Remotion（React）コンポジションのソースを HyperFrames に一方向で移植する場合にのみ使用します。新しいコンポジションを作成する場合、Remotion 以外のソース（After Effects、Framer Motion、プレーンな React/CSS — 変換する Remotion ソースがありません）から再作成する場合、軽く Remotion に言及しただけの場合、または不確かな場合 → 最初に/hyperframesを読んでください。インテントレイヤーがすべてのルート決定を行います。
概要
Remotion（React ベース）の動画コンポジションを HyperFrames（HTML + GSAP）のコンポジションに変換します。ほとんどの Remotion イディオムには直接対応する HyperFrames の同等機能があり、変換は典型的なコンポジションの約 80% で機械的に行われます。このスキルは、マッピングをエンコードし、損失の大きい 20% を拒否することで保護します。HF のシーク駆動モデルに適合しないパターンは変換を拒否し、代わりに PR #214 のランタイム相互運用パターンを推奨します。
このスキルには、階層化されたテストコーパス（T1～T4、計 4 つのフィクスチャ）が付属しており、測定された SSIM 閾値に対して変換を評価します。評価を実行せずに変換しないでください — 「見た目は正しい」が、検証済みベースラインより 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: ソースを 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 |
すべてをロードせず、特定のソースが必要なものだけをロードしてください。
テーブルにマッピングされていない視覚効果については、ライブカタログを検索してください。 ソースが HF API に同等機能のない外観をペイントする場合 — スキャンライン/CRT オーバーレイ、グリッチまたは色収差パス、シェーダーワイプ、フィルムグレイン処理 — GSAP で手書きする前に、npx hyperframes catalog --query "<効果を平易な英語で>" --json を実行してください。この検索には 何もインストールする必要はありません。プロジェクト、事前の add、アカウントは不要です。任意のディレクトリからホストされているレジストリ全体（約 400 のブロックとコンポーネント）をランク付けします。transitions.md はすでに npx hyperframes add sdf-iris を介して clockWipe() / iris() にこのルートを使用しています。実際のコンポーネントは手書きの近似よりもソースに近いため、通常は SSIM を下げるのではなく上げます — ただし、ステップ 4 のレンダリング差分が依然として判定基準です。検索で適切なものが見つからなかった場合はエフェクトを手書きし、どちらの場合も代替を TRANSLATION_NOTES.md に記録してください。
ステップ 3: HF コンポジションを生成する
index.html を出力します:
- ルート
<div id="stage">には、コンポジションのdata-composition-id、data-start="0"、data-duration（秒単位）、data-fps、data-width、data-height、およびスカラープロパティごとに 1 つのdata-*を含めます。 - シーンごとに 1 つのホスト
<div>には、data-composition-src="compositions/<scene>.html"とdata-start/data-duration/data-track-indexを含めます。ルートにはネストされたレイアウトは保持しません。 - シーンごとに 1 つの
compositions/<scene>.html（<template>サブコンポジション）: レイアウト用のインライン<style>（CSS はアニメーション化されるすべてのプロパティのfrom状態を設定します）、そのマークアップ、およびシーンのローカル時間内の 1 つの一時停止されたgsap.timeline({paused: true})。すべての Remotion のuseCurrentFrame()派生は、そのタイムライン上のシーン内のオフセットでのトゥイーンになります。 - 各シーンファイルに
window.__timelines["<scene-id>"] = tl;、ルート自身の（おそらく空の）タイムライン用にwindow.__timelines["<composition-id>"]。
カスタム 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 --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 のシーク駆動モデルにおける決定論的なフレームキャプチャターゲットではありません。ランタイム相互運用パターンを推奨します。 - 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 | マルチシーン + spring + オーディオ + 画像 | 0.985 | 0.95 |
| T3 | データ駆動、カスタムサブコンポーネント、カウントアップ | 0.953 | 0.90 |
| T4 | エスケープハッチ（8 lint ケース） | 8/8 合格 | n/a |