# TTS 模块 - 快速开始指南

## 📋 前置条件

- Python 3.8+
- pip 包管理器

## 🚀 快速开始（5 分钟）

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

这会自动安装 `edge-tts` 库。

### 2. 配置 TTS 引擎

编辑 `.env` 文件，添加或更新以下配置：

```env
# TTS 配置（可选，有默认值）
TTS_ENGINE=edge-tts
TTS_LANGUAGE=zh-CN
TTS_VOICE=
TTS_RATE=1.0
TTS_PITCH=1.0
```

### 3. 最小化代码示例

#### 选项 A：在 FastAPI 路由中使用

```python
# 在你的 FastAPI 应用中导入 TTS 路由
from api.v1.tts_routes import router as tts_router

app.include_router(tts_router)

# 然后调用 API
# POST /api/v1/tts/synthesize
# {
#   "text": "你好，世界！"
# }
```

#### 选项 B：在定时任务中使用

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

async def job_podcast():
    """生成播客音频"""
    text = "今天的新闻摘要..."
    audio = await TTSService.synthesize(text)
    
    # 保存音频
    with open("podcast.mp3", "wb") as f:
        f.write(audio.getvalue())
```

#### 选项 C：在其他异步函数中使用

```python
from tts.service import TTSService

async def my_function():
    # 合成语音
    audio = await TTSService.synthesize(
        text="你好，这是一个测试。",
        language="zh-CN",
        rate=1.0  # 正常速度
    )
    
    # 使用音频...
```

## 💡 常见用途

### 1. 将新闻文本转为语音播客

```python
from tts.service import TTSService

async def create_podcast(article_text: str):
    """将文章转为语音"""
    audio = await TTSService.synthesize(article_text)
    return audio
```

### 2. 多语言支持

```python
from tts.service import TTSService

async def multilingual_tts(text: str, language: str):
    """支持多语言的文本合成"""
    audio = await TTSService.synthesize(
        text=text,
        language=language
    )
    return audio

# 使用
audio_zh = await multilingual_tts("你好", "zh-CN")  # 中文
audio_en = await multilingual_tts("Hello", "en-US")  # 英文
```

### 3. 调整语速和音调

```python
from tts.service import TTSService

async def create_fast_speech(text: str):
    """创建加速的语音"""
    audio = await TTSService.synthesize(
        text=text,
        rate=1.5,  # 50% 快速
        pitch=1.2  # 音调提高 20%
    )
    return audio
```

### 4. 获取支持的声音

```python
from tts.service import TTSService

async def list_voices():
    """列出所有可用的声音"""
    voices = await TTSService.get_supported_voices(language="zh-CN")
    
    for voice in voices:
        print(f"名称: {voice['display_name']}")
        print(f"ID: {voice['name']}")
        print(f"性别: {voice['gender']}")
        print("---")
```

## 🔧 在实际项目中集成

### 集成到 routers.py

编辑 `api/v1/routers.py`：

```python
from fastapi import APIRouter
from api.v1.tts_routes import router as tts_router

router = APIRouter()

# 包含 TTS 路由
router.include_router(tts_router)

# 你的其他路由...
```

然后在 `main.py` 中：

```python
from api.v1.routers import router

app.include_router(router)
```

### 集成到定时任务

编辑 `scheduler/jobs.py`：

```python
from tts.service import TTSService
from utils.logger import logger

async def job_generate_podcast():
    """定时生成播客"""
    try:
        # 获取文章内容（从数据库或 API）
        article_text = "...你的文章内容..."
        
        # 合成语音
        audio = await TTSService.synthesize(article_text)
        
        # 保存到文件或数据库
        logger.info("Podcast generated successfully")
        
    except Exception as e:
        logger.error(f"Failed to generate podcast: {e}")
```

## 📚 支持的语言

| 语言 | 代码 | 默认声音 |
|------|------|---------|
| 中文（简体）| zh-CN | 晓晓 (XiaoxiaoNeural) |
| 中文（繁体）| zh-TW | HsiaoChen |
| 英文（美国）| en-US | Aria (AriaNeural) |
| 英文（英国）| en-GB | Sonia (SoniaNeural) |
| 日语 | ja-JP | NanaminNeural |
| 韩语 | ko-KR | SunHiNeural |
| 法语 | fr-FR | CelesteNeural |
| 德语 | de-DE | ConraadNeural |
| 西班牙语 | es-ES | AlvaroNeural |
| 俄语 | ru-RU | DmitryNeural |

## ⚙️ 配置参数详解

| 参数 | 说明 | 范围 | 默认值 |
|------|------|------|--------|
| TTS_ENGINE | 使用的 TTS 引擎 | edge-tts | edge-tts |
| TTS_LANGUAGE | 默认语言 | 任何支持的语言代码 | zh-CN |
| TTS_VOICE | 默认声音 | 任何支持的声音 ID | "" (使用默认) |
| TTS_RATE | 语速 | 0.5 - 2.0 | 1.0 |
| TTS_PITCH | 音调 | 0.5 - 2.0 | 1.0 |

## 🧪 运行示例

```bash
# 运行 TTS 示例代码
python tts/examples.py
```

## 📖 详细文档

更多详细信息请查看：
- `tts/README.md` - 完整的 TTS 模块文档
- `TTS_IMPLEMENTATION_SUMMARY.md` - 实现总结

## ❓ 常见问题

### Q: 如何切换到其他 TTS 引擎？
A: 编辑 `.env` 文件，更改 `TTS_ENGINE` 的值。当前只支持 `edge-tts`。

### Q: 如何添加新的 TTS 引擎？
A: 
1. 在 `tts/` 目录创建新文件，实现 `TTSEngine` 接口
2. 在 `tts/factory.py` 中注册新引擎
3. 更新 `config/settings.py` 中的配置选项
4. 在 `.env` 中使用新引擎

### Q: 合成的音频格式是什么？
A: MP3 格式，保存在 `BytesIO` 对象中。

### Q: 支持离线使用吗？
A: Edge-TTS 需要网络连接。如需离线支持，可以集成本地引擎如 pyttsx3。

### Q: 如何提高合成速度？
A: 
1. 设置 `TTS_RATE` > 1.0（例如 1.5）
2. 或在调用时传入 `rate` 参数

## 🐛 调试

如遇到问题，检查日志：

```python
from utils.logger import logger

logger.debug("TTS 调试信息")
logger.error("TTS 错误信息")
```

## 📞 支持

如需帮助，请参考：
1. `tts/README.md` - 详细文档
2. `tts/examples.py` - 使用示例
3. 查看 `utils/logger.py` 中的日志记录

---

祝使用愉快！🎉