论文讲解视频的自动生成 ★★

文档摘要

源文件：chapter5/paper-to-video/README.md 实验 5-5：论文讲解视频的自动生成 ★★ 在“论文 → PPT”的基础上，Agent 为每一页幻灯片生成口语化讲解词（引导性叙述，而非逐条复述要点），调用 TTS 合成语音，再用 ffmpeg 把 PPT 截图与音频逐页同步合成为一段带旁白的讲解视频。流程本项目自包含，不依赖实验 5-4：内置一份《Attention Is All You Need》的论文要点，用 PIL 直接渲染出 5 页幻灯片 PNG（也可替换为 5-4 的 Slidev 截图）。讲解词由生成；语音由 OpenAI （）合成。

源文件：chapter5/paper-to-video/README.md

实验 5-5：论文讲解视频的自动生成 ★★

在“论文 → PPT”的基础上，Agent 为每一页幻灯片生成口语化讲解词（引导性叙述，
而非逐条复述要点），调用 TTS 合成语音，再用 ffmpeg 把 PPT 截图与音频
逐页同步合成为一段带旁白的讲解视频。

流程


论文要点(内置示例)
   │  PIL 渲染
   ▼
每页 PNG 幻灯片 ──► gpt-5.6-luna 生成口语化讲解词 ──► OpenAI tts-1 合成 mp3
   │                                                        │
   └──────────────── ffmpeg：每页 PNG + 该页音频 ───────────┘
                              │  (每页时长 = 该页音频时长)
                              ▼
                     ffmpeg concat 拼接
                              ▼
                     output/lecture.mp4

本项目自包含，不依赖实验 5-4：内置一份《Attention Is All You Need》的论文要点，
用 PIL 直接渲染出 5 页幻灯片 PNG（也可替换为 5-4 的 Slidev 截图）。
讲解词由 gpt-5.6-luna 生成；语音由 OpenAI tts-1（voice=alloy）合成。
视频由 ffmpeg 合成：每页做一段 mp4，段时长等于该页音频时长，最后 concat 拼接，
因此每页展示时间与语音时长精确匹配。

运行命令


pip install -r requirements.txt      # 安装 Python 依赖
cp env.example .env                  # 填入 OPENAI_API_KEY（未配置时设 OPENROUTER_API_KEY 兜底讲解词，TTS 降级为离线占位）
python demo.py                       # 生成全部 5 页的完整讲解视频

常用参数（python demo.py --help 查看全部）：


python demo.py --check     # 环境自检：检查 ffmpeg/ffprobe/字体/配置，不调用任何 API
python demo.py --quick     # 快速冒烟：只跑第 1 页（等价 --limit 1），省时省钱
python demo.py --limit 2   # 只处理前 2 页
python demo.py --offline   # 无需 API：占位静音音轨，验证整条 ffmpeg 合成流水线

完整参数：

参数	说明
`--slides FILE`	幻灯片内容 JSON（`[{title, subtitle, bullets}, ...]`），替换内置示例
`--script FILE`	现成讲解词 JSON（字符串列表，每页一段），提供后跳过 LLM 生成
`-o, --output FILE`	最终视频输出路径（默认 `output/lecture.mp4`）
`--tts-provider {openai,offline}`	TTS 供应商；`offline` 用 ffmpeg 生成占位静音音轨（无需 API）
`--offline`	完全离线：等价 `--tts-provider offline`，并用要点占位讲解词（零 API 调用）
`--text-model / --tts-model / --tts-voice`	覆盖模型/音色（默认取同名环境变量）
`--limit N / --quick / --check`	只跑前 N 页 / 只跑第 1 页 / 仅自检

离线验证：--offline 不需要任何 API Key 或网络，用 ffmpeg anullsrc 按讲解词字数
估算时长合成静音占位音轨，跑通「渲染 → 估时 → 逐页合成 → concat 拼接」全链路，
专门用于验证 ffmpeg 的逐页时长对齐是否正确（音轨为静音占位，非真实配音）。

产物：

output/slides/slide_*.png 每页幻灯片
output/audio/audio_*.mp3 每页讲解音频
output/segments/seg_*.mp4 每页分段视频
output/narration.json 每页讲解词与音频时长清单
output/lecture.mp4 最终讲解视频

查看视频元信息：


ffprobe -v error -show_format -show_streams output/lecture.mp4

预期输出示例

以内置的 5 页《Attention Is All You Need》为例，一次完整运行的真实产物：

output/lecture.mp4：约 2.8 MB，时长 166.97s（≈2 分 47 秒），
分辨率 1280×720，视频 H.264 + 音频 AAC。
output/audio/audio_01.mp3 … audio_05.mp3：每页一段旁白，
单页时长约 28.6s / 33.3s / 37.2s / 37.9s / 29.9s（总计 ≈166.9s，与视频时长一致）。
output/narration.json：每页的口语化讲解词与音频时长清单，例如第 1 页：

今天，我们将一起探讨一个改变了自然语言处理领域的重要研究——"Attention Is All You Need"……
它完全依赖于注意力机制，摒弃了传统的循环和卷积结构。

运行日志会逐页打印「幻灯片 → 讲解词 → 音频时长」，末尾汇总各页音频总时长与最终视频时长
（二者应基本一致，说明每页展示时间与语音精确对齐）。

依赖

ffmpeg / ffprobe：命令行工具（本项目用 8.x 验证）。macOS 可 brew install ffmpeg。
Python 包：openai、Pillow、python-dotenv（见 requirements.txt）。
中文字体：渲染幻灯片需系统中文字体，脚本已按 macOS 常见字体
（PingFang / STHeiti / Hiragino / Arial Unicode）自动回退。
环境变量：需 OPENAI_API_KEY（走官方 OpenAI）；未配置时可用 OPENROUTER_API_KEY 兜底讲解词生成（此时 TTS 因不在 OpenRouter 上而降级为离线静音占位）。可选项见 env.example。

如何适配 / 扩展

换模型 / 换供应商：环境变量或命令行均可，无需改代码：
- TEXT_MODEL / --text-model：讲解词生成模型（默认 gpt-5.6-luna，可换其它）。
- TTS_MODEL / TTS_VOICE（或 --tts-model / --tts-voice）：语音模型与音色
  （默认 tts-1 / alloy，音色可选 nova / shimmer / echo 等）。
- --tts-provider offline：切到离线占位音轨（不产生任何 API 调用），用于本地验证。
- OPENAI_BASE_URL：指向任何兼容 OpenAI 协议的自定义端点（自建网关、代理或
  第三方供应商）；配合对应的 OPENAI_API_KEY 即可切换后端。
换输入（换论文 / PDF）：用 --slides my.json 传入外部幻灯片内容，或直接编辑
demo.py 中的 SLIDES 列表（标题 / 副标题 / 要点）；若已有真实 PDF，可先用 5-4 的
「论文 → PPT」流程产出要点或 Slidev 截图，再喂给本脚本，其余流程不变。
自带讲解词：用 --script narr.json（每页一段的字符串列表）跳过 LLM 生成，
直接进入「TTS → 合成」，便于人工润色脚本后重跑。
更长视频：增加 SLIDES 页数或加长每页讲解词即可（单次 5~15 分钟）。
快速调参：先用 --quick / --limit N 只渲染少量页，确认音色/风格满意后再跑全量。

局限

讲解词与 TTS 都会产生真实的 OpenAI API 调用（TEXT_MODEL 与 TTS_MODEL），会计费；
全量 5 页约生成 2~3 分钟视频。建议先 --check 自检、再 --quick 冒烟。
幻灯片为 PIL 纯静态渲染（无动画/转场），中文字体依赖系统字体，非 macOS 需自行调整
FONT_CANDIDATES。
每页时长严格等于该页音频时长，不做静音停顿或背景音乐；如需更精细的排版与转场，
建议改用 5-4 的 Slidev 截图作为输入。