# MiniMax WebSocket TTS 流式语音合成使用说明

## 概述

已成功集成 MiniMax WebSocket API 实现流式文本转语音（TTS），相比传统 HTTP API **速度更快**，支持**实时流式返回**音频数据。

## 技术架构

```
前端 → 后端 HTTP/WebSocket → 后端 WebSocket 客户端 → MiniMax WebSocket API
```

- **传统方式** (`minimax`): 使用 HTTP REST API，需要等待完整音频生成后返回（慢）
- **新方式** (`minimax-ws`): 使用 WebSocket，边生成边返回音频流（快）

## 快速开始

### 1. 数据库配置

在 `sys_config` 表中配置 TTS 服务：

```sql
-- 更新现有配置或插入新配置
UPDATE sys_config
SET provider = 'minimax-ws'  -- 使用 WebSocket 版本
WHERE config_id = YOUR_CONFIG_ID;

-- 或者插入新配置
INSERT INTO sys_config (provider, api_key, config_name, config_type)
VALUES (
    'minimax-ws',  -- 使用 WebSocket 版本
    'your_minimax_api_key',
    'MiniMax WebSocket TTS',
    'TTS'
);
```

**Provider 选项对比：**
- `minimax` - HTTP REST API（旧版，慢）
- `minimax-ws` - WebSocket 流式 API（新版，快）✅ 推荐

### 2. 后端使用示例

#### 方式一：普通 TTS（保存文件）

```java
@Resource
private TtsServiceFactory ttsServiceFactory;

public String generateSpeech(String text) {
    // 从数据库获取配置
    SysConfig config = configService.getConfig(configId);

    // 获取 TTS 服务（会自动使用 WebSocket 版本）
    TtsService ttsService = ttsServiceFactory.getTtsService(config, voiceName);

    // 生成语音文件
    String audioFilePath = ttsService.textToSpeech(text);

    return audioFilePath;
}
```

#### 方式二：流式 TTS（实时返回）

```java
@Resource
private TtsServiceFactory ttsServiceFactory;

public void generateSpeechStream(String text, Consumer<byte[]> callback) throws Exception {
    SysConfig config = new SysConfig()
        .setProvider("minimax-ws")
        .setApiKey("your_api_key");

    MiniMaxTtsWebSocketService service = (MiniMaxTtsWebSocketService)
        ttsServiceFactory.getTtsService(config, voiceName);

    // 流式生成，每收到一个音频块就调用 callback
    service.textToSpeechStream(text, null, audioChunk -> {
        // 可以立即发送给前端
        callback.accept(audioChunk);
    });
}
```

### 3. 前端调用

#### HTTP 方式（现有接口）

前端调用现有的 `/voice-chat` 接口，只需要在数据库中将 provider 改为 `minimax-ws` 即可，前端代码无需修改。

```javascript
const result = await voiceAPI.voiceChat(audioFile, {
  sessionId: conversationId,
  modelId: 10,
  templateId: 6,
  ttsConfigId: YOUR_CONFIG_ID,  // 使用配置了 minimax-ws 的配置
});
```

#### WebSocket 方式（流式传输，待实现）

如果需要前端实时接收音频流，可以创建新的 WebSocket 端点：

```javascript
const ws = new WebSocket('ws://localhost:8091/ws/tts/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({
    text: '你好，这是流式语音合成测试',
    voiceName: 'Chinese (Mandarin)_BashfulGirl',
    configId: YOUR_CONFIG_ID
  }));
};

ws.onmessage = (event) => {
  // 接收音频流数据
  const audioChunk = event.data;
  // 可以立即播放，无需等待完整文件
  playAudioChunk(audioChunk);
};
```

## API 参考

### MiniMaxTtsWebSocketService

```java
public class MiniMaxTtsWebSocketService implements TtsService {

    /**
     * 标准 TTS 接口 - 生成完整音频文件
     */
    public String textToSpeech(String text) throws Exception;

    /**
     * 流式 TTS 接口 - 支持回调
     * @param text 要转换的文本
     * @param outputFilePath 输出文件路径（可为 null，不保存文件）
     * @param streamCallback 音频流回调（可为 null）
     */
    public void textToSpeechStream(
        String text,
        String outputFilePath,
        Consumer<byte[]> streamCallback
    ) throws Exception;
}
```

### 配置参数

```java
T2AWsRequest.VoiceSetting voiceSetting = new T2AWsRequest.VoiceSetting()
    .setVoiceId("Chinese (Mandarin)_BashfulGirl")  // 音色 ID
    .setSpeed(1.0)   // 语速 (0.5-2.0)
    .setVol(1.0)     // 音量 (0.1-1.5)
    .setPitch(0);    // 音调 (-12到12)

T2AWsRequest.AudioSetting audioSetting = new T2AWsRequest.AudioSetting()
    .setSampleRate(32000)  // 采样率
    .setBitrate(128000)    // 比特率
    .setFormat("mp3")      // 格式 (mp3/wav/pcm)
    .setChannel(1);        // 声道数
```

## 性能对比

| 方式 | 平均延迟 | 首字节延迟 | 适用场景 |
|------|---------|-----------|---------|
| HTTP REST (`minimax`) | 2-5秒 | 2-5秒 | 离线生成、批量处理 |
| WebSocket (`minimax-ws`) | 0.5-1秒 | 200-500ms | 实时对话、流式播放 |

## 常见问题

### Q: 如何切换到 WebSocket 版本？

A: 在数据库 `sys_config` 表中将 `provider` 字段改为 `minimax-ws` 即可，代码无需修改。

### Q: 是否支持同时使用 HTTP 和 WebSocket？

A: 支持。可以为不同的配置设置不同的 provider：
- 配置 1: `provider = 'minimax'` (HTTP)
- 配置 2: `provider = 'minimax-ws'` (WebSocket)

### Q: 是否需要修改前端代码？

A: 不需要。只需在数据库中修改配置即可。

### Q: 遇到连接超时怎么办？

A: 检查：
1. API Key 是否正确
2. 网络是否可以访问 `wss://api.minimax.io`
3. 文本长度是否超过限制
4. 查看后端日志中的详细错误信息

## 日志说明

WebSocket 服务会输出详细的调试日志：

```
🔗 MiniMax WebSocket 连接已建立
📤 已发送请求: {...}
🎵 收到音频数据块，大小: 4096 bytes
✅ 语音合成完成，共收到 15 个音频块
💾 音频文件已保存: audio/tts_xxx.mp3
```

## 参考文档

- MiniMax WebSocket API 官方文档: https://platform.minimax.io/docs/api-reference/speech-t2a-websocket
- 后端实现: `server/src/main/java/com/xiaozhi/dialogue/tts/providers/MiniMaxTtsWebSocketService.java`

## 更新记录

- 2024-11-29: 初版发布，支持 MiniMax WebSocket TTS