# Audio Generator

**文本转音频生成技能**

将文本内容转换为自然流畅的中文语音，支持多种格式和批量生成。

---

## 触发词

- "生成音频"
- "文本转语音"
- "文字转音频"
- "制作有声书"
- "生成朗读音频"

---

## 功能描述

### 核心功能

1. **多格式支持**
   - Markdown 格式（按标题分割）
   - 纯文本格式（按大小分割）
   - 分隔符格式（按【章节】分割）

2. **高质量语音**
   - 使用微软 Edge TTS 引擎
   - 支持多种中文语音（晓晓、云希等）
   - 语音自然流畅，适合长文朗读

3. **智能分割**
   - 自动识别章节结构
   - 支持自定义分割策略
   - 过滤过短内容

4. **批量处理**
   - 批量生成所有章节
   - 支持增量更新
   - 可指定特定章节生成

5. **音频合并**
   - 合并多个章节为完整版
   - 自动按文件名排序
   - 保持原有文件不变
   - 支持自定义输出文件名

---

## 使用场景

### 场景一：知识库转音频课程

用户："帮我把这个知识库文档转成音频课程"

执行步骤：
1. 读取知识库文档
2. 分析文档结构
3. 转换为适合朗读的纯文本
4. 按章节生成音频文件
5. 合并为完整版音频
6. 创建播放说明文档

### 场景二：长文分段朗读

用户："把这篇文章分成几个音频文件"

执行步骤：
1. 分析文本长度
2. 按合适长度分割
3. 生成多个音频文件
4. 合并为完整版
5. 提供播放建议

### 场景三：特定章节生成

用户："只生成第一章和第三章的音频"

执行步骤：
1. 解析用户指定的章节
2. 定位对应文本内容
3. 只生成指定章节的音频
4. 保持文件命名连贯

### 场景四：音频合并

用户："帮我把这些章节音频合并成一个完整版"

执行步骤：
1. 扫描目录中的所有音频文件
2. 按文件名排序
3. 使用 ffmpeg 合并
4. 生成完整版文件
5. 保留原有分章节版本

---

## 工作流程

```
文本输入
    ↓
格式识别 (Markdown/纯文本/分隔符)
    ↓
章节分割
    ↓
内容过滤（跳过过短段落）
    ↓
音频生成（异步批量）
    ↓
输出到指定目录
    ↓
合并为完整版（可选）
    ↓
生成播放说明文档
```

---

## 输入要求

### 文本格式

**推荐格式 - 分隔符格式：**
```
================================================================
【第一章：标题】
内容内容内容...

================================================================
【第二章：标题】
内容内容内容...
```

**Markdown 格式：**
```markdown
## 第一章：标题
内容...

## 第二章：标题
内容...
```

**纯文本格式：**
- 将自动按字符数分割
- 建议预处理添加章节标记

### 内容建议

1. **口语化处理**
   - 移除 Markdown 标记（#、*、-等）
   - 转换为口语化表达
   - 添加适当的停顿和强调

2. **添加术语解释**
   - 专业术语首次出现时添加解释
   - 使用通俗易懂的语言

3. **控制章节长度**
   - 每个章节 5-10 分钟为宜
   - 过长内容建议细分

---

## 输出说明

### 文件结构

```
output_dir/
├── 01_第一章标题.mp3
├── 02_第二章标题.mp3
├── 03_第三章标题.mp3
└── ...
```

### 音频规格

- 格式：MP3
- 编码：128kbps
- 采样率：24kHz
- 语音：Microsoft Edge TTS

---

## 参数配置

### 命令行参数

```bash
python scripts/generate_audio.py <input_file> [options]

Options:
  --format {plain,markdown,separator}  文本格式 (默认: plain)
  --output-dir DIR                     输出目录 (默认: ./audio_output)
  --voice VOICE                        语音模型 (默认: zh-CN-XiaoxiaoNeural)
  --chapters CHAPTERS                  只生成指定章节，逗号分隔
```

### 推荐语音

| 语音代码 | 性别 | 适用场景 |
|---------|------|---------|
| zh-CN-XiaoxiaoNeural | 女声 | 课程内容、长文朗读（默认） |
| zh-CN-YunxiNeural | 男声 | 旁白解说、故事朗读 |
| zh-CN-YunjianNeural | 男声 | 正式场合、官方内容 |
| zh-CN-XiaoyiNeural | 女声 | 故事朗读、温柔亲切 |
| zh-CN-YunyangNeural | 男声 | 新闻播报、官方声明 |

### 命令行选择音色

```bash
# 使用男声（云希）
python scripts/generate_audio.py text.txt --voice zh-CN-YunxiNeural

# 使用女声（晓晓，默认）
python scripts/generate_audio.py text.txt --voice zh-CN-XiaoxiaoNeural
```

---

## 依赖要求

```bash
pip install edge-tts
```

**系统要求：**
- Python 3.7+
- 网络连接（Edge TTS 需要联网）
- 磁盘空间（每小时音频约 50MB）

---

## 示例用法

### 示例 1：基本使用

```bash
python scripts/generate_audio.py article.txt
```

### 示例 2：Markdown 文档

```bash
python scripts/generate_audio.py document.md --format markdown --output-dir ./audio
```

### 示例 3：指定章节

```bash
python scripts/generate_audio.py book.txt --chapters "第一章,第三章,第五章"
```

### 示例 4：使用男声

```bash
python scripts/generate_audio.py text.txt --voice zh-CN-YunxiNeural
```

### 示例 5：合并音频文件

```bash
# 合并所有章节为一个完整版
python scripts/merge_audio.py ./audio_chapters

# 合并并指定输出文件名
python scripts/merge_audio.py ./audio_chapters -o 完整课程.mp3

# 合并特定模式的文件
python scripts/merge_audio.py ./audio_chapters --pattern "part_*.mp3"
```

---

## 故障排除

| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| 生成失败 | edge-tts 未安装 | `pip install edge-tts` |
| 网络错误 | 无法连接 Edge TTS | 检查网络连接 |
| 乱码 | 文本编码错误 | 确保文本为 UTF-8 编码 |
| 文件名为空 | 章节标题非法 | 检查并清理标题中的特殊字符 |
| 部分章节缺失 | 内容过短被过滤 | 调整 MIN_SECTION_LENGTH 或合并短章节 |

---

## 最佳实践

1. **预处理文本**
   - 移除不适合朗读的内容（代码、表格等）
   - 添加口语化过渡
   - 确保术语有解释

2. **测试小样本**
   - 先生成一个章节测试
   - 确认语音效果满意后再批量生成

3. **合理分割**
   - 根据内容逻辑分割
   - 控制单个音频时长
   - 保持章节间连贯性

4. **添加元数据**
   - 创建播放说明文档
   - 标注章节内容摘要
   - 提供学习建议

---

## 相关技能

- **videocut-subtitle**: 视频字幕生成
- **video-creator**: 视频创作
- **story-to-scenes**: 故事拆镜

---

## 更新记录

### v1.0.0 (2026-02-19)
- 初始版本发布
- 支持三种文本格式
- 支持章节过滤
- 支持多种语音选择

---

## 维护者

- 创建者：AI Assistant
- 联系方式：通过 OpenCode 平台

---

## License

MIT License