"""
TTS 模块文档

本模块提供文本转语音（Text-to-Speech）的统一接口，支持多引擎扩展架构。
"""

# TTS 模块使用指南

## 模块结构

```
tts/
├── __init__.py           # 模块入口
├── base.py              # TTS 引擎基类（抽象接口）
├── edge_tts_engine.py   # Edge-TTS 引擎实现
├── factory.py           # TTS 引擎工厂类
├── service.py           # 高级 TTS 服务接口
├── examples.py          # 使用示例
└── README.md            # 本文档
```

## 快速开始

### 1. 安装依赖

```bash
pip install edge-tts
```

### 2. 配置 TTS 引擎

在 `.env` 文件中配置：

```env
# TTS 引擎配置
TTS_ENGINE=edge-tts           # 使用的 TTS 引擎
TTS_LANGUAGE=zh-CN            # 默认语言
TTS_VOICE=                    # 默认声音（为空使用引擎默认）
TTS_RATE=1.0                  # 语速（1.0 为正常）
TTS_PITCH=1.0                 # 音调（1.0 为正常）
```

### 3. 基本使用

#### 方法一：使用高级服务（推荐）

```python
from tts.service import TTSService
import asyncio

async def main():
    # 使用默认配置合成语音
    audio = await TTSService.synthesize("你好，世界！")
    
    # 自定义参数
    audio = await TTSService.synthesize(
        "Hello, World!",
        language="en-US",
        rate=1.2  # 快速
    )
    
    # 获取支持的声音
    voices = await TTSService.get_supported_voices()
    
    # 获取引擎信息
    info = TTSService.get_engine_info()

asyncio.run(main())
```

#### 方法二：直接使用引擎工厂

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

async def main():
    # 创建引擎实例
    engine = TTSEngineFactory.create("edge-tts")
    
    # 合成语音
    audio = await engine.synthesize(
        "你好，世界！",
        language="zh-CN"
    )
    
    # 获取支持的声音
    voices = await engine.get_supported_voices("zh-CN")

asyncio.run(main())
```

#### 方法三：直接使用引擎

```python
from tts.edge_tts_engine import EdgeTTSEngine
import asyncio

async def main():
    engine = EdgeTTSEngine()
    
    audio = await engine.synthesize(
        "你好，世界！",
        voice="zh-CN-XiaoxiaoNeural",
        language="zh-CN"
    )

asyncio.run(main())
```

## API 文档

### TTSService（推荐使用）

高级服务接口，自动使用配置文件中的设置。

```python
async def synthesize(
    text: str,
    language: Optional[str] = None,
    voice: Optional[str] = None,
    rate: Optional[float] = None,
    pitch: Optional[float] = None,
) -> BytesIO:
    """将文本合成为语音"""
    
async def get_supported_voices(language: Optional[str] = None) -> list[dict]:
    """获取支持的声音列表"""

def get_engine_info() -> dict:
    """获取引擎信息"""

def reset_engine() -> None:
    """重置引擎（仅在切换引擎时需要）"""
```

### TTSEngineFactory

引擎工厂类，管理引擎的创建和生命周期。

```python
@classmethod
def create(engine_type: str | TTSEngineType) -> TTSEngine:
    """创建引擎实例（单例模式）"""

@classmethod
def register_engine(engine_type: str, engine_class: type[TTSEngine]) -> None:
    """注册新的引擎类型"""

@classmethod
def get_supported_engines() -> list[str]:
    """获取所有支持的引擎"""
```

### TTSEngine（基类）

所有引擎必须实现的接口。

```python
async def synthesize(
    text: str,
    language: str = "zh-CN",
    voice: Optional[str] = None,
    rate: float = 1.0,
    pitch: float = 1.0,
) -> BytesIO:
    """将文本合成为语音"""

async def get_supported_voices(language: str = "zh-CN") -> list[dict]:
    """获取支持的声音"""

def get_engine_name() -> str:
    """获取引擎名称"""

def get_engine_version() -> str:
    """获取引擎版本"""
```

## 支持的语言和声音

### Edge-TTS 支持的主要语言

- **中文（简体）**: zh-CN - 晓晓 (zh-CN-XiaoxiaoNeural)
- **中文（繁体）**: zh-TW
- **英文（美国）**: en-US - Aria (en-US-AriaNeural)
- **英文（英国）**: en-GB - Sonia (en-GB-SoniaNeural)
- **日语**: ja-JP
- **韩语**: ko-KR
- **法语**: fr-FR
- **德语**: de-DE
- **西班牙语**: es-ES
- **俄语**: ru-RU

### 获取完整的声音列表

```python
from tts.service import TTSService
import asyncio

async def main():
    voices = await TTSService.get_supported_voices("zh-CN")
    for voice in voices:
        print(f"{voice['display_name']}: {voice['name']}")

asyncio.run(main())
```

## 扩展新的 TTS 引擎

### 步骤 1：创建引擎类

创建新文件 `tts/new_engine.py`：

```python
from .base import TTSEngine
from typing import Optional
from io import BytesIO

class NewTTSEngine(TTSEngine):
    """新的 TTS 引擎实现"""
    
    async def synthesize(
        self,
        text: str,
        language: str = "zh-CN",
        voice: Optional[str] = None,
        rate: float = 1.0,
        pitch: float = 1.0,
    ) -> BytesIO:
        # 实现合成逻辑
        pass
    
    async def get_supported_voices(self, language: str = "zh-CN") -> list[dict]:
        # 实现获取声音列表
        pass
    
    def get_engine_name(self) -> str:
        return "new-engine"
    
    def get_engine_version(self) -> str:
        return "1.0.0"
```

### 步骤 2：在工厂中注册

编辑 `tts/factory.py`：

```python
from .new_engine import NewTTSEngine

class TTSEngineType(Enum):
    EDGE_TTS = "edge-tts"
    NEW_ENGINE = "new-engine"  # 添加新引擎

class TTSEngineFactory:
    _engines = {
        TTSEngineType.EDGE_TTS: EdgeTTSEngine,
        TTSEngineType.NEW_ENGINE: NewTTSEngine,  # 注册引擎类
    }
```

### 步骤 3：更新配置

在 `.env` 中配置使用新引擎：

```env
TTS_ENGINE=new-engine
```

### 步骤 4：使用新引擎

```python
from tts.service import TTSService

# TTSService 会自动使用配置中的引擎
audio = await TTSService.synthesize("Hello, World!")
```

## REST API 端点

### 1. 合成语音

```http
POST /api/v1/tts/synthesize
Content-Type: application/json

{
  "text": "你好，世界！",
  "language": "zh-CN",
  "voice": null,
  "rate": 1.0,
  "pitch": 1.0
}
```

### 2. 获取声音列表

```http
GET /api/v1/tts/voices?language=zh-CN
```

### 3. 获取支持的引擎

```http
GET /api/v1/tts/engines
```

### 4. 获取引擎信息

```http
GET /api/v1/tts/engine-info
```

## 性能优化

1. **引擎缓存**：TTSEngineFactory 使用单例模式缓存引擎实例
2. **异步处理**：所有 IO 操作都是异步的，支持高并发
3. **配置缓存**：从配置文件读取的设置只在初始化时加载一次

## 错误处理

```python
from tts.service import TTSService

try:
    audio = await TTSService.synthesize("文本")
except Exception as e:
    print(f"TTS 合成失败: {e}")
```

## 许可证

参考主项目许可证

## 更新日志

### v1.0.0 (初始版本)
- ✅ Edge-TTS 引擎实现
- ✅ 工厂模式支持引擎扩展
- ✅ 高级服务接口
- ✅ REST API 支持
- ✅ 多语言支持