课件PPT转讲解视频

概述

PPT/PDF → 带语音讲解视频

Overview

把一份 N 页的演示文稿变成逐页讲解视频：画面 = 原稿每页高清图，声音 = 逐页讲解配音，字幕 = 逐句同步显示。最终产出 1920×1080 MP4(默认带字幕版)。

核心路径决策(避免头号大坑)：本环境不渲染 .pptx。画面一律从 PDF 渲染——PDF 每页已是"画好的页面"，用 pymupdf 直接转图，无需 Office/WPS/LibreOffice。因此任务开始时先向用户说明：直接提供 PDF 成本最低、速度最快，并询问是否已有 PDF；若只有 .pptx，指导用户用 PowerPoint/WPS "另存为 PDF"。

工作目录约定

在一个干净工作目录(如 {workspace}/视频工作目录/)下建立子目录:

工作目录/
├── 讲解稿.json          # narration: 标题/音色/每页讲解词(单一数据源)
├── 01_frames/           # frame_01.png ... frame_NN.png (画面)
├── 02_audio/            # slide_01.mp3 ... slide_NN.mp3 (语音)
└── 03_output/           # 成品: <title>(带字幕).mp4

执行前必读

通读 references/pitfalls.md(真实踩坑 16 条)与 references/voices.md(音色选择)。关键红线先记住:

• 未经用户明确确认讲解稿, 不得进入语音合成(强制关卡, 见第 3 步);
• 路径一律 Windows 绝对路径; 别用 zoompan; ASS alpha 00=不透明。

分步流程

1. 澄清需求(一次问清, 避免返工)

问三件事, 拿到答复再开工:

• 输入形态: 有现成 PDF 吗? 没有则请用户导出一份(最优先); 只有 .pptx 则先做第 2 步并让用户并行导出。
• 音色偏好: 参考 voices.md 的音色表; 用户想要"自己的声音/克隆音色"时走 voices.md A1 节

(百炼 CosyVoice 声音复刻, 已实测跑通; 用户侧只需录 10~20 秒样本)。

• 字幕策略: 默认带字幕(逐句+半透明底框); 用户明确不要再跳过。

2. 读内容 & 写讲解稿(单一数据源)

• 有 .pptx 且需要读文本: python scripts/extract_pptx.py <input.pptx> --out 讲解稿来源.txt
• 只有 PDF 时: 直接用 Read 工具读 PDF 获取每页内容。
• 逐页撰写讲解稿: 口语化、可朗读、每页 2~5 句、信息密度适中(不照读图表)。

讲解词必须忠实页面内容; 数据多/文字密的页提炼要点。

• 把讲解稿写入 讲解稿.json, 结构如下(这是语音、字幕、时间轴的唯一数据源):

{
  "title": "新员工入职培训-公司篇",
  "voice": "zh-CN-XiaoxiaoNeural",
  "rate": "+0%",
  "slides": [
    { "idx": 1, "text": "欢迎加入公司……" },
    { "idx": 2, "text": "今天的培训分五部分……" }
  ]
}

idx 必须从 1 连续编号且与帧/音频文件名 frame_XX.png、slide_XX.mp3 严格对应。

3. 确认讲解稿（强制关卡，不可跳过）

硬性规则：讲解稿未经用户明确确认，不得进入第 4 步语音合成。 音频一旦合成，改一个词就要重合成语音 + 重跑视频，代价很高 —— 磨刀不误砍柴工，确认必须前置。

操作：

1. 把 讲解稿.json 导出成可读的 讲解稿(待确认).md（一页一节：## 第 N 页 + 该页讲解词），

用 present_files 呈现给用户 —— 让用户"看着 word 稿点确认"，而不是在对话里翻 JSON。

1. 同时用一段话点明需要用户重点核对的三件事：
   • 口径：是否符合公司规范 / 业务事实；
   • 数字与政策：金额、期限、比例、制度条款是否准确；
   • 详略：每页篇幅是否合适（会不会太赶或太啰嗦）。
2. 明确告知后续成本：确认后再合成语音；此后再改词 = 重合成语音 + 重跑视频。
3. 等用户明确回复确认（如"确认 / 没问题 / 可以开始 / 就按这个"）后才继续。

用户只提了修改意见 → 改 讲解稿.json → 重新导出 md 再展示，循环直到确认。用户沉默或只问别的 → 不算确认，停下来等。

1. 用户确认后，在原 json 里记录确认动作（如把 "confirmed": true 写回，

或另存 讲解稿(已确认).json），语音合成的 --confirmed 开关即以此为准。

为什么做成硬关卡：讲解稿是"语音 + 字幕 + 时间轴"的唯一数据源，也是唯一能低成本修改的阶段；

音频合成之后，任何文字调整都要付出整门课重做的代价。用户是内容责任人，必须由他拍板。

4. 合成逐页语音

前置条件：第 3 步已获用户明确确认。 两个脚本都带 --confirmed 守卫，不加该参数会直接拒绝执行并提示先走确认流程（防误触，见 pitfalls 16）。

# edge-tts（免费、本地）
python scripts/make_tts.py --narration 讲解稿.json --out 02_audio --confirmed
# 覆盖音色/语速示例:
python scripts/make_tts.py --narration 讲解稿.json --out 02_audio 
    --voice zh-CN-YunxiNeural --rate -10% --confirmed

# 阿里云 CosyVoice（更自然，需 API Key；详见 voices.md A0 / A1 节）
python scripts/make_tts_cosyvoice.py --narration 讲解稿.json --out 02_audio 
    --model cosyvoice-v3-flash --voice longanli_v3 --api-key sk-xxx --confirmed

• 克隆音色必须匹配绑定模型：克隆时选的 target_model 是哪个，合成时 --model 就必须是哪个，

否则报错/失败。如 cosyvoice-v3.5-plus 克隆出来的音色，只能用 --model cosyvoice-v3.5-plus合成（不能用 v3-flash 配）。音色 ID 形如 cosyvoice-v3.5-plus-<prefix>-<hash>，控制台上按"我的复刻"查，也可用 voices.md A1 节的接口列出来。

• 校验: 输出应显示全部 OK, 02_audio/ 下每页一个 mp3。
• 时间轴将完全由这些语音时长驱动(此后再改讲解词 = 重新合成语音 + 重跑合成)。
• 34 页量级的批量合成约需 2~4 分钟：可后台跑，但必须在同一回合内阻塞等到跑完

（见 pitfalls 13，否则回合结束进程会被回收，只合成一半）。

5. 渲染页面帧(画面来源)

先确认 PDF 就位(用户导出或已有), 检查页数与 16:9:

python scripts/pdf_to_frames.py <输入.pdf> 01_frames 1920

• 渲染后抽查 3 页(首页/内容密的一页/表格页)确认字体、版式、表格正常再继续。

6. 合成视频(静态页 + xfade + 逐句字幕)

python scripts/compose_video.py --frames 01_frames --audio 02_audio 
    --narration 讲解稿.json --out 03_output

• 默认产出 <title>(带字幕).mp4; 需要无字幕版加 --also-plain;

只要无字幕用 --no-sub。

• 编码较久(数分钟~十几分钟): 放后台跑, 但必须在同一回合内阻塞等到完成

（如 TaskOutput block=true），否则回合结束进程会被环境回收、任务半途夭折（pitfalls 13）。

• 常见报错对照: 双输出音频需 asplit(脚本已内置); 滤镜引用字幕用 basename(已内置)。

7. 验证与交付

• 抽帧验证: 在转场点(页交界 ±0.3s)抽 1~2 帧确认 xfade 平滑、无黑闪;

在一页中段抽帧确认字幕位置与内容; 中文路径文件用 Python 脚本处理与 ffprobe 校验。

• present_files 交付成品并给出路径。
• 建议保留素材(帧/语音/讲解稿.json/脚本)到用户确认满意后再清理 —— 便于改词重合成。

常见失败对照速查

Resources

• scripts/extract_pptx.py — 提取 .pptx 每页文本(写讲解稿用)
• scripts/pdf_to_frames.py — PDF 逐页渲染高清帧(Windows 路径 + 写后校验)
• scripts/make_tts.py — edge-tts 批量语音(重试防限流)
• scripts/make_tts_cosyvoice.py — 阿里云 CosyVoice 批量语音(更自然; 支持预设音色与克隆音色)
• scripts/compose_video.py — 静态页+xfade+逐句字幕合成(默认带字幕)
• references/pitfalls.md — 16 条真实踩坑与规避(执行前必读)
• references/voices.md — 预设音色清单、CosyVoice 调用要点、克隆音色获取与使用