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

阶段 1——脚本

由你自行撰写，无需 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 将成为阶段 4 的动画提示。

阶段 2——配音（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}

对比需求文档，检查总时长是否合理。如果某个节拍过长，收紧旁白并仅重新生成该节拍。

阶段 3——关键帧（Seedream 5.0 Pro）

每个节拍生成一个关键帧，所有帧保持一致的视觉风格。一致性是难点；通过风格锚点模式解决：

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 个参考；锚点 + 可选的上一帧）。提示：“保持参考图像的精确艺术风格、调色板、纸拼贴处理和边框。新场景：{节拍.visual}”

这将锁定影片整体的调色板、纹理和构图，如同人类艺术总监一样。

每个提示应以样式后缀结尾（参见样式指南），该后缀编码了 Vox 的外观：带白色边框的纸剪影、半色调点、胶带条、粗体扁平几何点缀、宽边距、单一强调色。

设置了 caption_text 的帧：指示 Seedream 使用粗体窄版无衬线字体呈现文本，因为 Seedream 5.0 Pro 的文字渲染能力强大。每帧不超过 5 个单词。

阶段 4——动画（Gemini Omni Flash）

通过图像到视频，将每个关键帧制作成片段。目标片段时长 = 对应节拍的配音时长 + 0.5 秒缓冲（向上取整到模型支持的增量）。

拼贴美学的运动提示应保持微妙——这是最常见的失败点。Vox 风格是“动态图形”，而非“实拍镜头”。好的运动词汇：

• 缓慢推近/拉远（二维相机运动，非三维推轨）
• 剪影层之间的视差漂移
• 云/烟雾横向漂移
• 纸元素从画面边缘滑入并停驻
• 半色调点或纹理的微微闪烁
• 单一元素动画（旗帜飘扬、水面涟漪），其他元素保持静止

在每个提示中明确禁止：“无相机抖动，无三维旋转，无面部或文字变形，无风格漂移，元素保持平面纸剪影。”

轮询每个生成任务直至完成，并下载到 clips/clip_NN.mp4。生成有时会失败或偏离——审查每个片段；对文字扭曲或风格破坏的片段重新生成。预算约 15% 的重生成量。

阶段 5——音乐（MiniMax Music 2.6）

整部影片使用一段纯器乐背景。请求 is_instrumental: true——人声会干扰旁白。

提示公式：{情绪} {类型相近的质感}，{速度}，{配器}，{弧线}。历史题材示例：“沉思的电影感背景配乐，立式钢琴与轻柔弦乐搭配轻微打击乐节奏，90 bpm，从稀疏逐步过渡到饱满，纪录片风格”。配器需与主题匹配（唐朝作品使用古筝/笛子质感；技术主题使用模拟合成器脉冲）。

Music 2.6 生成固定长度的乐曲；如果曲目短于影片，则在组装时循环并做交叉淡入淡出；如果更长，则修剪并淡出。绝不能让音乐弧线与影片弧线冲突——中段跌落落在安静节拍上会显得突兀，因此请根据影片结构试听结果。

阶段 6——组装（ffmpeg，本地）

完整的配方请阅读 references/ffmpeg-assembly.md。步骤顺序：

1. 调整每个片段 至其节拍的配音时长（修剪或保持最后一帧），标准化为 1920x1080 30fps。
2. 串联 片段按顺序连接。
3. 构建配音轨道 通过连接节拍音频，并加入 0.5 秒间隙以匹配视频时间。
4. 生成 subs/captions.ass 从脚本——Vox 风格内嵌字幕：粗体无衬线，白色加浓黑描边，底部居中，最多两行，在分句处拆分旁白，并在节拍窗口内为每个段落计时。
5. 混合音频： 配音维持在满电平，音乐在旁白下方降低 -12 至 -15 dB（侧链压缩或简单的音量自动化——配方见参考文档）。
6. 烧录字幕 + 署名（如需要，在右下角小字显示“由……制作”）并编码：H.264，CRF 18，AAC 192k，-movflags +faststart。

最终 QC 通过检查： (a) 字幕/配音同步偏移，(b) 音乐盖过旁白，(c) 片段运动循环可见，(d) 帧之间风格漂移。在问题发生的阶段修复，而非通过组装技巧。

编排说明

• 首次按严格顺序运行阶段；之后，任何阶段可单独重新运行，因为所有状态都保存在项目文件中。
• API 生成较慢（视频片段：每段 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 之前阅读。调整、串联、字幕、压限和编码配方。