ray-broll

Ray Broll

一言のナレーションを鋭いビジュアルアイデアに凝縮し、何もない色場から一つずつ組み立てていく、編集メタファーを用いたコラージュアニメーションにします。

ray-cover の姉妹スキルです。「編集メタファーを用いたコラージュ」という共通のビジュアル体系を共有しています。cover は静止画のカバーを、broll は動きのある B-roll を制作します。ブランド化を避ける同じ方針に従い、特定ブランドや現役アーティストの識別可能な作風は模倣せず、「Vox」系の要望は、説明可能な編集コラージュの手法（ハーフトーン網点、色紙、keyline、色場）に一律に置き換えます。

デフォルトの流れ：

1. ビジュアルメタファーだけを設計し、ユーザーの確認を待つ（Gate 1）
2. 最終静止画だけを生成し、ユーザーの確認を待つ（Gate 2）
3. 動画モデルを呼び出して始点・終点フレームからアニメーションを組み立て、QA を完了する（Gate 3）

3 つのゲートはコストの低い順に並んでいます。メタファーは無料、静止画は安価、動画は最も高価です。バッチ処理では、承認された項目だけを通します。ユーザーから「止まらずに最後まで直接実行して」と明確な許可があれば全自動で実行できますが、各 Gate の QA 文書は必ず作成してください。

環境のセルフチェック

実行のたびに、まず以下を実行します：

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

すべて PASS ならそのまま開始します。FAIL がある場合は、不足項目の設定方法だけをユーザーに提示し、設定後に再度セルフチェックします。実測で確認した落とし穴が 2 つあります：

• agent セッションの shell 環境は起動時のスナップショットです。ユーザーが GEMINI_API_KEY を ~/.zshrc に書き込んだばかりの場合、コマンド内で明示的に source ~/.zshrc を実行しないと参照できません。
• 動画スクリプトのダウンロード手順は macOS の venv で CERTIFICATE_VERIFY_FAILED エラーになります。このスキルの generate_video.py には certifi の自動接続が組み込まれているため、手動で SSL_CERT_FILE を設定する必要はありません。venv 内の pip install で同じエラーが出る場合は、SSL_CERT_FILE=$(venv/bin/python -m certifi) pip install ... を使います。
• bash バッチスクリプトでは set -e と source ~/.zshrc を併用しないでください。bash 内で zsh 構文を使うとエラーになり、スクリプト全体が警告なしに中断します（バッチジョブが出力なしでそのまま失敗します）。必要な変数だけを抽出するのが正しい方法です：export GEMINI_API_KEY=$(grep -o 'GEMINI_API_KEY="[^"]*"' ~/.zshrc | cut -d'"' -f2)。

モデル

• 静止画：gemini-3-pro-image（品質優先。安価な代替モデルは gemini-3.1-flash-image）
• 動画：gemini-omni-flash-preview による始点・終点フレームの補間（スクリプトのデフォルト値。ユーザーが明示的に指定しない限り Veo に変更しないでください）
• ナレーション：gemini-3.1-flash-tts-preview（scripts/generate_tts.py、デフォルトは Charon の声）

3 つすべてで同じ GEMINI_API_KEY を共有し、従量課金です。実測コストの目安（2026-07）：動画は 1 本あたり約 $0.3 で圧倒的に高く、静止画は 3-pro で 1 枚あたり約 $0.11、TTS は無視できる程度です。8 ビートの解説動画 1 本で約 $3.5 です。

コスト管理

• 失敗した場合は失敗した job だけを再実行し、バッチ全体の再実行は禁止です——生成はサーバー側で課金されるため、ダウンロードに失敗しても料金は発生しています
• Gate 3 のたびに QA 文書へコストを 1 行記録します：生成回数 × モデル（失敗作も含む）。コストを可視化します
• コスト削減策は、効果の大きい順に次のとおりです：静止画を flash クラスに切り替えて試行 → シンプルな剛体動作（スライドイン／位置合わせ系のビート）を HyperFrames の確定的なアニメーションに変更し、動画モデルは物理的な質感が必要なカット（破裂／貫通）だけに使用 → 量産段階で Flow サブスクリプションのクレジット方式を検討します。後半 2 つはどちらも実測済みです。操作の詳細は references/flow-runbook.md を参照してください（L2 Flow クレジット + L3 HyperFrames ステッカー分離パイプライン）
• API 側では AI Studio のプロジェクト月次 spend cap に注意してください。上限に達するとすべての呼び出しが 429 になります。ai.studio/spend で上限を引き上げるか、月初のリセットを待ちます。利用停止中は Flow 内の Nano Banana 2 を静止画／ステッカー生成の代替として使えます

成功基準（ビジュアル文法）

• 一文で表現するのは明確なメタファー 1 つだけとし、重要なオブジェクトは 4 グループ以内にします
• 背景は鮮やかでフラットかつ均一な色場とし、意味に応じて色を選びます。同じバッチ内ではデザイン言語を統一しつつ、背景色は変えます
• 主体は白黒のハーフトーン写真切り抜きを骨格とし、情報の階層化に一部の色紙を使います
• すべての紙片に明確な裁断エッジ、クリームホワイトの keyline、透明度を抑えた柔らかな影、紙の粒子感を付けます
• 動きは何もない状態から一つずつ組み立てるものであり、漂流、揺れ、ゆっくりとしたズームにはしません
• 字幕、ナレーション全文、ロゴ、透かし、UI は入れません
• デフォルトの納品形式は 9:16、5 秒、720×1280、24fps、無音の MP4 です

色の意味

背景色	意味
焦げオレンジ／赤	時間の消費、労働、緊迫感
マスタードイエロー	ツール、警告、経験の喪失
インクグリーン／ディープティール	認知、判断、協働、自動実行
ディープパープル	規範、蓄積、長期記憶

アクセントカラーはクリームホワイト／マスタードイエロー／オレンジ系に統一し、バッチごとに個別判断しないでください。

プロジェクトディレクトリ

~/hyperframes-projects/YYYY-MM-DD-collage-broll-标题/   # 北京时间命名
├── brief.md                  # 文稿 + Gate 1 隐喻记录
├── 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-概念名/
    ├── imagegen-prompt.txt / omni-prompt.txt
    ├── frames/{last-frame-original.png, first-frame.png, last-frame.png, bg-hex.txt}
    └── omni/run-v01/{final-5s.mp4, final-5s-noaudio.mp4, contact-sheet.jpg,
                      video-first-frame.jpg, video-last-frame.jpg, end-frame-comparison.jpg}

Gate 1：メタファーの設計

各原稿から核心となる意味、感情、動詞を抽出し、1 つのビジュアル命題に凝縮します。成果物：核心となる意味／感情／一文のビジュアル命題／重要なオブジェクト 4 グループ以内／推奨する背景色とアクセントカラー／想定される組み立て順序。その後、確認を待ちます。

実測に基づく、構成のずれを防ぐ知見：オブジェクトが 4 グループを超える場合、または絡み合い・交差する空間関係（フィルムがハサミに巻き付くなど）がある場合、動画モデルは構図を並べ替えやすくなります。正確な位置決めが必要な項目では、グループ数を抑え、平面的な配置にします。多少のずれを許容できる項目に限り、より複雑な構成にできます。

バッチのメタファーは、前後の物語の流れ（例：手作業による消耗 → プロセスへの蓄積 → 自動実行）を優先して作り、物語の進行に合わせて背景色を切り替えます。

Gate 2：静止画の生成

Imagegen プロンプトのテンプレート

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; [N] 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.

必須制約（実測済み）：付箋、カード、本のページなどのオブジェクトには、"carrying only abstract wavy squiggle doodle lines — absolutely no letters or words" を明示的に追加してください。追加しないと、偽の文字が生成される可能性が高くなります。偽の文字が出たら静止画に戻って再生成してください。動画プロンプトでの修正は期待しないでください。

生成と QA

~/hyperframes-projects/.omni-venv/bin/python <本skill目录>/scripts/generate_image.py \
  --prompt-file <item>/imagegen-prompt.txt \
  --output <item>/frames/last-frame-original.png --aspect-ratio 9:16 \
  [--style-ref <第一张过审静帧>]

バッチではバックグラウンドで並列実行します（& + wait）。スタイルアンカー：バッチプロジェクトではまず 1～2 枚を試作し、最初に承認された静止画を --style-ref として残りの生成に渡します。これにより、一貫性を祈るのではなく、参照画像の仕組みで確保できます。QA チェックリスト：メタファーが一目で伝わる／主体が集中している／偽の文字、ロゴ、透かし、UI がない／色場の余白が十分にある／明確な大きなグループが 4 つ以内／バッチ内で質感が統一されている。番号付きのコンタクトシートを生成してユーザーに提示し、Gate 2 の確認を待ちます。再生成する場合は v2、v3 とバージョンを上げ、旧版も比較用に残します。

Gate 3：動画の生成

1. 始点・終点フレーム（重要な落とし穴：背景色には実測値を使う）

生成画像の背景色は、プロンプトに記載した hex より少し濃くなります。空の始点フレームから組み立てシーンへ切り替える際に色が跳ねないよう、生成画像から実際の背景色をサンプリングする必要があります。スクリプトに組み込み済みです：

bash <本skill目录>/scripts/prepare_frames.sh <item-dir> [采样点x:y]

1 つのコマンドで、色をサンプリング（4×4 の平均値 → frames/bg-hex.txt）し、1080×1920 の終点フレームと単色の空の始点フレームを作成します。サンプリング位置はデフォルトで左上の座標 28:58 です。複数のオブジェクトが端に接している場合は、座標を変更してください。

2. Omni アニメーションプロンプトのテンプレート

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: [按组装顺序描述各组如何 slide in / snap into place / 完成动作]. End by holding the supplied completed composition.

Preserve the exact 9:16 framing, [实测hex] color field, [点色] 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.

3. バッチ呼び出し

video-jobs.json の各 job は {prompt, image: [first-frame, last-frame], output, aspect_ratio: "9:16", duration: 5} です。provider（省略時は google。集約経由の fal）と model（fal では kling-o3-standard／kling-o3-pro／seedance-2.0／seedance-2.0-fast）は任意です。

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

dispatcher は provider ごとにグループ化して振り分けます：google → generate_video.py（従来どおりの動作で、旧 omni-jobs.json とそのまま互換）；fal → fal_driver.py（FAL_KEY が必要で、始点・終点フレームは data URI としてインラインでアップロードされます）。終点フレームのパラメーターを明示的にサポートするモデルだけを fal_driver.py の MODEL_MAP に登録してください。終点フレームをサポートしないモデルは、単一画像からの動画生成に黙ってフォールバックするのではなく、job を拒否してください。

• --resume：出力がすでに存在し、ffprobe の検証に合格している job は自動的にスキップされます。再実行時は必ず指定してください。「失敗した job だけを再実行する」ことを、規律ではなくツールによって保証します
• コスト記録の自動化：実行のたびに、新しく生成された job の推定コストを jobs と同じディレクトリの cost-ledger.jsonl に追記し、集計を出力します（fal は MODEL_MAP の価格、google は推定値を使用。GOOGLE_VIDEO_USD_PER_SEC で上書き可能）。Gate 3 の QA 文書では、集計行を引用するだけでかまいません
• google 側で legacy Interactions API の schema エラーが発生した場合は、古い SDK が使われています。共有 venv の python に切り替えてください

4. サイレント納品の強制 + QA 成果物

bash <本skill目录>/scripts/qa_video.sh <成片.mp4> <确认静帧.png> [输出目录] [bg-hex]

1つのコマンドで、サイレント版、秒単位のコンタクトシート、実際の開始／終了フレーム、終了フレームの比較画像を作成し、客観的なスコアを2つ出力します（qa_score.py：開始フレームの純度 ≥0.97 はクリーンな空の画面、終了フレームの再現度 ≥0.90 は高い再現度です。このスコアは確認済みの静止画との構図レベルの一致度を測るもので、HyperFrames による再構図では低くなるのが通常です。参考値としてのみ使用してください）。スコアは補助証拠として QA ドキュメントに記載し、目視確認の代わりにはしません。

バッチプロジェクトでは、さらに overview.py --project <dir>（beats.json を読み込みます）を実行して、3種類の一覧を統合します。各項目のコンタクトシートを vstack で結合したもの、実際の開始フレームを横並びにしたもの（すべて空の画面から始まっていることを確認）、終了フレームの比較を vstack で結合したものです。

動画 QA 基準

• 開始フレームはほぼ単色の空の画面です。端がわずかに早く見える程度なら許容されます
• 中盤では各要素が順番に組み立てられる様子が見えます。全体がフェードインするのではありません
• カット切り替え、ズーム、3D 化、写実的な逸脱、偽文字がないこと
• 終了フレームが確認済みの静止画と一致していること。軽微なポーズのずれは、比喩の意味が変わらなければ合格と判定し、このために再実行しないでください； 中程度の構図変更（物体の移動や拡大縮小）があっても、意味が保たれていれば「合格（注記あり）」と判定し、gate3-qa.md に記載します
• 720×1280、24fps、5秒、音声トラックなし

QA の結論は項目ごとに gate2-qa.md / gate3-qa.md に記載します。不備があっても通過とした場合は、その判定理由も含めてください。

完全な解説動画モード（beat map → 45～60秒の完成動画）

1文の B-roll の上位となる、2つ目の制作方法です。1つのテーマ（または ray-writer / ray-kb による完成稿の判定）を入力すると、ナレーション、字幕、内容に応じたテンポを備えた縦型の解説動画を作成します。全体は beat map 層 + 各 beat で上記の3つのゲートを通す工程 + 組み立て層で構成されます。

1. Beat map（Gate 1 の完全動画版）

テーマを8～10個の beat に分解し、各 beat に20～30字のナレーション1文と1つの比喩を設定します。ストーリーに関する議論は brief.md に記載し、構造化データはプロジェクトのルートディレクトリに beats.json として記述します（唯一の信頼できる情報源です。スキーマは references/beats-manifest.md を参照してください。prepare / assemble / overview / qa はすべてこれを読み込みます）。

• ストーリーアーク：まず内容の種類に応じて、references/narrative-arcs.md の14種類のアークから選びます （意見→opinion、マーケティング→pas/aida、科学解説→myth_buster、歴史→timeline、 人物→origin/story_spine…）。アークの beat 列が role 列となり、役割によって話速の段階と映像の重みが決まります
• ビジュアルテーマ（Gate 1.5 bake-off）：references/theme-presets.md から候補を2～4種類選び、 同じ beat をそれぞれ1枚ずつレンダリングしてユーザーに選んでもらいます。選ばれたプリセットを動画全体に適用して --style-ref のスタイルアンカーとし、 完成後もプリセットを切り替えて restyle できます
• 映像内のタイトル：hook / closing beat には headline を設定できます（切り絵の厚紙に大きな文字を載せ、 render_headline.py で決定論的にレンダリングするため、中国語の偽文字は発生しません。AI が生成する映像には引き続き文字を入れないでください）
• 生成ルート：各 beat に route を指定します。剛体のスライドイン／位置合わせ／積み重ねのような組み立てには hyperframes を使います（生成コストゼロ、決定論的、レンダリング7.5秒。パイプラインは references/flow-runbook.md L3 を参照）。破裂／貫通／変形／有機的な動きには video-model を使います。 8 beat の動画では通常、半数以上の beat を hyperframes で処理でき、1本あたりのコストを約 $3.5 から約 $1 に抑えられます
• 色彩のストーリーテリング：隣接する beat の背景色は異なるものにし、感情の進行に合わせて色を変えます（例：黄色で問いかけ → 青緑で状況提示 → オレンジでリスク → 赤で突破 → 紫で飛躍 → 緑で仕組み → 黄色でまとめ → 紫で締めくくり）
• 抽象概念を扱う beat（「2種類」「3つの段階」など）は、要素を盛り込みすぎる大きな原因になります。Constraints では必ず “The image contains ONLY these N groups and absolutely nothing else” という形式を使い、 Avoid で混入を避ける物体（trophies, clocks, hearts, compasses, arrows, hands, currency symbols）を列挙し、単色の空間を40％以上確保するよう指定します

2. ナレーションと速度変更

各 beat にTTSを1つ生成します（scripts/generate_tts.py。並列実行できます）。style prompt で話速を調整しないでください （実測では±2％しか変化しません）。組み立て層で ffmpeg の atempo を使い、役割ごとに速度を変更します。

beat の役割	atempo	末尾の間
フック（冒頭の問いかけ）	1.04	0.35s
定義／説明／転換の文	1.09–1.10	0.35s
権威ある判断／名言	1.05	0.50s
まとめ	1.07	0.35s
締めくくりの問いかけ／名言	1.02	0.85s

原則：重要な言葉はゆっくり、つなぎの言葉は速く話します。「ゆっくり + 間」で強調し、視聴者が問いを抱えたまま動画を見終えるように締めくくります。

3. 字幕

scripts/render_caption.py（Pillow + PingFang、2行形式、クリーム色の文字 + 半透明の黒い角丸ボックス） で beat ごとに字幕 PNG を1枚レンダリングし、組み立て時に (W-w)/2:H-h-170 にオーバーレイします。ffmpeg の drawtext には依存しません（ローカルビルドの多くには含まれていません）。

4. 組み立て

python <本skill目录>/scripts/assemble.py --project <dir>

beats.json をすべて自動で読み込みます。ffprobe でナレーションの実測時間を取得（手作業で転記するミスを防止）→ 役割テーブルから tempo/tail を導出 → beat の長さ = max(動画の長さ, lead + ナレーション/tempo + tail)。不足分は tpad で終了フレームを静止させて補います → 不足している字幕 PNG を自動でレンダリング → 1回の filter_complex で組み立て → volumedetect で確認（目標 max ≈ -1~-2dB）→ assembly/assemble-report.json に書き込みます。 manifest で tempo / tail を明示すると、役割テーブルの値を上書きできます。テンポに関するフィードバックは manifest のみを変更して再組み立てすればよく、 素材の再生成は不要で、コストもかかりません。

よくある問題

• 組み立て感が弱い → 物体グループの数を減らし、prompt を各要素が順にスライドインして所定位置にはまる明確な順序に変更します
• 終了フレームがずれる → "Image 2 is the exact completed last frame" を強調します。それでもずれる場合は Gate 1 に戻って空間的な関係を単純化します
• 偽文字が現れる → 静止画を再生成します（文字禁止の制約を追加）。動画 prompt で修正しないでください
• 空の画面を厳密に求める場合に、開始フレームの端に要素が現れる → HyperFrames で冒頭部分を補います
• 質感が写実的すぎる／3D になる → prompt で "Restrained tactile 2D paper craft only" を強調します

使用しないケース

• 正確なレイヤー、オクルージョン、カメラの通過、編集可能なタイムラインが必要 → HyperFrames
• prompt だけが必要で、完成動画は不要 → prompt を直接記述します
• 実写のトーク動画、製品の実写広告 → このワークフローは使用しません

出典

ワークフローと動画スクリプトは gbro-collage-broll（MIT、© 2026 狗哥笔记）を参考に改変し、Claude Code 環境に適応させています。静止画生成には Gemini 画像 API を使用しています（元は Codex 組み込みの image_gen に依存）。certifi による SSL 修正と、実測した背景色のサンプリング工程を内蔵しています。同種のオープンソースの参考例：vox-director。