atharhive/vox-explainer

Vox 風格解說影片管線

從單一主題產出完整、含旁白、字幕、配樂的解說影片。管線分六個階段，每個階段產出的成品供下一個階段使用。旁白在動畫之前產生，因為旁白時長主導所有時間決策。

主題 → 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 呼叫前，請先至 https://www.atlascloud.ai/docs 確認最新的端點路徑與模型 ID——媒體模型 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

第一階段——腳本

由你親手撰寫，無須 API 呼叫。這是決定品質最關鍵的階段——優秀腳本搭配普通視覺，成果仍勝過相反組合。

動筆前請先閱讀 references/vox-style-guide.md（寫作章節）。核心規則：

1. 以節拍為結構。 一個節拍 = 一段旁白（1–3 句，唸約 8–14 秒）＋一段視覺畫面。60 秒影片約 6–8 個節拍；3 分鐘約 16–22 個節拍。
2. Vox 敘事弧線： 開場鉤子（一個令人驚訝的具體事實或提問）→ 背景脈絡（「要理解 X，得先回到……」）→ 逐步解釋，貫穿一條清晰主線 → 轉折或意外 → 收尾，重新詮釋開場鉤子。
3. 語氣： 第二人稱歡迎用語（「你可能看過……」），歷史敘述用現在式，用具體數字取代抽象形容，短而明確的陳述句。不要廢話，不要說「在本影片中我們將要」。
4. 每個節拍只講一個概念。 如果一句話引入了第二個概念，就拆成兩個節拍。

撰寫 script.json：

{
  "title": "盛唐黃金時代",
  "topic": "唐朝如何建立起世界上最大的城市",
  "style_seed": "混合媒材紙雕拼貼，水墨中國山水，朱紅與舊米色調色板",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "七世紀時，唐朝建造了長安——世上最大、最富庶的城市。整個世界都來到它的城門前。",
      "visual": "唐太宗以紙雕人物居中登基，朝臣分列兩側，背後是寶塔與水墨山水，右上角朱紅印章刻有「盛唐」",
      "caption_text": null,
      "motion": "鏡頭緩慢推進皇帝，雲朵向左飄移，紙雕層之間有細微的視差效果"
    }
  ]
}

caption_text 用於螢幕上的動態字卡（關鍵統計或詞彙）——多數節保留 null；旁白字幕在組裝階段處理。motion 在第四階段成為動畫提示詞。

第二階段——旁白（xAI TTS v1）

為每個節拍產生一個音檔，然後測量時長。這些時長是整部影片的主時鐘。

每個節拍呼叫 Atlas Cloud 音訊端點（模型：xAI TTS v1——確切的請求格式與聲音選擇指南請見 references/atlas-cloud-api.md）。整部影片選用同一個聲音。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}

檢查總長度是否符合 brief。如果某個節拍太長，精簡旁白並只重新產生該節拍。

第三階段——關鍵幀（Seedream 5.0 Pro）

每個節拍一張關鍵幀，全部維持一致的視覺風格。一致性是最大的挑戰；透過「風格錨點模式」解決：

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 張參考；錨點 ＋ 可選前一幀）。提示詞：「保持參考圖片的精確美術風格、調色板、紙雕拼貼質感與邊框。新場景：{節拍.visual}」

這樣能鎖定整部影片的調色板、質感與構圖，如同真人美術指導所做。

每個提示詞都應以風格後綴結尾（見風格指南），該後綴編碼了 Vox 外觀：白色邊框的紙雕、網點、膠帶條、粗體扁平幾何點綴、充裕的白邊、單一強調色。

設有 caption_text 的幀：指示 Seedream 以粗體壓縮字體呈現文字，因為 Seedream 5.0 Pro 的文字渲染能力很強。每幀文字不超過 5 個詞。

第四階段——動畫（Gemini Omni Flash）

將每張關鍵幀透過影像轉影片動畫化。目標片段時長 = 該節拍旁白時長 ＋ 0.5 秒緩衝（無條件進位至模型支援的增量）。

拼貼美學的動作提示詞應輕柔——這是最常見的失敗模式。Vox 風格是「動態圖像」，不是「實拍畫面」。好的動作詞彙：

• 緩慢推近／拉遠（二維鏡頭，非三維滑軌）
• 紙雕層間視差漂移
• 雲朵／煙霧橫向飄動
• 紙元素從畫面邊緣滑入並定位
• 網點或紋理微微閃爍
• 單一元素動畫（旗幟飄動、水面漣漪），其餘保持靜止

每個提示詞中明確禁止：「無鏡頭晃動、無三維旋轉、無人臉或文字變形、無風格偏移、元素保持扁平紙雕質感。」

輪詢每個生成任務直到完成，下載至 clips/clip_NN.mp4。生成偶爾會失敗或偏移——檢查每個片段；文字變形或風格偏移者重新生成。預留約 15% 的重製預算。

第五階段——配樂（MiniMax Music 2.6）

整部影片只使用一首純音樂背景。要求 is_instrumental: true——人聲會與旁白衝突。

提示詞公式：{情緒} {類型相近的質感}, {速度}, {樂器編制}, {段落弧線}。歷史題材範例：「沉思型電影感背景樂，毛氈鋼琴與柔和弦樂搭配輕節奏脈動，90bpm，從稀疏逐漸豐滿，紀錄片風格」。樂器編制應配合主題（唐朝題材使用古箏／笛子質感；科技題材使用類比合成器脈動）。

Music 2.6 產生固定長度的歌曲；若曲目短於影片，在組裝時循環並加交錯淡入淡出；若較長，則修剪並淡出。切勿讓配樂弧線與影片弧線衝突——如果音樂在安靜節拍處突然下墜，會顯得突兀；請試聽配樂與影片的搭配。

第六階段——組裝（ffmpeg，本機）

完整操作方式請閱讀 references/ffmpeg-assembly.md。流程如下：

1. 每個片段根據其節拍的旁白時長調整（修剪或保留最後一幀），標準化為 1920×1080 30fps。
2. 依序串接所有片段。
3. 建立旁白音軌：將各節拍音訊串接，之間加入 0.5 秒間隔以配合影片時間。
4. 產生 subs/captions.ass：根據腳本製作 Vox 風格內嵌字幕——粗體無襯線字體、白色文字加上粗黑色外框、底部居中、最多兩行、在子句邊界分割旁白並在節拍時間窗內分配時間。
5. 混音： 旁白維持全音量，配樂在旁白時壓低 -12 至 -15dB（側鏈壓縮或簡單的音量自動化——參考檔案中有配方）。
6. 燒錄字幕 ＋ 出處標示（可選，右下角小字「由……製作」）後編碼：H.264、CRF 18、AAC 192k、-movflags +faststart。

最終 QC 檢查：確認 (a) 字幕與旁白同步無偏移，(b) 配樂未壓過旁白，(c) 片段動畫未明顯循環，(d) 幀間無風格偏移。問題應在根源階段修正，而非用組裝階段的 hack 解決。

協調備註

• 初次執行時嚴格依序執行各階段；之後任何階段可獨立重新執行，因為所有狀態都存在於專案檔案中。
• API 生成較慢（影片片段：每個 1–4 分鐘）。所有動畫任務應同時送出，然後輪詢——不要序列化。
• 將每次送出的提示詞記錄在 prompts.log 中——可重現性很重要，使用者可能只想微調並重新產生單一節拍。
• 費用與節拍數線性成長。在第三階段（第一個付費較高的階段）之前向使用者報價：節拍數 × ($0.10 圖片 + 每 10 秒片段約 $1.20) + 約 $0.50 音訊。

參考資料

• references/vox-style-guide.md——在第一和第三階段前閱讀。視覺語法、寫作語氣與提示詞範本。
• references/atlas-cloud-api.md——在第二階段前閱讀。端點、模型 ID、非同步任務模式、輪詢程式碼、費用。
• references/ffmpeg-assembly.md——在第六階段前閱讀。調整、串接、字幕、音量壓低與編碼配方。