Remotion → HyperFrames 変換スキル は何をしますか?
概要
Remotion(Reactベース)動画コンポジションをHyperFrames(HTML + GSAP)コンポジションに翻訳します。ほとんどのRemotionイディオムには直接的なHyperFramesの同等機能が存在し、典型的なコンポジションの約80%は機械的に翻訳可能です。このスキルはそのマッピングをエンコードし、HFのシーク駆動モデルに適合しないパターンの翻訳を拒否し、代わりにPR #214のランタイム相互運用パターンを推奨することで、損失の大きい残り20%を防ぎます。
このスキルには階層化テストコーパス(T1〜T4、合計4フィクスチャ)が付属しており、翻訳を測定されたSSIM閾値に対して評価します。evalを実行せずに翻訳しないでください — 「見た目は正しい」が、検証済みベースラインより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スキルを使用してネイティブな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 |
すべてを一度に読み込まず、特定のソースに必要なものだけを読み込んでください。
ステップ3: HFコンポジションの生成
index.htmlを出力します:
- ルート
<div id="stage">には、コンポジションのdata-composition-id、data-start="0"、data-duration(秒)、data-fps、data-width、data-height、およびスカラープロップごとに1つのdata-*属性を持たせます。 - シーンdivのフラットリストに
data-start/data-duration/data-track-index属性を持たせます。 - レイアウト用のインライン
<style>(CSSはすべてのアニメーションプロパティのfrom状態を設定) - 最後に1つの
<script>タグで、一時停止状態のgsap.timeline({paused: true})を含めます。すべてのRemotionuseCurrentFrame()の派生は、このタイムライン上の適切なオフセットでのトゥイーンになります。 window.__timelines["<composition-id>"] = tl;でタイムラインをHFのランタイムに登録します。
カスタムReactサブコンポーネントは、プロップインターフェースをテンプレートとして使用して、インラインで繰り返しHTMLとして展開します(インスタンスごとのdata-*パターンについてはparameters.mdを参照)。
ステップ4: 検証
evalハーネスを実行します — 完全なガイドはreferences/eval.mdを参照。クイックパス:
# Remotionベースラインのレンダリング(フィクスチャ内でnpm install後)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# HF翻訳のレンダリング
cd ../hf-src && npx hyperframes render --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 合格 | 該当なし |