## CosyVoice 引擎集成指南

本文档说明如何在项目中使用 CosyVoice 引擎进行语音合成。

### 前置条件

1. 已部署本地 CosyVoice API 服务
2. API 地址：`http://192.168.1.200:8000/tts/zero_shot`
3. 确保依赖已安装：`httpx`

### 快速开始

#### 方式 1: 使用工厂模式创建引擎

```python
import asyncio
from tts.factory import TTSEngineFactory

async def main():
    # 创建 CosyVoice 引擎实例
    engine = TTSEngineFactory.create("cosyvoice")
    
    # 合成语音
    text = "你好，这是 CosyVoice 合成的语音。"
    audio = await engine.synthesize(
        text=text,
        voice="your_speaker_id"  # 替换为实际的 speaker ID
    )
    
    # 保存音频
    with open("output.wav", "wb") as f:
        f.write(audio.getvalue())

asyncio.run(main())
```

#### 方式 2: 直接使用 CosyVoice 引擎

```python
import asyncio
from tts.cosyvoice_engine import CosyVoiceEngine

async def main():
    # 创建引擎实例，可以自定义 API 地址和超时时间
    engine = CosyVoiceEngine(
        api_url="http://192.168.1.200:8000/tts/zero_shot",
        timeout=30.0
    )
    
    try:
        # 合成语音
        text = "你好，这是测试文本。"
        audio = await engine.synthesize(
            text=text,
            voice="female_standard_speaker"
        )
        
        # 保存或处理音频
        with open("output.wav", "wb") as f:
            f.write(audio.getvalue())
    
    finally:
        # 关闭连接
        await engine.close()

asyncio.run(main())
```

### API 参数说明

#### 合成接口 (`synthesize`)

**必需参数：**
- `text` (str): 要合成的文本
- `voice` (str): 发音人 ID (`zero_shot_spk_id`)

**可选参数：**
- `language` (str): 语言代码，默认 "zh-CN"
- `rate` (float): 语速，默认 1.0（暂不支持）
- `pitch` (float): 音调，默认 1.0（暂不支持）

**返回值：**
- `BytesIO`: 包含音频数据的字节流对象

**异常：**
- `ValueError`: 如果 `voice` 参数为空，或 API 返回错误
- `httpx.RequestError`: 网络连接错误

### CosyVoice API 请求示例

```bash
curl -X POST "http://192.168.1.200:8000/tts/zero_shot" \
  -H "Content-Type: application/json" \
  -d {
    "text": "你好，世界",
    "zero_shot_spk_id": "female_standard_speaker"
  }
```

### 配置 CosyVoice

如果需要修改 API 地址或超时时间，可以：

1. **环境变量配置** (推荐)
```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)
```

2. **配置文件方式** (参考 `config/app.py`)
```python
from tts.cosyvoice_engine import CosyVoiceEngine

class CosyVoiceConfig:
    API_URL = "http://192.168.1.200:8000/tts/zero_shot"
    TIMEOUT = 30.0

engine = CosyVoiceEngine(**CosyVoiceConfig().__dict__)
```

### FastAPI 集成示例

在 API 路由中使用 CosyVoice：

```python
from fastapi import APIRouter, HTTPException
from tts.factory import TTSEngineFactory

router = APIRouter(prefix="/api/v1/tts", tags=["tts"])

@router.post("/cosyvoice/synthesize")
async def synthesize_with_cosyvoice(text: str, speaker_id: str):
    """
    使用 CosyVoice 合成语音
    
    Args:
        text: 要合成的文本
        speaker_id: 发音人 ID
    
    Returns:
        音频文件内容
    """
    try:
        engine = TTSEngineFactory.create("cosyvoice")
        audio = await engine.synthesize(text=text, voice=speaker_id)
        
        return {
            "status": "success",
            "audio_size": len(audio.getvalue()),
            "content_type": "audio/wav"
        }
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        raise HTTPException(status_code=500, detail="TTS synthesis failed")
```

### 发音人 ID 参考

常见的发音人 ID 示例（需根据实际部署调整）：

- `female_standard_speaker`: 女性标准发音
- `female_gentle_speaker`: 女性温柔发音
- `male_standard_speaker`: 男性标准发音
- `male_gentle_speaker`: 男性温柔发音

具体的发音人 ID 应该根据您部署的 CosyVoice 服务配置。

### 故障排查

#### 问题 1: "Failed to connect to CosyVoice API"

**原因：** 
- CosyVoice 服务未运行
- API 地址配置错误
- 网络连接问题

**解决方案：**
```bash
# 检查服务是否运行
curl http://192.168.1.200:8000/tts/zero_shot -X POST -d "{\"text\":\"test\",\"zero_shot_spk_id\":\"test\"}"

# 检查网络连接
ping 192.168.1.200
```

#### 问题 2: "voice (zero_shot_spk_id) is required for CosyVoice"

**原因：** 没有提供 `voice` 参数

**解决方案：** 确保调用 `synthesize()` 时提供了 `voice` 参数

```python
audio = await engine.synthesize(
    text="测试",
    voice="valid_speaker_id"  # 提供有效的发音人 ID
)
```

#### 问题 3: HTTP 错误 (400, 500 等)

**原因：** API 响应错误

**解决方案：**
- 检查文本格式是否正确
- 验证 speaker_id 是否有效
- 查看 CosyVoice 服务日志获取详细错误信息

### 性能优化

1. **连接重用**：使用工厂模式创建引擎实例可以重用 HTTP 连接
2. **超时配置**：根据网络情况调整 timeout 参数
3. **异步处理**：使用异步接口避免阻塞

### 相关文件

- `tts/cosyvoice_engine.py`: CosyVoice 引擎实现
- `tts/factory.py`: TTS 引擎工厂类
- `tts/base.py`: TTSEngine 抽象基类
- `tts/examples.py`: 使用示例代码

### 更多信息

- [TTS 架构文档](../docs/TTS_ARCHITECTURE.md)
- [TTS 实现指南](../docs/TTS_IMPLEMENTATION_SUMMARY.md)