kinetograph-migrate

Remotion プロジェクトを Kinetograph に移行する

Remotion プロジェクトの大部分は変更せずに動作します。CLI が remotion と 24 個の @remotion/* パッケージを Kinetograph のコアにマッピングするため、動画コードは変更する必要がありません。変わるのは周辺のツールと、相当するものがない一部のパッケージです。レンダリング経路にブラウザーは一切ありません。どのような理由でも代替策として追加しないでください。Chrome、Puppeteer、Playwright、iframe は使えません。

コマンドは npx kinetograph <command> として実行します。JSON オブジェクトを 1 つ取得するには --json を追加します。その他のコマンドとプロジェクト API については、kinetograph スキルを使用してください。

手順

1. エントリとコンポジションを確認します。 package.json（スクリプト、依存関係）と remotion.config.ts があればそれも読みます。doctor が確認するのはエントリからインポートされたファイルだけなので、プレイヤーページ、レンダリングスクリプト、設定ファイルはレポートに表示されません。プロジェクト内で @remotion/(player|renderer|bundler|lambda|cloudrun|cli|three)、from 'three'、IFrame を検索し、該当するものをそれぞれ問題として扱います。エントリは registerRoot を呼び出すファイルです（多くの場合 src/index.ts。ファイル名は package.json のスクリプトや remotion.config.ts に記載されています）。kinetograph compositions <entry> を実行します。... is not supported by Kinetograph yet というエラーが出た場合、そのインポートが最初の問題です。（メッセージには doctor を実行するように書かれていますが、同じインポートを修正するまで doctor も停止します。）
2. Doctor を実行します。 kinetograph doctor <entry> を実行します（1 つのコンポジションだけを対象にする場合は --comp <id> を追加します）。エンジンが描画できない各要素、プロパティ、理由がフレーム範囲とともに報告されます。バンドルできないインポートがあると、パッケージ名を示してレポートの作成前にコマンドが停止します。まずそれを修正し、doctor を再度実行します。レポートを保存し、それをもとに作業してください。
3. 各問題を修正します。 種類に応じて対応します。
   • @remotion/three または three のインポート：references/three.md を読みます。
   • @remotion/player、@remotion/renderer、@remotion/bundler、@remotion/lambda、@remotion/cloudrun、@remotion/cli、remotion.config.ts、npm run スクリプト、webpack のオーバーライド：references/tooling.md を読みます。
   • IFrame、@remotion/webcodecs、@remotion/media-parser のサンプルコールバック、@remotion/rive、@remotion/skia、Canvas、WebGL、またはレポートにある CSS の問題：references/unsupported.md を読みます。
   • それ以外：レポートにプロパティまたは要素の名前が記載されています。エンジンが描画できるものに変更するか、省略します。推測せず、doctor を再度実行してください。
4. Lint を実行します。 kinetograph lint <entry> と kinetograph check <entry>（型エラーの確認）を実行します。すべてのエラーを修正してください。react の「no declaration file」というエラーは、@types/react がインストールされていないことを意味します。プロジェクトで使用している React のバージョンに合わせて開発依存関係に追加し、そのことをユーザーに伝えてください。これは移行の問題ではなく、render の妨げにもなりません。
5. 見た目を確認します。 kinetograph strip <entry> -n 12 -o out/strip.png を実行してから、PNG を開きます。1 フレームだけ確認するには still <entry> <frame> を使います。プロジェクトが意図していた表示（Remotion のレンダリング結果、スクリーンショット、ユーザーの説明など）と比較します。比較対象がない場合は、コードと照らし合わせて確認し、比較できなかったことを伝えてください。テキストが表示されない場合でも doctor と lint の両方が問題なしと報告することがあるため、すべてのタイトルとキャプションが画面に表示されていることを確認してください（フォントを参照）。
6. レンダリングします。 kinetograph render <entry> --comp <id> -o out/video.mp4 --strict を実行します（まずは --range 0..30 を指定して簡易テストを行います。a..b は b-1 で停止し、a..=b は b を含みます）。--strict は未対応の要素がある最初のフレームで失敗するため、何かが欠けた状態で動画が出力されることはありません。

修正後も --strict で失敗する場合、残っている問題は実在します。近似表現に置き換える（方法も伝える）か削除してから、手順 7 でその旨を伝えてください。最終レンダリングで --strict を外して問題を隠してはいけません。

7. ユーザーに報告します。 そのまま移行したもの、置き換えたもの（置き換え先も含む）、省略または近似したもの、現在プロジェクトを実行するためのコマンドを列挙します。Remotion の結果と異なる場合は、明確に伝えてください。

ルール

• remotion のインポートは編集不要です。remotion または @remotion/* のインポートを @kinetographdev/core に書き換えないでください。
• 機能を黙って削除しないでください。省略や近似があれば、すべて手順 7 のレポートに記載してください。
• フォント。 登録されていないフォントのテキストは、doctor から警告が出ることなく、何も描画されない場合があります。よくある原因は、システムフォントのみ（Helvetica, Arial, sans-serif）を指定した fontFamily です。ユーザーが使用を許可されているフォントファイルを登録してください。@remotion/google-fonts/<Family>（loadFont()）、@kinetographdev/core の registerFont({ family, path: staticFile('F.ttf') })、またはインポートした .css ファイル内の @font-face { src: url(...) } を使います。システムフォントをプロジェクトにコピーしないでください。
• レンダリングはフレームの純粋関数です。Date.now()、Math.random()、タイマーを、フレーム計算と random(seed) に置き換えてください。
• ネットワークはありません。fetch が読み取るのはプロジェクトファイルのみです。リモートアセットは public/ にコピーし、staticFile を使用してください。
• レンダリングパス用の依存関係は追加しないでください。ただし、開発依存関係としての kinetograph は例外です（3D 要素がインポートする @kinetographdev/core を含みます）。まだ npm にない場合は、どこからインストールするかユーザーに確認してください。スタジオやテスト用のパッケージは問題ありません。

対応範囲の概要

コアの remotion と、次の @remotion/* パッケージに対応しています：transitions、motion-blur、noise、paths、shapes、layout-utils、animation-utils、captions、google-fonts、fonts、lottie、gif、media-utils、media、light-leaks、starburst、sfx、zod-types、timeline-utils、media-parser、webcodecs、canvas、rive、skia。意図的に移植していないもの：three、player、renderer、bundler、cli、lambda、cloudrun、tailwind、tailwind-v4（Tailwind 自体は動作します）。完全な表はドキュメントサイトの /docs/guides/migrate/ にあります。GSAP（コア、無料プラグイン、Flip）も動作します。レイアウトエフェクト内で一時停止中のタイムラインを frame / fps にシークするか、useEffect 内の gsap.to を単独で再生させてください（/docs/compat/#gsap）。

書き換え不要なもの：.svg ファイルを指定した <Img src>（内部のテキストは除外されます）、名前付きおよび関数形式の CSS 色（white、rgb()、oklch()）、Fragment 内の <TransitionSeries> および <Series> の子要素、<canvas> と <Canvas>、-webkit-text-stroke、フォントにない記号や絵文字（同梱のフォールバックを使用。CJK には読み込むフォントが必要です）。ライブラリ（Recharts、d3、rough.js、Chart.js、anime.js、Motion、Paper.js）は、フレームに基づいて描画する場合、そのまま動作します。/docs/libraries/ を参照してください。Mermaid は既定の HTML ラベル（<foreignObject>）で描画します。ラベルのフォントを先に読み込んでください。