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秒あたり約1.9分**（蒸留8step・2026-09実測。20stepだった頃は約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`
  - **`h3_run.py`と`build_h3_workflow.py`はノートブックが実行時に呼ぶ**（セル7・セル9）。欠けていると**Colabで初めて、しかも全チャプターが即失敗する**（2026-09-29の実測: 重み49GBをDL済みのセッションを捨てることになった）。`build_h3_run_package.py`が不足分をスキルからコピーし、zip作成後に中身も検証するので、**手動でzipせず必ずこのスクリプトを通す**。
- `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実測の線形則: **0.645秒/フレーム/step**＝蒸留8stepで約5.2秒/フレーム。2026-09・83ラン ch3 158f）を表示するので、そのままユーザーへの案内に使う
- 手動でzipだけ作る場合は従来コマンド（`cd 03_SCRIPTS && zip -r <NN>_<slug>_h3_bundle.zip <NN>_<slug> -x "*/ref_canvas_*" -x "*/validation/*" -x "*/.DS_Store" -x "*/h3/*"`）でもよいが、**`h3_run.py`と`build_h3_workflow.py`がzipに入っているかを`unzip -l`で必ず確認する**（この2本が無いとColabで全チャプターが失敗する）。**zipを展開して作り直す運用は避ける** — 実測でこの経路からツールが落ちた

- 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/`へコピー。**workflowが参照する画像・音声が実際に配備できたかをここで検証する**（不足があると重みDL完了後に `Invalid image file` で落ちるため早期に止める）。検証は**`CHAPTERS`指定時はその範囲だけ**を見る — 生成しないチャプターの素材不足で止める理由は無い（キーフレーム未生成のチャプターが残るラン・モード別ノートブック・1本だけ回すA/Bベンチで、無関係な不足に足を取られていた） |
| 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の両方**を見る＝セッションを跨いだ再開で退避済みチャプターを再生成しないのに加え、長時間ランの途中で別セッション・手動コピーが先に完成させたチャプターも上書きしない。グループ開始前の判定は「そのグループのために21GBのunetを落とすか」の下見のみ。`OUT_DRIVE_DIR`設定時は**完了ごとに即Drive退避**。`AUTO_SHUTDOWN=True`なら全チャプター成功＋Drive退避を確認後に**ランタイムを自動削除** |<br>**`TURBO_8STEP=True`（既定）のとき、生成の直前にworkflowへステップ蒸留を適用する**: 対象チャプターのユニットに応じたTurbo LoRA（1.4GB）をDLし、`LoraLoaderModelOnly`＋`MiniMaxH3SigmaShift(12/3)`を差し込んで`euler`/`beta`/8stepにする。ノードのクラス名・入力名は起動済みComfyUIの`/object_info`で確かめてから触り、名前が変わっていれば実機の定義を添えて止まる（`TURBO_8STEP=False`で従来の20stepに戻せる）。適用済みworkflowは再実行しても二重適用しない
| 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`）でも毎チャプター記録されるので、日常のランがそのまま速度の実測台帳になる。

### ステップ蒸留8step（`TURBO_8STEP` — 既定で有効・2026-09採用）

**20step → 8step で実測x2.34。** セル1の`TURBO_8STEP=True`（既定）でセル7が自動適用する。

計測（2026-09・L4+sage・`83_fukuchan_yotan_interview` ch3 R2V 158f＝6.6秒・同一シード）:

| arm | steps | 分 | s/step | vs base | 添付wavとの包絡一致 | baseとの映像差 PSNR/SSIM |
|---|---:|---:|---:|---:|---:|---|
| base（従来） | 20 | 37.5 | 101.9 | x1.00 | 0.95 | （基準） |
| **turbo8（採用）** | 8 | **16.0** | 105.5 | **x2.34** | **0.97** | 19.4 / 0.708 |
| pdd8（不採用） | 8 | 17.8 | 104.5 | x2.11 | **0.84** | 17.5 / 0.644 |

- **1stepの秒数は3armともほぼ同じ**（101.9 / 105.5 / 104.5）。差は純粋にstep数（20→8）から来ている＝
  蒸留が1stepを重くする副作用は無い。
- **品質はユーザーの目視で3armとも同等**。自動指標でもturbo8はbaseに最も近く、
  **添付wavとの包絡一致は0.95→0.97とむしろ上がった**（wavをAS-ISで使い続けている）。
- **pdd8を採らなかった理由**: 速度で劣り（x2.11）、公式PDD用のカスタムノードが要り、
  包絡一致が0.95→**0.84**と落ちた（目視では問題なかったが、指標が悪化した方をわざわざ採る理由が無い）。
- PSNRの平均と最小が近い（19.4/18.7）＝**差は全編に一様**で、特定フレームだけ破綻しているのではない。
- ラン全体への効き（83ラン・13チャプター・50秒）: **5.1時間・¥120〜180 → 2.5時間・¥60〜90**。

採用の条件と注意:

- LoRAは**ベンチした版に固定**してある（`minimax_h3_{fl2v,ref2v}_turbo_8step_v1.0_768p_comfyui_bf16.safetensors`
  ＠`lightx2v/Minimax-h3-Turbo`）。版を上げるときは**必ずベンチで測り直してから**セル7の`TURBO_LORA`を変える。
- レシピも測ったとおりに固定: `euler` / `beta` / 8step / `MiniMaxH3SigmaShift` video 12.0・audio 3.0。
  **サンプラーとshiftは蒸留の訓練条件**なので勝手に変えない。
- **新しいランでは従来どおりパイロット1本で声とリップシンクを確認してから残りを流す。**
  1チャプター1シードで測った結果なので、話者・尺・構図が変わったランでも同じとは限らない。
- 戻し方は`TURBO_8STEP=False`（セル1）だけ。バンドルもworkflowも作り直さなくてよい。

### 生成方式のA/Bベンチ（`h3_ab_bench_colab.ipynb`）

上のセル10が計測するのは**起動フラグ**だけ。**生成方式そのもの**（ステップ蒸留LoRA・sparse attention・重みのバリアント）を
同一チャプター・同一シードで比べて、**速度と精度の両方**を1枚のレポートにするのが本ノートブック。
「20ステップのまま回し続けてよいか」を判断するための道具で、採用を決めるまで本番の構成は変えない。

**作り方**（Claudeが実行する）:

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

正典`h3_colab.ipynb`のセル1〜9をそのまま取り込み（重み配置・ディスク管理・生成・Drive退避の機構を再利用するため）、
末尾にベンチ3セル（11=設定 / 12=実行 / 13=レポート）を足した`<ランディレクトリ>/h3/h3_ab_bench_colab.ipynb`を作る。
`--chapter ch8` / `--arms base,pdd8,sparse` で明示指定もできる。**正典を更新したらこのスクリプトを再実行**して反映させる。

対象チャプターの選び方（スクリプトが自動で行い、全チャプターの素材チェック表を出す）:

1. **入力ファイル（キーフレーム・シート・wav）が実際に揃っているチャプターだけを候補にする。** 素材不足は
   **ローカルで**弾く — Colabへ上げてDriveをマウントしてから落ちるのは、GPU課金を払ってから気付くということなので。
   明示指定したチャプターが揃っていなければ、不足ファイル名を挙げて止まる
2. その中から**R2V（セリフあり）を優先する** — wav駆動リップシンクの劣化がこのパイプラインの最大の関心事だから。
   揃ったR2Vが無ければI2Vで組み、「**この構成ではリップシンクは測れない**」と警告する
3. 選んだチャプターが160フレームより長ければ、**計測用に124フレーム（約5.2秒）へ切る**（セル11の`BENCH_FRAMES`）。
   全armで同じ尺なので比較は成立する。`0`にすれば台本どおりの尺に戻る。
   ⚠ **sparse armの効きは系列長に比例して大きくなる**ので、sparseの採用可否まで詰めるときは`BENCH_FRAMES=0`で測り直す

⚠ **キーフレームは直列チェーン**（各フレームが次の種になる・`gen_keyframes.sh`）なので、途中の1枚だけを作り直すことはできない。
素材の欠けたランでセリフありチャプターをベンチしたいなら、チェーンを通しで流し直すか、素材の揃った別のランを指定する。

**比較できるarm**（セル11の`BENCH_ARMS`。`base`は常に基準として先頭に入る）:

| arm | 中身 | 追加DL |
|---|---|---|
| `base` | **現行の本番設定**（そのGPUの既定重み・`res_multistep`/`simple`・20step） | — |
| `pdd8` / `pdd4` | 公式PDD Acc（alibaba-pai）8step / 4step。専用ノード＋`euler`＋訓練済みsigma＋CFG1 | node + 1.4GB |
| `turbo8` | lightx2v Turbo 8step v1.0 768p LoRA（素のLoRA・`euler`/`beta`・shift 12/3） | 約1.4GB |
| `sparse` | ComfyUI core の Block Sparse Attention（20step据え置き・attentionだけ疎に） | — |
| `enc_nvfp4` | テキストエンコーダを`nvfp4_awq`（14.6GB）へ。既定の`int8_convrot`は約32GB | 14.6GB |
| `unet_int8` | UNETを`int8_convrot`へ（**L4の既定は`fp8_scaled`**なのでAdaでのみ意味がある。A100は既定が同じ） | 21GB |
| `best` | `pdd8` + `enc_nvfp4` + `sparse` の合成（採用候補の最終確認） | 上記合計 |

**回し方**:

1. セル11で`BENCH_ARMS`を決め、**セル12をそのまま実行する**。既定`BENCH_DRY_RUN=True`＝**生成せず**に
   「各armのworkflowが実機のComfyUIで組めるか」を`/object_info`と突き合わせて検証し、所要時間とCU/円の見積りを出す。
   ノードのクラス名も入力名も**実機の定義から引く**ので、名前が変わっていれば実際の定義を添えて止まる（既定値のまま黙って走らない）。
2. 検証が通ったら`BENCH_DRY_RUN=False`にしてセル12を再実行 → armを順に生成する。
   成果物は`chN__<arm>.mp4`（生成済みはスキップ＝中断・再開・セッション跨ぎに強い）。
3. **セル13でレポート**。⚠ `BENCH_SHUTDOWN=True`だとセル12の最後で切断されるので、レポートは切断前に実行する。

**セル13が出すもの**（`<chapter>_ab_report.md`としてDriveへも退避。**そのままClaudeへ貼れば採用可否を相談できる**）:

- 性能: arm毎の wall分 / s per step / vs base / VRAMピーク / 円per本
- 精度（自動指標）:
  - **baseとの映像差**（PSNR平均・最小、SSIM）— 蒸留armは絵が変わって当然なので「劣化」ではなく**変化の大きさ**。最小PSNRが落ち込むフレームは破綻の疑いとして必ず目視する
  - **音声ピーク／クリップ数** — 低step蒸留で実際に報告のある劣化（6stepで−0.0dBまでクリップした第三者実測）。**base比で悪化したら不採用**
  - **添付wavとの包絡一致**（相関とオフセット）— 入力wavが素材としてそのまま使われているかの代理指標。**base比が大きく落ちたら「別の声を生成し始めた」疑い**
  - **キーフレーム追従**（先頭/末尾フレーム vs `ch*_start.png`/`ch*_end.png`のPSNR）— I2Vは厳密アンカーなので高いはず。R2Vは元々ゆるい
- 目で見る材料: **横並び動画**（全armを横に並べた無音mp4）と**コンタクトシート**（同一時刻のフレームをarm毎に1行）

**自動指標はスクリーニングであって合否ではない。** とくに**リップシンクは自動指標では判定しない**
（顔検出をしない全画面プロキシしか出していない）。合否はレポートの目視チェックリスト
（添付wavの声か／正しいキャラの口だけが鳴っている間だけ動くか／NG変更要素が崩れていないか等）と、
ローカルの`/image-validation`（Qwen3-VL）で確定させる。

**注意**:

- 重みを差し替えるarm（`enc_nvfp4`/`unet_int8`/`best`）は追加DLと入れ替えが起きる（L4のディスクは実測65GB）。
  **まずは重みを変えない`base`/`pdd8`/`turbo8`/`sparse`だけで回すのが安い。**
- 蒸留LoRAは**互いに併用できない**（PDDとlightx2vは同時に適用しない）。`euler`以外のサンプラーは訓練グリッド外を評価するので使わない。
- PDDは`SigmaShift`を**12.0/3.0ちょうど**に要求する。ベンチはSigmaShiftノードがあれば自動で挿すが、無い環境では警告して
  モデル既定のまま進む（音が破綻していたらここを疑う）。
- ベンチはバンドルの`chN_workflow.json`を書き換えて回すため、原本を`chN_workflow.orig.json`へ退避し、
  終了時に書き戻す。異常終了した場合は`.orig.json`から手で戻す。
- **採用を決めたら、実測を`H3_COLAB.md`と本スキル0章・5章へ反映してから**正典`h3_colab.ipynb`の既定を変える。
  ベンチで勝っただけでは本番構成を変えない。

### アドホック生成（セル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>`で逐語埋め込み。
   - **Action beats（`Beat 1 (0–1.2s): …`）はそのまま残す**（seedanceステップ1「アクションビート」）。尺を17k+5グリッドへ丸めたときは、最後のビートの終了秒だけ新しい尺に合わせる。ビートが無い旧ランを変換する場合は、変換時にFirst/Last frameの記述から起こして追記する — 中間の動きが台本と違う事故は、両端のキーフレームでは防げない。
   - **音声のセマンティクス差**: 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と同じ）。