---
name: ppt-to-video
description: "将 PDF 幻灯片和演讲稿转换为带同步字幕的完整演讲视频。当用户想要从 PPT/PDF 幻灯片生成带演讲配音和字幕的视频时使用。触发词包括：PPT 转视频、生成演讲视频、幻灯片生成视频、演讲视频、PPT 转视频、生成演讲视频等任何涉及将幻灯片转换为配音演讲视频的请求。"
---

# PPT转视频：演讲视频生成器

## 概述

本技能将 PDF 幻灯片 + 演讲稿转换为带同步字幕的完整演讲视频。使用 edge-tts（微软免费在线 TTS 服务）合成语音，无需 GPU、无需本地模型、无需付费 API。

**核心流水线**：演讲稿处理 → 语音合成 → 视频生成 → 最终合并

## 前置条件

### 必需的系统工具
- **FFmpeg**（含 ffprobe）：`brew install ffmpeg` 或系统包管理器
- **Python 3.8+** 及 pip

### 必需的 Python 包
```bash
pip install edge-tts PyMuPDF numpy
```

## 工作流程

### 步骤 0（必需）：LLM 整理演讲稿格式

**重要**：用户提供的演讲稿可能是各种格式，在调用 `step2_process_speech.py` 之前，**必须先使用 LLM 将演讲稿整理成标准格式**。

#### 整理标准

演讲稿必须符合以下 Markdown 结构：

```markdown
## 第 1 页 幻灯片标题

第 1 页的演讲内容第一段。

第 1 页的演讲内容第二段。

---

## 第 2 页 另一页标题

第 2 页的演讲内容。
```

#### LLM 整理提示词

当用户提供了演讲稿但格式不符合标准时，执行以下步骤：

**1. 调用 LLM 整理格式：**

```
你是一个专业的演讲稿整理助手。请将用户输入的演讲稿整理成标准格式。

## 输出格式要求
1. 使用 ## 第 X 页 标题 的格式来标识每一页幻灯片的开始
2. 每页内容放在标题下方，使用连续的自然段落
3. 删除所有与演讲内容无关的元信息（如备注、作者、时间戳、邮箱等）
4. 保留演讲的核心文字内容和标点符号
5. 清理特殊格式字符，但保留标点
6. 如果原稿件没有明确的页码划分，请根据内容逻辑合理分页（每页建议200-400字）
7. 保持原文语义不变，不要添加或删减实质内容
8. 使用 --- 作为页面之间的分隔符

## 示例

### 示例输入（混乱格式）：
各位朋友大家好
Page 1
欢迎致辞
今天非常高兴...

### 示例输出：
## 第 1 页 欢迎致辞
各位朋友大家好，今天非常高兴。

---

## 第 2 页 主题介绍
...
```

**2. 将 LLM 返回的标准格式内容写入文件**（如 `output/step0_manuscript_formatted.md`）

**3. 后续步骤使用整理后的文件**，而非原始文件

### 输入要求

| 输入 | 必需 | 说明 | 示例 |
|------|------|------|------|
| **演讲稿** | ✅ 必需 | 按页划分的 Markdown 演讲稿 | `slides-speech.md` |
| **PDF 幻灯片** | ✅ 必需 | 演示文稿 PDF 文件 | `slides.pdf` |

### 快速开始 — 一键运行

```bash
python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演讲稿.md> \
    --slides_pdf <幻灯片.pdf> \
    --output_dir <输出目录>
```

将 `{SKILL_DIR}` 替换为本技能目录的绝对路径。

**常用选项：**

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--voice` | `zh-CN-XiaoxiaoNeural` | edge-tts 语音名称 |
| `--resolution` | `1920x1080` | 视频分辨率 |
| `--sentence_pause` | `0.4` | 句子间停顿（秒） |
| `--slide_pause` | `1.0` | 页面间停顿（秒） |
| `--subtitle_mode` | `burn` | `burn`（烧录）/`soft`（软字幕）/`both`（两者） |
| `--font_name` | `auto` | 字幕字体（自动检测系统中文字体） |
| `--font_size` | `38` | 字幕字号 |
| `--dpi` | `200` | PDF 渲染质量 |

### edge-tts 推荐语音

| 语音名称 | 描述 |
|----------|------|
| `zh-CN-XiaoxiaoNeural` | 晓晓（女，温暖自然） |
| `zh-CN-XiaoyiNeural` | 晓伊（女，亲切活泼） |
| `zh-CN-YunjianNeural` | 云健（男，沉稳大气） |
| `zh-CN-YunxiNeural` | 云希（男，年轻阳光） |
| `zh-CN-YunyangNeural` | 云扬（男，新闻播报） |

### 分步执行

如需更精细控制，可逐步运行：

**（步骤 0 在上方"步骤 0（必需）"中说明，推荐在所有步骤之前执行）**

#### 步骤 1：处理演讲稿

解析并清洗 Markdown 演讲稿，生成结构化 TTS 数据。

```bash
python {SKILL_DIR}/scripts/step2_process_speech.py \
    --input <演讲稿.md> \
    --output <输出目录>/step2_speech_data.json
```

**脚本位置**：`scripts/step2_process_speech.py`

**输出**：包含每页句子的结构化 JSON

#### 步骤 2：语音合成

使用 edge-tts 生成演讲音频。

```bash
python {SKILL_DIR}/scripts/step3_tts.py \
    --speech_json <演讲数据.json> \
    --output_dir <输出目录>/step3_tts \
    --voice "zh-CN-XiaoxiaoNeural"
```

**脚本位置**：`scripts/step3_tts.py`

**输出**：
- `full_speech.wav` — 完整演讲音频
- `timing_data.json` — 精确时间数据
- `sentences/` — 逐句音频文件
- `slides/` — 逐页音频文件

#### 步骤 3：生成幻灯片视频

将 PDF 幻灯片转换为与音频时长匹配的视频。

```bash
python {SKILL_DIR}/scripts/step4_generate_video.py \
    --pdf <幻灯片.pdf> \
    --timing_json <时间数据.json> \
    --output_dir <输出目录>/step4_video
```

**脚本位置**：`scripts/step4_generate_video.py`

**输出**：`slides_video.mp4` — 无声幻灯片视频

#### 步骤 4：合并视频、音频和字幕

将所有组件合并为最终演讲视频。

```bash
python {SKILL_DIR}/scripts/step5_merge_all.py \
    --video <幻灯片视频.mp4> \
    --audio <完整音频.wav> \
    --timing_json <时间数据.json> \
    --output <最终输出.mp4>
```

**脚本位置**：`scripts/step5_merge_all.py`

**字幕样式**：白色文字，自动检测中文字体，黑色描边，半透明阴影，底部居中。

**输出**：`final_presentation.mp4` — 带字幕的完整演讲视频

## 演讲稿格式

演讲稿应遵循标准 Markdown 结构（详见上方"步骤 0"）。`step2_process_speech.py` 会自动清洗以下格式：

**自动清洗处理**：
- Markdown 粗体/斜体：`**文字**` → `文字`
- 时间标注：`**（约 1 分钟）**` → 移除
- 引用块：`> 文字` → `文字`
- 代码反引号：`` `代码` `` → `代码`
- 破折号：`——` → `，`（符合自然语流）

## 常见问题排查

### edge-tts 问题
- **连接失败**：检查网络连接，edge-tts 需要访问微软 TTS 服务
- **未安装**：`pip install edge-tts`
- **版本兼容**：自动兼容新版 `save_sync()` 和旧版 `asyncio.run(save())` 两种 API

### PDF 转换
- 安装 PyMuPDF（`pip install PyMuPDF`）作为主后端
- 降级方案：`pip install pdf2image` + 安装 poppler
- **页数不匹配**：如 PDF 页数与演讲稿页数不同，会自动打印警告并做合理处理（多余 PDF 页忽略，缺少则复用最后一页）

### 字幕渲染
- 默认 `--font_name auto`，自动检测当前系统可用的中文字体
- macOS 优先：`PingFang SC` → `Hiragino Sans GB`
- Linux 优先：`Noto Sans CJK SC` → `WenQuanYi Micro Hei` → `Source Han Sans SC`
- Windows 优先：`Microsoft YaHei` → `SimHei`
- 也可手动指定：`--font_name "Noto Sans CJK SC"`
- 验证字体存在：`fc-list :lang=zh family`

### 音视频同步
- 确保 `timing_data.json` 时间数据一致
- 检查 FFmpeg 版本支持 AAC 编码
