视频生成流程（Video Generation Pipeline）

概述

本技能封装"素材图生成与确认（缺图时）→ 剧本生成 → 虚拟场景生成 → 数字人生成 → 数字人与产品合成 → 按剧本分镜产出视频 → 字幕合成与配音/混音"的完整流水线。输入为：（可选，缺失时可用详细文字描述替代）产品多视图图片、英文卖点文案、真人照片、（可选）场景参考视频、（可选）BGM 音乐；输出为：确认后的参考图集、可交互 3D 场景模型、场景动态视频、数字人合成图、分镜视频片段、拼接成片，以及带字幕与配音的最终成片。

触发场景

• 用户上传产品六视图/多视图 + 卖点文案，要求生成社媒产品视频（TikTok / Reels / YouTube / 信息流等；默认 9:16，可按平台选任意比例）
• 用户只有简单图片（1-2 张）或没有任何图片，只有文字描述——先用文生图/参考图扩展生成参考图，经确认后再进入视频流程
• 用户提供一张产品图，要求扩展出多视角（正面/侧面/顶部/细节）或把产品放进不同使用场景
• 用户要求根据场景参考视频（如实拍工厂流水线）生成虚拟场景
• 用户要求基于真人照片生成数字人并手持真实产品做介绍
• 用户给出拍摄剧本，要求按分镜批量生成视频并拼接
• 用户希望为成片添加字幕与配音（TTS 旁白 + BGM 混音）

核心能力与工具映射

常见视频比例速查表（开工第一步先定比例）

开工前与用户确认目标平台，按下表锁定比例（默认 9:16）。生成阶段受模型面积限制（宽×高 ≤ 1024×1024），先用「生成分辨率」出图/出视频，拼接阶段统一升到「成片规格」：

各阶段如何使用比例：

• 剧本阶段：分镜表按比例标注构图——竖屏（9:16/4:5/3:4）人物主体居中、上下留安全区；横屏（16:9/4:3/21:9）用三分法构图、左右留白；方形（1:1）中心构图、四边留边
• 生成阶段：ImageGen/VideoGen 一律用「生成分辨率」列（超限会被拒），prompt 末尾写清构图比例词（vertical 9:16 / horizontal 16:9 / square 1:1 / portrait 4:5 / portrait 3:4 / standard 4:3 / ultrawide 21:9 / 3:2）
• 拼接阶段：concat_final.py --aspect <比例>（如 --aspect 16:9）自动映射成片规格；也可用 --width/--height 手动指定
• 安全区：竖屏避开顶部 10% / 底部 20% 平台 UI；横屏主体居中、字幕放底部 10% 内；方形四边各留 5-8% 边距

完整工作流（六阶段）

阶段 0：素材收集与目录初始化

开工前确认用户已提供（缺失则先索要；用户无法提供图片时，走阶段 0.7 用详细文字描述文生图/参考图扩展补齐，不必卡在这一步）：

1. 产品多视图（≥3 张：正面/侧面/顶部/底部/细节/包装/暗光场景，越多越好；不足 3 张时可用阶段 0.7 从现有图扩展）
2. 英文卖点文案（或中文卖点，翻译后使用）
3. 真人照片（1-5 张正脸/半身，光线好、五官清晰；多角度最佳）
4. 场景参考视频（可选；若提供则先跑关键帧提取分析场景）
5. 品牌名、目标平台、成片时长与比例

标准目录结构（在工作区创建）：

work/
├── refs/          # 参考素材（视频关键帧、六视图副本）
├── output/        # 生成产物
│   └── shots/     # 分镜视频片段

阶段 0.5：执行前检查与进度恢复（每次开工/续跑必读）

长流程（数小时）极易中断，开工时先做三件事：

1. 读记忆：读 .workbuddy/memory/ 最近日志，确认上次进度、已确认方案与遗留任务。
2. 盘点产物：ls 检查 work/output/ 与 work/output/shots/ 已有文件，识别已完成的阶段与镜号。
3. 建任务清单：用 TaskCreate/TaskUpdate 按五阶段建任务跟踪（每个阶段一个任务，分镜阶段可按批次建子任务），每完成一步立即更新状态——中断后靠任务清单+日志即可精确续跑。

续跑规则：已有合成图的镜号跳过合成直接跑视频；已有视频的镜号直接跳过；只对缺失镜号重新提交。绝不重新生成已落盘的资产（省积分）。

阶段 0.7：素材图生成与确认（可选——缺图时启用，v1.4 新增）

阶段 0 盘点后，若产品图不足（<3 张）、或场景/人物参考缺失、或用户只有文字描述，先走本阶段补齐参考图，经用户确认后才能进入后续视频生成。按手头素材三选一：

模式 A：纯文生图（用户没有任何图片）

1. 先向用户索取/从产品文案提炼产品描述五要素：①形状结构 ②颜色材质 ③关键部件及位置 ④尺寸比例感 ⑤典型使用场景——缺要素先问，不要猜
2. 用 ImageGen 文生图，同一描述按视角词变体生成 2-3 张候选（front / three-quarter / detail），size 按目标比例速查表的生成分辨率
3. 提示词用 references/提示词库.md §一（素材图生成）的产品图/人物图模板
4. 真人数字人场景：无真人照片时同样文生图生成"人物参考图"（模板见提示词库 §一），确认后替代人像进入阶段 3

模式 B：简图扩展（用户有 1-2 张简单图片）

1. 多视角扩展：以现有图为 image 输入 + 视角描述（front → side/top/back/detail view of the same product），input_fidelity: high，每视角出 2 张候选
2. 场景扩展：以局部/单一场景图为输入 + 扩展描述（expand the scene, wider view revealing ...），prompt 中逐项复述原场景核心要素防止场景漂移
3. 使用场景扩展：产品图 + 新场景描述（placed in <camping tent / workshop / dark room>），image 数组传产品图、input_fidelity: high 锁产品，场景由 prompt 驱动
4. 模板见 references/提示词库.md §一B

模式 C：素材齐全 → 跳过本阶段

主体风格一致性（贯穿模式 A/B）：

1. 本阶段开工前先建/补全「主体配方卡」（提示词库 §〇）：产品卡、场景卡、人物卡各一张，固定词汇
2. 模式 A 中第一张用户确认的产品图 → 立即提炼其外观描述回填产品卡（以图为准，不以最初的文字描述为准）；此后所有生成图都以该确认图为 image 参考接力
3. 模式 B 扩展图 prompt 开头粘贴配方卡条目逐字复用，禁止同义词替换（写 "white lantern" 就不再写 "pale lamp"）
4. 风格锚点追加到每个 prompt 末尾；同类图保持相同 size 与构图比例词

确认门（必过，不可跳过）：

1. 每批候选图生成后，用 present_files 一次性展示全部候选（文件名带编号与用途标注），请用户挑选
2. 用户可要求重生成某张（改描述再来）——未确认前不推进任何后续阶段
3. 确认后的图复制到 work/refs/ 并规范命名（product_front.png / product_side.png / product_detail_led.png / scene_main.png / scene_dark_room.png / person_ref.png），未确认候选留在 output/ 不入 refs/
4. 只有 refs/ 内的确认图才能作为阶段 2-4 的 image[] 输入——视频积分是图片的 10 倍以上，图选错再生成视频就是双重浪费
5. 确认完成后更新配方卡与任务清单，再进入阶段 1

阶段 1：剧本生成

1. 若有参考视频：先执行 python scripts/extract_frames.py <视频路径> --out refs/frames --count 8 提取关键帧，逐帧 Read 分析场景（设备、光线、色调、运镜）。
2. 按 references/剧本模板.md 的分镜表结构生成剧本，要点：
   - 五幕式结构：钩子(0-3s) → 痛点/品牌 → 产品亮相+卖点 → 使用场景 → CTA 收尾
   - 每镜 2-5s，总时长按平台要求（社媒 30-45s）
   - 每镜标注：景别、运镜、画面内容、是否含数字人、对应素材图、英文花字、英文旁白、音效
   - 按「常见视频比例速查表」标注每镜构图与安全区（竖屏顶部 10% / 底部 20% 避开平台 UI；横屏主体居中；方形四边留边）
3. 从剧本推导"生成清单"：需要几张合成图（数字人镜头数）、几段分镜视频。

阶段 2：虚拟场景生成

1. 场景图：用 ImageGen 文生图生成场景空镜。提示词要点见 references/提示词库.md §二（场景空镜）。尺寸按「常见视频比例速查表」的生成分辨率选择（如 9:16 用 768×1280、16:9 用 1024×576），quality: high。场景图同样受确认门约束（见阶段 0.7）：候选先给用户确认再用于合成。
2. 场景 3D 模型（可选）：
   - 先调用 connect_cloud_service 获取 token
   - ImageGen 产出图必须先压缩至 ≤512px 宽、≤200KB（cv2.resize + JPEG 质量 88），再上传临时图床获取 URL：
   bash curl -sS --max-time 30 -F "files[]=@scene_input.jpg" "https://uguu.se/upload.php"
   - 然后提交（token 走 stdin，避免命令行泄露）：
   bash echo -n "<token>" | python buddy-cloud.py 3d --image-url "<图床URL>" --enable-pbr --token-stdin
   - 轮询 status <任务ID> --type 3d --token-stdin（约 1-5 分钟），完成后从返回 JSON 的 COS 签名 URL 下载 .glb 与预览图
   - 复制 assets/viewer_template.html 为 <场景名>_viewer.html，将其中 {{GLB_PATH}} 替换为 GLB 文件名，起 python -m http.server 18899 本地服务供用户交互查看
3. 场景动态视频：对场景图跑 VideoGen 图生视频（5s、720P），提示词强调运镜（push-in / orbit / dolly）与氛围（dust particles / light beams）。

阶段 3：数字人生成（合成图）

1. 用 ImageGen 图生图多图输入合成"真人 + 产品 + 场景"：
   - image 参数传数组：[人像图, 产品图, 场景图]
   - input_fidelity: high 保持人物与产品一致性
   - prompt 明确：人物特征（服装/眼镜/发型）+ 持物方式 + 与场景光色调匹配
2. 人物一致性：若用户原始人像不可用，可用历史合成图作为人物参考继续传递。
3. 按剧本需要生成 N 张不同动作/机位的合成图（双手持灯、单手指向、挂灯、放桌上、收尾带 Logo 等），全部按目标比例出图。

阶段 4：按剧本分镜生成视频

1. 先小样验证：正式批量前先跑 1-2 段（1 段数字人镜头 + 1 段纯产品镜头），确认人物/产品/风格达标后再全量——避免十几段全废浪费积分。
2. 逐镜调用 VideoGen（图生视频）：
   - 有合成图的镜头 → 以合成图为输入，prompt 描述人物动作（轻微转头/手势/点头，避免大幅变形）
   - 纯产品镜头 → 以六视图原图为输入，prompt 描述运镜与光效（推近/环绕/灯光亮起）
   - 每段 prompt 末尾加负向过滤词：no distorted hands, no flickering, no morphing objects（数字人镜头另加 no face deformation）
3. 每段 5s、720P，输出到 output/shots/；生成画幅继承输入图比例（合成图按速查表生成分辨率出图）。
4. 每镜生成后立即记录文件名：VideoGen 输出文件名由 prompt 首词自动生成、不可控，当场把「镜号 → 实际文件名」按顺序写入 output/shots/order.txt（每行一个文件名）——最终拼接顺序以此为准，见阶段 5。
5. 注意：单段生成约需 2-5 分钟，且偶发"调用返回成功但无文件"或被拒绝的情况——每次调用后必须 ls 验证文件落盘，缺失则原样重新提交。
6. 建议分批提交（每批 3-4 段），批间验证。

阶段 5：拼接成片

1. 用 python scripts/concat_final.py --dir output/shots --out output/final.mp4 --aspect 9:16 --order output/shots/order.txt：
   - --aspect 支持 9:16 / 16:9 / 1:1 / 4:5 / 3:4 / 4:3 / 21:9 / 3:2（自动映射成片规格）；也可用 --width/--height 手动指定
   - 自动统一所有片段到目标比例（默认 9:16 720×1280）、统一帧率（30fps）、pix_fmt=yuv420p
   - 按 order.txt 的镜号顺序 concat（未提供 order 时按文件名排序，顺序不可靠，仅兜底）
   - 若某镜缺失：脚本提示缺失文件，先补镜（重新提交该镜）再拼接
2. 镜头间自然转场（v1.3 新增）：--transition <类型> --transition-dur <秒> 实现交叉过渡，比硬切更流畅：
   - 默认 cut（硬切，保持兼容）
   - 常用：fade 淡入淡出 / dissolve 交叉溶解 / slideleft 左滑 / wipeleft 左擦 / circleopen 圆形展开 / fadeblack 黑场过渡
   - 也支持 ffmpeg xfade 所有类型：slideright / slideup / slidedown / wiperight / circleclose / zoomin / fadewhite / pixelize 等
   - 内部用 ffmpeg xfade 链式实现，转场时长会从总片时长中扣除（5 段 ×5s + dissolve 0.5s ×4 → 23s）
   - 典型用法：--transition dissolve --transition-dur 0.5
3. VideoGen 无语音/口型，旁白靠字幕呈现（或 TTS 配音，见阶段 6）。
4. 按「质量检查清单」逐项验证后，通过 present_files 向用户交付成片 + 全部中间产物。

阶段 6：字幕合成与配音/混音

> 视频本身无音轨（VideoGen 无语音模块），本阶段为成片补充社媒必备的字幕 + 配音 + BGM，一条命令全包。剧本的「英文花字/英文旁白」直接驱动字幕与配音，所以阶段 1 就要把这些字段写好。

单条命令一站式合成（最常用）：

python scripts/add_audio_subtitles.py \
  --video output/final.mp4 \
  --script 产品视频拍摄剧本流程/剧本输出/Porteele_剧本.md \
  --bgm refs/bgm.mp3 \
  --bgm-volume 0.15 \
  --out output/final_audio.mp4

脚本完成五件事：

1. 解析剧本分镜表：自动识别「时间轴/英文花字/英文旁白」列（剧本模板默认结构），每镜时间轴 → SRT/ASS 字幕文件
2. 生成字幕文件：输出 subtitles.srt（通用剪辑软件用）与 subtitles.ass（社媒大字样式：大字体白字黑边、安全区内；或 classic 经典白字小字）。多语言字幕：若分镜表额外含「中文字幕」列（自动检测，支持别名：翻译字幕/中文翻译/副字幕/副语言字幕/Subtitle CN），自动生成双语字幕——SRT 双行（主+副），ASS 双样式（Default 大字 + Sub2 小字）
3. 烧录字幕（默认开）：用 ffmpeg subtitles filter 把 ASS 烧进视频（不可后期修改，但观众所见即所得）
4. 配音：三种方式按优先级——① --voice-audio 用户提供的现成配音音频（跳过 TTS）→ ② TTS 自动探测（edge-tts 在线优先 → pyttsx3 离线兜底，按英文旁白逐镜生成、按镜 start 时间 adelay 拼接）→ ③ 跳过（仅字幕）
5. BGM 混音：自动循环铺满、淡入淡出、音量默认 0.15；最终 amix 为单条立体声音轨 aac 192k

关键参数：

• --sub-field text|voice|both：字幕取哪个字段，默认 text（英文花字，大字标题），voice 取旁白，both 拼接
• --sub-style big|classic：默认 big（社媒大字白字黑边竖屏，字体 = 视频宽 × 0.115，顶部居中），classic（标准字幕底部居中）
• TTS 自然口语化（v1.3 增强）：
• --tts-voice <voice_name>：默认 en-US-ChristopherNeural（男声沉稳）。更自然推荐：en-US-AvaMultilingualNeural（女声自然）、en-US-EmmaMultilingualNeural（女声温柔）、en-US-JennyNeural（女声活力）、en-US-GuyNeural（男声温暖）
• --rate <+N%>：TTS 语速，如 +5% 略快更自然、-10% 慢速解说（edge-tts 支持 ±100%）
• --pitch <±NHz>：TTS 音调，如 -2Hz 略沉稳、+10Hz 活泼
• 推荐口语化组合：--tts-voice en-US-AvaMultilingualNeural --rate +5% --pitch -2Hz
• 外部配音（v1.3 新增）：用户已有现成配音（配音员/AI 录制/平台下载）时使用，提供后跳过 TTS
• --voice-audio <mp3/wav>：配音音频路径
• --voice-align trim|delay|stretch：默认 trim（直接铺满，短了自动补静音）；delay（按第一镜 start 时间整体后移）；stretch（atempo 变速拉伸适配全片时长——音质会受影响，慎用）
• --bgm-volume 0.15：BGM 音量（旁白为主，BGM 20% 以内不抢戏）
• --no-tts：跳过配音（只要字幕）
• --no-burn：不烧录字幕（仍可混音；适合用剪辑软件叠加花字）
• --srt-only：只生成 SRT/ASS，不烧录不混音（适合先看字幕再决定）
• --offset 0.5：全局时间偏移秒（正数延后），微调用

TTS 引擎自动探测：

• 优先 edge-tts（在线，英文超自然，免费，pip install edge-tts）—— 需要联网
• 兜底 pyttsx3（离线，Windows SAPI 自带声音，pip install pyttsx3）—— 音质一般
• 都没装：跳过配音，提示安装

降级路径（用户无 TTS 也无 BGM，但想要字幕）：

# 1. 只生成字幕文件，后期剪辑叠加
python scripts/add_audio_subtitles.py --video final.mp4 --script 剧本.md --srt-only
# 2. 烧录字幕但无音轨（适合先发静音版测水）
python scripts/add_audio_subtitles.py --video final.mp4 --script 剧本.md --no-tts --out final_sub.mp4
# 3. 用现成配音（无需 TTS 引擎）
python scripts/add_audio_subtitles.py --video final.mp4 --script 剧本.md --voice-audio narrator.mp3 --out final_audio.mp4

依赖：

• pip install edge-tts imageio-ffmpeg（推荐）/ pip install pyttsx3 imageio-ffmpeg（离线）
• 系统 ffmpeg 也可（PATH 含 ffmpeg 即自动选用）
• TTS 段文件输出到 <out 同目录>/voice/voice_XX.mp3，可复用

典型注意事项：

• 剧本分镜表必须含"时间轴"与"镜号"列（剧本模板已默认有）；含"中文字幕"列自动启用双语字幕
• TTS 单词发音偶发异常（如品牌名）→ 改用 --sub-field text 改字幕不带语音；或在剧本旁白里把品牌名写为同音替代词；或直接用 --voice-audio 提供真人/平台标准配音
• BGM 太响盖过旁白 → 调小 --bgm-volume（0.08-0.15 区间常见）
• 字幕太小看不清 → --sub-style big + 调整视频宽高（脚本按视频宽自动算字号）
• 双语字幕中文不显示 → 烧录时系统需有中文字体（Windows 自带微软雅黑/SimHei，Linux 需 apt install fonts-noto-cjk）

质量检查清单（交付前逐项过）

1. 逐镜首/中/末帧抽查：每段用 ffmpeg -ss <t> -i <片段> -frames:v 1 out.jpg 抽 3 帧，检查面部/产品/手部是否变形、有无闪烁
2. 跨镜一致性：相邻镜头的人物服装、产品颜色、场景光线一致（靠角色配方卡固定词汇复述防漂移）
3. 光方向匹配：数字人面部受光方向与场景光源方向一致，无"人物贴图感"
4. 拼接顺序：成片镜序与剧本一一对应，总时长 ≈ 剧本目标 ±2s
5. 平台安全区：竖屏人脸/产品/字幕保持在顶部 10% / 底部 20% 之间；横屏主体居中、字幕不越底部 10%；方形四边留边
6. 水印：ImageGen 水印是否已被品牌 Logo 尾帧/裁剪覆盖

关键约束与已知坑（务必阅读）

1. 3D 生成的图片输入只接受公网 URL：本地路径、base64 命令行传参（超 Windows 命令行长度限制）、localhost HTTP 均失败。唯一可行路径：压缩 → 上传 uguu.se 临时图床 → 拿 URL。uguu 链接有效期约 3 小时，生成完即可。
2. ImageGen 水印：合成图右下角带平台水印，成片中可用品牌 Logo 尾帧遮盖或后期裁剪。
3. VideoGen 无语音/口型：数字人"介绍"是动作演绎，不能说话对唇。剧本旁白靠字幕/阶段 6 的 TTS 配音呈现。
4. 积分消耗参考：文生图/图生图 ~5-10 积分/张；图生视频 ~50-100 积分/5秒；3D 生成 1-5 分钟云端处理。多分镜成片总消耗可达 1000+ 积分，开工前向用户报预估。
5. 人物一致性传递：一旦原始人像丢失，用已有合成图接力；合成图中人物特征（polo 衫颜色、眼镜）要在 prompt 中显式复述。
6. 视频异步落盘：调用"成功"≠文件存在，必须 ls 验证；未落盘的调用需原样重提。
7. 拼接顺序必须用 order.txt：VideoGen 输出文件名由 prompt 首词生成、不可控，绝不依赖文件名排序。
8. 参考图必须先确认再进视频（v1.4）：阶段 0.7 生成的所有候选图必须经用户确认并复制入 work/refs/ 后，才能作为阶段 2-4 的 image[] 输入；配方卡以确认图为唯一真源——文字描述与确认图冲突时，以确认图为准更新配方卡。

资源清单

交付物清单（每次完整执行）

1. （缺图场景）阶段 0.7 确认的参考图集（work/refs/ 规范命名）+ 主体配方卡
2. 拍摄剧本 MD（分镜表）
3. 场景图 + 场景 3D 模型（GLB + HTML 查看器）+ 场景动态视频
4. 数字人合成图（按剧本张数）
5. 分镜视频片段（每镜 5s）
6. 拼接成片（阶段 5，含统一分辨率、目标比例）
7. 最终成片（阶段 6：SRT/ASS 字幕文件 + 烧录字幕 + TTS 配音 + BGM 混音）+ TTS 段文件（voice/voice_XX.mp3）