commit code

tts/COSYVOICE_QUICK_START.md

@@ -0,0 +1,235 @@
+# CosyVoice 引擎集成 - 快速参考
+
+## 文件清单
+
+已创建/修改的文件：
+
+### 新增文件
+- `tts/cosyvoice_engine.py` - CosyVoice 引擎实现
+- `tts/COSYVOICE.md` - 详细使用指南
+- `tts/test_cosyvoice.py` - 集成测试文件
+
+### 修改文件
+- `tts/factory.py` - 注册 CosyVoice 引擎
+- `tts/__init__.py` - 导出 CosyVoiceEngine 类
+- `tts/examples.py` - 添加 CosyVoice 使用示例
+- `requirements.txt` - 添加 httpx 依赖
+
+## 核心实现
+
+### 1. CosyVoice 引擎类 (`cosyvoice_engine.py`)
+
+```python
+from tts.cosyvoice_engine import CosyVoiceEngine
+
+# 创建引擎实例
+engine = CosyVoiceEngine(
+    api_url="http://192.168.1.200:8000/tts/zero_shot",
+    timeout=30.0
+)
+
+# 合成语音
+audio = await engine.synthesize(
+    text="你好世界",
+    voice="speaker_id"  # zero_shot_spk_id
+)
+```
+
+### 2. 工厂模式注册
+
+```python
+from tts.factory import TTSEngineFactory, TTSEngineType
+
+# 通过工厂创建 CosyVoice 引擎
+engine = TTSEngineFactory.create("cosyvoice")
+
+# 或者
+engine = TTSEngineFactory.create(TTSEngineType.COSYVOICE)
+```
+
+## API 调用示例
+
+### POST 请求格式
+
+```
+POST http://192.168.1.200:8000/tts/zero_shot
+Content-Type: application/json
+
+{
+    "text": "合成的文本内容",
+    "zero_shot_spk_id": "发音人ID"
+}
+```
+
+### Python 集成示例
+
+```python
+import asyncio
+from tts.factory import TTSEngineFactory
+
+async def main():
+    # 创建引擎
+    engine = TTSEngineFactory.create("cosyvoice")
+    
+    # 合成语音
+    text = "你好，我是 CosyVoice 合成的语音。"
+    audio = await engine.synthesize(
+        text=text,
+        voice="female_speaker_001"
+    )
+    
+    # 保存音频文件
+    with open("output.wav", "wb") as f:
+        f.write(audio.getvalue())
+
+asyncio.run(main())
+```
+
+### FastAPI 路由示例
+
+```python
+from fastapi import APIRouter, HTTPException
+from tts.factory import TTSEngineFactory
+
+router = APIRouter(prefix="/api/tts", tags=["tts"])
+
+@router.post("/cosyvoice")
+async def synthesize(text: str, speaker_id: str):
+    """使用 CosyVoice 合成语音"""
+    try:
+        engine = TTSEngineFactory.create("cosyvoice")
+        audio = await engine.synthesize(text=text, voice=speaker_id)
+        return {
+            "status": "success",
+            "size": len(audio.getvalue())
+        }
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail="TTS failed")
+```
+
+## 支持的引擎列表
+
+获取所有支持的 TTS 引擎：
+
+```python
+from tts.factory import TTSEngineFactory
+
+engines = TTSEngineFactory.get_supported_engines()
+# 返回: ['edge-tts', 'cosyvoice']
+```
+
+## 关键特性
+
+✓ **异步支持** - 使用 asyncio 异步操作  
+✓ **HTTP 客户端** - 使用 httpx 库进行异步 HTTP 请求  
+✓ **错误处理** - 完善的异常处理和日志记录  
+✓ **连接管理** - 提供 close() 方法管理 HTTP 连接  
+✓ **工厂模式** - 统一的引擎创建和管理接口  
+✓ **参数验证** - 强制要求 voice 参数  
+
+## 依赖项
+
+- `httpx>=0.24.0` - 异步 HTTP 客户端
+- `loguru` - 日志记录（已存在）
+
+## 配置建议
+
+### 环境变量方式
+
+在 `.env` 文件中添加：
+
+```
+COSYVOICE_API_URL=http://192.168.1.200:8000/tts/zero_shot
+COSYVOICE_TIMEOUT=30
+```
+
+在代码中使用：
+
+```python
+import os
+from tts.cosyvoice_engine import CosyVoiceEngine
+
+api_url = os.getenv("COSYVOICE_API_URL", "http://192.168.1.200:8000/tts/zero_shot")
+timeout = float(os.getenv("COSYVOICE_TIMEOUT", "30"))
+
+engine = CosyVoiceEngine(api_url=api_url, timeout=timeout)
+```
+
+### 配置类方式
+
+创建 `config/cosyvoice.py`：
+
+```python
+from pydantic_settings import BaseSettings
+
+class CosyVoiceSettings(BaseSettings):
+    api_url: str = "http://192.168.1.200:8000/tts/zero_shot"
+    timeout: float = 30.0
+    
+    class Config:
+        env_prefix = "COSYVOICE_"
+
+settings = CosyVoiceSettings()
+```
+
+## 故障排查
+
+### 问题：连接失败
+
+```
+ValueError: Failed to connect to CosyVoice API
+```
+
+**检查清单：**
+1. CosyVoice 服务是否运行
+2. 网络连接是否正常
+3. API URL 是否正确
+4. 防火墙是否阻止连接
+
+### 问题：缺少 voice 参数
+
+```
+ValueError: voice (zero_shot_spk_id) is required for CosyVoice
+```
+
+**解决方案：** 确保在调用 `synthesize()` 时提供 `voice` 参数
+
+### 问题：httpx 未安装
+
+```
+ModuleNotFoundError: No module named 'httpx'
+```
+
+**解决方案：** 安装依赖
+```bash
+pip install httpx
+```
+
+## 测试
+
+运行集成测试：
+
+```bash
+python tts/test_cosyvoice.py
+```
+
+运行示例代码：
+
+```bash
+python tts/examples.py
+```
+
+## 更多信息
+
+- [完整使用指南](./COSYVOICE.md)
+- [TTS 架构](../docs/TTS_ARCHITECTURE.md)
+- [示例代码](./examples.py)
+
+---
+
+**版本信息**
+- CosyVoice 引擎版本: 1.0.0
+- 最后更新: 2025年11月
+- 兼容 Python 3.7+