vox-director

Vox Director

1 行のトピックから、完成したVox スタイルのペーパークラフト・コラージュ動画を作成します。各ビートが命を吹き込まれた、印象的でテンポのよいナレーション付き解説動画／広告になります。ボイスオーバー、音楽、字幕を備え、Atlas Cloud API キー 1 つとローカルのffmpegで動作します。

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

基本の考え方（最初にお読みください）

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

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

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

前提条件（省略せずに確認してください）

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

標準ワークフロー（トピック → 動画）

これがデフォルトの、最も自動化された手順です。すべての工程は、プロジェクトごとに out/<project>/ に置かれる単一の beats.json を使って、スクリプト 1 つずつで進めます。

1. トピック → ビートマップ。 まず、ストーリーのレイヤーである references/beat-layer.md をお読みください。トピックに合った物語の arc を選びます（歴史なら timeline、広告なら pas／bab、解説なら how_it_works、変化を描くなら man_in_hole など）。次に、そのアークに沿って out/<project>/beats.json を作成します。beat-1 の見出しは 3 秒以内のフックにしてください。 時間に応じたビート数は、30 秒なら 6～8、60 秒なら 10～12 です。各ビートを 2 つのショット（ワイド＋ディテール）に分け、隣接するビート間でショットごとの camera_move に変化をつけ（同じ動きを繰り返さず、見せ場では static を使います）、豊かな element_motion を指定します（手順 4 を参照）。各ビートには narration、title_cn／title_en、scene、bg、feel、hook を設定します。このドラフトは最初の必須承認ポイントです。生成前にビートマップをユーザーに見せてください（もう 1 つの承認ポイントは手順 4 のアスペクト比振り分けの概算です）。例は 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、newsprint-editorial）。合うものがなければ、プロンプトガイドの各要素（メディア／時代／配色／書体／仕上げ）を組み合わせてカスタムテーマを作成します。言語ではなく、トピックに合わせてください（中国史を英語で紹介する動画なら、中国風の見た目にします）。テーマは見た目全体のレイヤー（表現スタイル＋配色＋書体＋仕上げ＋雰囲気＋動き）をまとめたものです。複数の候補を比較し、見た目で選べるようにしてください。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"を設定してください。 アスペクト比のルーティング（styles.resolve_video_aspect、2つ目の承認ゲート）：clips.pyは doc["aspect"]を選択したvideo_modelがサポートする比率と照合します。一致する比率があればそれを使用します。 Omniは16:9／9:16のみ、Klingのreference-to-videoは1:1にも対応し、Klingのimage-to-video／video-editと Seedanceは入力／比率パラメーターに従います。一致する比率がない場合は最も近い比率を選びますが、 映像を黙ってリフレームするのではなく、停止して確認を求めます（確認後に"aspect_approx_confirmed": trueを設定してください）。 1回の実行に含まれるすべてのクリップは同じ解決済みアスペクト比を共有するため、完成した映像で比率が混在することはありません。

5. 音声＋音楽。 python3 scripts/audio.py out/<project> xai/tts-v1による一貫したナレーター音声と、minimax/music-2.6によるインストゥルメンタルBGMを用意します。 トピックと言語に合ったvoice_idを選んでください（デフォルトのままにしないでください）。全音声一覧は references/voices.mdを参照してください（言語別に5つの多言語音声と約66のネイティブ音声があり、性別も記載されています）。 デフォルトはleo（男性、ドキュメンタリー向け）です。実在の人物自身の声（Cロール写真の登場人物やブランドの声）でナレーションするには、 voice.clone_refにローカルの音声サンプルを設定してください。ナレーションは、ビートごとのタイミングを安定させる 固定話者のスタジオ品質テンプレートを使ったシード音声のボイスクローニングに切り替わります （注意事項を参照：固定話者の指定なしに、シード音声へナレーションだけをそのまま渡してはいけません）。

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つのビートを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 を設定します。

A-roll モード（トーキングヘッド → コラージュ）

上記の標準ワークフローはB-rollです。トピックをAI生成のコラージュポスターにし、それをアニメーション化します。A-roll はその逆のケースです。ユーザーがすでに実際に録画されたトーキングヘッド動画（カメラに向かって話すプレゼンター）を持っており、本人の実際のパフォーマンス（顔、唇の動き、ジェスチャー）をそのまま保ちながら、動画自体をコラージュ風にしたい場合です。生成するポスターはありません。「キーフレーム」となるのはプレゼンター自身の映像です。ゼロから文章を作るトピックではなく、ユーザーから本人またはプレゼンターが話している動画ファイルを渡された場合に A-roll を使用します。

1. 文字起こしと自動分割。 python3 scripts/asr_beats.py <project_dir> <source.mp4> ソースの音声に xai/stt-v1 を実行し、文末の句読点または自然な間でビートに分割します（1回あたりの処理上限である10秒を超えないよう、約9.5秒以下にします）。start／end／text を含む各ビートを beats.json に書き込みます。これは B-roll のビートマップと同じ必須の承認ゲートです。内容を確認し、"theme" を設定し（style_bakeoff.py は同じ方法で実行します。ベイクオフのソースにはプレゼンターのセグメントを使えます）、生成を始める前に、必要に応じて各ビートに content_beats の文字列（重ねるステッカー／スタンプのアイデア）を記入します。

2. 生成。 python3 scripts/aroll_clips.py <project_dir> [only_ids] 各ビートの時間範囲をソースから切り出してアップロードし、プレゼンターに写真風のペーパーカットアウトステッカーの処理を施します。実際の顔立ち、唇の動き、視線、ジェスチャーはソースとフレームごとに一致し、紙のコラージュ風になるのはシルエットの縁と周囲の世界だけです。デフォルトモデルは google/gemini-omni-flash/video-edit です。これが拒否したビートは bytedance/seedance-2.0/reference-to-video で自動的に再試行されます（beats.json の video_model／video_model_fallback で設定します）。モデルに顔自体を描き直させたり、顔に網点テクスチャを加えたりしてはいけません。プロンプトの表現を強くした場合も、和らげた場合も試しましたが、どちらも拒否されました。clips.py と同じアスペクト比ルーティングの確認ゲートを使用します。

3. 組み立て。 python3 scripts/aroll_assemble.py <project_dir> 生成された各クリップを、そのビートに対応する元のセグメントの音声と多重化します（動画モデルが生成した音声は使用しません）。そのため、どのモデルがビートを処理した場合でもリップシンクが保証されます。すべてのビートを同じキャンバスサイズに正規化し、結合して final.mp4 を作成します。

C-roll モード（写真 1 枚 → コラージュ）

3 つ目の入力モダリティである「カットアウト・ロール」です。A-roll はトーク動画のスタイルを変更し、B-roll はトピックからすべてを生成します。C-roll は 1 枚の静止写真（自撮り写真、アバターカード、商品写真）を使い、その写真をコラージュの世界に固定します。被写体は写真のまま切り抜きステッカーにし、描き直すことはありません。画像編集モデルで周囲にビートごとのポスターを生成してから、通常のクリップ工程でアニメーション化します。ユーザーから写真 1 枚とトピックが提供された場合に C-roll を使います。本人の顔が前面に出る個人向け解説や、実物の商品写真を中心にしたコラージュ広告に適しています（どちらも 2026-07-17 に検証済み）。

1. ビートマップ。 B-roll と同様です（references/beat-layer.md、承認ゲートも同じ）。さらに、beats.json に C-roll 用のフィールドを追加します。"mode": "croll"、"anchor_photo"、"croll_subject"（portrait | product）、および subject_wardrobe（ポートレートの場合。服装を固定しないと、ペーパードールの体が変わってしまいます）または subject_desc（商品）。ショットには "title": false を設定します。C-roll のポスターに見出しはなく、テキストはキャプションに入れます。別途台本がない場合は、まずナレーションを書き起こすか内容から作成し、音声の ASR タイムスタンプでビートを定義します（A-roll と同じ音声優先で、B-roll のようなテキスト優先ではありません）。

2. アンカー付きキーフレーム。 python3 scripts/croll_keyframes.py <project_dir> は写真を 1 回アップロードし、ショットごとに google/nano-banana-2/edit（フォールバックは openai/gpt-image-2/edit）でアンカー付きポスターを 1 枚生成します。ポートレートでは写真のような顔とイラストのペーパードールの体を使い、商品ではラベルの文字組みをそのまま保った、画素単位で忠実なステッカーにします。プロンプトには、あとから気づくと再実行が必要になる次の 3 つのルールが組み込まれています。ポーズや表情は体だけに指定します。ウィンクを頼むと顔が描き直されます。ハーフトーンは背景だけに適用します。そうしないと肌にも広がります。ポートレートの服装は明示的に固定する必要があります。このスクリプトは beats.json に anchor_freeze も書き込みます。

3. アニメーション化、音声、組み立て。 通常どおり clips.py → audio.py → assemble.py の順に実行します。 clips.py はすべてのモーションプロンプトに anchor_freeze ガードを挿入します。これがないと、動画生成の工程で商品ラベルの文字が変わったり（実例：「PARFUM」→「PAREUM」）、顔のタイミングが変わったりすることがあります。被写体本人の声でナレーションを作る場合は、voice.clone_ref を設定します（上記の「音声と音楽」を参照）。スタンプやスナップズームのタイミングは、ナレーションの ASR 単語タイムスタンプから導きます（asr_beats.py は A-roll の映像に限らず、どの音声にも使えます）。

Host モード（プレゼンターがカメラに向かって話す）

ユーザーが、録画映像ではなくプレゼンターの静止画像 1 枚から、ナレーションの一部を話すデジタルプレゼンターを画面に表示したい場合に使います（録画映像の場合は A-roll です）。該当するビートには、ショットの "kind": "host" を指定します。それ以外のビートは通常の B-roll のままです。詳細な手順、ルール、制限については references/host-mode.md を参照してください（このモードを使う前に読んでください）。

1. host.avatar に完成済みのキャラクターデザイン（描き直し不可）を追加します。また、host ビートごとに "kind": "host" のショットを 1 つ用意し、世界だけを描写する scene と、各要素の名前を挙げて形状を固定する element_motion を設定します。ビートのナレーションは最大 9.5 秒です。
2. まず audio.py を実行し、続いて python3 scripts/host_plates.py out/<project> を実行します。動画生成に費用をかける前に、2 枚のプレートを両方確認してください（緑一色で、顔が崩れておらず、空の領域が明瞭であること）。
3. python3 scripts/host_clips.py out/<project> を実行すると、費用の見積もりが表示されて停止します。見積もりをユーザーに提示してから、--yes を付けて再実行します。プレゼンター（Seedance）と世界（Omni）を別々に生成し、プレゼンターのクリップ自体の音声を採用して、両者を合成します。
4. clips.py と keyframes.py は host ショットをスキップし、assemble.py は host ショットを引き伸ばしません。

ユーザーは host.position と host.size でプレゼンターの位置とサイズを指定できます。16:9 と 9:16 に対応しています。host クリップは、1 秒あたりの費用が B-roll クリップのおよそ 2 倍です。既知の問題として、世界の動画が変化することがあります（詳細はリファレンスを参照）。その場合は再生成してください。

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
  "image_model": "google/nano-banana-2/text-to-image",       // keyframes; or openai/gpt-image-2/text-to-image
  "image_resolution": "1k",               // 1k (default) | 2k | 4k
  "video_resolution": "720p",             // 720p (default); Seedance also 480p/1080p (Omni is 720p-only)
  "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},  // pick per topic/language — see references/voices.md
                                          // + optional "clone_ref": "path/to/sample.mp3" (clone that voice via seed-audio)
                                          //   and "persona": "YouTube tutorial creator" (delivery style for cloned VO)
  "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)
  "caption_style": "white",               // white (default: clean white subtitle) | paper (cream cut-out collage look)
  "captions": true,                       // false = no burned-in captions (deliver clean, subtitle in post)
  "watermark": "Made with Atlas Cloud",
  "host": {"avatar": "path/to/presenter.jpg", "position": "left", "size": 0.25},   // host mode only (references/host-mode.md)
  "mode": "croll",                        // C-roll only — plus the four fields below
  "anchor_photo": "path/to/photo.png",    // C-roll: the still to anchor (person or product)
  "croll_subject": "portrait",            // C-roll: portrait | product
  "subject_wardrobe": "a cream knitted sweater and charcoal trousers",  // C-roll portrait: outfit lock
  "subject_desc": "the perfume bottle",   // C-roll product: short noun phrase for the sticker
  "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	デフォルト。中国語と英語のテキストを適切に描画します。image_resolution は 1k／2k／4k
キーフレーム（代替）	openai/gpt-image-2/text-to-image	image_model で設定します。サイズと品質はアスペクト比と解像度に応じて自動で割り当てられます
要素の切り抜き	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 でのダウンロード、libass を使わない字幕、コンテンツブロックなど）については、references/models-and-gotchas.md を参照してください。 失敗をデバッグする前に必ず読んでください。よくある失敗の大半はすでに記載されています。

バックエンドはプラグイン式です。 すべての API 呼び出しは プロバイダー（scripts/provider.py）を経由します。現在のデフォルトは Atlas Cloud で、利用できるバックエンドも 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 を使っていない場合は、ビートマップ、ビートごとの画像プロンプト、クリップごとのモーションプロンプト、ナレーションスクリプトを作成し、任意のジェネレーターに貼り付けられるようにします。クリエイティブエンジン（プロンプト）は同じです。