meme/docs/TTS_INTEGRATION_CHECKLIST.md

TTS 模块集成检查清单

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

✅ 基础集成步骤

1. 依赖安装

• edge-tts 已添加到 requirements.txt
• 运行 pip install -r requirements.txt 安装新依赖

pip install edge-tts

2. 配置设置

• 配置项已添加到 config/settings.py
• 在 .env 文件中添加 TTS 相关配置

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

3. 核心模块

• tts/base.py - 抽象基类
• tts/edge_tts_engine.py - Edge-TTS 实现
• tts/factory.py - 工厂类
• tts/service.py - 高级服务
• tts/__init__.py - 模块入口

🔌 集成到应用

4. API 路由集成

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

编辑 api/v1/routers.py：

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：

from api.v1.tts_routes import router as tts_router

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

验证：

• API 路由已集成
• 可以访问 /api/v1/tts/engines 获取支持的引擎列表

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

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

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 中注册：

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

验证：

• 定时任务已注册（如需要）
• 任务可以正确执行

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

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

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（可选）：

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

运行测试：

pytest tests/test_tts.py -v

验证：

• 测试已创建
• 所有测试通过

8. 手动测试

测试 1：API 端点

# 测试获取支持的引擎
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 代码

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. 添加缓存（可选）

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

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

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

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

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

@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. 添加音频输出功能（可选）

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 值或使用缓存

---

完成日期： _____________

负责人： _____________

备注： _____________