CK42BB/vox-explainer-skill

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 秒影片的 API 费用约为 3–8 美元（参考 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": "在 7 世纪，唐朝中国建造了长安——地球上最大、最富裕的城市。整个世界都来到了它的门前。",
      "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}

检查总时长与 brief 是否大致相符。如果某个节拍过长，收紧旁白并仅重新生成该节拍。

阶段 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 张参考；锚点帧加上前一个帧）。提示词：“保持参考图像的确切艺术风格、调色板、纸拼贴处理和边框。新场景：{beat.visual}”

这样就锁定了整部影片的调色板、纹理和构图，如同人类艺术总监所做的那样。

每个提示词应以风格后缀结尾（参见风格指南），该后缀编码了 Vox 外观：带有白色边框的纸剪裁、半色调圆点、胶带条、大胆扁平几何点缀、宽敞的边距、单一强调色。

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

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

通过图像到视频，将每个关键帧动画化为一个片段。目标片段时长 = 该节拍的配音时长 + 0.5 秒的呼吸空间（向上舍入到模型支持的增量）。

针对拼贴美学的运动提示词应该微妙——这是最常见的失败模式。Vox 的效果是“动态图形”，而非“实拍镜头”。良好的运动词汇：

• 缓慢推进/拉出（2D 摄像机移动，不是 3D 车轨）
• 剪纸层之间的视差漂移
• 云彩/烟雾横向飘移
• 纸张元素从画面边缘滑入并定位
• 半色调圆点或纹理柔和闪烁
• 单个元素动画化（旗帜飘动，水波荡漾），其他元素保持静止

在每个提示词中明确禁止：“无摄像机抖动，无 3D 旋转，无面部或文字变形，无风格漂移，元素保持扁平纸剪裁状态。”

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

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

为整部影片生成一首纯音乐背景曲。请求 is_instrumental: true——人声会与旁白冲突。

提示词公式：{情绪} {类似风格的质感}, {节奏}, {乐器配置}, {弧线}。历史题材的示例：“沉思的电影式伴奏，以钢琴和柔和的弦乐为主，配以轻柔的打击乐脉搏，90bpm，从稀疏逐渐发展到丰满，纪录片风格”。乐器配置应与主题匹配（唐朝作品用古筝/笛子音色；科技话题用模拟合成器脉冲）。

Music 2.6 生成固定长度的歌曲；如果音轨短于影片，在合成时通过交叉淡入淡出循环；如果更长，则裁切并渐出。切勿让音乐的情绪变化与影片的弧线冲突——一段中段低谷落在安静的节拍上会很突兀，因此请根据影片的节奏试播结果。

阶段 6 —— 合成（ffmpeg，本地）

阅读 references/ffmpeg-assembly.md 以获取完整配方。顺序如下：

1. 调整每个片段以匹配其节拍的配音时长（修剪或延长最后一帧），标准化为 1920x1080 30fps。
2. 按顺序拼接片段。
3. 构建配音音轨：将节拍音频与 0.5 秒间隙拼接，以匹配视频时序。
4. 生成 subs/captions.ass：根据脚本生成——Vox 风格烧录式字幕：粗体无衬线，白色带厚重黑色轮廓，底部居中，最多两行，按从句边界分割旁白，并在节拍的时间窗口内为每个块设定时间。
5. **混音：**配音保持满音量，音乐在旁白下降至 -12 到 -15dB（侧链压缩或简单音量自动化——参考文档中有配方）。
6. 烧录字幕 + 归属信息（如果需要，右下角小字显示“使用 ... 制作”）并编码：H.264，CRF 18，AAC 192k，-movflags +faststart。

交付前进行最终质量控制检查：检查（a）字幕/配音同步漂移，（b）音乐压过旁白，（c）某个片段运动明显循环，（d）帧之间的风格漂移。在问题产生的阶段修复，而不是通过合成阶段的修补。

编排说明

• 首次执行时严格按顺序运行各阶段；之后，由于所有状态都保存在项目文件中，任何阶段都可以独立重新运行。
• API 生成较慢（视频片段：每个 1–4 分钟）。并发提交所有动画任务，然后轮询——不要串行化。
• 将你发送的每个提示词保存在 prompts.log 文件中——可复现性很重要，用户可能想要调整并重新生成单个节拍。
• 成本与节拍数线性相关。在阶段 3（首个高付费阶段）之前向用户提供粗略成本估算：节拍数 × (0.10 美元图像费 + 约 1.20 美元每 10 秒片段) + 约 0.50 美元音频。

参考资料

• references/vox-style-guide.md —— 在阶段 1 和阶段 3 之前阅读。包含视觉语法、写作风格和提示词模板。
• references/atlas-cloud-api.md —— 在阶段 2 之前阅读。包含端点、模型 ID、异步任务模式、轮询代码和费用。
• references/ffmpeg-assembly.md —— 在阶段 6 之前阅读。包含调整、拼接、字幕、闪避和编码配方。