vox-video-director

Vox 视频导演

将一行主题变成一部完整的 Vox 风格纸艺拼贴视频：一则大胆、有力的讲解视频或广告，每个节拍都是一张活灵活现的撕纸拼贴海报，并配有旁白、可选的音乐和字幕。通过经过身份验证的 Bailian CLI（bl） 和本地 ffmpeg 运行。

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

核心理念（请先阅读）

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

1. 风格在图像生成阶段形成。 每个节拍都是由文生图模型制作的完整拼贴海报。所有拼贴元素（撕纸、剪纸、半色调、大胆的色彩、标题文字）都体现在图像中。如果图像本身不是丰富的拼贴风格，后续步骤就无法补救。
2. 之后再添加动画。 默认情况下，AI 视频模型会让整张海报动起来（即“活海报”路径——简单且自动化）。如果要逐片拼贴组装出戏剧性效果，则需将海报切成多个部分，并通过本地关键帧引擎驱动（高级路径）。

一切都取决于提示词。编写任何图像或视频提示词之前，请先阅读 references/prompt-guide.md——其中包含精准的提示词结构，能决定最终效果是“真正的 Vox 拼贴”还是“会动的 PowerPoint”。

先决条件（请检查，不要跳过）

• bl --version——需要 Bailian CLI 1.14.3 或更高版本。
• bl auth status——如果尚未通过身份验证，请运行 bl auth login --api-key <key>，并等到登录成功后再继续。
• 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。第 1 个节拍必须在 3 秒内吸引观众。 默认设置为一个节拍 = 一个生成的视频片段 = 一个镜头。根据旁白时长确定每个片段的长度，不要使用固定模板：目标为 5–10 秒，运行 python3 scripts/timing.py out/<project> --estimated，并拆分所有预计时长超过 10 秒的旁白。60 秒的视频通常包含 7–10 个按内容划分的节拍，而不是六段固定的 10 秒片段或十二个固定的 5 秒镜头。相邻节拍的 camera_move 应有所变化（绝不重复；高潮处使用 static），并编写丰富的 element_motion。每个节拍都需要 narration、title_cn/title_en、scene、bg、feel、hook 和一个 shots 条目；其中 dur 可省略。包含预计时长的这版草稿是第一个必须通过的审批关卡。默认的架构示例请使用 examples/content-timing.beats.json。

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、 newsprint-editorial）——或者在没有合适预设时，混合提示指南中的维度（媒介／时代／配色／字体／质感）来 自定义主题。风格应契合主题，而非语言（讲述中国历史的英语影片也应呈现中国风格）。一个主题涵盖完整的外观层 （表现手法＋配色＋字体＋质感＋氛围＋动效）。进行对比测试，让用户凭视觉选择——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/audio.py out/<project> 使用 bl speech synthesize + cosyvoice-v3-flash 生成统一的旁白声线，然后 用实测音频时长加上较短的剪辑尾音替换文本估算时长。新片段时长限制为 5–10 秒。如果 timing_issues 不为空，请拆分相应的旁白节拍并重新运行 audio，之后再付费生成图片或视频。根据主题和语言选择 voice_id；参见 references/voices.md。百炼 CLI 1.14.x 没有音乐生成功能；请提供本地 bgm_path，或在不加音乐的情况下完成合成。

4. 关键帧（拼贴风格）。 python3 scripts/keyframes.py out/<project> 使用 bl image generate + qwen-image-3.0 为每个节拍／镜头生成一张拼贴海报， 并将标题文字融入画面。按照 references/prompt-guide.md 中的 5 部分结构编写提示词。动画制作前，请确认每张海报都像真实的分层拼贴——此处重新生成成本低（$0.08），不要为质量不佳的图片支付动画制作费用。

5. 动态效果。 python3 scripts/clips.py out/<project> 使用 bl video generate + happyhorse-1.1-i2v 为每张海报制作动画。两个独立维度 （参见 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／大胆运镜；不满意的结果就重新生成）。只有带标题的镜头才会严格保护标题文字（没有标题的细节镜头可以自由发挥）。百炼默认使用 happyhorse-1.1-i2v；完整运行前，请根据所选模型的当前政策确认真人和品牌相关内容的使用方式。 宽高比路由（styles.resolve_video_aspect，第二道审批关卡）：clips.py 会根据所选 video_model 支持的比例解析 doc["aspect"] — 精确匹配优先；Omni 仅支持 16:9／9:16，Kling 参考图转视频还支持 1:1，Kling 图生视频／视频编辑和 Seedance 则直接遵循输入／比例参数。没有精确匹配时，会选择最接近的比例，但会暂停并请你确认（确认后设置 "aspect_approx_confirmed": true），而不是悄悄重新裁切影片 — 一次运行中的所有片段都会使用相同的解析后宽高比，因此成片不会混用不同比例。

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

节奏 — 时长由内容决定

• 默认每个片段对应一个旁白节拍和一个生成片段。每个片段应控制在模型安全的 5–10s 范围内。
• 生成前根据文本长度估算；TTS 完成后，以测得的 narration_dur 为准，并向上取整到下一个 0.5s，另加约 0.45s 的剪辑余量。
• 视频 API 接收向上取整后的整数秒数（例如 6.5s → 请求 7s）；合成时会将返回片段裁剪到精确的剪辑时长，因此不会截断旁白。
• 短文本仍使用 5s，以便充分表达观点。长文本最多使用 10s。如果旁白加剪辑余量超过 10s，请在句子或分句边界处拆分；不要加快语速，也不要悄悄将片段延长到模型限制之外。
• 60s 的影片通常包含 7–10 个时长不一的片段。除非源内容的节拍时长确实相同，否则不要让整部影片的片段时长完全一致。
• 仅在明确的剪辑需求下，才在一个节拍内使用多个镜头。仍支持旧版多镜头项目，但新建的内容驱动型项目应将旁白拆分成独立节拍，让每个生成片段都对应一个 5–10s 的内容单元。

A-roll 模式（真人出镜 → 拼贴）

上述标准工作流是 B-roll：将主题变成 AI 生成的拼贴海报，再为其添加动画。A-roll 则相反——用户已经有一段真实录制的真人出镜视频（演讲者对着镜头说话），希望将视频本身转换成拼贴风格，同时保留其真实表现（面部、唇部动作、手势）。无需生成海报；“关键帧”就是演讲者自己的视频素材。用户提供自己或演讲者讲话的视频文件时使用 A-roll，而不是让用户从零开始提供主题。

1. 转录并自动分段。 python3 scripts/asr_beats.py <project_dir> <source.mp4> 对源音频运行 bl speech recognize（fun-asr），并在句末标点或自然停顿处切分片段（时长不会超过约 9.5 秒，低于 Omni/Kling 视频编辑每次调用 10 秒的上限）。生成包含每个片段 start/end/text 的 beats.json——这与 B-roll 节拍图一样，必须经过审批：检查节拍图，设置 "theme"（按相同方式运行 style_bakeoff.py——演讲者片段也适合作为对比测试素材），并可选择为每个片段填写 content_beats 字符串（用于叠加的贴纸／印章创意），然后再开始生成。

2. 生成。 python3 scripts/aroll_clips.py <project_dir> [only_ids] 从源视频中截取每个片段的时间范围，上传并为演讲者重新设计风格，采用照片质感的剪纸贴纸处理——她真实的面容、唇部动作、视线和手势都会逐帧跟随源视频；只有轮廓边缘和周围环境呈现纸艺拼贴风格。默认模型是通过 bl video edit 调用的 happyhorse-1.0-video-edit（在 beats.json 中通过 video_model/video_model_fallback 设置）。绝不要让模型重新绘制人脸或为人脸添加半调纹理——无论提示词如何措辞，都会被拒绝（试过强硬和委婉两种表述，均未通过）。使用与 clips.py 相同的宽高比路由确认关卡。

3. 合成。 python3 scripts/aroll_assemble.py <project_dir> 将每个生成片段与其原始片段的音频合并（绝不使用视频模型生成的音频），无论哪个模型处理了相应片段，都能确保唇音同步；同时将所有片段统一到同一画布尺寸，并拼接成 final.mp4。

C-roll 模式（单张照片 → 拼贴）

第三种输入模态——“剪贴卷”。A-roll 会为真人出镜视频重新设计风格；B-roll 会根据主题生成所有内容；C-roll 则使用一张静态照片（自拍照、头像卡片、产品照），将其锚定在拼贴世界中：主体会被抠出，作为真实照片风格的贴纸——绝不重新绘制；每个节拍的海报则通过图像编辑模型生成，随后进入常规片段阶段进行动画处理。用户提供一张照片和一个主题时，使用 C-roll：例如以本人面孔为主角的个人讲解，或围绕真实产品照制作的拼贴广告（两种场景均已验证，2026-07-17）。

1. 节拍图。 与 B-roll 相同（references/beat-layer.md，审批关卡也相同），并在 beats.json 中添加 C-roll 字段："mode": "croll"、"anchor_photo"、"croll_subject"（portrait | product），以及 subject_wardrobe（人像——锁定服装，否则纸娃娃身体会发生漂移）或 subject_desc（产品）。在镜头上设置 "title": false——C-roll 海报不带标题；文字应放在字幕中。如果没有单独的脚本，请先转录或推导旁白，并使用音频的 ASR 时间戳定义节拍（以音频为先，类似 A-roll——而非像 B-roll 那样以文本为先）。

2. 锚定关键帧。 python3 scripts/croll_keyframes.py <project_dir> 会上传一次照片，并通过 bl image edit 使用 qwen-image-3.0 为每个镜头生成一张锚定海报。人像会保留照片般真实的面孔，并搭配插画风格的纸娃娃身体；产品会生成像素级忠实的贴纸，并保留标签字体排版。提示词规则已内置（要弄清楚这三条，每条都得重新运行一次）：姿势和表情只应用于身体——要求眨眼会导致面孔被重新绘制；网点效果必须限定在背景，否则会蔓延到皮肤上；人像服装必须明确锁定。脚本还会将 anchor_freeze 写入 beats.json。

3. 语音定时 + 动画处理 + 合成。 使用标准流程 audio.py → clips.py → assemble.py。 clips.py 会将 anchor_freeze 保护规则注入每条动作提示词——如果没有该规则，视频阶段可能会重新生成产品标签上的文字（观察到“PARFUM”变成“PAREUM”），或改变面部的时序。若旁白使用主体本人的声音，请设置 voice.clone_ref（见上文“语音 + 音乐”）；根据旁白的 ASR 单词时间戳推导印章和快速缩放的时序（asr_beats.py 适用于任何音频，不仅限于 A-roll 素材）。

beats.json 架构

{
  "project": "my-film", "topic": "...", "language": "en",
  "aspect": "9:16",                       // 16:9 | 9:16 | 1:1 | 3:4
  "style": "collage",
  "provider": "bailian_cli",              // default; invokes authenticated `bl` child processes
  "theme": "american-retro",              // THEME_PRESET (styles.THEME_PRESETS) — the LOOK layer
  "arc": "timeline",                      // narrative arc (beat-layer.md) — the STORY skeleton
  "video_model": "happyhorse-1.1-i2v",
  "image_model": "qwen-image-3.0",
  "image_resolution": "1k",               // 1k (default) | 2k | 4k
  "video_resolution": "720p",             // 720p (default); Seedance also 480p/1080p (Omni is 720p-only)
  "motion_style": "punchy",               // amplitude: calm | punchy | max (theme sets a default)
  "constraints": "strict",                // strict = defect guards on | loose = let AI explore + re-roll
  "timing_mode": "content",               // default: text estimate, then measured TTS duration
  "timing": {"min_segment": 5, "max_segment": 10, "tail": 0.45},
  "voice": {"voice_id": "longtian_v3", "language": "zh", "speed": 1.0}, // see references/voices.md
                                          // + optional "clone_ref": "path/to/sample.mp3" (clone that voice via seed-audio)
                                          //   and "persona": "YouTube tutorial creator" (delivery style for cloned VO)
  "bgm_path": "path/to/instrumental.mp3", // optional; omit to assemble without music
  "mix": {"music": 0.6, "voice": 1.25},   // audio balance — optional; these are the defaults (BGM ducks under the VO)
  "caption_style": "white",               // white (default: clean white subtitle) | paper (cream cut-out collage look)
  "captions": true,                       // false = no burned-in captions (deliver clean, subtitle in post)
  "watermark": "Made By 阿里云百炼CLI",
  "mode": "croll",                        // C-roll only — plus the four fields below
  "anchor_photo": "path/to/photo.png",    // C-roll: the still to anchor (person or product)
  "croll_subject": "portrait",            // C-roll: portrait | product
  "subject_wardrobe": "a cream knitted sweater and charcoal trousers",  // C-roll portrait: outfit lock
  "subject_desc": "the perfume bottle",   // C-roll product: short noun phrase for the sticker
  "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": [
        // Omit dur: timing.py/audio.py sets a content-driven 5-10s duration.
        {"id": "a", "title": true, "shot_size": "WIDE", "camera_move": "push_in",
         "scene": "...wide establishing collage...",
         "element_motion": "traders gesture, goat bobs, a paper bird crosses, coins scatter"}
      ]
    }
  ]
}

theme + arc 设置两个主要层；每个镜头的 element_motion 决定能量（尽量丰富——见下文）。为保持向后兼容，仍会读取 motion / collage_style / era。

Bailian 模型选择

需要验证或覆盖 ID 时，请使用 bl model list。本版本的默认设置如下：

用途	模型	备注
关键帧 / 拼贴海报	qwen-image-3.0	通过 bl image generate 调用
锚定图像编辑	qwen-image-3.0	通过 bl image edit 调用
动画处理 / 图像转视频	happyhorse-1.1-i2v	通过 bl video generate 调用
真人出镜风格重塑	happyhorse-1.0-video-edit	通过 bl video edit 调用
旁白	cosyvoice-v3-flash	通过 bl speech synthesize 调用
ASR	fun-asr	通过 bl speech recognize 调用
音乐	本地文件	设置 bgm_path；可选

完整的模型选择理由及所有 API / ffmpeg 注意事项（身份验证标头、curl 下载、无 libass 字幕、内容块等）请参阅 references/models-and-gotchas.md。调试任何故障前请先阅读——大多数问题都已有记录。

后端可插拔。 每次生成调用都会通过 scripts/provider.py。bailian_cli 是默认后端，会并行启动 bl 子进程，且不会向项目暴露 API 密钥。atlas_cloud 仍作为明确指定的兼容后端保留。失败的 CLI 任务可以重试；运行中的 CLI 任务遇到停滞时绝不会重复启动，以免产生重复费用。

高级：元素级动态拼贴

标准流程会为整张海报制作动画（效果出色、自动化，呈现出“动态海报”的效果）。如果要制作戏剧性的元素飞入并组装动态拼贴（类似 cr7v2），或要在完全掌控且不受内容过滤限制的情况下为真实人物制作动画，可将每张海报拆分为独立元素，再由本地关键帧引擎驱动（无需视频模型）。

阅读 references/local-engine.md。简而言之：extract_elements.py（裁切 + 背景移除 + 残留清理/擦除）→ motion.py（图层 + 关键帧、fly_in/slap/drop/pop_settle 缓动效果、程序化彩纸/放射线、镜头缩放 + 抖动 + 急摇、帧渲染）。元素会飞回原始位置，背景则使用模糊占位图，因此组装后的画面会还原原始海报。

版本

• 自动版（此技能）：输入主题，经由 Bailian CLI 生成影片。
• 手动提示词包：如果用户无法运行 Bailian CLI，只需为他们生成节拍图 + 每个节拍的图像提示词 + 每个片段的动态提示词 + 旁白脚本，供他们粘贴到任意生成器中。创意引擎（提示词）完全相同。