274 lines
5.9 KiB
Markdown
274 lines
5.9 KiB
Markdown
# 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` 中的日志记录
|
||
|
||
---
|
||
|
||
祝使用愉快！🎉
|