loop-video

前後工程

• 前工程: /thumbnail
• 後工程: /videoup

Overview

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

thumbnail.jpg は YouTube アップロード用のテキスト付きサムネイルであり、/loop-video の入力には使わない。/thumbnail で先に生成・承認したテキストなし main.png または main.jpg を入力にする。

動画構成は skill-config の video_type で明示し、現行 generator は loop を実装する。新しいタイプの追加箇所と hook 契約は .claude/skills/videoup/references/video-type-extension.md を参照する。

完了条件

10-assets/loop.mp4 が生成され、ユーザーの品質確認（「ステップ」5-6）を通過したとき完了とする。継ぎ目補正が必要になった場合は、--smooth 適用後の loop.mp4 をユーザーが確認するまでを完了条件に含める。

確認・プレビュー承認ゲート

• 生成・リトライ・--smooth の各処理が成功するたび、10-assets/loop.mp4 を動画として再生できるプレビューで開く。静止画やキーフレームだけを提示して代替してはならない
• /thumbnail と同じ順序で、成果物を開いた後に AskUserQuestion の明示 2 択「承認する」/「受理せず修正する」を提示する
• ユーザーに承認されるまで /videoup などの後工程へ進まず、完了報告もしない
• 「受理せず修正する」の場合は現行 loop.mp4 を最終出力として扱わない。継ぎ目だけの問題は --smooth、動き・構図・静止画 fallback は prompt 調整後の Veo 再生成へ戻す。Veo 再生成はフル再課金なので、既存の課金承認を再度得るまで実行しない
• 修正またはリトライ成功後は [改善しました] と表示し、直後に再び同じ動画プレビューを開く。改善したというメッセージだけで承認済みにしてはならない

Subagent Contract

subagent として呼ぶ場合、メインエージェントは対象コレクション、入力 10-assets/main.png/jpg、確定済み mode と prompt をリポジトリルート相対パスまたは値で入力に含める。Veo 課金、再生成、品質確認の承認が必要なら、メインが承認を得るまで subagent を起動しない。subagent は workflow-state.json を読み書きせず、AskUserQuestion を実行しない。完了報告には status: success | failure、生成または補正した 10-assets/loop.mp4 の絶対パス、使用 mode、エラーを含める。メインはファイル存在を検証し、品質確認を担当する。直接実行時は既存手順を変更しない。

設定読み込みゲート

前提確認や Step 1 に入る前に、以下を必ず Read（Codex では同等のファイル閲覧）で開く。SKILL.md の説明や記憶から設定値を推測しない。

1. .claude/skills/loop-video/config.default.yaml
2. config/skills/loop-video.yaml（存在する場合）

読み込み後は youtube_automation.utils.skill_config.load_skill_config("loop-video") と同じ deep-merge 前提で、チャンネル上書きを優先して扱う。存在しない override は未設定として扱い、勝手に作成しない。

前提

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

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

• 新規チャンネル → /channel-new を案内
• 既存チャンネル（YouTube で既に運営中）→ /channel-new（既存チャンネル取り込みモード）を案内

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

バックアップ保持数: 通常生成で既存 loop.mp4 を loop-v{n}.mp4 へ退避した後、skill-config の max_backups（default 3）を超えた最古のバックアップを自動削除する。チャンネル別の保持数は config/skills/loop-video.yaml::max_backups で上書きできる。--skip-existing / --smooth 経路では退避も削除も行わない。

Script

Quick Reference

再実行時のコスト警告

Veo 3.1 は課金 API（モデルにより 1 本あたり数十円〜数百円）。デフォルト経路は 既存 loop.mp4 を skip せず、loop-v{n}.mp4 に退避してから Veo を再度叩く（=フル再課金）。退避後のバックアップは max_backups（default 3）まで保持し、超過分は最古から削除する。同じコレクションで 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 に自動退避され、max_backups まで保持される。ただし 必ず Veo 再課金が発生するので意図的に行うこと。

想定 API call 数

• 上限 / 承認: 実行前に [y/N] プロンプトで承認する（-y でスキップ）。enabled: false のチャンネルでは fail-loud で停止し Veo を叩かない。

Instructions

対象コレクション

$ARGUMENTS

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

前提条件

• 10-assets/main.png または main.jpg が存在すること（/thumbnail で先に生成・承認したテキストなし動画背景）
• 10-assets/thumbnail.jpg ではなく、テキストなし main.png/jpg を入力にすること
• Veo は Vertex AI ADC が初期化されていること (gcloud auth application-default login + set-quota-project)。Omni は GEMINI_API_KEY（環境変数または op://Personal/Gemini_API_Key/credential）が必要

ステップ

1. 有効/無効確認: config/skills/loop-video.yaml::enabled を確認。false なら Veo を実行せず、main.png/jpg の静止画背景運用として終了する

2. 対象確認: 10-assets/ にテキストなし main.png or main.jpg があることを確認。文字入り thumbnail.jpg しか無い場合は /thumbnail に戻って textless 背景を生成・承認する

3. プロンプト検討: シーンに応じた自然な動きを指定

   • デフォルトプロンプトは skill-config (config/skills/loop-video.yaml または .claude/skills/loop-video/config.default.yaml) の veo.default_prompt を使用
   • シーンに合わない場合は --prompt でカスタマイズ

4. 生成実行: uv run yt-generate-loop-video <collection-path> -y

   • 冪等再実行が必要な場面（CI / バッチ / 「もう生成済みか分からない」ケース）では --skip-existing を付けて Veo 再課金を避ける

5. 確認・プレビュー承認ゲート: 生成された loop.mp4 の絶対パスを解決して動画プレイヤーで開く。Codex アプリでは同じ絶対パスを動画として会話内に表示してもよい

   LOOP_VIDEO_PATH="$(cd <collection-path>/10-assets && pwd)/loop.mp4"
   open "$LOOP_VIDEO_PATH"
   

   静止画、先頭フレーム、サムネイルだけでは合否を判定できないため、必ず動画として再生する。ユーザーには次のチェック項目を提示する:

   • 再生開始後、時間経過で被写体または背景が実際に動く（静止画 fallback ではない）
   • 意図した対象だけが自然に動き、固定対象の数・形・構図が保たれる
   • 末尾から先頭へ繰り返し再生してもループの継ぎ目が不自然でない

   プレビューを開いた後、AskUserQuestion で /thumbnail と同じ並びの明示 2 択を提示する:

   1. 承認する — 現在の loop.mp4 を受理し、完了できる
   2. 受理せず修正する — 修正フローへ戻り、後工程には進まない

6. 不受理時の修正 → 再プレビュー: 受理しない場合は、観測した問題から次の経路へ戻す

   • ループの継ぎ目だけが不自然: --smooth 単独 mode で再実行（uv run yt-generate-loop-video <path> --smooth -y）。Veo は叩かず FFmpeg クロスフェード補正のみ適用するため 追加課金は発生しない
   • 動きがない / 静止画 fallback / 意図しない対象が動く / 構図が崩れる: motion/static targets または prompt を修正する。Veo 再生成の内容とフル再課金を表示し、ユーザーの承認後にだけ通常生成を再実行する

   どちらの経路も処理成功時に [改善しました] と表示し、Step 5 に戻って再び同じ動画プレビューを開く。ユーザーが「承認する」を選ぶまで Step 5-6 を繰り返し、/videoup へ進まない。--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 の文言のみで制御する（issue #1747）:

• 既定 prompt_template は {motion_clause} に強度断定（subtle 等）を付加しない。強度語は motion_targets の各項目に含める
• 静かな動き: subtle steam rising from coffee, gentle candle flame flicker のように微動語彙を対象側に書く
• はっきりした動き: clearly rolling ocean waves, steady rain falling のように書けば、テンプレ側の弱化文言と矛盾せずそのまま効く

動かす対象（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（v14）が自動検出し、 静止画の代わりにループ動画を背景として使用します（24fps、CRF 22 で正規化）。

パイプラインは 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 で防ぐ」効果しかない。
• 中断 → 同じ model・同じ入力画像で即再実行すれば、保存済み operation_name から resume して既課金分を回収できる（loop.mp4 を取り出せる）。再課金は発生しない。
• model または入力画像を変えて完全に作り直す場合は、state を手動削除する必要はない。次回 yt-generate-loop-video 実行時に自動で state を破棄して新規 submit する。

運用ガイドライン

• 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": "...", "input_image_sha256": "..." }
• 再実行時は model と入力画像内容の SHA-256 が両方一致した state だけを resume する。不一致または旧形式の state は破棄して新規 submit する
• 再開不要なら手動削除可（次回実行は新規 submit になる）

長時間処理の取り扱い

yt-generate-loop-video は Veo 3.1 API を同期ポーリングするため 30〜90 秒 程度（モデルとリージョン次第）かかる。必ず Bash ツールを run_in_background=true で起動する。これによりユーザーは処理中も同じセッションで質問できる（Claude Code は完了時に自動でメッセージ通知するため、sleep ループや until での自前ポーリングは禁止）。Codex など run_in_background 非対応の実行環境では、同コマンドを nohup ... > <log> 2>&1 & で background 起動し、完了はログ末尾で確認する読み替えとする。

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)
• Gemini Omni Flash video generation (Google AI for Developers)