atharhive/vox-explainer

Voxスタイル解説動画パイプライン

単一のトピックから、ナレーション付き、字幕付き、BGM付きの完全な解説動画を生成します。パイプラインは6つのステージで構成され、各ステージが次のステージで消費される成果物を生成します。ナレーションはアニメーションの前に生成されます。なぜなら、ナレーションの長さがすべてのタイミング決定の基準となるからです。

TOPIC → 1.スクリプト → 2.ナレーション → 3.キーフレーム → 4.アニメーション → 5.音楽 → 6.アセンブリ
         (Claude)      (xAI TTS)       (Seedream)      (Omni Flash)   (MiniMax)   (ffmpeg)

前提条件

• ATLASCLOUD_API_KEY 環境変数が設定されていること（atlascloud.ai で取得可能。サインアップ時に無料クレジットあり）
• ffmpeg と ffprobe がインストールされていること（libassによる字幕焼き込みが必要）
• Python 3.10+ と requests ライブラリ
• 60秒動画あたり約3～8ドルのAPIクレジット（コスト表は references/atlas-cloud-api.md を参照）

API呼び出しを行う前に、現在のエンドポイントパスとモデルIDを https://www.atlascloud.ai/docs で確認してください。メディアモデルAPIは急速に進化します。references/atlas-cloud-api.md のパターンは2026年7月時点で検証済みです。

プロジェクト構造

すべての動画で以下のレイアウトを作成し、維持してください。各ステージはこの構造から読み取り、書き込みを行います。

project/
├── brief.md            # トピック、視点、目標尺、視聴者
├── script.json         # ビート（ナレーション、ショット説明、キャプション）
├── audio/
│   ├── vo/             # beat_01.mp3 ... beat_NN.mp3
│   ├── vo_durations.json
│   └── music.mp3
├── frames/             # keyframe_01.png ... style_anchor.png
├── clips/              # clip_01.mp4 ... （無音アニメーションクリップ）
├── subs/               # captions.ass
└── final/              # film.mp4

ステージ1 — スクリプト

このステージは自分自身で作成します。API呼び出しはありません。品質を最も左右するステージです。優れたスクリプトと平均的なビジュアルの組み合わせは、その逆よりも優れた結果をもたらします。

草案を書く前に references/vox-style-guide.md（ライティングセクション）を読んでください。基本ルール:

1. ビートとして構造化する。 1ビート = 1つのナレーションパラグラフ（1～3文、8～14秒の発話）+ 1つのビジュアル。60秒動画は6～8ビート、3分動画は16～22ビート。
2. Voxの物語の弧: コールドオープンのフック（驚くような具体的な事実または質問）→ 文脈（「Xを理解するには、まず…に戻らなければなりません」）→ 明確な一本の糸による段階的な説明 → 複雑さまたはひねり → フックを再構成する解決。
3. 語り口: 二人称での歓迎（「おそらく見たことがあるでしょう…」）、歴史的な物語には現在形、抽象概念よりも具体的な数字、短い平叙文。「この動画では…します」などの前置きは避ける。
4. 1ビートにつき1つのアイデア。 ある文が2つ目の概念を導入する場合は、ビートを分割する。

script.json を記述:

{
  "title": "唐の黄金時代",
  "topic": "唐の中国が世界最大の都市を建設した方法",
  "style_seed": "ミクストメディアのペーパーコラージュ、水墨画風の中国の山々、バーミリオンレッドとエイジドクリームのパレット",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "7世紀、唐の中国は長安を建設しました——地球上で最大かつ最も豊かな都市を。全世界がその門に集まりました。",
      "visual": "太宗皇帝がペーパーカットアウトとして中央に即位、廷臣が両側に並び、背後に塔と水墨画の山々、右上に赤い印鑑「盛唐」",
      "caption_text": null,
      "motion": "皇帝にゆっくりとズームイン、雲が左に流れ、カットアウトレイヤー間で微妙なパララックス効果"
    }
  ]
}

caption_text は画面上のキネティックタイポグラフィの瞬間（重要な統計や用語）に使用します。ほとんどのビートでは null のままにします。ナレーションの字幕はアセンブリ時に処理します。motion はステージ4のアニメーションプロンプトになります。

ステージ2 — ナレーション（xAI TTS v1）

ビートごとに1つの音声ファイルを生成し、長さを測定します。これらの長さが動画全体のマスタークロックとなります。

ビートごとに Atlas Cloud の音声エンドポイント（モデル: xAI TTS v1 — 正確なリクエスト形式と音声選択のガイダンスについては references/atlas-cloud-api.md を参照）を呼び出します。動画全体で1つの音声を選択してください。Voxのレジスター: 慎重で、温かみがあり、やや皮肉が効いている — 「映画予告編」のような声は避けてください。

生成後、すべてのファイルをプローブし、audio/vo_durations.json を作成:

ffprobe -v error -show_entries format=duration -of csv=p=0 audio/vo/beat_01.mp3

{"beats": [{"id": 1, "file": "audio/vo/beat_01.mp3", "duration": 9.83}], "total": 61.2}

合計の長さがブリーフと一致するか確認してください。ビートが長すぎる場合は、ナレーションを短くしてそのビートだけ再生成します。

ステージ3 — キーフレーム（Seedream 5.0 Pro）

ビートごとに1つのキーフレームを、一貫したビジュアルスタイルで生成します。一貫性が最も難しい問題です。スタイルアンカーパターンで解決します:

1. アンカーを生成する。 ビート1（通常はタイトル/フックフレーム）には bytedance/seedream-v5.0-pro/text-to-image を使用します。references/vox-style-guide.md（ビジュアル文法セクション）のスタイルブロック + ビートの visual + 動画の style_seed と accent_color からプロンプトを構築します。16:9、2Kをリクエストします。
2. 先に進む前にアンカーを確認する。 スタイルが適切になるまで再生成します。他のすべてのフレームはこれを継承します。
3. 編集モデルで残りのフレームを生成する。 アンカーを参照画像として bytedance/seedream-v5.0-pro/edit を使用します（最大10枚の参照がサポートされています。アンカー＋オプションで前のフレーム）。プロンプト: 「参照画像とまったく同じアートスタイル、パレット、ペーパーコラージュ表現、ボーダーフレーミングを維持すること。新しいシーン: {beat.visual}」

これにより、人間のアートディレクターが行うように、パレット、テクスチャ、フレーミングが動画全体で固定されます。

すべてのプロンプトはスタイルサフィックス（スタイルガイド参照）で終了する必要があります。これはVoxルックをエンコードします。白いボーダーのペーパーカットアウト、ハーフトーンドット、テープ片、太いフラットな幾何学アクセント、広い余白、単一のアクセントカラー。

caption_text が設定されているフレーム: Seedreamに太字でコンデンスされたサンセリフフォントでテキストをレンダリングするよう指示します。Seedream 5.0 Proのタイポグラフィレンダリングは強力です。フレームあたり5語以内に抑えてください。

ステージ4 — アニメーション（Gemini Omni Flash）

各キーフレームを画像から動画へ変換し、クリップをアニメーション化します。目標クリップ長 = そのビートのナレーション長 + 0.5秒の余裕（モデルのサポートする増分に切り上げ）。

コラージュ美学のモーションプロンプトは微妙にすること — これが最も一般的な失敗モードです。Voxルックは「モーショングラフィックス」であり、「実写映像」ではありません。適切な動きの語彙:

• ゆっくりとしたズームイン/アウト（3Dドリーではなく2Dカメラ）
• カットアウトレイヤー間のパララックスドリフト
• 雲/煙の横方向のドリフト
• フレーム端から紙要素がスライドインして静止する
• ハーフトーンドットやテクスチャが優しくきらめく
• 他の要素は静止したまま、単一の要素がアニメーションする（旗がはためく、水がさざ波立つ）

すべてのプロンプトで明示的に禁止: 「カメラの揺れ、3D回転、顔やテキストのモーフィング、スタイルの逸脱、要素は平らなペーパーカットアウトのまま」

各生成タスクの完了をポーリングし、clips/clip_NN.mp4 にダウンロードします。生成は時々失敗したり逸脱したりします。各クリップを確認してください。テキストが歪んだりスタイルが崩れたクリップは再生成します。約15%の再生成を見込んでおいてください。

ステージ5 — 音楽（MiniMax Music 2.6）

動画全体に1つのインストゥルメンタルBGMを生成します。is_instrumental: true をリクエストしてください。ボーカルはナレーションと競合します。

プロンプトの公式: {ムード} {ジャンルに近いテクスチャー}、{テンポ}、{楽器編成}、{弧}。歴史作品の例: 「思索的な映画的なアンダースコア、フェルトピアノと柔らかな弦楽器、軽いパーカッションパルス、90bpm、まばらから徐々に豊かになる、ドキュメンタリースタイル」。楽器編成を主題に合わせてください（唐の作品には古筝/笛子のテクスチャー、テクノロジートピックにはアナログシンセパルス）。

Music 2.6は固定長の曲を生成します。トラックが動画より短い場合は、アセンブリ時にクロスフェードでループします。長い場合は、フェードアウトでトリミングします。音楽の弧が動画の弧と競合しないようにしてください。トラック途中のドロップが静かなビートに重なると違和感があるため、結果を動画の形状と照らし合わせて確認してください。

ステージ6 — アセンブリ（ffmpeg、ローカル）

完全なレシピについては references/ffmpeg-assembly.md を読んでください。順序:

1. 各クリップをそのビートのナレーション長に合わせる（トリミングまたはラストフレームを保持）、1920x1080 30fpsに正規化。
2. クリップを順に連結する。
3. ビート音声を0.5秒のギャップを入れて連結し、ビデオタイミングに一致させてVOトラックを構築する。
4. スクリプトから subs/captions.ass を生成する — Voxスタイルの焼き込み字幕: 太字サンセリフ、白文字に太い黒い輪郭、下部中央揃え、最大2行、ナレーションを節境界で分割し、各チャンクをビートのウィンドウ内でタイミング調整。
5. 音声ミックス: VOはフルレベル、音楽はナレーション中に-12～-15dBにダッキング（サイドチェイン圧縮または単純なボリュームオートメーション。レシピはリファレンス）。
6. 字幕とクレジットを焼き込み（「Made with ...」小さく右下に任意）エンコード: H.264、CRF 18、AAC 192k、-movflags +faststart。

最終QCパス: (a) 字幕/VO同期ズレ、(b) 音楽がナレーションを overpowering、(c) クリップのモーションループが目立つ、(d) フレーム間のスタイル逸脱。問題の発生したステージで修正し、アセンブリハックでごまかさないこと。

オーケストレーションの注意点

• 初回は厳密に順序通りに実行する。その後は、すべての状態がプロジェクトファイルに存在するため、任意のステージを単独で再実行できる。
• API生成は遅い（動画クリップ: 1つあたり1～4分）。すべてのアニメーションタスクを同時に送信し、ポーリングする。直列化しないこと。
• 送信したすべてのプロンプトを prompts.log ファイルに記録する。再現性が重要であり、ユーザーは単一のビートを微調整して再生成したいと考えるだろう。
• コストはビート数に比例する。ステージ3（最初の有料が重いステージ）の前に、ユーザーにおおまかなコストを見積もる: ビート数 × ($0.10 画像 + 10秒クリップあたり約$1.20) + 約$0.50 音声。

参考文献

• references/vox-style-guide.md — ステージ1とステージ3の前に読むこと。ビジュアル文法、ライティングの声、プロンプトテンプレート。
• references/atlas-cloud-api.md — ステージ2の前に読むこと。エンドポイント、モデルID、非同期タスクパターン、ポーリングコード、コスト。
• references/ffmpeg-assembly.md — ステージ6の前に読むこと。コンフォーム、連結、字幕、ダッキング、エンコードのレシピ。