loop-video

name: loop-video description: "Use when コレクションのサムネイル画像からループ動画背景を生成したいとき。Veo 3.1 API で main.png/jpg を元に微細アニメーション付きの 8秒シームレスループ動画を生成。ループ動画、背景動画、loop.mp4、アニメーション背景、動画背景など、静止画を動画化する場面で必ず使用すること"

Overview

Veo 3.1 API を使い、コレクションの main.png/jpg から 8秒のシームレスループ動画を生成します。 生成された loop.mp4 は generate_videos.sh が自動検出し、静止画の代わりに動画背景として使用します。

前提

config/channel/ が存在すること（load_config() でロード可能）。

存在しない場合、ユーザーに確認:

• 新規チャンネル → /channel-new を案内
• 既存チャンネル（YouTube で既に運営中）→ /channel-import を案内

ループ動画化の有効/無効: skill-config の enabled（default true）で制御する。config/skills/loop-video.yaml::enabled: false のチャンネルでは本スキルは実行不可で、yt-generate-loop-video は fail-loud で停止する（Veo 課金を防ぐ）。サムネが完成済みでループ動画のリターンが Veo コストに見合わないチャンネルは false にする。

Script

Quick Reference

再実行時のコスト警告

Veo 3.1 は課金 API（モデルにより 1 本あたり数十円〜数百円）。デフォルト経路は 既存 loop.mp4 を skip せず、loop-v{n}.mp4 に退避してから Veo を再度叩く（=フル再課金）。同じコレクションで yt-generate-loop-video <path> を素で繰り返すと、その回数だけ Veo クレジットが消費される点に注意。

既存 loop.mp4 がある状態での挙動マトリクス

既存ファイル不在で --smooth を指定した場合は [ERROR] --smooth は既存 loop.mp4 を必要としますが見つかりません で exit 1（fail-loud）。Veo を叩かずに失敗する。

運用ガイドライン

• 冪等再実行のデフォルト: バッチや CI から繰り返し叩く経路では --skip-existing を必ず付ける。既存があれば 0 円で no-op、無ければ通常生成にフォールバック（ではなく early exit のため事前に生成済みの前提を明示）。
• 継ぎ目だけ直したいとき: --smooth を 単独 mode として使う。/loop-video で 1 度生成 → 品質確認 → 継ぎ目が気になる → --smooth 再実行、という二段運用にすれば Veo は 1 回しか叩かない。
• 本気で作り直したいとき: 素の yt-generate-loop-video <path> -y を再実行。既存は loop-v{n}.mp4 に自動退避されるため上書き事故はない。ただし 必ず Veo 再課金が発生するので意図的に行うこと。

Instructions

対象コレクション

$ARGUMENTS

引数が指定されている場合、そのコレクションを対象とします。 未指定の場合、collections/planning/ から thumbnail.approved = true かつ loop.mp4 が未生成のコレクションを自動検出します。

前提条件

• 10-assets/main.png または main.jpg が存在すること（サムネイル生成済み）
• Vertex AI ADC が初期化されていること (gcloud auth application-default login + set-quota-project)。project_id は ADC quota project から自動解決される（GOOGLE_CLOUD_PROJECT は任意で上書き可）。region は generate_loop_video.py 側で us-central1 を明示固定するため GOOGLE_CLOUD_LOCATION は不要
• gcloud auth application-default login で ADC が取得済みであること

ステップ

1. 対象確認: 10-assets/ に main.png or main.jpg があることを確認
2. プロンプト検討: シーンに応じた自然な動きを指定
   • デフォルトプロンプトは skill-config (config/skills/loop-video.yaml または .claude/skills/loop-video/config.default.yaml) の veo.default_prompt を使用
   • シーンに合わない場合は --prompt でカスタマイズ
3. 生成実行: uv run yt-generate-loop-video <collection-path> -y
   • 冪等再実行が必要な場面（CI / バッチ / 「もう生成済みか分からない」ケース）では --skip-existing を付けて Veo 再課金を避ける
4. 品質確認: ユーザーに loop.mp4 を確認してもらう
5. ループ確認: 継ぎ目が気になる場合は --smooth 単独 mode で再実行（uv run yt-generate-loop-video <path> --smooth -y）。Veo は叩かず FFmpeg クロスフェード補正のみ適用するため 追加課金は発生しない。--smooth は post-process 専用 mode で、生成と post-process は別コマンドとして 2 段に分かれている — 「再生成 + post-process」を 1 コマンドでまとめる API は 意図的に提供していない（再生成は明示的なフル再課金イベントとして扱うため）

構造化プロンプト（推奨）

「動かす対象」と「固定対象」をリストで明示する方式。Veo 3.1 公式推奨のポジティブ表現テンプレートに展開される。default_prompt の単一文字列より事故率が低い（動物の数が変わる / 肩から鳥が湧く等の現象を抑制）。

プロンプト解決の優先順位:

Veo 3.1 公式推奨:

• ポジティブ表現で書く（"do not animate X" より "only Y moves, the rest remains exactly as in the source image"）
• count / shape を肯定文で固定: "two animals (count remains 2)", "the character (same posture)" のように数や形を明示
• 微動語彙: subtle, gentle, slight, barely perceptible, slow sway, living painting
• I2V は 50〜100 words が目安（テンプレが既に圧縮されている）

動かす対象（motion_targets）の例:

• slow leaves swaying, gentle leaves fluttering（屋外）
• subtle steam rising from coffee, steam from mug（カフェ/書斎）
• gentle candle flame flicker, slow candle flicker（室内）
• slight character breathing（人物のみ動かしたいとき）
• soft light shifts on surfaces（光のみ）
• rain streaks on window（雨シーン）
• slow subtle ripples on water surface（水辺）
• subtle monitor glow shifts（書斎・モニター）

固定対象（static_targets）の例:

• the character (same posture, same expression) — 人物の姿勢/表情固定
• two animals (count remains 2) — 動物の数固定
• keyboard, monitor frame, books, desk objects — オブジェクト固定
• interior structure, background elements — 背景固定
• dessert plates, cups and saucers — 小物固定

チャンネル別 structured 設定例

config/skills/loop-video.yaml の上書き例:

rjn（lo-fi jazz × rainy night）:

veo:
  motion_targets:
    - "rain streaks on window"
    - "subtle steam rising from coffee"
    - "soft light shifts on surfaces"
  static_targets:
    - "the character (same posture, same expression)"
    - "dessert plates and cups"
    - "interior structure"

deepfocus365（deep focus × deep house）:

veo:
  motion_targets:
    - "subtle monitor screen glow shifts"
    - "slow steam from coffee mug"
    - "slight character breathing"
  static_targets:
    - "the character (same posture)"
    - "keyboard and monitor frame"
    - "books and desk objects"

bobble（cafe ambience）:

veo:
  motion_targets:
    - "subtle steam from coffee"
    - "soft light shifts"
  static_targets:
    - "the character"
    - "cups, plates, and counter items"

freeform プロンプトガイドライン（後方互換）

default_prompt を直接書く旧方式。structured が使えない場合のみ。

基本テンプレート:

Static scene with only natural subtle movements: [シーン固有の動き].
No smoke, no magical effects, no particles, no falling objects.
Keep the scene calm and grounded, like a living painting.

避けるべき表現:

• smoke, particles, falling leaves（不自然な追加要素が生成される）
• magical effects（原画にない要素が追加される）
• butterflies, insects（描画品質が低く不自然になる）
• dramatic movement（BGM チャンネルには過度な動き）

サードパーティ IP ガードレール

Veo 3.1 は画像内容からディズニー等の IP を認識すると 生成をブロック する。 PD（パブリックドメイン）の童話キャラでも、ディズニー版に似た見た目だと弾かれる。

ブロックされた場合の対策:

• プロンプト変更では回避不可（画像自体が判定される）
• 背景のみの画像を別途生成して Veo に渡す
• または静止画背景のまま運用

設定

skill-config (.claude/skills/loop-video/config.default.yaml) で管理。チャンネル側上書きは config/skills/loop-video.yaml:

ループ動画化を停止したいチャンネルは 1 行で無効化できる:

# config/skills/loop-video.yaml
enabled: false  # default: true。/loop-video は fail-loud 停止、/videoup は静止背景を使用

veo:
  model: "veo-3.1-fast-generate-001"

  # structured prompt（推奨）
  motion_targets:
    - "slow leaves swaying"
    - "subtle steam rising from coffee"
  static_targets:
    - "the character"
    - "two animals (count remains 2)"

  # freeform プロンプト（後方互換、structured 未指定時のみ使用）
  default_prompt: |
    Static scene with only natural subtle movements...

  duration_seconds: 8
  crossfade_sec: 0.5

Integration

loop.mp4 が 10-assets/ に存在すると、generate_videos.sh v11.0 が自動検出し、 静止画の代わりにループ動画を背景として使用します（24fps、CRF 20）。

パイプラインは Veo 生成 → strip_audio → CRF 圧縮（compression.enabled=true のとき）。 --smooth 経路でも同じ crf/preset が適用されるため、/loop-video → --smooth のいずれの順でも 最終的な loop.mp4 ビットレートは設定値（既定 CRF 22 ≒ 3〜4 Mbps）に揃う。

中断 (Ctrl+C) 時の挙動

yt-generate-loop-video の Veo 生成中に Ctrl+C を送ったときの挙動は、運用上以下の通り厳密に決まっている。「中断 = キャンセル = 無料」ではないことに注意。

現状のコード挙動 (cancel API 未利用)

ポイント:

• Veo API には operations.cancel 相当が現状未実装 (client.operations.cancel は未提供)。本スキルの実装 (utils/veo_generator.py) も KeyboardInterrupt を捕捉してメッセージ表示と state 保存だけを行い、cancel API を呼んでいない。Ctrl+C はあくまでローカルプロセスを止めるだけで、API 側のジョブとクレジット消費は止められない。
• submit が成功した時点で課金は確定する想定で運用する。中断は「節約」にはならず、せいぜい「次回の二重課金を resume で防ぐ」効果しかない。
• 中断 → 即再実行すれば、保存済み operation_name から resume して既課金分を回収できる（loop.mp4 を取り出せる）。再課金は発生しない。
• 完全に捨てる場合でも、state ファイル (<CHANNEL_DIR>/tmp/veo-operations/<output-hash>.json) を手動削除しない限り、次回 yt-generate-loop-video 実行時に resume を試みる点に注意（不要なら削除）。

運用ガイドライン

• submit 成功後の Ctrl+C は「無料化」ではなく「次回 resume の予約」と思え。クレジット節約目的で中断してはいけない。
• 真に止めたい（誤プロンプトでの submit など）場合でも、submit が通った後は API 側のジョブを止める手段が（現状コードからは）ない。submit 前に prompt を確認すること。
• ループ動画化そのものを停止したいチャンネルは config/skills/loop-video.yaml::enabled: false で CLI ごと無効化する（yt-generate-loop-video が fail-loud で停止し、submit 自体が走らない）。
• 将来 Veo API が operations.cancel を公開し、本スキルの実装が対応した場合は、Ctrl+C で API 側 operation も cancel して以降のクレジット消費を停止する挙動に変わる予定。現状はその段階に到達していないため、上記の「中断してもクレジットは消費される」前提で運用する。

state ファイルの場所

• パス: <CHANNEL_DIR>/tmp/veo-operations/<output-hash>.json
• 中身: { "operation_name": "operations/...", "model": "veo-3.1-fast-generate-001", "output_path": "..." }
• 再開不要なら手動削除可（次回実行は新規 submit になる）

長時間処理の取り扱い

yt-generate-loop-video は Veo 3.1 API を同期ポーリングするため 30〜90 秒 程度（モデルとリージョン次第）かかる。必ず Bash ツールを run_in_background=true で起動する。これによりユーザーは処理中も同じセッションで質問できる（Claude Code は完了時に自動でメッセージ通知するため、sleep ループや until での自前ポーリングは禁止）。

spawn 例:

uv run yt-generate-loop-video <collection-path> -y > /tmp/loop-video-$(date +%s).log 2>&1

これを Bash run_in_background=true で投げ、spawn 直後に次のメッセージを返す:

⏳ Veo 3.1 でループ動画を生成中（推定 30〜90 秒）。完了まで他の質問にもお答えできます。 ログ: /tmp/loop-video-*.log

cmux 環境下（$CMUX_WORKSPACE_ID あり）であれば補助で cmux set-status "loop-video" "running" --icon "hourglass" --color "#f59e0b"、完了で cmux clear-status "loop-video" + cmux notify --title "loop-video 完了" を呼ぶ（非 cmux 環境では skip）。

完了通知が届いたらログ末尾から結果サマリー（10-assets/loop.mp4 のパス）をユーザーへ返す。--smooth 再実行時も同じパターンで起動する。IP ガードレールでブロックされた場合のエラーメッセージはログから抜き出して報告する。

障害時ガイダンス

Next Step

ループ動画生成後: → /videoup <collection-path> でマスター動画を生成

参考リンク

• Ultimate prompting guide for Veo 3.1 (Google Cloud Blog)
• Veo prompt guide (Google DeepMind)