gbro-collage-broll

gbro Collage B-roll

約 5 秒のナレーションをシャープな視覚的アイデアに凝縮し、上質なエディトリアル風の紙コラージュ組み立てアニメーションにします。

デフォルトの流れ：

1. 視覚的なメタファーだけを設計し、ユーザーの確認を待つ
2. 最終静止画だけを生成し、ユーザーの確認を待つ
3. Gemini Omni Flash を自動で呼び出して動画を生成し、QA を完了する

この 2 つの確認ゲートはワークフローの一部です。ユーザーが美的方向性や全体の方向性に集中できるようにし、誤ったメタファーや静止画によって動画生成コストが無駄になるのを防ぎます。

初回使用時：環境セルフチェック

この skill を起動するたびに、Gate 1 に入る前にセルフチェックのスクリプトを実行します：

bash <本skill目录>/scripts/check_setup.sh

すべて成功した場合は、そのまま Gate 1 を開始し、設定情報をユーザーに繰り返し伝えないでください。項目が 1 つでも失敗した場合は初回使用とみなし、Gate 1 には進まず、まず以下の設定ガイドをユーザーに提示します（不足項目のみを列挙）。ユーザーが設定完了を確認したら、セルフチェックを再実行します。

設定ガイド（不足項目に応じて出力）

1. GEMINI_API_KEY が設定されていない Google AI Studio で API key を作成し、shell の設定に書き込みます：

   echo 'export GEMINI_API_KEY="你的key"' >> ~/.zshrc && source ~/.zshrc
   

   注意：動画生成は従量課金で、該当する key に紐づいた Google アカウントに請求されます。

2. ffmpeg / ffprobe が見つからない macOS：brew install ffmpeg；Debian/Ubuntu：sudo apt install ffmpeg。

3. Python 環境がない、またはバージョンが古い（>= 3.10 が必要） macOS：brew install python3；または python.org からインストールします。

4. 共有 venv が作成されていない（google-genai >= 2.10.0） ユーザーの同意を得て自動作成します。ユーザーによる手動操作は不要です：

   python3 -m venv ~/hyperframes-projects/.omni-venv
   ~/hyperframes-projects/.omni-venv/bin/python -m pip install --upgrade "google-genai>=2.10.0" "httpx[socks]"
   

5. Codex 環境ではない／組み込みの image_gen がない Gate 2 の静止画生成には、Codex に組み込まれた image_gen ツールが必要です。他の agent 環境で実行する場合は、同等の画像生成方法を自分で用意する必要があることをユーザーに説明します（または静止画を手動で用意し、Gate 2 から続行する確認を行います）。

必須の承認プロトコル

Gate 1：メタファーの確認

原稿を受け取ったら、まず視覚的なメタファーを提案します。画像や動画は生成せず、動画モデルも呼び出しません。

各項目について、以下をユーザーに提示します：

• 核となる意味
• 感情
• 一文で表す視覚的な命題
• 3～6 個の主要なオブジェクト
• 背景色とアクセントカラーの提案
• 想定する組み立て順序

その後、明確に停止して、ユーザーが「よいです」「承認」「すべて承認」と返信するか、項目ごとの修正意見を提示するのを待ちます。

ユーザーが一部の番号だけを承認した場合は、承認された項目だけを Gate 2 に進めます。未承認の項目は、メタファーの修正を続けます。

Gate 2：静止画の確認

メタファーの承認後に限り、visual spec と imagegen prompt を作成し、Codex の imagegen で最終静止画を生成します。

元画像をプロジェクトディレクトリに保存し、番号付きの静止画 contact sheet を生成してユーザーに提示し、再び停止します。この段階では、まだ Omni Flash を呼び出さず、動画も生成しません。

ユーザーが一部の静止画だけを承認した場合は、承認された静止画だけを Gate 3 に進めます。修正が必要な静止画は再生成して、再度確認を取ります。

Gate 3：動画生成

静止画の承認後は、使用する動画モデルを再度尋ねず、この skill に付属する scripts/generate_video.py を直接使用して、デフォルトで以下を呼び出します：

gemini-omni-flash-preview

ユーザーが他の動画モデルを明確に指定した場合に限り、このデフォルトを上書きします。Veo を自動で呼び出さないでください。また、モデルの選択をユーザーに再度委ねないでください。

成功基準

• 一文で表すメタファーは、明確なものを 1 つだけにします
• 同じバッチの映像でデザイン言語を統一しつつ、すべてを青い背景にする必要はありません
• 背景は強く、フラットで均一な色面にし、意味に応じて変化させられます
• 主体の骨格には、白黒のハーフトーン写真の切り抜きを使用します
• 重要なカード、ボタン、フィルム、ルールブックなどには、赤、黄、シアン、オレンジ、紫、クリーム色などの色紙を使用できます
• すべての紙片に、はっきりした裁断エッジ、クリーム色の keyline、低透明度の柔らかな影、紙の粒子感を持たせます
• 動きは空の状態から組み立てるものであり、わずかな漂い、揺れ、ゆっくりしたズームではありません
• 字幕、ナレーション全文、logo、透かし、UI は使用しません
• デフォルトの納品形式は 9:16、5 秒、720×1280、24fps、音声なしの MP4 です

使用しないケース

• レイヤー、オクルージョン、カメラの通り抜け、または編集可能なタイムラインを正確に制御する必要がある場合：レイヤーアニメーションツール（HyperFrames のような HTML レンダリング動画ソリューションなど）を使用します
• 動画プロンプトだけが必要で、完成動画の生成が不要な場合：プロンプトを直接作成し、このプロセスは使用しません
• 実在の人物を使った製品広告や、ナレーションを行う出演者が必要な場合：このコラージュのプロセスは使用しません
• ユーザーがレイヤーごとに編集可能な透明素材を明確に希望する場合：この skill ではデフォルトで透明レイヤーに分割しません

デフォルトのプロジェクトディレクトリ

北京時間 Asia/Shanghai で命名します：

~/hyperframes-projects/YYYY-MM-DD-collage-broll-标题/

バッチプロジェクトに推奨する構成：

<project>/
├── brief.md
├── visual-spec.json
├── imagegen-prompts.md
├── omni-jobs.json
├── gate2-qa.md
├── gate3-qa.md
├── still-contact-sheet.jpg
├── omni-contact-sheet-all.jpg
├── video-first-frame-all.jpg
├── end-frame-comparison-all.jpg
├── 01-概念名/
│   ├── omni-prompt.txt
│   ├── frames/
│   │   ├── last-frame-original.png
│   │   ├── first-frame.png
│   │   └── last-frame.png
│   └── omni/run-v01/
│       ├── final-5s.mp4
│       ├── final-5s-noaudio.mp4
│       ├── contact-sheet.jpg
│       ├── video-last-frame.jpg
│       └── end-frame-comparison.jpg
└── 02-概念名/...

Phase 1：視覚的なメタファーを設計する

まず原稿を 1 つの視覚的な命題に凝縮します。

抽出する項目：

• 核となる意味：最終的に視聴者に理解してほしいこと
• 感情：冷静、驚き、緊迫、腑に落ちる感覚、不条理、皮肉
• 動作を表す動詞：開く、つなぐ、漏らす、綴じる、ファイルする、点灯する、圧縮する、分岐する、組み立てる
• 視覚化できるメタファー：機械、時計、フィルム、ファイルキャビネット、コンソール、ルールブック、漏斗、軌道、駒

原稿を逐語的に画面に入れないでください。デフォルトでは、1 つの原稿につきメタファーは 1 つだけにし、主要なオブジェクトは 3～6 個に抑えます。要素が多すぎると意味が弱まり、Omni の組み立ても不安定になります。

バッチのメタファーは、前後のストーリーを優先して構成します。たとえば、まず手作業による消耗と経験の喪失を表現し、次に規範の蓄積と人間・機械の役割分担を表現します。

Gate 1 の出力例

1. 核心意思：经验每次都在重复消耗
   视觉隐喻：熟练剪辑师围着巨大的胶片时钟逐帧裁切，时钟走完一圈却只得到一小段成片
   关键物件：胶片时钟、剪辑师、剪刀、短胶片
   色彩：焦橙底，奶油白与浅青点色
   组装顺序：时钟 → 人物与剪刀 → 胶片 → 最终短输出

出力後は停止して、確認を待ちます。

Phase 2：カラーコラージュ静止画を生成する

メタファーの承認後、まず自己完結した visual-spec.json を作成し、次に imagegen prompt を作成します。

Visual spec

{
  "script_meaning": "",
  "visual_metaphor": "",
  "style_signature": "flat bold color field, mixed black-and-white halftone cut-outs and colored cardstock accents, crisp cut edges, cream keylines, soft paper shadows, editorial paper collage",
  "aspect_ratio": "9:16",
  "color_field": {
    "background_hex": "",
    "accent_colors": [],
    "paper_grain": "fine uncoated-paper fiber"
  },
  "elements": [
    {
      "what": "",
      "role": "",
      "motion": "",
      "placement": ""
    }
  ],
  "composition": {
    "layout": "",
    "negative_space": "",
    "final_frame": ""
  },
  "motion_plan": "structure first, subject or cards second, action and result last",
  "avoid": "typography, readable letters, numerals, logos, watermark, UI, subtitles, glossy 3D, photoreal environment"
}

色のルール

cobalt blue を唯一のデフォルトカラーにしないでください。意味に応じて強い色面を選び、作品のバッチ内で「統一されたデザイン言語、異なる背景色」を保ちます：

• 焦げたオレンジ／赤：時間の消費、労働、緊迫感
• マスタードイエロー：ツール、警告、経験の喪失
• 墨色のグリーン：認知、美的感覚、システムのリセット
• 濃い紫：規範、蓄積、長期記憶
• 青緑：判断、協働、自動実行

主体は白黒のハーフトーンを中心にできますが、部分的な色紙は情報の階層に役立つものにします。色を付けるためだけに色を使わないでください。

Imagegen prompt テンプレート

Codex に組み込まれた image_gen ツールを使用します（ローカルに imagegen skill がある場合は、それにも従います）：

Use case: ads-marketing
Asset type: final still frame for a 9:16 image-to-video B-roll clip
Primary request: Create a finished editorial paper-collage image expressing [一句话视觉命题].
Scene/backdrop: perfectly flat [颜色] paper field [hex] with subtle uncoated paper fiber.
Style/medium: premium editorial stop-motion paper collage; black-and-white halftone photographic cut-outs mixed with selective [点色] colored cardstock.
Composition/framing: vertical 9:16 locked poster frame; central subject within the middle 70 percent; generous clean color-field negative space; 3–6 large separable paper groups for later assemble-from-empty animation.
Materials/textures: visible printed halftone dots, crisp machine-cut edges, thin warm-cream paper keylines, soft low-opacity physical drop shadows.
Constraints: [本条隐喻必须一眼看懂的关系].
Avoid: no typography, no readable letters, no numerals, no logos, no watermark, no UI, no subtitles, no glossy 3D, no photoreal environment, no clutter.

静止画 QA

• メタファーが一目で理解できるか
• 主体がまとまっているか
• 偽の文字、logo、透かし、UI がないか
• 空の状態から組み立てるのに十分な無地の色面が残されているか
• 画面全体に細片が散らばっているのではなく、3～6 個の明確な大きなグループになっているか
• 同じバッチ内で質感が統一されつつ、色に変化があるか

QA に合格した元画像をプロジェクトディレクトリにコピーし、番号付きの静止画 contact sheet を生成して、ユーザーに提示したうえで停止し、Gate 2 の確認を待ちます。静止画の QA 結果は <project>/gate2-qa.md に記録します。

ユーザーが一部の静止画の再生成を求めた場合は、再生成後に still-contact-sheet-v2.jpg を作成します（以降は v3、v4…と増やします）。比較できるよう、旧版の contact sheet は上書きせずに残します。

Phase 3：Omni Flash で動画を生成する

1. 開始フレームと終了フレームを準備する

imagegen の元画像を保持し、終了フレームを統一します：

ffmpeg -y -i <item>/frames/last-frame-original.png \
  -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920" \
  <item>/frames/last-frame.png

開始フレームはデフォルトで、終了フレームと同じ背景色の無地の紙面にします：

ffmpeg -y -f lavfi -i color=c=0x<HEX>:s=1080x1920 \
  -frames:v 1 <item>/frames/first-frame.png

ユーザーが完全な空白から始めないよう明確に求めた場合に限り、開始フレームに基本のオブジェクトを 1 つ残します。

2. Omni のアニメーション prompt を作成する

デフォルトの動作順序：

基础结构 → 人物或关键卡片 → 连接件 → 动作 → 最终结果

Prompt テンプレート：

Paper-collage stop-motion assembly, using Image 1 as the exact empty first frame and Image 2 as the exact completed last frame. In one continuous locked-off vertical shot, open on the empty flat [color] paper field.

Assemble the scene piece by piece with crisp physical stop-motion timing: [按顺序描述 3–6 个元素如何滑入、卡位、连接和完成动作]. End by holding the supplied completed composition.

Preserve the exact 9:16 framing, [hex] color field, colored cardstock accents, uncoated paper grain, halftone dots, cream keylines, crisp cut edges and soft shadows. Restrained tactile 2D paper craft only.

No scene cuts, no camera movement, no zoom, no morphing, no new objects, no text, no letters, no numbers, no logos, no watermark, no UI, no sound.

各 prompt で、Image 1 が空の開始フレーム、Image 2 が承認済みの完成フレームであることを明確にします。最終構図は Image 2 に近づけ、モデルに終了フレームを自由に作り変えさせないでください。

3. Omni の実行環境を確認する

実際に実行スクリプトで使う Python インタープリターを使用して、google-genai のバージョンを確認します。>= 2.10.0 が必要です。

システムの Python バージョンが古すぎる場合、または externally managed environment の場合は、--break-system-packages を使用しないでください。共有の隔離環境 ~/hyperframes-projects/.omni-venv/ を使用します。すでに存在する場合はそのまま再利用し、存在しない場合に限って作成します。プロジェクトごとに .venv を新規作成しないでください：

[ -x ~/hyperframes-projects/.omni-venv/bin/python ] || {
  python3 -m venv ~/hyperframes-projects/.omni-venv
  ~/hyperframes-projects/.omni-venv/bin/python -m pip install --upgrade "google-genai>=2.10.0" "httpx[socks]"
}

GEMINI_API_KEY が設定されていることを確認します。ただし、キーの内容を出力または記録しないでください。

4. Gemini Omni Flash を一括で呼び出す

omni-jobs.json を作成します。各 job では 2 枚の画像を使ってキーフレーム補間を行います：

{
  "prompt": "<omni prompt>",
  "image": [
    "<item>/frames/first-frame.png",
    "<item>/frames/last-frame.png"
  ],
  "output": "<item>/omni/run-v01/final-5s.mp4",
  "aspect_ratio": "9:16",
  "duration": 5
}

この skill に付属するスクリプトを使用します：

~/hyperframes-projects/.omni-venv/bin/python \
  <本skill目录>/scripts/generate_video.py \
  --batch <project>/omni-jobs.json \
  --concurrency 3

デフォルトのモデルは gemini-omni-flash-preview です。legacy Interactions API schema エラーが発生した場合は、古い SDK を誤って使用していることを意味します。共有環境の ~/hyperframes-projects/.omni-venv/bin/python に切り替えて再試行し、Veo に切り替えないでください。

5. 音声なしで納品を強制

プロンプトに no sound と記載されていても、ffmpeg を使用して音声トラックなしのバージョンを出力します。

ffmpeg -y -i <run>/final-5s.mp4 \
  -map 0:v:0 -c:v copy -an \
  <run>/final-5s-noaudio.mp4

デフォルトでは final-5s-noaudio.mp4 を納品し、元の final-5s.mp4 は中間生成物として残します。

動画 QA

最後のフレームだけを見るのではなく、組み立ての過程と最終的な配置を必ず確認します。

コンタクトシート

ffmpeg -y -i <run>/final-5s-noaudio.mp4 \
  -vf "fps=1,scale=270:480,tile=5x1" \
  -frames:v 1 <run>/contact-sheet.jpg

合格基準：

• 最初のフレームがほぼ単色の空の画面であること。端から紙片がわずかに早く見えても許容されます
• 中盤で、全体がフェードインするのではなく、構造物、人物、カードなどが徐々に入ってくる様子が確認できること
• カット切り替え、ズーム、3D 化、写実的なシーンへの逸脱がないこと
• 意味のない文字、ロゴ、透かし、UI がないこと
• 最終フレームが確認済みの静止画と一致していること。人物の姿勢がわずかに変わる、小さな部品が増減するといった軽微なポーズや細部の変化は、比喩の意味に影響しなければ合格とします。そのために再実行しないでください
• 完成動画が 720×1280、24fps、5 秒、音声トラックなしであること

さらに、動画の最後のフレームを抽出し、確認済みの静止画と並べて end-frame-comparison.jpg を生成します。バッチプロジェクトでは、次の 3 枚の総覧画像も作成します。

• omni-contact-sheet-all.jpg：すべての完成動画から 1 秒ごとに抽出したフレーム
• video-first-frame-all.jpg：すべての完成動画の実際の最初のフレーム。単色の空の画面から本当に始まることを確認します
• end-frame-comparison-all.jpg：確認済みの静止画と動画の最後のフレームを並べた比較画像

不備がありながら合格とする場合の理由も含め、各項目の QA 判定を <project>/gate3-qa.md に記録します。

よくある問題

• 最初のフレームの端から要素が早く見える：わずかであれば許容します。完全な空の画面が必要な場合は、HyperFrames を使って前半を追加してください
• 組み立て感が弱い：要素数を減らし、プロンプトで要素が一つずつ slide in し、所定の位置に snap into place する順序を明確に指定します
• 最後のフレームがずれる：「Image 2 is the exact completed last frame」と「End by holding the supplied completed composition」を強調します
• 意味のない文字が現れる：まず静止画に戻って再生成します。動画プロンプトで直接修正しないでください
• 一部の動画が失敗する：該当する job だけを再実行し、合格済みの項目は再実行しないでください

デフォルトの納品物

ユーザーには次を納品します。

• 各 <item>/omni/run-v01/final-5s-noaudio.mp4
• 各項目のコンタクトシート
• バッチ全体のコンタクトシート
• 最終フレームの比較画像
• 各原稿をどのように視覚的な比喩に変換したかを説明する一文

完成動画の問題が Omni の高速生成の制限によるものであれば、その旨を直接説明します。HyperFrames への切り替えは、レイヤーを正確に制御する必要がある場合にのみ提案してください。

旧 Veo スクリプト

ディレクトリ内の scripts/generate_veo_first_last.py は、旧プロジェクトとの互換性のためだけに残されています。デフォルトのワークフローでは呼び出さないでください。ユーザーから Veo を明示的に求められた場合にのみ使用してください。