Remotion → HyperFrames
概要
Remotion(Reactベース)の動画構成をHyperFrames(HTML + GSAP)構成に翻訳します。ほとんどのRemotionイディオムにはHyperFramesに直接対応するものがあり、典型的な構成の約80%は機械的に翻訳可能です。このスキルは対応マッピングをエンコードし、損失の発生する20%については、HFのシーク駆動モデルに適合しないパターンを翻訳せず、代わりにPR #214のランタイム相互運用パターンを推奨することで保護します。
このスキルには段階的テストコーパス(T1~T4、計4つのフィクスチャ)が付属しており、測定されたSSIMしきい値に対して翻訳を評価します。評価を実行せずに翻訳してはいけません。「見た目が正しい」翻訳でも、検証済みベースラインよりSSIMが0.05低い場合は、暗黙的に誤っています。
ワークフロー
ステップ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設定は標準的な警告のケースです。スキルはimport文とrenderMediaOnLambda(...)呼び出しを削除しつつ、構成の残り部分は翻訳します。
ステップ2: 翻訳計画の立案
references/api-map.mdを読んでください。これはすべてのRemotion APIとそのHF相当品、またはトピック別リファレンスの索引です。ソースで使用されているAPIに基づいて、必要なトピックリファレンスを特定します。
| ソースに含まれるもの | ロードするリファレンス |
|---|---|
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、およびスカラーpropごとに1つのdata-*を含めます。 data-start/data-duration/data-track-indexを持つシーンdivのフラットリスト。- レイアウト用のインライン
<style>。CSSはすべてのアニメーションプロパティのfrom状態を設定します。 - 末尾の単一の
<script>タグ。これには1つの一時停止されたgsap.timeline({paused: true})が含まれます。すべてのRemotionuseCurrentFrame()派生は、このタイムライン上の適切なオフセットでのトゥイーンになります。 window.__timelines["<composition-id>"] = tl;により、タイムラインをHFのランタイムに登録します。
カスタムReactサブコンポーネントは、propインターフェースをテンプレートとして使用し、インライン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 --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")を設定してください。設定しない場合、差分は翻訳の忠実度ではなくエンコーダの差異(SSIM約0.05の低下)を測定することになります。
ステップ5: ギャップの文書化
クリーンに翻訳できなかったもの(削除されたボリュームランプ、近似されたカスタムプレゼンテーション、置換されたフォントなど)は、HF出力の横にTRANSLATION_NOTES.mdとして書き出します。形式についてはreferences/limitations.mdを参照してください。
このスキルが明示的に行わないこと
- React状態機械の翻訳は行いません。
useState+useEffectでアニメーションを駆動する構成は、HyperFramesのシーク駆動モデルにおける決定論的フレームキャプチャの対象外です。代わりにランタイム相互運用パターンを推奨します。 - HyperFramesと並行してRemotionのレンダリングパイプラインを実行することはしません。 これはPR #214のランタイム相互運用パターンであり、このスキルのリントに失敗する構成のための別のソリューションです。
(@remotion/lambdaはブロッカーではありません。Lambda設定はデプロイメントであり、アニメーションではありません。スキルはこれを警告として削除し、残りを翻訳します。references/escape-hatch.mdを参照してください。)
自身の翻訳を評価する方法
テストコーパスオーケストレータを実行します:
./assets/test-corpus/run.sh
これによりT1、T2、T3(レンダリング + 差分)とT4(リント検証)が実行され、ティアごとの合格/不合格テーブルが表示され、集約JSONレポートが出力されます。これを使用して、クリーンチェックアウトでスキルがエンドツーエンドで動作することを確認し、リファレンス編集後のリグレッションチェックとしても使用します。
検証済みベースライン(2026-04-27時点):
| ティア | 構成の形状 | 平均SSIM | しきい値 |
|---|---|---|---|
| T1 | 単一要素のフェードイン | 0.974 | 0.95 |
| T2 | 複数シーン + spring + オーディオ + 画像 | 0.985 | 0.95 |
| T3 | データ駆動、カスタムサブコンポーネント、カウントアップ | 0.953 | 0.90 |
| T4 | エスケープハッチ(8リントケース) | 8/8合格 | n/a |