vox-director

Vox Director

1行のトピックから、完成したVox風のペーパーカットコラージュ動画を作成します。各ビートが動き出す切り絵コラージュのポスターとなり、ナレーション、音楽、字幕が付いた、インパクトのある歯切れのよい解説・広告動画です。必要なのはAtlas Cloud API キー1つとローカルのffmpegだけです。

このビジュアルは、Voxの解説動画やStav Zilber、rom1trsのようなクリエイターによって広まった、現代的なエディトリアル・ペーパーカットコラージュです。手で切り抜いた紙片、破れた縁、テープ、網点、新聞の切り抜き、ビートごとの鮮やかなベタ塗り、大きな切り抜き見出しが特徴です。

核心となるアイデア（まずお読みください）

Vox風コラージュの見た目とコラージュの動きは、別々の工程です。

1. 見た目は画像生成の工程で生まれます。 各ビートは、テキストから画像を生成するモデルで作られた、完成したコラージュポスターです。コラージュのDNA（破れた紙、切り抜き、網点、鮮やかな色、見出しテキスト）はすべて画像に含まれます。画像に豊かなコラージュ感がなければ、その後の工程では補えません。
2. 動きはその後に加えます。 デフォルトでは、AI動画モデルがポスター全体にアニメーションを付けます（シンプルで自動化された「動くポスター」方式）。ドラマチックなパーツごとの組み立てを表現するには、ポスターをパーツに分割し、ローカルのキーフレームエンジンで動かします（上級者向けの方式）。

すべてはプロンプト次第です。画像または動画のプロンプトを書く前に、references/prompt-guide.mdをお読みください。「本物のVox風コラージュ」と「動くPowerPoint」を分ける、具体的なプロンプトの構成が記載されています。

前提条件（必ず確認してください）

• echo "${ATLASCLOUD_API_KEY:+set}" — 空の場合は、ユーザーにAPIキーの設定を案内し（https://www.atlascloud.ai/console/api-keys で取得できます）、作業を中止してください。
• command -v ffmpeg ffprobe — 動画の組み立てに必要です（macOSではbrew install ffmpeg）。
• python3 -c "import PIL" — 字幕・透かしのオーバーレイに必要なPillowです。

標準ワークフロー（トピック → 映像）

デフォルトで最も自動化された方法です。各工程はスクリプト1つで実行し、プロジェクトごとのout/<project>/にある単一のbeats.jsonですべてを管理します。

1. トピック → ビートマップ。 まずストーリーのレイヤーである**references/beat-layer.mdをお読みください**。トピックに合ったナラティブのarcを選びます（歴史ならtimeline、広告ならpas/bab、解説ならhow_it_works、変革ならman_in_holeなど）。次に、そのアークに沿ってout/<project>/beats.jsonを作成します。ビート1の見出しは3秒以内のフックにします。尺に応じたビート数（30秒→6～8、60秒→10～12）を設定し、各ビートを2つのショット（ワイド＋ディテール）に分けます。隣り合うビートでショットごとのcamera_moveに変化を付け（繰り返しは禁止。見せ場ではstatic）、豊かなelement_motionを指定します（手順4を参照）。各ビートにはnarration、title_cn/title_en、scene、bg、feel、hookを指定します。この草案が唯一の必須承認ゲートです。生成前にビートマップをユーザーに提示してください。例はexamples/にあります。

2. ビジュアルスタイルを選ぶ（ハイブリッド方式 — キーフレーム作成前に実施）。 すべてのトピックに同じ定番スタイルを使い回さないでください。references/prompt-guide.mdの§5「テーマプリセット」を読み、トピックの時代・文化・トーンに合うテーマプリセットを3～4個選びます（styles.THEME_PRESETSのamerican-retro、swiss-modern、punk-zine、soviet-constructivist、wpa-propaganda、70s-groovy、chinese-ink、atomic-age）。合うプリセットがない場合は、プロンプトガイドの要素（メディア／時代／配色／書体／仕上げ）を組み合わせてカスタムテーマを作ります。言語ではなく、トピックに合わせてください（中国の歴史を扱う英語の映像なら、中国らしい見た目にします）。テーマにはLOOKレイヤー全体（表現様式＋配色＋書体＋仕上げ＋ムード＋動き）が含まれます。複数案を作って比較し、見た目で選んでもらいます。AIが候補を提案し、ライブラリが品質の下限を担保し、最終的には人が決めます。選んだテーマを"theme"に設定します。 python3 scripts/style_bakeoff.py out/<project> american-retro,swiss-modern,punk-zine,atomic-age 選んだ名前をbeats.jsonの"collage_style"に設定します（keyframes.pyが読み込みます）。

3. キーフレーム（コラージュ風のルック）。 python3 scripts/keyframes.py out/<project> google/nano-banana-2/text-to-image を使って、ビート／ショットごとにコラージュポスターを1枚生成し、 見出しテキストも焼き込みます。references/prompt-guide.md にある5パート構成でプロンプトを作成します。 アニメーション化する前に、各ポスターが本物のレイヤーコラージュのように見えることを確認してください。 ここで安価に（$0.08）再生成するほうが、弱い画像のアニメーション化に費用をかけるよりよいでしょう。

4. モーション。 python3 scripts/clips.py out/<project> google/gemini-omni-flash/image-to-video を使って各ポスターをアニメーション化します。独立した2つの軸があります （references/beat-layer.md §3 を参照。こちらのスタックでテスト済みです）。 • camera_move — 1ショットにつき1つの動き。安全なデフォルトは {static, push_in, pull_out, pan, tilt, parallax} です。大胆／実験的な動き {orbit, dolly_zoom, roll, whip} も使用可能であり、禁止ではありません。ただし、 平面的なアートが歪むことがあるため、constraints: loose と組み合わせて再生成してください。 カスタムのフレーズもそのまま渡されます。 • element_motion — エネルギーを生み出す要素です。各シーンに合うよう、AIがビートごとに記述します（テンプレートではありません）。 動きを豊かに（複数の要素を動かして）してください。大胆に表現しましょう。画面を横切って飛ぶ主役要素 （紙の鳥／飛行機／コインなど）は、キービートで時折使うと効果的ですが、すべてのショットでは使わないでください （すべてのフレームに飛ぶものがあると、ワンパターンに見えます）。 motion_style は振幅を表し、calm | punchy | max から選びます（テーマによってデフォルトが設定されます）。constraints は strict（デフォルト。欠陥を防ぐ制約が有効で、フラットな2D、一方向の動き、変形なし。テキストの多い説明動画に最適）または loose（モデルに3Dや大胆な動きを試させ、うまくいかないものは再生成）です。見出しテキストが厳密に保護されるのは、タイトルがあるショットのみです （見出しのないディテールショットは自由に大胆な動きを付けられます）。実在の人物／ブランドロゴの場合、OmniとSeedanceは拒否するため、 "video_model": "kwaivgi/kling-video-o3-pro/image-to-video" を設定してください。

5. 音声＋音楽。 python3 scripts/audio.py out/<project> xai/tts-v1（多言語対応、voice_id）を使って一貫したナレーター音声を生成し、minimax/music-2.6 で インストゥルメンタルのBGMを生成します。（注意点を参照。話者を固定しない限り、通常のナレーションにseed-audioは使わないでください。）

6. 組み立て。 python3 scripts/assemble.py out/<project> ffmpegで、すべてのショットを正規化して連結し、ナレーション1本を音量調整して音楽の下に重ね、 ビートごとのタイミングに合わせた字幕を焼き込み、ウォーターマークを追加します。出力先は out/<project>/final.mp4 です。

7. 確認。 mp4を直接読むことはできません。フレームをjpgに抽出して確認してください。 ffmpeg -ss <t> -i final.mp4 -vf "scale=640:-1,format=yuvj420p" -frames:v 1 f.jpg

カデンス — ショットの長さ

よくある間違いは、ビートごとに1つの長いショットを使うことです。特に9:16のSNS向け動画では、 静止した10秒のショットは間が空いているように見えます。約4～6秒ごとにカットすることを目指してください。

• ショットは3～6秒とし、1つのショットが約7秒を超えないようにしてください。それ以上ではAIのモーションに展開の余地がなくなり、静的に感じられます。
• 1ビートのナレーションは約8～10秒なので、各ビートにショットを2つ用意します（見出しのあるワイドな導入ショットと、見出しのないディテールの挿入ショット）。ナレーションは両方のショットにまたがって連続し、映像は文の途中でカットします。これがリズムを大きく改善するポイントです。
• そのため、約60秒の動画は通常、6ビート×2ショット×約5秒＝12ショットほどとなり、6ショット×10秒ではありません。
• ワイドのキーフレームをショット a として再利用し、ショット b にはさらに寄ったディテールシーンを生成します。 keyframes.py はすでに keyframe_url があるショットをスキップするため、ショット b を追加して再実行すれば、新しいショットだけが生成されます。

各ビートに shots 配列を追加してください（スキーマを参照）。各ショットには短い scene と motion を設定します。見出しがビートごとに1回だけ表示されるよう、ワイドショットにのみ "title": true を設定してください。

beats.json スキーマ

{
  "project": "my-film", "topic": "...", "language": "en",
  "aspect": "9:16",                       // 16:9 | 9:16 | 1:1 | 3:4
  "style": "collage",
  "provider": "atlas_cloud",              // media backend — default; pluggable (scripts/provider.py)
  "theme": "american-retro",              // THEME_PRESET (styles.THEME_PRESETS) — the LOOK layer
  "arc": "timeline",                      // narrative arc (beat-layer.md) — the STORY skeleton
  "video_model": "google/gemini-omni-flash/image-to-video",  // Kling for real people
  "motion_style": "punchy",               // amplitude: calm | punchy | max (theme sets a default)
  "constraints": "strict",                // strict = defect guards on | loose = let AI explore + re-roll
  "voice": {"voice_id": "leo", "language": "en", "speed": 1.0},
  "music": "epic cinematic orchestral, instrumental, no vocals",
  "mix": {"music": 0.6, "voice": 1.25},   // audio balance — optional; these are the defaults (BGM ducks under the VO)
  "watermark": "Made with Atlas Cloud",
  "beats": [
    {
      "id": 1, "title_cn": "", "title_en": "BEFORE MONEY",
      "bg": "earthy clay tan", "feel": "ancient, humble", "hook": "surprising_stat",
      "narration": "For most of history, there was no money...",
      "shots": [
        // shot_size: EST_WIDE|WIDE|MEDIUM|CLOSE|DETAIL ; camera_move: static|push_in|
        // pull_out|pan|tilt|parallax (flat-safe only) — VARY per adjacent beat, static for payoff
        {"id": "a", "dur": 5, "title": true,  "shot_size": "WIDE", "camera_move": "push_in",
         "scene": "...wide establishing collage...",
         "element_motion": "traders gesture, goat bobs, a paper bird flaps across the frame, coins scatter"},
        {"id": "b", "dur": 5, "title": false, "shot_size": "CLOSE", "camera_move": "parallax",
         "scene": "...close cut-in detail...",
         "element_motion": "the exchanged goods slide together, halftone pulses"}
      ]
    }
  ]
}

theme と arc が2つの大きなレイヤーを設定し、ショットごとの element_motion がエネルギーを生み出します（下記を参照し、豊かな動きを付けてください）。motion／collage_style／era も後方互換性のため引き続き読み込まれます。

モデルの選択（IDは必ず最新のものを確認してください）

モデルIDは変更されるため、まず最新のリストを取得してください：GET https://api.atlascloud.ai/api/v1/models （認証不要。display_console: true のものだけを残します）。現在利用できるデフォルト設定は次のとおりです。

用途	モデル	備考
キーフレーム／コラージュポスター	google/nano-banana-2/text-to-image	中国語と英語のテキストを適切に描画します
要素の切り抜き	youchuan/v8.1/remove-background	高度な方法でのみ使用します
アニメーション化（実在しないコンテンツ）	google/gemini-omni-flash/image-to-video	テキストを安定させ、レイヤー化された動きを維持します
アニメーション化（実在の人物／ブランド）	kwaivgi/kling-video-o3-pro/image-to-video	Omni と Seedance は著名人をブロックします
ナレーション	xai/tts-v1	明瞭で、多言語に対応し、voice_id を指定できます
音楽	minimax/music-2.6	is_instrumental: true

モデル選択の詳しい理由と、API／ffmpeg の注意点（認証ヘッダー、curl によるダウンロード、no-libass 字幕、コンテンツブロックなど）については、references/models-and-gotchas.md を参照してください。 失敗のデバッグを始める前に読んでください。ほとんどの失敗について、すでに説明されています。

バックエンドはプラグインで切り替えられます。 すべての API 呼び出しは プロバイダー（scripts/provider.py）を経由します。現在は Atlas Cloud がデフォルトかつ唯一のバックエンドです。別のバックエンドが追加されたら、beats.json の "provider" を設定して切り替えられます。ステージスクリプトを変更する必要はありません。scripts/provider.py の run_jobs() は、処理が停滞または失敗した場合に自動で再送信しながら、ジョブの送信とポーリングも行います。

上級編：要素単位のモーションコラージュ

標準的な方法では、ポスター全体をアニメーション化します（優れた自動処理で、「動くポスター」を作成できます）。ドラマチックなパーツが飛び込んで組み上がるモーションコラージュ（cr7v2 のようなもの）や、コンテンツフィルターなしで実在の人物を完全に制御してアニメーション化する場合は、ポスターを個別の要素に切り分け、ローカルのキーフレームエンジンで動かします（動画モデルは不要です）。

references/local-engine.md を参照してください。概要：extract_elements.py（切り抜き＋背景除去＋残留部分の消去処理）→ motion.py（Layer とキーフレーム、fly_in／slap／drop／pop_settle のイージング、手続き型の紙吹雪／スターバースト、カメラのズーム＋シェイク＋ウィップ、フレームのレンダリング）。パーツはぼかしたプレースホルダーの背景上で元の位置に戻るため、組み上がったフレームは元のポスターを再現します。

エディション

• 自動エディション（このスキル）：トピックを入力すると、Atlas 上ですべて処理して動画を出力します。
• 手動プロンプトパック：ユーザーが Atlas を利用していない場合は、ビートマップ＋各ビートの画像プロンプト＋各クリップのモーションプロンプト＋ナレーション台本を作成し、任意のジェネレーターに貼り付けてもらいます。クリエイティブエンジン（プロンプト）は同じです。