meme/tts/README.md

""" 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. 安装依赖

pip install edge-tts

2. 配置 TTS 引擎

在 .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. 基本使用

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

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())

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

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())

方法三：直接使用引擎

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（推荐使用）

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

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

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

@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（基类）

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

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

获取完整的声音列表

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：

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：

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 中配置使用新引擎：

TTS_ENGINE=new-engine

步骤 4：使用新引擎

from tts.service import TTSService

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

REST API 端点

1. 合成语音

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

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

2. 获取声音列表

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

3. 获取支持的引擎

GET /api/v1/tts/engines

4. 获取引擎信息

GET /api/v1/tts/engine-info

性能优化

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

错误处理

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 支持
• ✅ 多语言支持