add edge tts

docs/TTS_INTEGRATION_CHECKLIST.md

@@ -0,0 +1,306 @@
+# 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` 值或使用缓存
+
+---
+
+**完成日期：** _____________
+
+**负责人：** _____________
+
+**备注：** _____________