Colab Video

---
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と同じ）。