# TTS 模块集成检查清单

使用此清单来完整集成 TTS 模块到你的应用中。

## ✅ 基础集成步骤

### 1. 依赖安装
- [x] `edge-tts` 已添加到 `requirements.txt`
- [ ] 运行 `pip install -r requirements.txt` 安装新依赖

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

### 2. 配置设置
- [x] 配置项已添加到 `config/settings.py`
- [ ] 在 `.env` 文件中添加 TTS 相关配置

```env
# 添加到 .env 文件
TTS_ENGINE=edge-tts
TTS_LANGUAGE=zh-CN
TTS_VOICE=
TTS_RATE=1.0
TTS_PITCH=1.0
```

### 3. 核心模块
- [x] `tts/base.py` - 抽象基类
- [x] `tts/edge_tts_engine.py` - Edge-TTS 实现
- [x] `tts/factory.py` - 工厂类
- [x] `tts/service.py` - 高级服务
- [x] `tts/__init__.py` - 模块入口

## 🔌 集成到应用

### 4. API 路由集成

**选项 A：添加到现有的 API 路由中（推荐）**

编辑 `api/v1/routers.py`：

```python
from fastapi import APIRouter
from api.v1.tts_routes import router as tts_router

router = APIRouter()

# 包含 TTS 路由
router.include_router(tts_router)

# 你的其他路由...
```

**选项 B：在 main.py 中直接注册**

编辑 `main.py`：

```python
from api.v1.tts_routes import router as tts_router

# 在应用启动时
app.include_router(tts_router)
```

**验证：**
- [ ] API 路由已集成
- [ ] 可以访问 `/api/v1/tts/engines` 获取支持的引擎列表

### 5. 在定时任务中使用（可选）

编辑 `scheduler/jobs.py`，如果需要定时生成播客：

```python
from tts.service import TTSService

async def job_generate_podcast():
    """定时生成播客任务"""
    try:
        # 获取需要转换的文本（从数据库、API 等）
        text = "需要转换的文本内容..."
        
        # 合成语音
        audio = await TTSService.synthesize(text)
        
        # 保存或处理音频
        # ...
        
        logger.info("Podcast generated successfully")
    except Exception as e:
        logger.error(f"Failed to generate podcast: {e}")
```

如果添加了新的任务，需要在 `main.py` 中注册：

```python
scheduler.add_job(
    jobs.job_generate_podcast,
    trigger="cron",
    hour="2",  # 每天凌晨 2 点
    id="podcast-job",
    replace_existing=True,
)
```

**验证：**
- [ ] 定时任务已注册（如需要）
- [ ] 任务可以正确执行

### 6. 在其他服务中使用（可选）

编辑 `services/` 下的相关服务文件：

```python
from tts.service import TTSService

class MyService:
    async def generate_audio(self, text: str) -> BytesIO:
        """使用 TTS 生成音频"""
        return await TTSService.synthesize(text)
```

**验证：**
- [ ] 服务已集成 TTS 功能
- [ ] 可以正常调用

## 🧪 测试验证

### 7. 单元测试

创建 `tests/test_tts.py`（可选）：

```python
import pytest
from tts.service import TTSService

@pytest.mark.asyncio
async def test_tts_synthesize():
    """测试 TTS 合成"""
    audio = await TTSService.synthesize("测试")
    assert audio.getbuffer().nbytes > 0

@pytest.mark.asyncio
async def test_tts_voices():
    """测试获取声音列表"""
    voices = await TTSService.get_supported_voices()
    assert len(voices) > 0
```

运行测试：
```bash
pytest tests/test_tts.py -v
```

**验证：**
- [ ] 测试已创建
- [ ] 所有测试通过

### 8. 手动测试

**测试 1：API 端点**

```bash
# 测试获取支持的引擎
curl http://localhost:8000/api/v1/tts/engines

# 测试获取声音列表
curl http://localhost:8000/api/v1/tts/voices

# 测试获取引擎信息
curl http://localhost:8000/api/v1/tts/engine-info

# 测试合成语音
curl -X POST http://localhost:8000/api/v1/tts/synthesize \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，世界！"}'
```

**测试 2：Python 代码**

```python
import asyncio
from tts.service import TTSService

async def test():
    # 测试合成
    audio = await TTSService.synthesize("测试语音合成")
    print(f"合成成功，音频大小: {audio.getbuffer().nbytes} bytes")
    
    # 测试获取声音列表
    voices = await TTSService.get_supported_voices()
    print(f"找到 {len(voices)} 个声音")
    
    # 测试引擎信息
    info = TTSService.get_engine_info()
    print(f"引擎信息: {info}")

asyncio.run(test())
```

**验证：**
- [ ] API 端点响应正常
- [ ] 可以成功合成语音
- [ ] 可以获取声音列表
- [ ] 引擎信息输出正确

## 📋 可选增强功能

### 9. 添加缓存（可选）

为避免重复合成相同文本：

```python
# 在 tts/service.py 中添加缓存
from functools import lru_cache

class TTSService:
    @lru_cache(maxsize=128)
    async def synthesize(self, text: str, ...):
        # 缓存合成结果
        ...
```

### 10. 添加声音选择界面（可选）

在 API 中添加选择声音的端点：

```python
@app.get("/api/v1/tts/voices/{language}")
async def get_voices_by_language(language: str):
    voices = await TTSService.get_supported_voices(language)
    return {"language": language, "voices": voices}
```

### 11. 添加音频输出功能（可选）

```python
from fastapi.responses import StreamingResponse

@app.post("/api/v1/tts/stream")
async def stream_audio(request: TTSSynthesizeRequest):
    """流式输出音频"""
    audio = await TTSService.synthesize(request.text)
    return StreamingResponse(
        iter([audio.getvalue()]),
        media_type="audio/mpeg"
    )
```

## 📚 文档和示例

- [ ] 阅读 `tts/README.md` - 完整文档
- [ ] 查看 `tts/examples.py` - 使用示例
- [ ] 参考 `TTS_QUICK_START.md` - 快速开始
- [ ] 查看 `TTS_IMPLEMENTATION_SUMMARY.md` - 实现总结

## 🚀 部署前检查

- [ ] 所有依赖已安装
- [ ] 配置文件已更新
- [ ] API 路由已集成（如需要）
- [ ] 定时任务已注册（如需要）
- [ ] 所有测试通过
- [ ] 日志记录正常
- [ ] 异常处理完整
- [ ] 文档已更新

## 🔄 后续维护

### 扩展新引擎

如需添加新的 TTS 引擎（如 Google TTS、Baidu TTS 等）：

1. 在 `tts/` 下创建新文件 `tts/google_tts_engine.py`
2. 实现 `TTSEngine` 接口
3. 在 `tts/factory.py` 中注册
4. 更新 `config/settings.py`
5. 更新此清单

### 监控和日志

确保系统中有以下监控：

- [ ] TTS 调用次数和时间
- [ ] 失败率和错误日志
- [ ] 音频文件大小统计
- [ ] 不同语言的使用频率

## 📞 支持和问题排查

**问题：edge-tts 需要网络连接**
- 解决方案：确保网络连接正常，或使用离线 TTS 引擎

**问题：某些语言声音不可用**
- 解决方案：检查支持的声音列表，确保使用了正确的语言代码

**问题：合成速度慢**
- 解决方案：设置较高的 `TTS_RATE` 值或使用缓存

---

**完成日期：** _____________

**负责人：** _____________

**备注：** _____________