307 lines
6.7 KiB
Markdown
307 lines
6.7 KiB
Markdown
# 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` 值或使用缓存
|
||
|
||
---
|
||
|
||
**完成日期：** _____________
|
||
|
||
**负责人：** _____________
|
||
|
||
**备注：** _____________
|