Index-TTS-VLLM Client

一个用于调用 index-tts-vllm 语音引擎的 Python 客户端库，将文本转换为语音，支持情感控制。

• 简单易用的文本转语音接口
• 支持使用说话人参考音频进行声音克隆
• 支持多种情感控制方式（情感参考音频、情感向量、情感描述文本）
• 直接返回音频数据流
• 服务健康检查
• 完整的错误处理

1. 克隆项目：

git clone <repository-url>
cd indextts-test

2. 创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

3. 安装依赖：

pip install -r requirements.txt

4. 配置环境变量：

cp .env.example .env

编辑 .env 文件，设置 index-tts-vllm API 地址：

INDEX_TTS_API_URL=http://192.168.31.32:6006/

index-tts-vllm API 要求必须提供说话人参考音频文件路径（spk_audio_path）。

• 参考音频文件必须存在于服务端服务器上
• 不提供参考音频或提供无效路径会导致 500 错误
• 参考音频路径是服务端服务器上的文件路径，不是客户端路径
• 需要联系服务端管理员确认可用的参考音频文件路径

1. 从 index-tts-vllm 项目获取：

   • 克隆 index-tts-vllm 项目
   • 查找 assets/ 目录中的音频文件
   • 将音频文件上传到服务端服务器的相应路径

2. 使用服务端已有的音频文件：

   • 联系服务端管理员
   • 确认可用的参考音频文件路径
   • 在请求中使用确认的路径

3. 准备自己的参考音频：

   • 录制或获取参考音频文件
   • 将文件上传到服务端服务器
   • 使用服务端上的文件路径

from src.tts import text_to_speech

# 基本使用（需要提供服务端上的参考音频路径）
text_to_speech(
    "你好，世界！",
    spk_audio_path="/path/to/reference.wav",  # 服务端上的文件路径
    output_path="output/hello.wav"
)

text_to_speech(
    "你好，世界！",
    spk_audio_path="/path/to/speaker.wav",  # 服务端上的文件路径
    emo_control_method=1,  # 使用情感参考音频
    emo_ref_path="/path/to/emotion.wav",  # 情感参考音频路径
    emo_weight=0.6,
    output_path="output/hello.wav"
)

# 情感向量：["喜", "怒", "哀", "惧", "厌恶", "低落", "惊喜", "平静"]
emo_vec = [0, 0, 0.55, 0, 0, 0, 0, 0]  # 悲伤情感

text_to_speech(
    "你好，世界！",
    spk_audio_path="/path/to/speaker.wav",  # 服务端上的文件路径
    emo_control_method=2,  # 使用情感向量
    emo_vec=emo_vec,
    output_path="output/hello.wav"
)

text_to_speech(
    "你好，世界！",
    spk_audio_path="/path/to/speaker.wav",  # 服务端上的文件路径
    emo_control_method=3,  # 使用情感描述文本
    emo_text="极度悲伤",
    output_path="output/hello.wav"
)

from src.client import IndexTTSClient

# 创建客户端
client = IndexTTSClient("http://192.168.31.32:6006/")

# 检查服务状态
if client.health_check():
    print("服务可用")

# 文本转语音
audio_data = client.text_to_speech(
    "你好，世界！",
    spk_audio_path="/path/to/speaker.wav",  # 服务端上的文件路径
    emo_control_method=2,
    emo_vec=[0, 0, 0.55, 0, 0, 0, 0, 0],
    output_path="output/test.wav"
)

python examples/basic_usage.py

注意：示例程序会跳过所有测试，因为需要服务端上的参考音频文件。

将文本转换为语音（简化接口）

参数：

• text (str): 要转换的文本
• output_path (str, 可选): 输出文件路径
• api_url (str, 可选): API 地址
• spk_audio_path (str, 必需): 说话人参考音频文件路径（服务端上的文件路径）
• emo_control_method (int, 可选): 情感控制方法
  • 0: 无情感控制（默认）
  • 1: 使用情感参考音频
  • 2: 使用情感向量
  • 3: 使用情感描述文本
• emo_ref_path (str, 可选): 情感参考音频路径（emo_control_method=1 时使用）
• emo_weight (float, 可选): 情感权重，默认 1.0
• emo_vec (list, 可选): 情感向量，8维浮点数列表（emo_control_method=2 时使用）
  • 对应情感：["喜", "怒", "哀", "惧", "厌恶", "低落", "惊喜", "平静"]
• emo_text (str, 可选): 情感描述文本（emo_control_method=3 时使用）
• emo_random (bool, 可选): 是否随机情感，默认 False
• max_text_tokens_per_sentence (int, 可选): 每句最大文本token数，默认 120

返回：

• bytes: 语音数据的字节流

index-tts-vllm API 客户端类

方法：

• __init__(api_url): 初始化客户端
• text_to_speech(text, output_path, spk_audio_path, emo_control_method, ...): 文本转语音
• health_check(): 检查服务是否可用

indextts-test/
├── src/
│   ├── __init__.py
│   ├── client.py      # API 客户端实现
│   └── tts.py         # 简化的接口函数
├── examples/
│   └── basic_usage.py # 使用示例
├── assets/             # 参考音频文件说明（需要手动添加到服务端）
├── output/            # 生成的音频文件（自动创建）
├── .env               # 环境变量配置
├── .env.example       # 环境变量示例
├── .gitignore
├── requirements.txt   # Python 依赖
└── README.md

• POST /tts_url - 文本转语音
• GET /health - 健康检查

{
  "text": "要转换的文本",
  "spk_audio_path": "说话人参考音频路径（服务端上的文件路径）",
  "emo_control_method": 0,
  "emo_ref_path": null,
  "emo_weight": 1.0,
  "emo_vec": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
  "emo_text": null,
  "emo_random": false,
  "max_text_tokens_per_sentence": 120
}

情感向量是8维浮点数，对应以下情感：

• 索引 0: 喜
• 索引 1: 怒
• 索引 2: 哀
• 索引 3: 惧
• 索引 4: 厌恶
• 索引 5: 低落
• 索引 6: 惊喜
• 索引 7: 平静

示例：

# 悲伤
emo_vec = [0, 0, 0.55, 0, 0, 0, 0, 0]

# 喜悦
emo_vec = [0.8, 0, 0, 0, 0, 0, 0.3, 0]

成功时返回音频数据流（application/octet-stream），失败时返回 JSON 错误信息。

1. 确保 index-tts-vllm 服务正在运行并可访问
2. 默认 API 地址为 http://192.168.31.32:6006/
3. spk_audio_path 参数是必需的，必须提供服务端服务器上的音频文件路径
4. 参考音频文件必须存在于服务端服务器上（不是客户端）
5. 输出目录会自动创建
6. 参考 API 文档: http://192.168.31.32:6006/docs

问题：无法连接到服务

• 检查 index-tts-vllm 服务是否正在运行
• 确认 API 地址配置正确
• 检查网络连接和防火墙设置

问题：API 返回 500 错误

• 确认 spk_audio_path 参数已提供
• 检查参考音频文件是否存在于服务端服务器上
• 验证音频文件路径是否正确
• 联系服务端管理员确认可用的参考音频文件路径

问题：生成的音频文件为空或损坏

• 检查 index-tts-vllm 服务日志
• 确认 API 响应格式是否正确
• 如果使用参考音频，确保音频文件存在且格式正确

问题：情感控制不生效

• 确认 emo_control_method 参数设置正确
• 检查对应的情感参数是否提供（emo_ref_path、emo_vec 或 emo_text）
• 验证情感向量格式是否正确（8维浮点数列表）

MIT License

• index-tts-vllm GitHub
• API 文档