---

name: colab-video description: 窓際族物語の動画生成工程（/local-videoのステップ7）だけをGoogle Colab（CUDA GPU）で実行する派生ワークフロー。ローカルMacにCUDA GPUが無くMiniMax H3を実行できないとき、ユーザーから「Colabで動画を作って」「H3をColabで回して」「LTXで動画を作って」と指示されたときに必ず使用する。台本・音声・キーフレーム生成・画像検証（ステップ1〜6）と最終結合（ステップ8〜9）はローカルで行い、動画生成だけを同梱ノートブック（H3=h3_colab.ipynb / LTX-2.5=ltx25_colab.ipynb）でColabに切り出す。セリフ（wav駆動リップシンク）はH3、セリフなしI2VチャプターはLTX-2.5も選べる。無料T4は配管検証用、本番生成はL4/A100（Pay As You Go / Colab Pro）。

Colab動画制作ワークフロー（MiniMax H3 / LTX-2.5 on Google Colab）

実行主体はClaude Code・Cursor・Codexのいずれでもよい（/local-videoと同じ扱い。.agents/skills/と.cursor/skills/の両方にsymlinkしてある）。

位置づけ（local-videoの派生）

本スキルは**/local-videoのステップ7（H3動画生成）の実行先をローカルCUDA機からGoogle Colabに置き換えるだけ**の派生スキルである。それ以外の全工程・全ルールは.claude/skills/local-video/SKILL.md（および同スキルが参照するseedanceの共通ルール）をそのまま適用する:

| 工程 | 実行場所 | ルールの参照元 | |---|---|---| | ステップ1〜6（台本・音声・キーフレーム・検証） | ローカル（Mac） | local-video SKILL.md | | ステップ7（H3動画生成） | Google Colab | 本スキル（以下） | | ステップ8〜9（ffmpeg結合・バンドル検証） | ローカル（Mac） | local-video SKILL.md |

Apple SiliconでH3が実行できない理由（MPSの型/オペレータ非対応）と、Macで動く工程/CUDAが必要な工程の切り分けはlocal-video SKILL.mdの「動作環境の前提」を参照。

0. 前提（アカウント・料金・制約）

| 段階 | 必要なもの | 費用 | できること | |---|---|---|---| | L4生成（単発） | Pay As You Go 100CU購入 | ¥1,179（単発） | L4（VRAM 実測22GiB / RAM 約53GB）で実チャプター生成。目安2〜3CU/時・動画1秒あたり約4.5分（実測） | | L4生成（常用） | Colab Pro | ¥1,179/月（100CU付き） | 同上＋長めのセッション。大規模ランは複数セッションに分けて回す |

※初回の配管検証（無料T4でのカーネルプローブ・workflowバリデーション）は2026-08に完了済み。現行のh3_colab.ipynbは製品生成専用で、検証セルは撤去した。

GPUの選択（L4 / A100 — 作業開始時に必ずユーザーに確認する）

「Colabで動画を作って」と依頼されたら、ランの規模を見てL4かA100かをユーザーに確認してから手順を案内する:

| | L4 | A100 40GB | |---|---|---| | 速度 | 実測61.4秒/step・SageAttention採用で56.1秒/step | 実測36.5秒/step＝L4比約1.7倍速（2026-08・同一チャプターのR2V 20stepで直接比較） | | 単価 | 約2〜3CU/時 | 約8〜12CU/時 | | 1本あたり費用 | 15秒≒¥40〜55 | 15秒≒¥50〜90（速いが単価高） | | 使う重み | fp8ペア（Ada） | int8ペア（Ampere）— 別ファイル | | 並列生成 | 非推奨（VRAM 22GiBを割ると足りない） | WORKERS=2 が目安（40GiBを2分割） | | 向き | 15秒級の単発（既定） | 60秒超の大規模ラン（1セッション完走でき、切断リスクと管理の手間が減る） |

• 並列生成（セル1のWORKERS）: ComfyUIは1プロセスにつき1本ずつしか実行しないので、同時生成にはプロセスを複数立ててVRAMを分け合う。WORKERS=Nにすると、セル6がポート8188〜8188+N-1でN個のComfyUIを起動し（各プロセスに--reserve-vramで「VRAM/N」だけ使わせる）、セル7がチャプターをN本ずつ流す。WORKERS=1が従来どおりの直列で、L4はこちらのまま。

  • 速くなるのはモデルロード・VAEデコード・IOが重なる分だけで、サンプリングは同じSMの取り合いになるため1本あたりは遅くなる。総時間が半分になるわけではない（A100での実測値は未取得。ランのH3_COLAB.mdに実測を書き足していく）。見積りは直列時間で立てる。
  • ホストRAMもプロセス数で分け合うのが並列の主なリスク。ワーカーが突然消える／ログ末尾がKilledならRAM不足なのでWORKERS=1に戻す。VRAM側でOOMが出た場合はWORKERSを減らすかCOMFY_FLAGS=["--lowvram"]。
  • セル7はユニット（fl2va/ref2va）ごとにチャプターをグループ化してグループ単位で並列実行する。ローカルへ置くユニットは常に1本だけで済むのでディスク見積りは直列時と変わらない（重みの実体は全ワーカーで共有される）。I2VとR2Vが混在するランでも、モードをまたいで同時実行することはない。
  • パイロットはWORKERSを本番と同じ値にしたまま1本だけ回す。busyなワーカーが1つでも、1ワーカーあたりのVRAM上限は本番と同じなのでOOM検証になる（未検証で残るのはRAM競合だけ）。
  • 並列時はセル6がsqlite DBもワーカー毎に分けて起動する（同一DBだとCould not acquire lock on database等の初期化競合ERRORが出る・2026-08実測）。

• 高速化フラグ（両GPUとも計測済み・2026-08）: A100はフラグなし、L4はSAGE_ATTENTION=True（x1.07）が正 — セル1の既定SAGE_ATTENTION="auto"が割り当てGPUからこの正解を自動選択する。--fast系はどちらのGPUでも効果ゼロ（x1.00）＝常用しない。詳細は5章「高速化フラグのA/B計測」の実測表。

• 費用対効果（同一チャプター実測から）: A100はL4の約1.7倍速だが単価は約4倍 → 円あたりのスループットはL4が約2.4倍。L4×2セッション並列（sage採用）はA100×1と比べ「約1.3倍のスループット・約半額」になる計算で、チャプター数が多いランはL4×2が合理的。1〜2チャプターの単発や急ぎはA100。

• ノートブックはどちらのGPUでも設定変更なしで動く。セル1の実行時に、実際にランタイムへ割り当てられているGPUを正としてバリアントを自動選択する（ユーザーの申告とColab側の設定が食い違っても、実物に追従する）。意図したGPUをEXPECTED_GPU（例: "A100"）に書いておくと、ランタイムの変更漏れをセル1で検知して止まる。workflowの重み名書き換えはセル5。

• 重みの供給は「毎セッションHFからaria2並列DL」が正（2026-08確定）。キャッシュ類（Drive有料プラン・GCS）はコストが見合わず廃止した。セル3が必要分（共通33GB＋先に使うユニット21GB≒54GB）をaria2の-j3（3ファイル同時・各16接続）でDLし、pip install・バンドル展開・ComfyUI起動と並走する。I2V/R2V混在ランのもう一方のユニットは、セル7がグループ切替時にDLする（-cでレジューム可・約21GB）。追加費用ゼロ。

• モデルはComfy-Org/MiniMax-H3（非ゲート公開リポジトリ）から取得するためHFアカウント・トークンは不要。ゲート化されていたらノートブックがエラーを出すので、その場合のみHFトークンを用意する。

• Colabのディスクはセッション終了で消えるため、毎セッション重みをDLし直す（既定運用。必要分のみ54GB・aria2並列・セットアップと並走するので体感の待ちは短い — 詳細は4章）。

• Drive重みキャッシュは廃止（2026-08・費用削減方針）。WEIGHTS_DRIVE_DIRを指定すれば旧動作（Drive→ローカル8スレッド並列コピー実測83MB/s）が残っているが、有料プラン（Google One）が必要なので使わない。Driveは無料15GB枠でバンドルzip（h3_inputs/）と成果物退避（h3_outputs/）だけに使う＝Google Oneは解約してよい（Gmail/フォト込み15GB以下が条件）。以下は旧運用時代の実測知見（Driveキャッシュを使う場合のみ関係）:注意（2026-08実測）: Drive上のファイルへのsymlink直参照は実行時に使えない（ComfyUIのcomfy_aimdoがFUSE越しのスライス読みに失敗しHostBuffer.read_file_slice failedになる）。Driveはあくまでキャッシュで、実行前に必要な重みをローカルへコピーする（エンコーダ・VAEはセル3で、ユニットも使うのが1本だけならセル3が先にローカル化し、I2V/R2V両方必要なランではセル7が使用直前に自動ローカル化する。L4のディスク65GBでも「共通33GB＋ユニット1本21GB≒54GB」で収まるよう、他方のユニットは自動退避される）。もう一つの罠（2026-08実測）: DriveFSはFUSE読み出しの内容をローカルディスクにもキャッシュするため、コピー中は「コピー先＋キャッシュ」の二重でディスクを消費し、shutil.copyだと空きチェックを通過した後にENOSPCで落ちる。ノートブックのコピーは空きが逼迫するとDriveFSキャッシュを自動掃除（unmount→削除→remount）しながら進むレジューム可能なチャンクコピーになっている（セル3・セル7）。

• GCS重みキャッシュは撤退済み（2026-08）— 使わない（実装も撤去済み）。重みの正は毎セッションHFからのDL。 一時導入して立ち上がり4.5分（Drive比▲10分）を実測したが、転送課金で破綻した: ①USマルチリージョンは書き込み複製費＋読み出し$0.01/GB（請求¥386）、②シングルリージョン(us-central1)に移行してもColabのVMリージョンはユーザーが選べず、日本からはアジアに割り当てられて大陸間転送$0.08/GB＝1ラン¥600級が発生（SKU GCP Storage Data Transfer between Northern America and Asia・請求¥3,294）。「同一リージョンなら無料」はVM側を固定できない以上成立しない、が結論。

  • 実装もノートブックから完全撤去済み（再導入の提案をしないこと）。この教訓だけをここに残す。
  • 撤退時の後始末: GCSバケットを削除して保管料を止める（コンソールのCloud Storageから削除）。Driveのh3_weightsとGoogle Oneは維持する。L4/A100の両ペア（117GB）を常備するならGoogle One 200GB（月¥380）。

• 無料枠はセッション上限が短く（実質2〜4時間・保証なし）、約90分の放置で切断される。ダウンロード中もブラウザを閉じない。

• GPUの割当は「ランタイム → ランタイムのタイプを変更」で L4 / A100 を選ぶ（どちらを使うかは上記「GPUの選択」で決める）。

1. ワークフロー全体

素材（台本・キーフレーム・シート・セリフ音声・プロンプト）は動画スキル側で用意済みのものを受け取るのが既定。供給元は2通りあり、どちらでも以降の流れは同じ:

• seedanceラン（/seedanceで制作済みのランディレクトリ）→ 下記7章の変換手順でH3チャプター化する（こちらが既定）
• local-videoラン → local-videoのステップ1〜6を完了させた状態から引き継ぐ

1. ローカル: 素材を受け取り、必要ならH3向けに変換する（7章）。
2. ローカル: build_h3_run_package.pyでラン直下のh3/にバンドルzip＋I2V用/R2V用ノートブックの3ファイルを生成する（下記2章）。
3. h3/の3ファイルをユーザーに渡す: zipはDriveのh3_inputs/へ置いてもらい、ノートブック（I2V用・R2V用の2本。片モードのランは1本）は https://colab.research.google.com →「アップロード」で開いてもらう。
4. Colab（L4）: パイロットチャプター→残りチャプターを生成する（下記5章）。2本のノートブックは別セッションで同時に回してよい（L4×2並列）。
5. ローカル: mp4を回収し、結合して仕上げる（下記6章）。

セルの実行はユーザーがブラウザで行う。Claudeの担当は「バンドルとworkflow JSONの準備」「ノートブックと手順の提示」「ユーザーが貼ったセル出力・ログの診断」「回収後の検証と結合」。

2. ポータブルバンドルの要件

ラン専用ディレクトリ03_SCRIPTS/<NN>_<slug>/に以下が揃っていることを確認してからzipする（不足分はlocal-videoのスキルディレクトリからコピーして同梱する）:

• script.md（H3 inputs表・生成実行プロトコル込み）
• ch*_start.png / ch*_end.png（検証済みキーフレーム）、R2V用キャラクターシート・スケール参照
• ch*_*.wav（全セリフ・ナレーション音声）
• ch*_prompt.txt（extract_prompts.pyで逐語抽出済み）
• ch*_workflow.json（gen_all_workflows.shまたはbuild_h3_workflow.pyで生成済み）
• ツール一式: build_h3_workflow.py / extract_prompts.py / h3_run.py / gen_all_workflows.sh / assemble.sh
• RUNBOOK_CUDA.md相当の手順書（パイロットのチェックリスト込み。テンプレートは03_SCRIPTS/26_kansha_no_bug_ichimankai/RUNBOOK_CUDA.md）

揃ったら**build_h3_run_package.py（本スキル同梱）でラン一式を生成する**のが既定:

python3 .claude/skills/colab-video/build_h3_run_package.py 03_SCRIPTS/<NN>_<slug>

生成物は03_SCRIPTS/<NN>_<slug>/h3/に3ファイル:

• <NN>_<slug>_h3_bundle.zip — ポータブルバンドル（除外は従来どおりref_canvas_*・validation/・.DS_Store＋h3/自身。通常20〜200MB）
• h3_colab_i2v.ipynb / h3_colab_r2v.ipynb — 正典h3_colab.ipynbのセル1に「そのモードのCHAPTERS（workflowのunet_nameから自動分類）・BUNDLE_ZIP_FROM_DRIVE=/content/drive/MyDrive/h3_inputs/<NN>_<slug>_h3_bundle.zip・OUT_DRIVE_DIR=/content/drive/MyDrive/h3_outputs/<NN>_<slug>」を書き込んだもの。片モードしか無いランはそのモードの1本だけ生成される

運用:

• zipはDriveの**h3_inputs/直下へファイル名そのまま置く。成果物はラン名と同名のh3_outputs/<NN>_<slug>/**に貯まる（どちらもノートブックに設定済みで、ユーザーの編集は不要）

• I2V/R2Vの2セッション並列が既定の回し方: 2本を別々のColabセッション（L4×2推奨）で同時に★一括実行する。モード毎にユニットが分かれているため干渉せず、ユニット入れ替えも発生しない（NEED_I2V/NEED_R2Vは各ノートブックのCHAPTERSから自動判定、AUTO_SHUTDOWNも各自の担当分だけ確認して切断する）

• スクリプトがチャプターのモード分類と所要時間の目安（L4+sage実測の線形則: 約10.7秒/フレーム）を表示するので、そのままユーザーへの案内に使う

• 手動でzipだけ作る場合は従来コマンド（cd 03_SCRIPTS && zip -r <NN>_<slug>_h3_bundle.zip <NN>_<slug> -x "*/ref_canvas_*" -x "*/validation/*" -x "*/.DS_Store" -x "*/h3/*"）でもよい

• workflow JSONの重み名はどのGPU向けでもよい（ノートブックのセル5が、割り当てられたGPUに合う重み名へ自動で書き換え、SaveVideoのcodecも補完する）。

• --framesのグリッド（17k+5）、R2Vの入力上限（画像9・音声3・合計12）はローカルと同一。local-video形式のランはvalidate_local_run_bundle.pyをzip前に通しておく（seedance変換ランは対象外）。

3. ノートブックのセル構成（製品生成専用）

回し方: セル1（設定）を編集 → その直下の**★一括実行セル**を1回押す（セル1〜7を続けて実行）→ 完了後にセル8で回収。1つずつ確認しながら進めたいときは従来どおりセル1→8を順に実行してもよい（挙動は同じ）。

立ち上げの並列化（★一括実行セルのRUN_ORDER）: セル3（重み配置）は呼ぶとバックグラウンドスレッドでコピー／DLを進めて即座に返るため、番号順（2→3）ではなく**1 → 4 → 3 → 2 → 5 → 6 → 7で流す。これで33〜54GBの重みDLがセル2のpip install（2〜3分）・セル6のComfyUI起動と並走**し、直列に積み上げた場合より立ち上がりが数分〜10分以上短くなる（GPUランタイム接続中は常に課金されるので、この短縮はそのままCU節約になる）。セル4（バンドル展開・数十秒）をセル3より先にするのは、セル3のNEED_I2V/NEED_R2V自動判定がバンドル内のworkflowを読むため。依存関係は「セル2 → セル6（起動にはインストール済みが必要）」「セル4 → セル5（workflow調整にBUNDLEが必要）」「セル4 → セル3（モード自動判定。未展開なら両ユニットへフォールバック）」「セル3 → セル7冒頭のwait_weights()」だけで、この順序はすべて満たしている。IPythonは1カーネルなのでセル自体を同時実行はできない — 並列にできるのは「バックグラウンドスレッドに逃がせるIO（重み配置）」と「subprocessで走る処理（pip install・aria2）」で、その重ね合わせを最大化する順序にしてある。1つずつ手で実行する場合も番号順で問題なく動く（セル2のclone判定を順序非依存にしてある）。

| セル | 内容 | |---|---| | 1 | 設定＋環境チェック（毎セッションここだけ編集）: 編集が必要なのはCHAPTERS・AUTO_SHUTDOWN・Driveパス程度。GPU依存の項目は既定"auto"で自動設定される — WORKERS（A100=2/L4=1）・SAGE_ATTENTION（L4=True/A100=False・実測に基づく）は割り当てGPUから、NEED_I2V/NEED_R2Vはバンドルのworkflowから（セル3で確定）。いずれも明示指定で上書き可。EXPECTED_GPUは通常空（自動追従）で、特定GPUを固定したいときだけ指定すると割当違いで停止する。実行すると実際に割り当てられているGPUを正として重みバリアントを自動選択・表示し、WORKERSから各ワーカーのVRAM上限（--reserve-vram）を決める | | ★ | 一括実行（セル1の直下・番号なし）: セル1〜7を1つずつ押す代わりに、これ1つで続けて実行する。get_ipynbでノートブック自身のセルソースを取り出し、#@title <番号>.で番号を拾ってFROM_STEP〜TO_STEP（既定1〜7）の範囲をrun_cellする（Colab標準の「すべてのセルを実行」はセル9＝アドホック生成や計測セルまで走るので使えない）。実行順は番号順ではなく1 → 4 → 3 → 2 → 5 → 6 → 7（下記「立ち上げの並列化」）。操作が必要なもの（Driveのマウント承認・バンドルzipのアップロード）はセル1直後に先出しで済ませ、zipのパスをBUNDLE_ZIP_LOCALに入れる（セル4はそれを使うのでダイアログを出さない）＝以降は無人で流れる。BUNDLE_ZIP_FROM_DRIVEを設定してあればアップロードは求めない。失敗したセルで停止し、FROM_STEPをその番号にして再実行すれば続きから流せる（生成済みチャプターはセル7がスキップするのでやり直しは安い）。失敗時はFAIL_SHUTDOWN_SEC（既定600秒・0で無効）のカウントダウン後にランタイムを切断・削除して課金を止める（■で取り消せる。切断前にComfyUIログ末尾を出力へ残し、OUT_DRIVE_DIRがあればログもDriveへコピー。Driveへ退避されていない成果物があるときは切断しない）。■で手動停止したときは切断しない | | 2 | ComfyUIインストール＋aria2導入＋H3ノード確認。cloneの判定はComfyUI/main.pyの有無（ディレクトリの有無ではない）で、別の場所へcloneしてからcp -rnでマージする。一括実行はセル3・4を先に走らせる＝ComfyUI/modelsやComfyUI/inputだけが先に作られた状態で来るため、ディレクトリ判定だとcloneが丸ごとスキップされてしまう | | 3 | 重み配置（バックグラウンド実行 — 開始したらすぐセル4〜6へ進んでよい。セル7の冒頭が完了を待つ）: 必要分（共通33GB＋先に使うユニット）をaria2の-j3で同時DL（各16接続・-cレジューム・15秒毎に進捗）。NEED_I2V/NEED_R2Vはバンドルのworkflowから自動判定し、2ユニット必要なランは後で使う方をセル7の切替時DLに回す（ディスク54GBで回る）。WEIGHTS_DRIVE_DIR指定時のみ旧Driveキャッシュ動作。GPU切替時は容量が足りなければDrive上の旧バリアントを自動削除。ユニットは**NEED_I2V/NEED_R2Vの片方だけがTrue（＝使うユニットが1本）ならここで先にローカル化し（共通33GB＋21GB≒54GBで収まる）、両方必要なランでは同時に載らないのでsymlinkに留めてセル7が遅延ローカル化する | | 4 | バンドルzip投入→展開→ComfyUI/input/へコピー | | 5 | workflowをこのGPUの重み名に調整＋codec補完 | | 6 | ComfyUI起動（WORKERS個をポート8188〜で並列起動。各ログは/content/comfyui_<i>.log。OOM時はCOMFY_FLAGS=["--lowvram"]にしてここから再実行）。SAGE_ATTENTION=Trueならここでpip install＋--use-sage-attention付与、FAST_FLAGSは--fastとして付与する（フラグは起動引数なので、セル1で変えたらこのセルの再実行が必須） | | 7 | チャプター生成: 冒頭でセル3のバックグラウンド重み配置の完了を待ち、同じユニットを使うチャプターをグループにまとめ（21GBのユニット入れ替え回数を最小化。同一グループ内は番号順）、グループのユニットを流す直前にHFからDL**（WEIGHTS_DRIVE_DIR設定時はDriveからコピー。ディスクが足りなければ他方のユニットを自動退避。削除した旧unetをComfyUIがmmapで掴んでいて空きが戻らないときは、自動でComfyUIを再起動して解放してからやり直す — 2026-08実測）してから**WORKERS本ずつ同時実行**（出力は[w0]/[w1]のワーカー名付きで流れる）。生成済みスキップはローカルとOUT_DRIVE_DIR上のmp4の両方を見る＝セッションを跨いだ再開でも退避済みチャプターを再生成しない。OUT_DRIVE_DIR設定時は完了ごとに即Drive退避。AUTO_SHUTDOWN=Trueなら全チャプター成功＋Drive退避を確認後にランタイムを自動削除 | | 8 | 成果物の回収（zip→ブラウザDL） | | 9 | （任意）アドホック生成 — 画像・音声・プロンプト直指定で1本 | | 10 | （任意）高速化フラグの全パターン計測: パイロットチャプター1本を、GPUに応じた全フラグパターン（A100=2通り base/sage、L4=4通り base/fast/sage/sage_fast）で同一シード生成し、最後に比較表（wall分・1step秒・base比）を出す。セットアップ（セル1→3→4→2→5）も内部で実行するので、セル1の設定さえ済んでいればこのセル1つで完結する。BENCH_SHUTDOWN=TrueでDrive退避確認後に自動切断（離席用）。詳細は5章「高速化フラグのA/B計測」 |

課金の実態（重要）: CUは「GPUランタイムが接続されている時間」で消費される。セルが動いていない待ち時間（アップロード待ち・放置）も課金対象。 対策: (1) バンドルzipと実行計画を手元に揃えてから接続する（★一括実行セルはアップロードを最初に求めるので、以降は席を外してよい）、(2) 成果物はOUT_DRIVE_DIR（無料Drive枠）へ即退避して回収時間を最小化する、(3) 成果物を回収したら即「ランタイム → ランタイムを接続解除して削除」で課金を止める、(4) 離席して流すなら「成功時＝セル1のAUTO_SHUTDOWN」「失敗時＝★一括実行セルのFAIL_SHUTDOWN_SEC」の両方を有効にしておく（どちらも成果物のDrive退避を確認できないときは切断しない）。

• 自動切断（セル1のAUTO_SHUTDOWN）: 生成の完了を待って手動で切る必要がないよう、セル7が指定チャプターを全て成功させたらSHUTDOWN_GRACE_SEC（既定90秒）のカウントダウン後にruntime.unassign()でランタイムを削除する。長尺ランを流して離席するときの取りこぼし（生成後に放置され続けて課金だけ進む）を防ぐのが目的。既定はFalse。
• 失敗時の自動切断（★一括実行セルのFAIL_SHUTDOWN_SEC）: 上が「成功して終わったとき」用なのに対し、こちらはエラーで止まったまま放置されるケース用（離席中に落ちると気付かず課金が続く）。既定600秒で、0にすると切断しない。切断前にComfyUIログの末尾をセル出力に残す（ランタイムを消すと/contentのログは失われるため。OUT_DRIVE_DIR設定時はログ本体もDriveへコピー）ので、戻ってきてから原因を追える。■で手動停止した場合と、Driveへ退避されていない/content/outputs/*.mp4がある場合は切断しない。
  • OUT_DRIVE_DIRが必須（未設定だとセル1で停止する）。ランタイムを消すと/content/outputsのmp4は失われるため、切断前に指定した全チャプターのmp4がDrive上に実在することを確認し、1本でも欠けていれば切断せず警告して止まる。生成が1本でも失敗した場合は手前のassertで止まるので切断には到達しない。
  • パイロット中はFalseにする。合格判定・回収を挟む前にランタイムが消える。セル8でブラウザに落としたい場合も同様。
  • カウントダウン中にセルを停止（■）すれば切断を取り消せる。

4. ダウンロードの知見（実測）

• aria2cが無い状態でセル3が走る問題（2026-08修正）: ★一括実行の順序は1 → 4 → 3 → 2 …（重みDLをセル2のpip installと並走させるため）で、aria2をapt-getで入れるのはセル2だった。このため重み配置スレッドがFileNotFoundError: aria2cで即死し、そのままセル4〜6が流れてセル7のwait_weights()で初めて発覚する（=セットアップ時間と課金を無駄にする）。現在はセル3側にensure_aria2()を置き、無ければ自前でapt-get（dpkgロック競合は最大240秒リトライ）、それでも駄目ならcurlの並列DL（-C -でレジューム可・aria2より遅い）へフォールバックする。セル2側はcommand -v aria2cで既に在れば叩かない。LTX-2.5ノートブックにも同じensure_aria2()を入れた（順序が1 → 3 → 4 → 2 …で同じ罠がある）。
• HF公式クライアントは大容量DLが不安定（タイムアウト→レジュームの繰り返し、終盤の速度低下）。ノートブックはaria2（-c -x16）を既定にした。中断してもセル3の再実行でレジュームされる。
• ディスクがほぼ満杯になると書き込み自体が遅くなり、DL速度が数MB/sまで落ちる。L4の実測ディスクは65GB程度しかないことがあり、両モードの実体（約75GB）は同時に置けない → ユニットをチャプター毎に入れ替えるローカル化方式（セル7）で「常に54GB以下」に保つ。WEIGHTS_DRIVE_DIRはDL回避のキャッシュとして併用する。
• Drive上の重みはサイズ照合（MIN_BYTES）で不完全ファイルを検出し、自動で落とし直す。
• Drive→ローカルのコピー中のENOSPC（2026-08実測）: DriveFSがFUSE読み出し内容をローカルディスク（/root/.config/Google/DriveFS）にもキャッシュするため、21GBのユニットコピーで最大2倍のディスクを消費する。対策としてセル3・セル7のコピーはチャンクコピー化し、空きが逼迫するとreclaim_disk()が「他ユニットのローカル実体 → pip/HFキャッシュ・展開済みバンドルzip → DriveFSキャッシュ（unmount→削除→remount）」の順に空けてから続行、中断してもコピー済みバイトからレジュームする。
• 「空きは残っているのに『ディスク不足』で止まる」（2026-08修正）: 旧実装は必要量を「コピー残り＋固定4GiB」で判定していたため、レジューム（残り数GiB）の場面で空きが十分あるのに落ちた。現在はheadroom_for(remaining)＝残り＋min(2GiB, max(残り/4, 512MiB))で判定し、足りないときはreclaim_disk()を通してから停止する。停止時のメッセージには空き/全体/必要量・削除済みなのにプロセスが掴んでいるバイト数・ローカルの大きいファイル一覧が出るので、まずその数字を読む。削除済み…掴んでいるが数GiB以上なら（ComfyUIが旧ユニットをmmapしたまま等）セル6を再実行してComfyUIを再起動すれば解放される（セル7のユニット入れ替えではこの再起動を自動で行う — 2026-08にL4のfl2va/ref2va混在ランで実測し自動化）。DriveFSキャッシュ掃除は「何GiB解放したか」を必ず表示するので、0GiBなら原因はキャッシュではない。
• FUSE読み出しの並列化ベンチ（2026-08、未読領域4GiBずつをpreadで読み比べ）: 1/4/8/16スレッド = 62.6 / 76.0 / 83.4 / 76.6 MB/s。8スレッドが最速（約1.33倍）だったのでコピーは8スレッド並列preadを採用。伸びが小さいのはFUSEよりDriveバックエンドが律速のため。GCS（数百MB/s級）への移行も試したが転送課金で撤退した（0章の教訓を参照 — 再提案しないこと）。

5. 生成モード（L4 / A100 共通）

1. ランタイムを選んだGPUにしてセル1（設定＋環境チェック）→2〜6を実行。重みDL（54GB）はバックグラウンドでセットアップと並走する。WORKERSはここで本番と同じ値にしておく（後から変えるならセル1→6→7をやり直す）。
2. パイロット必須: セル1のCHAPTERSを最初のセリフ（R2V）チャプター1本だけにしてセル7を実行し、チェックリスト（wav駆動・正しい話者のリップシンク・キーフレームアンカー・NG要素・尺）を全部確認してから、CHAPTERSを残りに書き換えてセル1→セル7を再実行する（生成済みは自動スキップ）。並列運用でもWORKERSは下げずにパイロットを回す（1ワーカーあたりのVRAM上限は本番と同じなのでOOM検証になる）。
3. 尺の長いランは1セッション2〜3チャプターに区切る。OUT_DRIVE_DIRを設定しておけば完了ごとに自動でDriveへ退避される（未設定ならセル8でこまめに回収。セッションが落ちると未回収のmp4は消える）。
   • L4実測（2026-08、初の成功ラン）: 5.9秒のR2V（141f・20step・1344x768）でサンプリング27分（81秒/step）＝動画1秒あたり約4.5分＋モデルロード等で計38.5分。割当VRAMは公称24GBに対し実測22.0GiB、ディスクは65.9GiBしかないことがある（両モードの重み74GBは同時に載らない→セル7がユニットをチャプター毎にローカル化して回避）。
   • 実測で確認済みの品質: wav駆動の音声（エンベロープが元wavと一致・二重声なし）、発話区間と同期したリップシンク、発話後の閉口、実写調画風・キャラ同一性の維持。
4. 生成中はブラウザを放置しない（無料・Pro問わず約90分アイドルで切断。Colabのタブを開いたままにする）。用が済んだら即ランタイムを削除して課金を止める（OUT_DRIVE_DIR＋AUTO_SHUTDOWN=Trueの本番ランなら完了時に自動で削除される。放置ランと相性がよい）。

高速化フラグのA/B計測（セル1のSAGE_ATTENTION・FAST_FLAGS・AB_LABEL）

総時間の大半はサンプリング（L4実測81秒/step×20step）なので、1stepを安くする起動フラグを2系統用意してある。常用を決める前にパイロットチャプター1本でA/Bを取り、実測をランのH3_COLAB.mdに記録する:

| 設定 | 内容 | 実測（2026-08・同一チャプターch1 R2V 20stepの同一シード比較） | |---|---|---| | SAGE_ATTENTION=True | INT8量子化attention（pip sageattention＋--use-sage-attention。セル6がインストールと付与を行う） | A100: x0.95（遅くなる）＝不採用（36.5→38.6s/step）。L4: x1.07＝採用（61.4→56.1s/step。品質はパイロットで確認してから常用） | | FAST_FLAGS=["fp16_accumulation", "fp8_matrix_mult"] | ComfyUIの--fast最適化 | L4・A100とも効果ゼロ（x1.00）＝不採用（L4実測61.4→61.5s/step。H3の行列積はcomfy-aimdoの量子化カーネル（w4a8_int8等）を通るため、--fastが差し替える標準経路を使っていないとみられる） |

確定した本番構成（2026-08計測）: A100=フラグなし（既定のまま）、L4=SAGE_ATTENTION=Trueのみ。SageAttentionがA100で逆効果・L4で+7%に留まるのは、H3がcomfy-aimdoの量子化カーネルで既に最適化済みのため。残る高速化余地はstep数削減（品質A/B前提）・セリフなしチャプターのLTX-2.5移行・複数セッション並列。

計測の既定はセル10（全パターン一括計測）。セル1の設定（Driveパス・EXPECTED_GPU・WORKERS）だけ済ませてセル10を実行すると、セットアップ→GPUに応じた全パターンの同一シード生成→比較表まで無人で流れる:

1. セル1を設定し、セル10を実行する（BENCH_CHAPTER空=バンドル先頭のチャプター。離席するならBENCH_SHUTDOWN=True — Drive退避を確認してから切断し、比較表はセル出力に残る）。所要はA100=2パターン、L4=4パターン×チャプター1本分。
2. 出た比較表（pattern / wall_min / s_per_step / vs_base）をそのままClaudeに貼り、品質（ch*__<パターン>.mp4は同一シードなので条件差だけが出る。リップシンク・キャラ同一性・音声・破綻を見比べる）と合わせて採用フラグを決める。
3. 採用を決めたら実測をH3_COLAB.mdと本スキル0章の速度目安に反映し、本番ランはセル1で採用フラグを設定・AB_LABELを空にして★一括実行で回す。計測成果物を本番の結合に流用するならchN.mp4へリネームしてから回収する。
4. 生成済みパターンはスキップされ、以前の計測値（bench_log.csv）が表に使われるので、途中で切れてもセル10の再実行で続きから流せる。
5. Drive FUSEの瞬断（[Errno 107] Transport endpoint is not connected・2026-08実測）や重み配置の失敗はセル10が自動復旧する（強制再マウント→セル3再実行→再試行。コピーはレジューム）。パターンの失敗（status列）にErrno 107や重み配置が残っている場合も、セル10の再実行だけで続きから流れる。

計測の仕組み: セル7が毎チャプター/content/outputs/bench_log.csvへ「ラベル・チャプター・GPU・WORKERS・フラグ・wall秒・サンプリング1step秒」を追記する（OUT_DRIVE_DIR設定時はDriveにもコピーされ、次セッションはDrive側から引き継ぐ＝セッションを跨いで比較できる）。個別に1条件だけ試すときは、セル1でAB_LABELとフラグを手で変えてセル1→6→7を再実行する（フラグはComfyUIの起動引数なので、セル6の再起動を挟まないと反映されない）。

• AB_LABEL設定中は成果物名がchN__<ラベル>.mp4になり、生成済みスキップと衝突せずに同一チャプターを別条件で再生成できる（自動切断のDrive退避確認もラベル付き名で行われる）。
• bench_log.csvは通常運用（AB_LABEL空＝label列default）でも毎チャプター記録されるので、日常のランがそのまま速度の実測台帳になる。

アドホック生成（セル9）— seedance風の単発生成

チャプター定義に縛られず「素材＋プロンプト → 動画1本」を回せる。セル内のADHOC辞書を編集する:

• mode: "i2v"（開始/終了フレーム厳密固定・音声なし）/ "r2v"（参照画像最大9＋音声最大3・リップシンク）
• frames: 17k+5グリッドのみ（90, 124, 141, 158, ...）。セリフありは「wav合計長＋約1秒」を目安に選ぶ
• prompt: local-video SKILL.mdのMotion prompt規約そのまま（Required attached input files:宣言、<Picture N>/<Audio N>タグ、<d>[Japanese] 原文</d>のセリフ逐語埋め込み、末尾にSoundscape:とMusic:）
• 素材はバンドル同梱ならファイル名指定のみ。新素材はColab左のファイルペインから/content/ComfyUI/input/へドラッグ＆ドロップしてから指定する

プロンプトはClaude側で組み立ててユーザーに渡すこと（要約・省略禁止のルールはチャプター生成と同じ）。

6. 回収と後工程

回収したchN.mp4をローカルのラン専用ディレクトリに置き、以降はlocal-video SKILL.mdのステップ8（結合→VOICEVOXクレジット焼き込み）→ステップ9（validate_local_run_bundle.py）をそのまま実行する。検証が失敗したまま完了報告してはいけない（local-videoと同一ルール）。

音声の扱い（2026-08実測で確定）: H3の埋め込み音声は渡したwavと同等（エンベロープ一致・聴感で劣化なし）と確認済みのため、セリフ入りチャプターも埋め込み音声をそのまま使ってよい（Seedanceと同じ扱い。オフセット調整・載せ直しは不要）。パイロットの音声チェックで劣化・二重声を検出したランに限り、local-video SKILL.mdステップ8の載せ直し手順にフォールバックする。

7. seedanceランからの変換（既定の素材供給元）

seedance形式のラン（クリップ・CapCut inputs・@ImageN/@Audio1タグ）をH3チャプターへ変換する手順。実例: 03_SCRIPTS/41_okayaman_watching_cm/H3_COLAB.md。

1. クリップ→チャプター対応: 1クリップ＝1チャプター。境界共有（クリップNのFrame B＝クリップN+1のFrame A）はそのまま引き継ぐ。尺は17k+5グリッド（24fps）へ丸め、対応表をH3_COLAB.mdに記録する。動きの少ないクリップは90フレーム（3.75秒）以下へ短縮するか、中間キーフレームを1枚作って2チャプターに分割する（低イベントの長尺はモデルが台本に無い動作を発明する。判定基準はlocal-video SKILL.mdの「I2Vの弱点と必須ガード」）。
2. モード判定: セリフなし＝I2V（Frame A/Bを--first/--lastに）。セリフあり＝R2V（Frame A/Bを<Picture 1>/<Picture 2>に、シート・スケール参照を残りスロットへ。画像9・音声3・合計12の上限に注意）。ただしセリフが無くても、正典を守るべき要素（仮面・顔・体型・NG変更小道具）がFrame A/Bの両方に写っていないクリップ（フードで隠れている・人物が画面外等）はI2Vにしない — R2Vへ切り替えてシートを渡すか、I2Vのまま必須ガード＋90f以下への短縮を適用する（local-video SKILL.md「I2Vの弱点と必須ガード」のアンカー可視性チェック）。
3. プロンプト変換（逐語ベース。要約禁止はseedanceと同じ）:
   • I2VはH3に参照画像を渡せないため、Required attached reference files: @ImageN...の宣言部を削除し、本文中の(@ImageN, ...)は同定句だけ残す。冒頭付近に "The video starts EXACTLY on the attached first frame and ends EXACTLY on the attached last frame." を足す。
   • I2V必須ガード: アンカー2枚に写らない正典要素・画面外の人物があるチャプターでは、本文に「隠している物は全フレームで隠し続ける（never slips / never falls / never revealed）」「新しい人物・キャラクターは一切現れない（no new person or character enters the frame at any time）」「全フレーム実写のみ（no 2D, anime, cartoon, chibi, or illustrated character ever appears）」を否定形込みで必ず入れる（実測事故2件の再発防止。詳細はlocal-video SKILL.md）。
   • R2Vは@ImageN→<Picture N>（接続順に振り直し）、@Audio1→<Audio 1>、話者に(S1)、セリフは<d>[Japanese] 原文</d>で逐語埋め込み。
   • 音声のセマンティクス差: seedanceの「voice sample（似た声を生成）」記述は、H3では「Use <Audio 1> AS-IS as the dialogue audio and do NOT generate any voice」に置き換える。
   • Soundscape:/Music:行はseedanceランに既にあるのでそのまま使える。
4. 音声パディング: H3は1ファイル2.0秒以上。短いwavはapadで末尾パディングした別名ファイル（*_h3pad.wav）を作り、元ファイルは変更しない（seedance側の正典を保つ）。
5. workflow生成: build_h3_workflow.py（local-videoスキル同梱・codec対応版）をラン直下にコピーしてchN_workflow.jsonを生成。h3_run.pyも同梱してからzipする。
6. atmosphere参照（ポスター等）はH3入力にしない（雰囲気はキーフレームに焼き込み済み。文字漏れリスクも避けられる）。
7. パイロットはセリフのあるチャプター。チェックリストはseedanceランのscript.mdの生成プロトコルを使い、音声の項だけ「添付wavそのものが鳴っているか」に読み替える。回収後のQCは境界フレームだけでなく中間フレームも必ずサンプリングする（1チャプター最低3点。アンカーに正典要素が写らないI2Vチャプターは重点確認。事故は両端が正しく中間だけで起きる）。

8. LTX-2.5モード（セリフなしI2Vチャプターの代替エンジン）

H3の代わりにLTX-2.5（Lightricks・2026-08公開のオープンウェイト動画生成モデル）でチャプターを生成する派生モード。ノートブックはltx25_colab.ipynb（本スキル同梱・セル番号体系はH3版と同じ）。H3と併用でき、どちらの重み・成果物もDriveの別ディレクトリ（ltx25_weights / ltx25_outputs）に共存する。

使い分け（重要）

| | MiniMax H3（h3_colab.ipynb） | LTX-2.5（ltx25_colab.ipynb） | |---|---|---| | セリフあり（R2V相当） | ◎ wav駆動リップシンク | 不可（添付wavで駆動する入力が無い） | | セリフなしI2V（開始/終了フレーム固定） | ◎ fl2va | ◎ LTXVAddGuide×2（frame_idx 0 / -1） | | 音声 | 添付wavをそのまま埋め込み | プロンプトのSoundscape/Music記述から自動生成（合わなければローカルで差し替え） | | ステップ数 | 20 | 蒸留8（速度はColab未実測 — パイロットで計測） | | 重み | GPU別バリアント・約75GB | int8一式・約39GBがL4/A100共通（切替なし・ユニット入れ替えなし） |

**セリフチャプターは必ずH3。**LTXは「セリフなしチャプターだけのラン」または「混在ランのセリフなし分」に使い、混在ランは両ノートブックで生成したmp4を同じラン直下に集めて結合する。

前提（H3との差分）

• HFリポジトリLightricks/LTX-2.5はゲート付き: 初回に https://huggingface.co/Lightricks/LTX-2.5 で「Agree and Access」を押してライセンス承諾し、READ権限（gated reposアクセス可）のHFトークンをColabのシークレット（鍵アイコン → HF_TOKEN）に登録する。重みがDrive配置済みのセッションではトークン不要。ノートブックはトークンでリダイレクトを解決してからaria2でDLする。
• ライセンスはLTX-2 Community License（年間収益1000万ドル以下なら商用利用可）。
• Drive容量の指針: LTX int8一式は約39GB。H3の通常運用（共通33GB＋ユニットペア42GB≒75GB）と併存させるとGoogle One 100GBに収まらない。選択肢: ①H3を片ユニット運用（33＋21=54GB）にして計93GBで100GBに収める（I2VをLTXへ移すならH3のfl2vaを消す運用と相性がよい）、②200GBプラン（月¥380）にする、③LTXはDrive配置せず毎セッションDL（39GB・aria2で15〜30分）。
• 生成速度・L4（VRAM 22GiB）での1344x768生成の可否は未実測。OOM時は--lowvram→それでも駄目なら1120x640（同アスペクト比）へ落とす。確実なのはA100。

seedanceランからの変換（7章との差分）

1. 尺のグリッドが違う: LTXは8k+1フレーム（97, 121, 145, 193, ...）@24fps。H3の17k+5と取り違えない（ノートブックのセル5が検証する）。

2. workflow生成: build_ltx25_workflow.py（本スキル同梱）をラン直下にコピーしてchN_workflow.jsonを生成する。h3_run.pyは不要（ランナーはノートブックに内蔵）。

   python3 build_ltx25_workflow.py --out ch1_workflow.json --prompt-file ch1_prompt.txt \
       --frames 121 --first ch1_start.png --last ch1_end.png
   

3. プロンプト変換はH3のI2V変換と同じ（@ImageN宣言部を削除し同定句だけ残す、"starts EXACTLY on the attached first frame..."を足す）。Soundscape:/Music:行は必ず残す — LTXはここから音声を自動生成する。音声wavは投入しない（できない）。

4. バンドル要件: script.md＋ch*_start.png/ch*_end.png＋ch*_prompt.txt＋ch*_workflow.json＋build_ltx25_workflow.py。wav・キャラクターシートは不要（I2Vは参照画像を取れない）。

5. パイロットのチェックリストは「キーフレームアンカー・NG要素・尺・生成環境音の質・中間フレーム（最低3点、隠れた要素の露出・人物の湧きが無いか）」。環境音が合わなければffmpeg -anで消してローカルの音に差し替える（結合はlocal-videoステップ8と同じ）。