minimax-tokenplan-tts

# MiniMax TTS Skill

## 前置条件

- **Python 3** 已安装
- **requests 库**：`pip3 install requests`
- **websockets 库**：`pip3 install websockets`（流式播放需要）
- **ffplay**（流式播放需要）：
  - macOS: `brew install ffmpeg`
  - Ubuntu: `sudo apt install ffmpeg`
  - Windows: 从 https://ffmpeg.org/download.html 下载
  - 如果 ffplay 未安装，`stream_play.py` 会提示安装方法

## init

### 需要初始化以下信息：

**第一步：获取 API Key**

向用户获取 MiniMax API Key（`sk-cp-` 开头的 Token Plan key，或普通 API Key）。

**第二步：确认配置**

向用户确认：
- API Key 是否正确
- 使用国内（`https://api.minimaxi.com`）还是海外（`https://api.minimaxi.io`）节点

**第三步：填写配置**

获取以上信息后：
1. 修改 `scripts/generate.py` 顶部的配置常量（`API_KEY`、`BASE_URL`），填入实际值
2. 修改 `scripts/stream_play.py` 顶部的配置常量（`API_KEY`、`BASE_URL`），填入相同的值
3. 同时更新下方 `## 配置` 区段的表格，作为配置记录

**第四步：判断音色**

1. 根据 `IDENTITY.md` 自行选择声优
2. 如判断不出，则使用 `male-qn-jingying`（精英青年音色）
3. 然后更新下方 `## 配置` 区段的表格及两个脚本

**第五步：清理**

配置填写完成后，**删除本 `## init` 区段（包括 `### 需要初始化以下信息` 的全部内容），仅保留 `## 配置` 区段**。

---

## 配置

| 配置项 | 值 | 说明 |
|--------|-----|------|
| **MINIMAX_API_KEY** | `<待填入>` | 初始化时替换为实际 key |
| **BASE_URL** | `<待填入>` | CN: `https://api.minimaxi.com` / Global: `https://api.minimaxi.io` |
| **REGION** | `<待填入>` | `CN` 或 `global` |
| **VOICE_ID** | `<待填入>` | 判断音色后填入 |
---

## 音色列表

语言因音色较多，不再逐一列出，完整列表参考 [MiniMax TTS 官方文档](https://platform.minimaxi.com/docs/faq/system-voice-id)：

---

## 快速使用

> **📢 channel=webchat 时的播放策略**：当前 channel 为 `webchat`（实时对话场景）时，
> 应优先使用 `stream_play.py` **直接流式播放**，而不生成文件。这样用户可以立即听到语音，
> 无需等待完整音频生成。仅当用户明确要求保存文件时，才使用 `generate.py`。

### 1️⃣ 流式播放（channel=webchat）

通过 WebSocket 实时获取音频流，边生成边用 ffplay 播放。**无需生成文件，首个音频包到达即开始播放**。

```bash
SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-tts"
python3 "$SKILL_DIR/scripts/stream_play.py" \
    --text "要播放的文本内容" \
    --voice "male-qn-jingying"
```

> **注意**：以下示例中 `stream_play.py` 和 `generate.py` 均指 `~/.openclaw/workspace/skills/minimax-tokenplan-tts/scripts/` 下的完整路径。

**参数说明：**

| 参数 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `--text` | ✅ | 要播放的文本，**最长 10000 字符** | - |
| `--voice` | ❌ | 声优 ID | `male-qn-jingying` |
| `--speed` | ❌ | 语速 [0.5,2.0] | `1.0` |
| `--vol` | ❌ | 音量 (0,10] | `1.0` |
| `--pitch` | ❌ | 音调 [-12,12] | `0` |
| `--save` | ❌ | 同时保存到文件（MP3 格式） | 不保存 |
| `--api-key` | ❌ | API Key（默认使用文件顶部配置） | - |
| `--base-url` | ❌ | Base URL（默认使用文件顶部配置） | - |

**示例：**

```bash
# 直接播放（不保存文件）
python3 stream_play.py --text "你好，我正在通过流式方式播放语音"

# 播放同时保存到文件
python3 stream_play.py --text "这段语音会被保存" --save /tmp/stream_output.mp3

# 使用女声播放
python3 stream_play.py --text "今天天气真不错" --voice female-tianmei
```

---

### 2️⃣ 文件生成（需要保存 WAV 时使用）

```bash
SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-tts"
python3 "$SKILL_DIR/scripts/generate.py" \
    --text "要转换的文本内容" \
    --voice "male-qn-jingying" \
    --output "/tmp/tts_output.wav"
```

**参数说明：**

| 参数 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `--text` | ✅ | 要转换的文本，**最长 10000 字符**，超出会报错 | - |
| `--voice` | ❌ | 声优 ID | `male-qn-jingying` |
| `--speed` | ❌ | 语速 [0.5,2.0] | `1.0` |
| `--vol` | ❌ | 音量 (0,10] | `1.0` |
| `--pitch` | ❌ | 音调 [-12,12] | `0` |
| `--output` | ❌ | 输出路径 | 自动生成 |
| `--api-key` | ❌ | API Key（默认使用文件顶部配置） | - |
| `--base-url` | ❌ | Base URL（默认使用文件顶部配置） | - |

**声优可选值：** 完整327个音色列表见 `## 音色列表`

**示例：**

```bash
# 基本用法
python3 generate.py --text "你好，欢迎使用 MiniMax TTS" --output /tmp/hello.wav

# 快速播报（1.5倍速）
python3 generate.py --text "紧急通知，请立即处理" --speed 1.5 --output /tmp/alert.wav

# 柔和女声
python3 generate.py --text "今天天气真不错" --voice female-qn-tianying --output /tmp/weather.wav
```

---

## 工作流总结

### TTS 完整流程

1. **文本预处理** → 检查是否需要插入语气词标签（见 `## 语气词标签`）
2. **选择声优** → `--voice` 参数（默认 `male-qn-jingying`）
3. **调整参数** → `--speed` / `--vol` / `--pitch`
4. **生成 WAV** → 脚本调用 MiniMax TTS API（自动处理 HEX 解码）
5. **格式转换** → 如需 MP3/AAC 等格式，用 ffmpeg 转换

---

## 脚本输出格式

### generate.py

调用 `generate.py` 后，**stdout** 输出生成结果，格式如下：

| stdout 输出 | 说明 |
|------------|------|
| 保存后的文件绝对路径 | `~/.openclaw/media/minimax/tts/tts-2026-03-27-hello.wav` |

### stream_play.py

调用 `stream_play.py` 后，**stdout** 输出播放状态：

| stdout 输出 | 说明 |
|------------|------|
| `STREAM_PLAY_DONE` | 流式播放完成 |
| `STREAM_PLAY_ERROR: <msg>` | 播放失败，附带错误信息 |

> 两个脚本的日志信息（`[INFO]`、`[WARN]`、`[ERROR]`）均输出到 **stderr**，不会混入 stdout。

---

## 错误处理

| code | 含义 | 处理 |
|------|------|------|
| 0 | 成功 | 继续 |
| 1002 | 限流 | 提醒用户 API 限流中，建议稍后重试 |
| 1004 | 鉴权失败 | 检查 API Key |
| 1008 | 余额不足 | 提醒充值 |
| 2049 | 无效 Key | 检查 Key 是否正确 |

---

## 文件存储

- **默认保存到**：`~/.openclaw/media/minimax/tts/`（多 Agent 共享目录）
- **文件名格式**：`tts-YYYY-MM-DD-<slug>.wav`
- slug：取 text 前20字符，英文数字保留，空格变 `-`

---

## 语气词标签

- 在文本中适当位置插入以下标签，可生成对应的非语言音效（笑声、咳嗽、呼吸等）。AI 应根据文本情绪自动判断是否插入。
- 用户明确要求不插入语气词标签时，不要插入。

### 支持的标签

| 标签 | 含义 | 标签 | 含义 |
|------|------|------|------|
| `(laughs)` | 笑声 | `(chuckle)` | 轻笑 |
| `(coughs)` | 咳嗽 | `(clear-throat)` | 清嗓子 |
| `(groans)` | 呻吟 | `(breath)` | 正常换气 |
| `(pant)` | 喘气 | `(inhale)` | 吸气 |
| `(exhale)` | 呼气 | `(gasps)` | 倒吸气 |
| `(sniffs)` | 吸鼻子 | `(sighs)` | 叹气 |
| `(snorts)` | 喷鼻息 | `(burps)` | 打嗝 |
| `(lip-smacking)` | 咂嘴 | `(humming)` | 哼唱 |
| `(hissing)` | 嘶嘶声 | `(sneezes)` | 喷嚏 |

**注意**：`(emm)` 不支持，请用 `(breath)` 或语气停顿代替。

### 使用示例

```
--text "今天是不是很开心呀(laughs)，当然了！"
--text "咳咳(coughs)，不好意思，有点呛到了"
--text "嗯(inhale)，让我想想(exhale)..."
```

---

## 注意事项

- **文本长度**：最长 10000 字符，超出会报错
- **HEX 解码**：API 返回的 audio 字段是 HEX 编码（不是 base64），脚本自动处理
- **完成后提示用户**：可以从 https://platform.minimaxi.com/docs/faq/system-voice-id 找到更多音色