vox-director

Vox Director

将一行主题转化为完整的 Vox 风格剪纸拼贴视频：制作一则大胆、有冲击力、带旁白的解说视频／广告，每个节拍都是一张栩栩如生的撕纸拼贴海报，并配有配音、音乐和字幕。只需 一个 Atlas Cloud API 密钥 和本地 ffmpeg。

这种视觉风格是由 Vox 解说视频以及 Stav Zilber / rom1trs 等创作者推广的现代编辑风格剪纸拼贴：手工剪出的纸片、撕裂边缘、胶带、半色调网点、报纸剪报、每个节拍采用醒目的纯色，以及大型剪纸标题。

核心理念（请先阅读）

Vox 拼贴风格和拼贴动画是两个不同的步骤：

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. 主题 → 节拍图。 首先阅读 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。此草稿是唯一必须经过审批的环节——生成内容前，先向用户展示节拍图。示例见 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），使之符合主题所处的时代、文化和基调；如果没有合适的预设，则通过混合提示词指南中的维度（媒介／时代／调色板／字体／效果）组合自定义主题。风格应符合主题，而非语言（以中国历史为主题的英文影片也应呈现中国风格）。一个主题涵盖整个视觉风格层（风格特征＋调色板＋字体＋效果＋氛围＋动态效果）。进行多方案比选，让用户凭视觉挑选——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，为每个节拍／镜头生成一张拼贴海报， 并将标题文字直接融入画面。按照 references/prompt-guide.md 中的 5 部分结构撰写提示词。 动画制作前，确认每张海报看起来像真正的分层拼贴——在这里重新生成的成本很低（$0.08）， 不要花钱为效果不佳的图像制作动画。

4. 动态效果。 python3 scripts/clips.py out/<project> 使用 google/gemini-omni-flash/image-to-video 为每张海报制作动画。两个独立维度 （参见 references/beat-layer.md §3，已在我们的技术栈上测试）： • camera_move——每个镜头使用一种运镜。安全／默认选项：{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"。

5. 配音＋音乐。 python3 scripts/audio.py out/<project> 使用 xai/tts-v1（多语言，voice_id）生成统一的旁白，并通过 minimax/music-2.6 配上纯音乐背景音乐。（纯旁白不要使用 seed-audio，除非固定说话人——参见注意事项。）

6. 合成。 python3 scripts/assemble.py out/<project> 使用 ffmpeg：统一所有镜头的规格并拼接，将整段旁白压低后铺在音乐下方，按节拍时间点烧录字幕，再添加水印。 输出 out/<project>/final.mp4。

7. 验证。 你无法直接读取 mp4——提取帧为 jpg 后查看： ffmpeg -ss <t> -i final.mp4 -vf "scale=640:-1,format=yuvj420p" -frames:v 1 f.jpg

节奏——镜头时长

常见的错误是每个节拍只用一个长镜头。尤其是 9:16 的社交媒体视频中，静止的 10 秒镜头会显得空洞。建议每约 4–6 秒切一次镜头：

• 每个镜头时长 3–6 秒；单个镜头绝不要超过约 7 秒——再长的话，AI 动效就没有发挥空间， 画面会显得静止。
• 每段节拍的旁白约为 8–10 秒，因此每段节拍安排 2 个镜头（一个带标题的全景建立镜头， 加一个不带标题的细节切入镜头）。旁白在两个镜头间连续播放； 画面会在句子中途切换。这是提升节奏感最有效的方法。
• 因此，一部约 60 秒的影片通常是 约 6 段节拍 × 每段 2 个镜头 × 每个约 5 秒 = 12 个镜头，而不是 6 段 × 10 秒。
• 将全景关键帧复用为镜头 a；为镜头 b 生成更紧凑的细节场景。 keyframes.py 会跳过已有 keyframe_url 的镜头，因此添加 b 镜头后， 重新运行只会生成新增镜头。

为每段节拍添加一个 shots 数组（参见架构定义）。为每个镜头设置简短的 scene 和 motion；仅在全景镜头上设置 "title": true，这样每段节拍只显示一次标题。

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
  "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},
  "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)
  "watermark": "Made with Atlas Cloud",
  "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 设定两个主要层级；每个镜头的 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	中英文文字渲染效果出色
抠出元素	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 是默认且目前唯一的后端。添加其他后端后，可在 beats.json 中设置 "provider"，将请求路由到不同后端——阶段脚本无需更改。scripts/provider.py 的 run_jobs() 还负责提交／轮询，并会在任务卡住或失败时自动重新提交。

高级：元素级动态拼贴

标准路径会让整张海报动起来（效果出色、自动化，形成“动态海报”）。若要制作戏剧性的碎片飞入并拼合动态拼贴（类似 cr7v2），或在完全掌控且不受内容过滤限制的情况下为真人制作动画，可将海报拆分为独立元素，并使用本地关键帧引擎驱动它们（无需视频模型）。

请阅读 references/local-engine.md。简而言之：extract_elements.py（裁剪 + 移除背景 + 清理残留／擦除）→ motion.py（图层 + 关键帧、fly_in／slap／drop／pop_settle 缓动、程序化彩纸／星爆、摄像机缩放 + 抖动 + 鞭甩运镜、帧渲染）。碎片会飞回其原始位置，背景为模糊占位图，因此拼合后的画面会重现原始海报。

版本

• 自动版（此技能）：输入主题，输出影片，全程使用 Atlas。
• 手动提示词包：如果用户不使用 Atlas，只需生成节拍图 + 每个节拍的图像提示词 + 每个片段的运动提示词 + 旁白脚本，供用户粘贴到任意生成器中。创意引擎（提示词）保持不变。