# 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+