video2dsprite

2Dアニメーションへの動画変換

承認済みの静止画でキャラクターの同一性と形状を定め、動画モデルで動きを加え、決定論的なツールでエンジン向けに整えます。動画はスプライトシートより小さく、シームレスで、安価になるとは限りません。

使用する場合

• キャラクターやクリーチャーをアニメーション化する場合：すべての動作を承認済みのマスター静止画から作成し、動作ごとに1本のクリップを用意します。
• 承認済みのマスターから滑らかな動きを作る場合：待機中の呼吸、歩行、走行、攻撃、魔法の詠唱、髪、マント、クリーチャーなどです。
• 提供されたクリップを、透過・位置合わせ済みのループフレームとエンジン用動画にする場合。

使用しない場合

• エフェクト、アイコン、プロップのシート：generate2dsprite。
• 静止画のシーンプレート内の水、炎、霧：generate2dmap。API または CLI 呼び出しのみの場合：generate2dmedia。
• ユーザーが依頼したコード描画アニメーション：codeart2d。

機能の確認（セッションごとに1回）

python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json を実行します。<tools> には、使用するツール一覧にあるメディアツール（image_gen、image_edit、image_to_video）または none を指定します。ROUTES ブロックには、設定済みの API キー（yes または no）、ローカル環境の準備状況、解決された実行順が表示されます。encoding.stdout が失敗する場合は、PYTHONUTF8=1 を設定してください。python "<skill-dir>/scripts/video2dsprite.py" doctor で ffmpeg（5.1 以上、VP9 アルファのラウンドトリップ）を確認できます。

アートソース

マスター静止画は、generate2dsprite（画像生成、ユーザー承認済み）で作成するか、ユーザーから提供を受けます。動きは画像から動画への変換で作成し、マスターから動作ごとに1本のクリップを生成します。ルートを art_source として記録し、返信で明記します。

1. API：キーが設定されている場合は、xAI Grok Imagine Video（XAI_API_KEY）、BytePlus Seedance（ARK_API_KEY）、または fal.ai（FAL_KEY：Kling v3、Veo 3.1、Luma Ray 3.2、MiniMax H3、Wan 3.0、Vidu Q3、LTX）を使用します（route-media.md）。設定済みのキーは所有者の同意を意味するため、呼び出しごとに確認する必要はありません。--last-frame <still> を指定すると、待機クリップと攻撃クリップの終了時のポーズを開始時と同じにできます。
2. ローカル：利用可能であれば、独自の画像から動画への変換ツール（Grok のネイティブ image_to_video）を使用し、なければユーザーの Grok CLI を ACP モードで使用します（最終フレームを固定できません。結果には lastFrameUsed が表示されます）。
3. ユーザーが提供するクリップ（アカウント不要）。
4. ユーザーがコード描画アニメーションを明示的に依頼した場合、または route_media.py が no-route（終了コード 3）を出力した場合に限り、codeart2d を使用します。それ以外の場合は、ジョブとプロンプトを準備して不足点を説明し、生成に成功したと決して偽ってはいけません。

すべてのクリップは、1つのコマンドで処理します。python "<skill-dir>/../generate2dmedia/scripts/route_media.py" video --prompt-file <job>/prompt.txt --reference <job>/input.png --last-frame <job>/input.png --duration 6 --resolution 720p --out-dir <new> を実行します。route、artifact、sha256、estimateUsd、lastFrameUsed を含む JSON を1行で出力します。仕上がりはデフォルトで HD です。ユーザーがピクセルアートを求めた場合は、ピクセル仕上げを選択できます。

1枚の静止画からスプライトセット全体を作成

キャラクターのゲーム用セットを作るには、sprite_set.py を使います。承認済みのマスター（generate2dsprite の master.json）を入力すると、アクションごとに1本の画像から動画クリップを生成し、キー処理、ゲート判定、登録、カット、仕上げ、パッケージ化を行います。クリップを1本だけ作る場合や、用意済みの動画を使う場合は、以下のパイプラインを使用します。詳細は sprite-set.md をご覧ください。プロンプトと修正条項は motion-prompts.md をご覧ください。

1. 計画します。 python "<skill-dir>/scripts/sprite_set.py" plan --master <art>/master.json --output-dir <set> を実行します。デフォルトは、--actions idle,walk,run,attack,jump,hurt、マスターに基づく --finish（デフォルトは hd）、--target-height（hd は 256、pixel は 80）です。Jump には上部に34％の余白がある3:4のキャンバス、attack には16:9のキャンバスを使用します。idle と attack では、最終フレームをマスターに合わせます。<set>/set_plan.json で各アクションの prompt を確認し、必要に応じて実行前に motion、negatives、gates を編集してください。
2. 実行します。 python "<skill-dir>/scripts/sprite_set.py" run --plan <set>/set_plan.json を実行します。クリップは generate2dmedia の route_media.py で生成され、その後、以下の処理を行います。
   • ソフトマットによるキー処理。
   • 数値によるゲート判定：面積 0.72～1.32、足元、アイデンティティ（デザインが失われていない限り警告）、ズーム、背面を向く動き、端、背景、追加オブジェクト、動き、終了ポーズ、色にじみ、ワンショットのタイミング。
   • 最大3テイク。リテイクには、失敗したゲートに対応する修正条項を付けます。すべてのテイクが失敗した場合は、使用可能な中で最良の区間を保持します。
   • 登録後、ループ化するか、動きのエネルギーに基づいてワンショットをゲーム内の長さに合わせてリタイミングします（attack は0.7秒でヒットは40％地点、jump は0.9秒、hurt は0.5秒、cast は0.9秒。計画の timing で設定します）。
   • finish_frames.py による hd または pixel での仕上げ。デフォルトではマスターの色にロックします（plan --no-colour-lock）。
   • png、webm、パッケージ化された各種形式で出力し、検証します。 再実行すると途中から再開し、同じものを二度生成することはありません。
3. ルートがない場合（終了コード3）。 入力とサマリーで指定されたプロンプトを使って、お使いの画像から動画を生成するツールでクリップを作成し、指定された media/clip.mp4 として保存してから、再実行します。
4. 確認します。 python "<skill-dir>/scripts/sprite_set.py" review --plan <set>/set_plan.json を実行してから、すべての -sheet.png、すべての -final.png、および lineup を必ず目で確認してください（Claude Code では Read、Codex では view_image を使用します）。数値だけでは、アイデンティティ、向き、武器の変更、テキスト、顔が隠れているかどうかを判定できません。
5. アクションごとに決定します。
   • 承認する場合：accept --plan <set>/set_plan.json --action <id> --take <n>。失敗したテイクの一部を保持するには、--window START:END を追加します。
   • 拒否する場合：retake --plan <set>/set_plan.json --action <id> --fix <clause id or text> を実行し、続けて run を再実行します。条項 ID には never-turn、weapon-shape、face-visible、no-text、no-flares、keep-colours があります。
6. レポートします。 python "<skill-dir>/scripts/sprite_set.py" report --plan <set>/set_plan.json を実行すると、ルート、テイク、QC 数値、ループ、タイミング、パッケージのパスが一覧表示されます。回答では、各クリップの生成に使ったルートを明記してください。シートを確認する前に、アクションを承認済みと判断してはいけません。

ホストに関する注意

• Codex： ネイティブの画像から動画を生成するツールはありません。route_media.py は xAI API または Grok CLI を使用します。確認用の画像は view_image で確認してください。
• Claude Code： メディアツールはありません。route_media.py にルートを指定します。確認用の PNG とコンタクトシートは Read で確認し、ツールは Bash で実行してください。<skill-dir> は ${CLAUDE_SKILL_DIR} です。
• Grok： ネイティブの image_to_video ツールはお使いのツールです。同じ grok 実行ファイルは、他のホスト向けの「Grok (local CLI)」ルートとして使用できます。

コマンド

各ツールは、ユーザーのプロジェクトルートから1行で実行します：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir> はこのスキルのフォルダーで、兄弟スキルはその隣にあります。入力と出力はプロジェクト内に置いてください。各動詞は新しい --output-dir に書き込みます。既存の出力先は拒否され、チェック後にのみ公開されます（残留物がある場合、--strict は失敗します）。成功時は1行の JSON を出力し、エラー時は error: ... を出力して終了コード1で終了します。使い方の誤りは終了コード2です。Python 3.10 以降、numpy、Pillow、ffmpeg 5.1 以降が必要です。すべてのフラグは --help で確認できます。

パイプライン（1クリップ）

1. キー画像を計画します。 video2dsprite.py key-plan --master <master.png>：background_sentenceをプロンプトに貼り付け、design_colours_at_riskを保護するか、色を変更します。
2. 準備します。 prepare_i2v_input.py prepare --master <art> --action <idle|walk|run|attack|cast|guard|hurt|victory|defeat|ambient|fx> --output-dir <job>：input.pngとprompt.txtを送信します。registration_job.jsonに変換情報が保持されます。単色のマゼンタ、緑、または青の背景に置かれた不透明なマスター画像は、最初にキー処理されます（--master-keyで別の背景色を指定します。ジョブにはmasterKeyingが記録されます）。--subjectにはアイデンティティを示すフレーズ全体を指定します。背景の文では、その頭部を示します（「スカーフを巻いた冒険者」と指定すると、「冒険者の後ろ」になります）。手書きのプロンプトはprepare_i2v_input.py lintで確認します。
3. 生成します。 上記のArtソースを使ってroute_media.py videoを実行します。
4. テイクを採用します。 register_clip.py qc --job <job>/registration_job.json --video <take>を実行し、続けてvideo2dsprite.py triage --video <take> --output-dir <new>を実行します。アクション中に境界へ触れる場合は、パディングせず、必ず再生成します。
5. キー処理します。 video2dsprite.py process --video <take> --output-dir <new> --reference <master.png>（ソフトマット）を実行します。frames-clean/matte-report.jsonを読み、明るい背景と暗い背景の両方でフレームを確認します。キャラクターのすべてのクリップで同じキー処理を使います：--matte-profile <character-profile.json>。キー色に近いデザイン色には、--protect-color #rrggbbを使います。デコード済みのフレーム（frame_*.pngまたはraw_*.png。静止画のキー処理では1フレームを使用）には、video2dsprite.py clean --raw-dir <dir> --output-dir <new>を実行します。
6. 位置合わせします。 register_clip.py apply --job <job>/registration_job.json --frames <out>/frames-clean --output-dir <new>を実行します。足のずれや跳ねがある場合は--lock feet、魔法やヒットのFXには--profile fxを指定します。キャラクターごとにスケールを統一するには、register_clip.py profileを実行してから--character-profileを指定します。
7. ループまたはリタイミングします。 歩き、走り、待機アニメーションには、gait_loop.py select --frames-dir <reg>/frames --fps N --output-dir <new>（--kind idleまたはhover）を使い、aids/loop3x.gifを再生します。攻撃、魔法、FXには、retime.py --frames-dir <reg>/frames --fps N --output-dir <new> --spans <spans>（impact、hold、ticks）を使います。スローモーションのワンショットには、--range 0:N --auto-oneshot --duration 700 --key hit=<impact>@0.4+80を使います（停止したホールドをカットし、ヒット位置を固定して、ゲーム向けの長さに圧縮します）。歩行のケイデンスにはgait_loop.py measure-strideを使います。
8. 仕上げてパッケージ化します。 位置合わせ済みのフレームを仕上げて（下記「仕上げ」を参照）、engine_export.py package --clean-dir <fin>/frames --output-dir <new> --selection <selection.json> --source-size W,H --source-anchor X,Y --formats png,webm,packed --tiers actorを実行します（W,HとX,Yはfinish.jsonから取得します）。キーの残留がある場合は拒否されるため、再度キー処理します。--allow-key-residueは、記録済みの例外がある場合に限り使用します。
9. 検証します。 engine_export.py verify --package <dir>を実行し、続けてvalidate_animation.py <character dir> --require-states idle,walk --require-verifyを実行します。--require-statesは各パッケージの--nameと照合します（hero-runという名前のパッケージには、runではなく--require-states hero-runが必要です）。

詳細：pipeline.md、キー処理についてはmatte.md、レビューとカットについてはanimation-review.md、プロンプトについてはprompt-rules.md。

仕上げ（デフォルトはHD、ピクセルオプションあり）

パッケージ化する前に、登録済みのすべてのアクションを仕上げます。仕上げ済みのフレームは元の名前を維持するため、gait_loopとretimeの選択も引き続き適用されます。詳細：finishing.md。

• HD（デフォルト）： python "<skill-dir>/scripts/finish_frames.py" hd --frames <reg> --output-dir <new> --target-height <px> --role hero --character <id>。静止ポーズ（フレーム0または--rest-frame）で1つのスケールを設定します。足元を基準にしたグリッド上で、プリマルチプライドアルファを使ってボックス縮小し、その後アルファをクリーンアップします。ニアレストネイバーは使用せず、拡大もしません。--display-sizes 1x,2xを指定すると、各サイズをソースから再構築します。
• 同じキャラクターの別アクション： --target-heightの代わりに--scale-ref <idle finish dir>を指定します（スケールはx sqrt(rest-area ratio)、±3%でクランプ）。警告が出た場合、静止ポーズのフレームがベースの静止画ではありません。
• ピクセル（要望があった場合）： まずfinish_frames.py palette build --frames <every action's reg dir> --colors 32 [--reserve #hex] --out <palette.json>を実行し、次にアクションごとにfinish_frames.py pixel ... --target-height <1/8 to 1/12 of the source> --palette <palette.json>を実行します。デフォルトは大胆なピクセルアートです。くっきりした4x4クラスター縮小（中間色をぼかさず、線や目を維持）、軽めのコントラストと彩度の向上、フレームあたり最大--colors（32）色、目を維持する単独ピクセルのクリーンアップ、1 pxの選択的アウトライン（--outline dark|none）、時間方向のヒステリシス、二値アルファ、ディザリングなしで仕上げます。--canvas 48x64を指定すると、セルサイズを固定できます。攻撃には--loop-policy oneshotを、インデックス付きシートには--indexed-sheetを使用します。
• カラー固定： --colour-lock <keyed master.png>を指定すると、マスターのすべてのデザインカラーをOKLabで維持し（彩度のみを調整し、明度は維持するため、ポスタリゼーションは発生しません）、静止ピクセルを時間方向に滑らかにします。colour_lock.py measureは色相の反転と領域の広がりを報告します。
• キャスト確認： finish_frames.py lineup --sets <finished dirs> --out <lineup.png>を実行します。役割は--roleまたはROLE=DIRから取得します。デフォルトのルールは、hero:1.0、mob:<=1.0、boss:~2.0、spirit:~1.0（面積比）です。x1/x3シートを確認してください。ルールに合格しない場合、終了コード1で終了します。
• レビュー： review-contact.pngを確認し、JSON行のqa（flipsPerPair、specksRemoved、alphaBinary）を読みます。ステータスはneeds-visual-reviewのままです。
• パッケージ化： engine_export.py package --clean-dir <fin>/frames --source-size W,H --source-anchor X,Yを実行します。W,HとX,Yには、finish.jsonのsizeとanchorの値を使用します。--registrationは指定しないでください。ピクセル仕上げでは--pixel-art --sampling nearestを追加します。

モーションとジオメトリのルール

• 1クリップにつき1アクションにします。移動、ヒットのタイミング、ダメージ、状態の変化はゲーム側で処理します。
• クリップごとに固定の変換を1つ使用します。各フレームのアルファ境界に合わせてトリミングやサイズ変更をしないでください（サイズが変動し、空中にいるときに足元が固定されてしまいます）。静止画のアルファを、動いているRGBに重ねて固定しないでください。
• 1キャラクターのすべてのアクションで、マスターの静止ポーズから決めた同じ胴体の高さを使用します。仕上げ済みスプライトは拡大しないでください。
• gait_loop.py selectでサイクルを選び、目視だけで判断せず、必ず目視でも確認します。歩行アニメーションはピンポン再生にしません。攻撃アニメーションはフレームを逆再生して戻しません。アクションはインパクトに合わせてリタイムし、その状態を維持します。歩行アニメーションには、一定の歩調と歩幅を持たせます。
• キーイングに関する記述では、マットレポートの数値を引用し、ステータスはneeds-visual-reviewのままにします。--matte binary --despill-mode offを指定すると、cfed170キーヤーを再現できます。

ランタイムと受け入れ

• 受け入れの順序は、パッケージ化、検証、validate_animation.py の順です。animation.json（3.0。2.0 のすべてのキーを維持し、durationsMs は整数ミリ秒、fpsRational は正確な値）、QA、ポスター、PNG フォールバック、および要求された各トランスポートを納品します。ジオメトリはソース単位（sourceSize、sourceAnchor、sourceRect）のままにします。
• パック済み H.264 では、左側に RGB、右側にアルファを格納します。透明な MP4 ではありません。コンポジターの lease.drawable（references/runtime/packed-alpha-webgl.mjs 上の packed-alpha-runtime.js）を描画し、デコード済みフレームが存在するまではポスターを表示します。距離駆動の歩行、ヒットストップ、トランジションについては、references/runtime/forge-runtime.mjs を参照してください。
• ゲーム内の表示サイズで、顔とシルエットの安定性、接触、明るい背景と暗い背景上でのアルファ境界の動き、ループの継ぎ目、視認性を確認します。アルファまたはフレームレートを保証する前に、実機の iPhone で再生を検証してください。スプライトシートを置き換える前に、バイト数とデコードコストを比較してください。

データ契約：references/schemas/video.schema.json。